update to latest version: v1.2.0

Author: su-amaas

CHANGELOG.md

@@ -1,5 +1,8 @@
 # CHANGELOG
 
+## 1.2.0 - 2024-08-07
+* Support verbose scan result
+
 ## 1.1.1 - 2024-04-10
 * Update README.md
 * Extend the scan default timeout to 300s

README.md

@@ -75,6 +75,8 @@ public static void main(String[] args) {
 
 ### Sample JSON Response
 
+#### Concise Format
+
 ```json
 {
   "version": "1.0",
@@ -94,6 +96,58 @@ public static void main(String[] args) {
 
 When malicious content is detected in the scanned object, `scanResult` will show a non-zero value. Otherwise, the value will be `null`. Moreover, when malware is detected, `foundMalwares` will be non-empty containing one or more name/value pairs of `fileName` and `malwareName`. `fileName` will be filename of malware detected while `malwareName` will be the name of the virus/malware found.
 
+#### Verbose Format
+
+```json
+{
+  "scanType": "sdk",
+  "objectType": "file",
+  "timestamp": {
+    "start": "2024-07-05T20:01:21.064Z",
+    "end": "2024-07-05T20:01:21.069Z"
+  },
+  "schemaVersion": "1.0.0",
+  "scannerVersion": "1.0.0-59",
+  "fileName": "eicar.com",
+  "rsSize": 68,
+  "scanId": "40d7a38e-a1d3-400b-a09c-7aa9cd62658f",
+  "accountId": "",
+  "result": {
+    "atse": {
+      "elapsedTime": 4693,
+      "fileType": 5,
+      "fileSubType": 0,
+      "version": {
+        "engine": "23.57.0-1002",
+        "lptvpn": 385,
+        "ssaptn": 731,
+        "tmblack": 253,
+        "tmwhite": 239,
+        "macvpn": 914
+      },
+      "malwareCount": 1,
+      "malware": [
+        {
+          "name": "Eicar_test_file",
+          "fileName": "eicar.com",
+          "type": "",
+          "fileType": 5,
+          "fileSubType": 0,
+          "fileTypeName": "COM",
+          "fileSubTypeName": "VSDT_COM_DOS"
+        }
+      ],
+      "error": null,
+      "fileTypeName": "COM",
+      "fileSubTypeName": "VSDT_COM_DOS"
+    }
+  },
+  "fileSHA1": "3395856ce81f2b7382dee72602f798b642f14140",
+  "fileSHA256": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
+  "appName": "V1FS"
+}
+```
+
 ## Java SDK API Reference
 
 ### ```AmaasClient```
@@ -144,7 +198,7 @@ Scan a file for malware and retrieves response data from the API.
 **_Return_**
 String the scanned result in JSON format.
 
-#### ```public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException```
+#### ```public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException```
 
 Scan a file for malware, add a list of tags to the scan result and retrieves response data from the API.
 
@@ -156,6 +210,7 @@ Scan a file for malware, add a list of tags to the scan result and retrieves res
 | tagList       | A list of strings to be used to tag the scan result. At most 8 tags with the maximum length of 63 characters.                                  |
 | pml           | A flag to indicate whether to enable predictive machine learning detection.                  |
 | feedback      | A flag to indicate whether to enable Trend Micro Smart Protection Network's Smart Feedback.  |
+| verbose       | A flag to enable log verbose mode.                                                       |
 
 **_Return_**
 String the scanned result in JSON format.
@@ -174,7 +229,7 @@ Scan a buffer for malware and retrieves response data from the API.
 **_Return_**
 String the scanned result in JSON format.
 
-#### ```public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException```
+#### ```public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException```
 
 Scan a buffer for malware, add a list of tags to the scan result, and retrieves response data from the API.
 
@@ -187,6 +242,7 @@ Scan a buffer for malware, add a list of tags to the scan result, and retrieves
 | tagList       | A list of strings to be used to tag the scan result. At most 8 tags with maximum length of 63 characters.                                     |
 | pml           | A flag to indicate whether to enable predictive machine learning detection.                  |
 | feedback      | A flag to indicate whether to enable Trend Micro Smart Protection Network's Smart Feedback.  |
+| verbose       | A flag to enable log verbose mode.                                                        |
 
 **_Return_**
 String the scanned result in JSON format.
@@ -207,7 +263,7 @@ public class AmaasScanResult {
   private String fileName:              // Name of the file scanned
   private MalwareItem[] foundMalwares;  // A list of malware names and the filenames found by AMaaS
 
-  // getter and seter methods for the above private variables.
+  // getter and setter methods for the above private variables.
 }
 ```
 
@@ -223,7 +279,32 @@ public class MalwareItem {
   private String malwareName;           // A detected Malware name
   private String fileName:              // File name that the malware is detected.
 
-  // getter and seter methods for the above private variables.
+  // getter and setter methods for the above private variables.
+}
+```
+
+### ```AMaasScanResultVerbose```
+
+The AMaasScanResultVerbose has the data elements of the response data in verbose mode that is retrieved from our API. The class has the following private members. There are getter and setter methods for each of the members. See javaDoc for the class of each data element.
+
+```java
+public class AMaasScanResultVerbose {
+    private String scanType;          // Type of scan
+    private String objectType;        // Type of the object being scanned. e.g, file
+    private StartEnd timestamp;       // begin and end time strings in ISO 8601 format
+    private String schemaVersion;     // Version of the data schema
+    private String scannerVersion;    // Scanner version
+    private String fileName;          // Name of the file
+    private long rsSize;              // Size of the scanned file
+    private String scanId;            // ID of the scan
+    private String accountId;         // ID of the customer
+    private ScanResult result;        // Result for the current scan
+    private String[] tags;            // Tags used for this scan
+    private String fileSha1;          // Sha1 of the scanned file
+    private String fileSha256;        // Sha256 of the scanned file
+    private String appName;           // Name of the application
+
+    // getter and setter methods for the above private variables.
 }
 ```
 

VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

examples/README.md

@@ -46,6 +46,7 @@ There are 4 examples under the following sub-folders:
    --taglist a commas separated string of tags. e.g. dev,sdk
    --pml enable predictive machine language detection. default to false
    --feedback enable Smart Feedback of Trend Micro Smart Protection Network. default to false
+   -v enable log verbose mode. default to false
    ```
 
    For example:

examples/filescan/App.java

@@ -34,12 +34,12 @@ private static String[] listFiles(final String pathName) {
             .collect(Collectors.toList()).toArray(new String[] {});
     }
 
-    static void scanFilesInSequential(final AMaasClient client, final String[] fList, final String[] tagList, final boolean pmlFlag, final boolean feedbackFlag) {
+    static void scanFilesInSequential(final AMaasClient client, final String[] fList, final String[] tagList, final boolean pmlFlag, final boolean feedbackFlag, final boolean verbose) {
         for (String fileName: fList) {
             try {
                 info("===============> Scanning file {0}", fileName);
                 long startTS = System.currentTimeMillis();
-                String scanResult = client.scanFile(fileName, tagList, pmlFlag, feedbackFlag);
+                String scanResult = client.scanFile(fileName, tagList, pmlFlag, feedbackFlag, verbose);
                 long endTS = System.currentTimeMillis();
                 info("{0}", scanResult);
                 info("===============> File scan time {0}", endTS - startTS);
@@ -58,6 +58,7 @@ private static Options getCmdOptions() {
         optionList.addOption(null, "taglist", true, "commas separated string of tags.e.g, sdk,dev");
         optionList.addOption(null, "pml", true, "Enable predictive machine language detection");
         optionList.addOption(null, "feedback", true, "Enable Trend Smart Protection Network's Smart Feedback");
+        optionList.addOption("v", "verbose", true, "Enable log verbose mode");
         return optionList;
     }
 
@@ -71,6 +72,7 @@ private static Options getCmdOptions() {
      *                  --taglist a commas separated string of tags. e.g. dev,sdk
      *                  --pml enable predictive machine language detection. default to false
      *                  --feedback enable Trend Micro Smart Protection Network's Smart Feedback. default to false
+     *                  -v enable log verbose mode. default to false
      */
     public static void main(final String[] args) {
         String pathname = "";
@@ -80,6 +82,7 @@ public static void main(final String[] args) {
         String tags = null;
         boolean pmlFlag = false;
         boolean feedbackFlag = false;
+        boolean verbose = false;
 
         DefaultParser parser = new DefaultParser();
         HelpFormatter helper = new HelpFormatter();
@@ -111,6 +114,11 @@ public static void main(final String[] args) {
                     feedbackFlag = true;
                 }
             }
+            if (cmd.hasOption("v")) {
+                if (cmd.getOptionValue("v").equals("true")) {
+                    verbose = true;
+                }
+            }
             String[] tagList = null;
             if (tags != null) {
                 info("tags to used {0}", tags);
@@ -121,7 +129,7 @@ public static void main(final String[] args) {
             String[] listOfFiles = listFiles(pathname);
             long totalStartTs = System.currentTimeMillis();
 
-            scanFilesInSequential(client, listOfFiles, tagList, pmlFlag, feedbackFlag);
+            scanFilesInSequential(client, listOfFiles, tagList, pmlFlag, feedbackFlag, verbose);
 
             long totalEndTs = System.currentTimeMillis();
             info("*************** Total scan time {0}", totalEndTs - totalStartTs);

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>com.trend</groupId>
   <artifactId>file-security-java-sdk</artifactId>
-  <version>1.1.1</version>
+  <version>1.2.0</version>
 
   <name>file-security-java-sdk</name>
   <url>https://github.com/trendmicro/tm-v1-fs-java-sdk</url>

protos/scan.proto

@@ -29,6 +29,7 @@ message C2S {
   repeated string tags = 9;
   bool bulk = 10;
   bool spn_feedback = 11;
+  bool verbose = 12;
 }
 
 enum Command {

src/main/java/com/trend/cloudone/amaas/AMaasClient.java

@@ -53,7 +53,7 @@ public AMaasClient(final String region, final String apiKey, final long timeoutI
      * @param region region we obtained your api key
      * @param apiKey api key to be used
      * @param timeoutInSecs number in seconds to wait for a scan. 0 default to 180 seconds.
-     * @param enabledTLS boolean flag ro enable or disable TLS
+     * @param enabledTLS boolean flag to enable or disable TLS
      * @param appName application name to use.
      * @throws AMaasException if an exception is detected, it will convert to AMassException.
      *
@@ -266,10 +266,11 @@ static AMaasException getTagListErrors(final String[] tagList) {
     * @param tagList List of tags.
     * @param pml flag to indicate whether to use predictive machine learning detection.
     * @param feedback flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback.
+    * @param verbose flag to enable log verbose mode
     * @return String the scanned result in JSON format.
     * @throws AMaasException if an exception is detected, it will convert to AMassException.
     */
-    private String scanRun(final AMaasReader reader, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException {
+    private String scanRun(final AMaasReader reader, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException {
 
         long fileSize = reader.getLength();
 
@@ -282,7 +283,7 @@ private String scanRun(final AMaasReader reader, final String[] tagList, final b
         String sha1Str = reader.getHash(AMaasReader.HashType.HASH_SHA1);
         String sha256Str = reader.getHash(AMaasReader.HashType.HASH_SHA256);
 
-        ScanOuterClass.C2S.Builder builder = ScanOuterClass.C2S.newBuilder().setStage(Stage.STAGE_INIT).setFileName(reader.getIdentifier()).setRsSize(fileSize).setOffset(0).setFileSha1(sha1Str).setFileSha256(sha256Str).setTrendx(pml).setSpnFeedback(feedback).setBulk(this.bulk);
+        ScanOuterClass.C2S.Builder builder = ScanOuterClass.C2S.newBuilder().setStage(Stage.STAGE_INIT).setFileName(reader.getIdentifier()).setRsSize(fileSize).setOffset(0).setFileSha1(sha1Str).setFileSha256(sha256Str).setTrendx(pml).setSpnFeedback(feedback).setBulk(this.bulk).setVerbose(verbose);
         if (tagList != null) {
             AMaasException except = getTagListErrors(tagList);
             if (except != null) {
@@ -308,22 +309,40 @@ private String scanRun(final AMaasReader reader, final String[] tagList, final b
     * @throws AMaasException if an exception is detected, it will convert to AMassException.
     */
     public String scanFile(final String fileName) throws AMaasException {
-        return this.scanFile(fileName, null, false, false);
+        return this.scanFile(fileName, null, false, false, false);
     }
 
     /**
     * Scan a file and return the scanned result.
     *
+    * @deprecated
     * @param fileName Full path of a file to be scanned.
     * @param tagList List of tags.
     * @param pml flag to indicate whether to enable predictive machine learning detection.
     * @param feedback flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback.
     * @return String the scanned result in JSON format.
     * @throws AMaasException if an exception is detected, it will convert to AMassException.
     */
+    @Deprecated
     public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException {
         AMaasFileReader fileReader = new AMaasFileReader(fileName);
-        return this.scanRun(fileReader, tagList, pml, feedback);
+        return this.scanRun(fileReader, tagList, pml, feedback, false);
+    }
+
+    /**
+    * Scan a file and return the scanned result.
+    *
+    * @param fileName Full path of a file to be scanned.
+    * @param tagList List of tags.
+    * @param pml flag to indicate whether to enable predictive machine learning detection.
+    * @param feedback flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback.
+    * @param verbose flag to enable log verbose mode
+    * @return String the scanned result in JSON format.
+    * @throws AMaasException if an exception is detected, it will convert to AMassException.
+    */
+    public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException {
+        AMaasFileReader fileReader = new AMaasFileReader(fileName);
+        return this.scanRun(fileReader, tagList, pml, feedback, verbose);
     }
 
     /**
@@ -335,11 +354,11 @@ public String scanFile(final String fileName, final String[] tagList, final bool
     * @throws AMaasException if an exception is detected, it will convert to AMassException.
     */
     public String scanBuffer(final byte[] buffer, final String identifier) throws AMaasException {
-        return this.scanBuffer(buffer, identifier, null, false, false);
+        return this.scanBuffer(buffer, identifier, null, false, false, false);
     }
 
     /**
-    * Scan a buffer and return the scanned result.
+    * Scan a buffer and return the scanned result. (TBD: LSK remove this API).
     *
     * @param buffer the buffer to be scanned.
     * @param identifier A unique name to identify the buffer.
@@ -351,6 +370,23 @@ public String scanBuffer(final byte[] buffer, final String identifier) throws AM
     */
     public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException {
         AMaasBufferReader bufReader = new AMaasBufferReader(buffer, identifier);
-        return this.scanRun(bufReader, tagList, pml, feedback);
+        return this.scanRun(bufReader, tagList, pml, feedback, false);
+    }
+
+    /**
+    * Scan a buffer and return the scanned result.
+    *
+    * @param buffer the buffer to be scanned.
+    * @param identifier A unique name to identify the buffer.
+    * @param tagList List of tags.
+    * @param pml flag to indicate whether to use predictive machine learning detection.
+    * @param feedback flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback.
+    * @param verbose flag to enable log verbose mode
+    * @return String the scanned result in JSON format.
+    * @throws AMaasException if an exception is detected, it will convert to AMassException.
+    */
+    public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException {
+        AMaasBufferReader bufReader = new AMaasBufferReader(buffer, identifier);
+        return this.scanRun(bufReader, tagList, pml, feedback, verbose);
     }
 }