From 9c7a648fc749a0001bf60d7159476b3a93cc5fab Mon Sep 17 00:00:00 2001 From: su-amaas Date: Mon, 7 Jul 2025 07:37:46 +0000 Subject: [PATCH] update to latest version: v1.6.0 --- CHANGELOG.md | 5 + README.md | 129 ++++++++------ VERSION | 2 +- examples/filescan/App.java | 25 ++- examples/s3app/S3App.java | 10 +- examples/s3lambda/S3Lambda.java | 16 +- examples/s3stream/S3Stream.java | 17 +- pom.xml | 2 +- protos/scan.proto | 1 + .../com/trend/cloudone/amaas/AMaasClient.java | 95 +++++++++- .../com/trend/cloudone/amaas/AMaasReader.java | 18 +- .../cloudone/amaas/AMaasScanOptions.java | 162 ++++++++++++++++++ 12 files changed, 401 insertions(+), 81 deletions(-) create mode 100644 src/main/java/com/trend/cloudone/amaas/AMaasScanOptions.java diff --git a/CHANGELOG.md b/CHANGELOG.md index 3cc69fb..2062f72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # CHANGELOG +## 1.6.0 - 2025-06-30 + +* Support active content detection +* Add `AMaasScanOptions` to support customizable scan options. + ## 1.5.0 - 2025-06-18 * Supports HTTP and SOCKS5 proxy diff --git a/README.md b/README.md index 85093e2..0df1c6a 100644 --- a/README.md +++ b/README.md @@ -47,28 +47,40 @@ You can manage these keys from the Trend Vision One API Keys Page. Using File Security Java SDK to scan for malware involves the following basic steps: 1. Creating an AMaaS Client object by specifying preferred Vision One region where scanning should be done and a valid API key. -2. Invoking file scan or buffer scan method to scan the target data. -3. Parsing the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not. +2. Configuring scan options using the `AMaasScanOptions` class with the builder pattern. +3. Invoking file scan or buffer scan method to scan the target data. +4. Parsing the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not. ### Sample Code ```java -import com.trend.fs.AMaasClient; +import com.trend.cloudone.amaas.AMaasClient; +import com.trend.cloudone.amaas.AMaasScanOptions; +import com.trend.cloudone.amaas.AMaasException; public static void main(String[] args) { try { // 1. Create an AMaaS Client object and configure it to carry out the scans in Vision One "us-east-1" region. AMaasClient client = new AMaasClient("us-east-1", "your-api-key"); try { - // 2. Call ScanFile() to scan the content of a file. - String scanResult = client.scanFile("path-of-file-to-scan"); + // 2. Configure scan options using the builder pattern + AMaasScanOptions options = AMaasScanOptions.builder() + .pml(true) // Enable predictive machine learning + .feedback(true) // Enable Smart Feedback + .verbose(false) // Disable verbose logging + .activeContent(false) // Disable active content scanning + .tagList(new String[]{"tag1", "tag2"}) // Optional tags + .build(); + + // 3. Call scanFile() to scan the content of a file + String scanResult = client.scanFile("path-of-file-to-scan", true, options); if (scanResult != null) { - // 3. Print out the JSON response from ScanFile() + // 4. Print out the JSON response from scanFile() System.out.println("scan result " + scanResult); } } finally { - // 4. Always close the client to release resources + // 5. Always close the client to release resources client.close(); } } catch (AMaasException err) { @@ -100,6 +112,15 @@ 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. +### Enable Active Content Detection + +Enables active content detection for scanning operations. This feature allows the scanner to detect potentially malicious active content within files, specifically: + +- **PDF scripts**: Detects embedded JavaScript and other scripting content in PDF files +- **Office macros**: Detects VBA macros and other executable content in Microsoft Office documents + +When active content is detected, the scan result will include a type field with values of either `macro` or `script` to indicate the type of active content found. + #### Verbose Format ```json @@ -191,58 +212,38 @@ Creates a new instance of the `AmaasClient` class, and provisions essential sett **_Return_** An AmaasClient instance -#### ```public String scanFile(final String fileName) throws AMaasException``` +#### ```public String scanRun(final AMaasReader reader, final AMaasScanOptions options) throws AMaasException``` -Scan a file for malware and retrieves response data from the API. +Scan an AMaasReader for malware and retrieves response data from the API. This is the core scanning method that provides the most flexibility by accepting an AMaasReader interface, allowing for different types of data sources. **_Parameters_** | Parameter | Description | | ------------- | ---------------------------------------------------------------------------------------- | -| fileName | The name of the file with path of directory containing the file to scan. | +| reader | `AMaasReader` to be scanned. This can be an `AMaasFileReader` or any custom implementation you develop to support your specific data sources. | +| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). | **_Return_** String the scanned result in JSON format. -#### ```public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException``` +**_Note_**: For an example of implementing a custom AMaasReader, please refer to the `examples/s3stream/S3Stream.java` code which demonstrates a streaming implementation of the AMaasReader interface. -Scan a file for malware, add a list of tags to the scan result and retrieves response data from the API. +#### ```public String scanFile(final String fileName, final boolean digest, final AMaasScanOptions options) throws AMaasException``` + +Scan a file for malware and retrieves response data from the API. **_Parameters_** | Parameter | Description | | ------------- | ---------------------------------------------------------------------------------------- | | fileName | The name of the file with path of directory containing the file to scan. | -| 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. | | digest | A flag to enable/disable calculation of digests for cache search and result lookup. | +| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). | **_Return_** String the scanned result in JSON format. -#### ```public String scanRun(final AMaasReader reader, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose, final boolean digest) throws AMaasException``` - -Scan an AMaasReader for malware and retrieves response data from the API. This is the core scanning method that provides the most flexibility by accepting an AMaasReader interface, allowing for different types of data sources. - -**_Parameters_** - -| Parameter | Description | -| ------------- | ---------------------------------------------------------------------------------------- | -| reader | `AMaasReader` to be scanned. This can be an `AMaasFileReader` or any custom implementation you develop to support your specific data sources. | -| 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 use predictive machine learning detection. | -| feedback | A flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback. | -| verbose | A flag to enable log verbose mode. | -| digest | A flag to enable calculation of digests for cache search and result lookup. | - -**_Return_** -String the scanned result in JSON format. - -**_Note_**: For an example of implementing a custom AMaasReader, please refer to the `examples/s3stream/S3Stream.java` code which demonstrates a streaming implementation of the AMaasReader interface. - -#### ```public String scanBuffer(final byte[] buffer, final String identifier) throws AMaasException``` +#### ```public String scanBuffer(final byte[] buffer, final String identifier, final boolean digest, final AMaasScanOptions options) throws AMaasException``` Scan a buffer for malware and retrieves response data from the API. @@ -252,28 +253,54 @@ Scan a buffer for malware and retrieves response data from the API. | ------------- | ----------------------------------------------------------------------------------------- | | buffer | The byte buffer to scan. | | identifier | A unique name to identify the buffer. | +| digest | A flag to enable/disable calculation of digests for cache search and result lookup. | +| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). | **_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, 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. +### ```AMaasScanOptions``` -**_Parameters_** +The AMaasScanOptions class provides a convenient way to configure scan parameters using the builder pattern. This class encapsulates all scan-related configuration options. -| Parameter | Description | -| ------------- | ----------------------------------------------------------------------------------------- | -| buffer | The byte buffer to scan. | -| identifier | A unique name to identify the buffer. | -| 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. | -| digest | A flag to enable/disable calculation of digests for cache search and result lookup. | +#### Creating Scan Options -**_Return_** -String the scanned result in JSON format. +```java +// Create scan options with default values (all flags disabled, no tags) +AMaasScanOptions defaultOptions = AMaasScanOptions.builder().build(); + +// Create scan options with specific configuration +AMaasScanOptions customOptions = AMaasScanOptions.builder() + .pml(true) // Enable predictive machine learning + .feedback(true) // Enable Smart Feedback + .verbose(false) // Disable verbose logging + .activeContent(true) // Enable active content scanning + .tagList(new String[]{"tag1", "tag2"}) // Add custom tags + .build(); +``` + +**_Builder Methods_** + +| Method | Parameter | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------- | +| `pml(boolean)` | pml | Enable or disable predictive machine learning detection. Default: false. | +| `feedback(boolean)` | feedback | Enable or disable Trend Micro Smart Protection Network's Smart Feedback. Default: false. | +| `verbose(boolean)` | verbose | Enable or disable verbose logging mode. Default: false. | +| `activeContent(boolean)` | activeContent | Enable or disable active content scanning. Default: false. | +| `tagList(String[])` | tagList | Set the list of tags for the scan. At most 8 tags with maximum length of 63 characters. Default: null. | +| `build()` | - | Build and return the AMaasScanOptions instance. | + +**_Getter Methods_** + +| Method | Return Type | Description | +| --------------------- | ----------- | --------------------------------------------------------------- | +| `isPml()` | boolean | Returns true if PML detection is enabled. | +| `isFeedback()` | boolean | Returns true if Smart Feedback is enabled. | +| `isVerbose()` | boolean | Returns true if verbose mode is enabled. | +| `isActiveContent()` | boolean | Returns true if active content scanning is enabled. | +| `getTagList()` | String[] | Returns the array of tags, or null if no tags are set. | --- diff --git a/VERSION b/VERSION index bc80560..dc1e644 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.0 +1.6.0 diff --git a/examples/filescan/App.java b/examples/filescan/App.java index 05dd955..f68a1cd 100644 --- a/examples/filescan/App.java +++ b/examples/filescan/App.java @@ -11,6 +11,7 @@ import com.trend.cloudone.amaas.AMaasClient; import com.trend.cloudone.amaas.AMaasException; +import com.trend.cloudone.amaas.AMaasScanOptions; public final class App { @@ -34,12 +35,13 @@ 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, final boolean verbose, final boolean digest) { + static void scanFilesInSequential(final AMaasClient client, final String[] fList, final boolean digest, final AMaasScanOptions options) { for (String fileName: fList) { try { info("===============> Scanning file {0}", fileName); long startTS = System.currentTimeMillis(); - String scanResult = client.scanFile(fileName, tagList, pmlFlag, feedbackFlag, verbose, digest); + + String scanResult = client.scanFile(fileName, digest, options); long endTS = System.currentTimeMillis(); info("{0}", scanResult); info("===============> File scan time {0}", endTS - startTS); @@ -62,6 +64,7 @@ private static Options getCmdOptions() { optionList.addOption("v", "verbose", true, "Enable log verbose mode"); optionList.addOption(null, "ca_cert", true, "CA Certificate of hosted AMaaS Scanner server"); optionList.addOption(null, "digest", true, "Enable/Disable calculation of digests for cache search and result lookup"); + optionList.addOption(null, "active_content", true, "Enable active content scanning. Default to false"); return optionList; } @@ -79,6 +82,7 @@ private static Options getCmdOptions() { * -v enable log verbose mode. default to false * --ca_cert CA certificate of self hosted AMaaS server * --digest Enable/Disable calculation of digests for cache search and result lookup + * --active_content Enable active content scanning. Default to false */ public static void main(final String[] args) { String pathname = ""; @@ -92,6 +96,7 @@ public static void main(final String[] args) { boolean verbose = false; String caCertPath = null; boolean digest = true; + boolean activeContent = false; DefaultParser parser = new DefaultParser(); HelpFormatter helper = new HelpFormatter(); @@ -139,6 +144,13 @@ public static void main(final String[] args) { digest = false; } } + + if (cmd.hasOption("active_content")) { + if (cmd.getOptionValue("active_content").equals("true")) { + activeContent = true; + } + } + String[] tagList = null; if (tags != null) { info("tags to used {0}", tags); @@ -149,8 +161,15 @@ public static void main(final String[] args) { try { String[] listOfFiles = listFiles(pathname); long totalStartTs = System.currentTimeMillis(); + AMaasScanOptions options = AMaasScanOptions.builder() + .pml(pmlFlag) + .feedback(feedbackFlag) + .verbose(verbose) + .tagList(tagList) + .activeContent(activeContent) + .build(); - scanFilesInSequential(client, listOfFiles, tagList, pmlFlag, feedbackFlag, verbose, digest); + scanFilesInSequential(client, listOfFiles, digest, options); long totalEndTs = System.currentTimeMillis(); info("*************** Total scan time {0}", totalEndTs - totalStartTs); diff --git a/examples/s3app/S3App.java b/examples/s3app/S3App.java index a488eae..b281266 100644 --- a/examples/s3app/S3App.java +++ b/examples/s3app/S3App.java @@ -17,6 +17,7 @@ import com.trend.cloudone.amaas.AMaasClient; import com.trend.cloudone.amaas.AMaasException; +import com.trend.cloudone.amaas.AMaasScanOptions; public final class S3App { private static final Logger logger = Logger.getLogger(S3App.class.getName()); @@ -119,7 +120,14 @@ public static void main(final String[] args) { AMaasClient client = new AMaasClient(amaasRegion, apikey, timeout); try { long totalStartTs = System.currentTimeMillis(); - client.scanBuffer(bytes, keyName); + AMaasScanOptions options = AMaasScanOptions.builder() + .pml(true) // Predictive Machine Learning detection + .feedback(true) // Smart Feedback + .verbose(false) // Verbose mode + .activeContent(true) // Active content scanning + .build(); + + client.scanBuffer(bytes, keyName, true, options); long totalEndTs = System.currentTimeMillis(); info("*************** Total scan time {0}", totalEndTs - totalStartTs); } finally { diff --git a/examples/s3lambda/S3Lambda.java b/examples/s3lambda/S3Lambda.java index 625f28d..72b2483 100644 --- a/examples/s3lambda/S3Lambda.java +++ b/examples/s3lambda/S3Lambda.java @@ -18,6 +18,7 @@ import com.trend.cloudone.amaas.AMaasClient; import com.trend.cloudone.amaas.AMaasException; +import com.trend.cloudone.amaas.AMaasScanOptions; public final class S3Lambda implements RequestHandler { private static final Logger logger = Logger.getLogger(S3Lambda.class.getName()); @@ -87,12 +88,15 @@ private static void sequentialScan(final AMaasClient client, final S3Client s3cl byte[] bytes = downloadS3Object(s3client, bucketName, keyName); long startTs = System.currentTimeMillis(); info("===============> Scanning S3 key {0}", keyName); - String scanResult = ""; - if (tagList == null) { - scanResult = client.scanBuffer(bytes, keyName); - } else { - scanResult = client.scanBuffer(bytes, keyName, tagList, false, false); - } + AMaasScanOptions options = AMaasScanOptions.builder() + .pml(false) // Predictive Machine Learning detection + .feedback(false) // Smart Feedback + .verbose(false) // Verbose mode + .activeContent(false) // Active content scanning + .tagList(tagList) + .build(); + + String scanResult = client.scanBuffer(bytes, bucketName, true, options); long endTs = System.currentTimeMillis(); info("===============> scanResult {0}, scanTime {1}.", scanResult, endTs - startTs); } catch (S3Exception err) { diff --git a/examples/s3stream/S3Stream.java b/examples/s3stream/S3Stream.java index 508240a..e3d0fe1 100644 --- a/examples/s3stream/S3Stream.java +++ b/examples/s3stream/S3Stream.java @@ -1,5 +1,3 @@ -package com.trend.cloudone.amaas; - import java.io.IOException; import java.nio.ByteBuffer; import java.util.logging.Level; @@ -19,7 +17,11 @@ import software.amazon.awssdk.services.s3.model.HeadObjectRequest; import software.amazon.awssdk.services.s3.model.HeadObjectResponse; -import com.trend.cloudone.amaas.AMaasReader.HashType; +import com.trend.cloudone.amaas.AMaasReader; +import com.trend.cloudone.amaas.AMaasClient; +import com.trend.cloudone.amaas.AMaasException; +import com.trend.cloudone.amaas.AMaasScanOptions; +import com.trend.cloudone.amaas.AMaasErrorCode; /** * S3Stream class implements the AMaasReader interface for S3 objects. @@ -241,9 +243,14 @@ public static void main(final String[] args) { AMaasClient client = new AMaasClient(amaasRegion, apikey, timeout); try { long totalStartTs = System.currentTimeMillis(); - + AMaasScanOptions options = AMaasScanOptions.builder() + .pml(true) // Predictive Machine Learning detection + .feedback(true) // Smart Feedback + .verbose(false) // Verbose mode + .activeContent(true) // Active content scanning + .build(); // Use scanRun with the S3Stream AMaasReader - String scanResult = client.scanRun(s3Stream, null, false, false, false, true); + String scanResult = client.scanRun(s3Stream, options); long totalEndTs = System.currentTimeMillis(); info("Scan Result: {0}", scanResult); info("*************** Total scan time {0}", totalEndTs - totalStartTs); diff --git a/pom.xml b/pom.xml index 9023f2e..69bfa78 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ com.trend file-security-java-sdk - 1.5.0 + 1.6.0 file-security-java-sdk https://github.com/trendmicro/tm-v1-fs-java-sdk diff --git a/protos/scan.proto b/protos/scan.proto index 3537f2f..561138b 100644 --- a/protos/scan.proto +++ b/protos/scan.proto @@ -30,6 +30,7 @@ message C2S { bool bulk = 10; bool spn_feedback = 11; bool verbose = 12; + bool active_content = 13; } enum Command { diff --git a/src/main/java/com/trend/cloudone/amaas/AMaasClient.java b/src/main/java/com/trend/cloudone/amaas/AMaasClient.java index 6e7e651..87fc8e2 100644 --- a/src/main/java/com/trend/cloudone/amaas/AMaasClient.java +++ b/src/main/java/com/trend/cloudone/amaas/AMaasClient.java @@ -10,6 +10,7 @@ import java.util.logging.Level; import java.util.logging.Logger; import javax.net.ssl.SSLException; + import io.grpc.ManagedChannel; import io.grpc.netty.GrpcSslContexts; import io.grpc.netty.NettyChannelBuilder; @@ -457,7 +458,31 @@ static AMaasException getTagListErrors(final String[] tagList) { * @return String the scanned result in JSON format. * @throws AMaasException if an exception is detected, it will convert to AMassException. */ + @Deprecated public String scanRun(final AMaasReader reader, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose, final boolean digest) throws AMaasException { + AMaasScanOptions options = AMaasScanOptions.builder() + .tagList(tagList) + .pml(pml) + .feedback(feedback) + .verbose(verbose) + .build(); + return this.scanRun(reader, options); + } + + /** + * Scan a AMaasReader and return the scanned result. + * + * @param reader AMaasReader to be scanned. + * @param options scan options containing configuration for the scan operation. + * @return String the scanned result in JSON format. + * @throws AMaasException if an exception is detected, it will convert to AMassException. + */ + public String scanRun(final AMaasReader reader, final AMaasScanOptions options) throws AMaasException { + boolean pml = options.isPml(); + boolean feedback = options.isFeedback(); + boolean verbose = options.isVerbose(); + boolean activeContent = options.isActiveContent(); + String[] tagList = options.getTagList(); long fileSize = reader.getLength(); @@ -471,7 +496,20 @@ public String scanRun(final AMaasReader reader, final String[] tagList, final bo String sha256Str = reader.getHash(AMaasReader.HashType.HASH_SHA256); log(Level.FINE, "sha1={0} sha256={1}", sha1Str, sha256Str); - 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); + 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) + .setActiveContent(activeContent); + if (tagList != null) { AMaasException except = getTagListErrors(tagList); if (except != null) { @@ -486,7 +524,6 @@ public String scanRun(final AMaasReader reader, final String[] tagList, final bo String scanResult = serverCallback.waitTilExit(); return scanResult; - } /** @@ -496,6 +533,7 @@ public String scanRun(final AMaasReader reader, final String[] tagList, final bo * @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) throws AMaasException { return this.scanFile(fileName, null, false, false, false, true); } @@ -513,8 +551,7 @@ public String scanFile(final String fileName) throws AMaasException { */ @Deprecated public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException { - AMaasFileReader fileReader = new AMaasFileReader(fileName, true); - return this.scanRun(fileReader, tagList, pml, feedback, false, true); + return this.scanFile(fileName, tagList, pml, feedback, false, true); } /** @@ -529,9 +566,29 @@ public String scanFile(final String fileName, final String[] tagList, final bool * @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, final boolean verbose, final boolean digest) throws AMaasException { + AMaasScanOptions options = AMaasScanOptions.builder() + .tagList(tagList) + .pml(pml) + .feedback(feedback) + .verbose(verbose) + .build(); + return this.scanFile(fileName, digest, options); + } + + /** + * Scan a file and return the scanned result. + * + * @param fileName Full path of a file to be scanned. + * @param digest flag to enable calculation of digests for cache search and result lookup. + * @param options scan options containing configuration for the scan operation. + * @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 boolean digest, final AMaasScanOptions options) throws AMaasException { AMaasFileReader fileReader = new AMaasFileReader(fileName, digest); - return this.scanRun(fileReader, tagList, pml, feedback, verbose, digest); + return this.scanRun(fileReader, options); } /** @@ -542,6 +599,7 @@ public String scanFile(final String fileName, final String[] tagList, final bool * @return String the scanned result in JSON format. * @throws AMaasException if an exception is detected, it will convert to AMassException. */ + @Deprecated public String scanBuffer(final byte[] buffer, final String identifier) throws AMaasException { return this.scanBuffer(buffer, identifier, null, false, false, false, true); } @@ -560,8 +618,7 @@ public String scanBuffer(final byte[] buffer, final String identifier) throws AM */ @Deprecated 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, true); - return this.scanRun(bufReader, tagList, pml, feedback, false, true); + return this.scanBuffer(buffer, identifier, tagList, pml, feedback, false, true); } /** @@ -577,8 +634,30 @@ public String scanBuffer(final byte[] buffer, final String identifier, final Str * @return String the scanned result in JSON format. * @throws AMaasException if an exception is detected, it will convert to AMassException. */ + @Deprecated public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose, final boolean digest) throws AMaasException { + AMaasScanOptions options = AMaasScanOptions.builder() + .tagList(tagList) + .pml(pml) + .feedback(feedback) + .verbose(verbose) + .build(); + return this.scanBuffer(buffer, identifier, digest, options); + } + + /** + * 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 digest flag to enable calculation of digests for cache search and result lookup. + * @param options scan options containing configuration for the scan operation. + * @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 boolean digest, final AMaasScanOptions options) throws AMaasException { AMaasBufferReader bufReader = new AMaasBufferReader(buffer, identifier, digest); - return this.scanRun(bufReader, tagList, pml, feedback, verbose, digest); + return this.scanRun(bufReader, options); } + } diff --git a/src/main/java/com/trend/cloudone/amaas/AMaasReader.java b/src/main/java/com/trend/cloudone/amaas/AMaasReader.java index e7eb2e2..213372d 100644 --- a/src/main/java/com/trend/cloudone/amaas/AMaasReader.java +++ b/src/main/java/com/trend/cloudone/amaas/AMaasReader.java @@ -5,30 +5,38 @@ /* * Interface for implementing a reader class to be scanned. */ -interface AMaasReader { +public interface AMaasReader { + /** + * Supported hash types for content hashing. + */ enum HashType { + /** SHA-1 hash type. */ HASH_SHA1, + /** SHA-256 hash type. */ HASH_SHA256 } - /* + /** * Get Length of the content of the reader. + * @return length of the content in bytes. */ long getLength(); - /* + /** * Get the identifier of the reader. + * @return identifier of the reader. */ String getIdentifier(); - /* + /** * Method to fill the given buffer with part of the reader's content starting from the offset. * @param offset starting offset to be read * @param buff byte array to be filled with reader's content. + * @return number of bytes read into the buffer. */ int readBytes(int offset, byte[] buff) throws IOException; - /* + /** * Method to return the hashes as a Hex string for the content read by the reader. * @param htype one of HashType: sha-1, sha-256 * @return a hex string represent the hash of a given type diff --git a/src/main/java/com/trend/cloudone/amaas/AMaasScanOptions.java b/src/main/java/com/trend/cloudone/amaas/AMaasScanOptions.java new file mode 100644 index 0000000..4a88d71 --- /dev/null +++ b/src/main/java/com/trend/cloudone/amaas/AMaasScanOptions.java @@ -0,0 +1,162 @@ +package com.trend.cloudone.amaas; + +/** + * Scan options class to encapsulate scan configuration parameters. + * This class provides a convenient way to group scan-related boolean flags together. + */ +public final class AMaasScanOptions { + private final boolean pml; + private final boolean feedback; + private final boolean verbose; + private final boolean activeContent; + private final String[] tagList; + + /** + * Private constructor - can only be called by the builder. + * + * @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 + * @param activeContent flag to enable active content scanning. + * @param tagList List of tags to be used for the scan. + */ + private AMaasScanOptions(final boolean pml, final boolean feedback, final boolean verbose, final boolean activeContent, final String[] tagList) { + this.pml = pml; + this.feedback = feedback; + this.verbose = verbose; + this.activeContent = activeContent; + this.tagList = tagList != null ? tagList.clone() : null; + } + + /** + * Create a builder for constructing ScanOptions with fluent API. + * + * @return new ScanOptionsBuilder instance + */ + public static ScanOptionsBuilder builder() { + return new ScanOptionsBuilder(); + } + + /** + * Get the predictive machine learning detection flag. + * + * @return true if PML detection is enabled, false otherwise. + */ + public boolean isPml() { + return pml; + } + + /** + * Get the Smart Feedback flag. + * + * @return true if Smart Feedback is enabled, false otherwise. + */ + public boolean isFeedback() { + return feedback; + } + + /** + * Get the verbose mode flag. + * + * @return true if verbose mode is enabled, false otherwise. + */ + public boolean isVerbose() { + return verbose; + } + + /** + * Get the active content scanning flag. + * + * @return true if active content scanning is enabled, false otherwise. + */ + public boolean isActiveContent() { + return activeContent; + } + + /** + * Get the list of tags. + * + * @return array of tags, or null if no tags are set + */ + public String[] getTagList() { + return tagList; + } + + /** + * Builder class for creating ScanOptions instances with fluent API. + */ + public static final class ScanOptionsBuilder { + private boolean pml = false; + private boolean feedback = false; + private boolean verbose = false; + private boolean activeContent = false; + private String[] tagList = null; + + private ScanOptionsBuilder() { + } + + /** + * Enable or disable predictive machine learning detection. + * + * @param pml true to enable PML, false to disable + * @return this builder instance for method chaining + */ + public ScanOptionsBuilder pml(final boolean pml) { + this.pml = pml; + return this; + } + + /** + * Enable or disable Smart Feedback. + * + * @param feedback true to enable Smart Feedback, false to disable + * @return this builder instance for method chaining + */ + public ScanOptionsBuilder feedback(final boolean feedback) { + this.feedback = feedback; + return this; + } + + /** + * Enable or disable verbose mode. + * + * @param verbose true to enable verbose mode, false to disable + * @return this builder instance for method chaining + */ + public ScanOptionsBuilder verbose(final boolean verbose) { + this.verbose = verbose; + return this; + } + + /** + * Enable or disable active content scanning. + * + * @param activeContent true to enable active content scanning, false to disable + * @return this builder instance for method chaining + */ + public ScanOptionsBuilder activeContent(final boolean activeContent) { + this.activeContent = activeContent; + return this; + } + + /** + * Set the list of tags for the scan. + * + * @param tagList array of tags to be used for the scan + * @return this builder instance for method chaining + */ + public ScanOptionsBuilder tagList(final String[] tagList) { + this.tagList = tagList != null ? tagList.clone() : null; + return this; + } + + /** + * Build the ScanOptions instance. + * + * @return new ScanOptions instance with configured values + */ + public AMaasScanOptions build() { + return new AMaasScanOptions(pml, feedback, verbose, activeContent, tagList); + } + } +}