Skip to content

Commit 8f295ab

Browse files
neilhsu-tmneilhsu-tm
authored
Merge pull request #26 from trendmicro/update_to_latest_version_v1.6.0
update to latest version: v1.6.0
2 parents 0d690d2 + 9c7a648 commit 8f295ab

File tree

12 files changed

+401
-81
lines changed

12 files changed

+401
-81
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# CHANGELOG
22

3+
## 1.6.0 - 2025-06-30
4+
5+
* Support active content detection
6+
* Add `AMaasScanOptions` to support customizable scan options.
7+
38
## 1.5.0 - 2025-06-18
49

510
* Supports HTTP and SOCKS5 proxy

‎README.md‎

Lines changed: 78 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -47,28 +47,40 @@ You can manage these keys from the Trend Vision One API Keys Page.
4747
Using File Security Java SDK to scan for malware involves the following basic steps:
4848

4949
1. Creating an AMaaS Client object by specifying preferred Vision One region where scanning should be done and a valid API key.
50-
2. Invoking file scan or buffer scan method to scan the target data.
51-
3. Parsing the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
50+
2. Configuring scan options using the `AMaasScanOptions` class with the builder pattern.
51+
3. Invoking file scan or buffer scan method to scan the target data.
52+
4. Parsing the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
5253

5354
### Sample Code
5455

5556
```java
56-
import com.trend.fs.AMaasClient;
57+
import com.trend.cloudone.amaas.AMaasClient;
58+
import com.trend.cloudone.amaas.AMaasScanOptions;
59+
import com.trend.cloudone.amaas.AMaasException;
5760

5861
public static void main(String[] args) {
5962
try {
6063
// 1. Create an AMaaS Client object and configure it to carry out the scans in Vision One "us-east-1" region.
6164
AMaasClient client = new AMaasClient("us-east-1", "your-api-key");
6265
try {
63-
// 2. Call ScanFile() to scan the content of a file.
64-
String scanResult = client.scanFile("path-of-file-to-scan");
66+
// 2. Configure scan options using the builder pattern
67+
AMaasScanOptions options = AMaasScanOptions.builder()
68+
.pml(true) // Enable predictive machine learning
69+
.feedback(true) // Enable Smart Feedback
70+
.verbose(false) // Disable verbose logging
71+
.activeContent(false) // Disable active content scanning
72+
.tagList(new String[]{"tag1", "tag2"}) // Optional tags
73+
.build();
74+
75+
// 3. Call scanFile() to scan the content of a file
76+
String scanResult = client.scanFile("path-of-file-to-scan", true, options);
6577

6678
if (scanResult != null) {
67-
// 3. Print out the JSON response from ScanFile()
79+
// 4. Print out the JSON response from scanFile()
6880
System.out.println("scan result " + scanResult);
6981
}
7082
} finally {
71-
// 4. Always close the client to release resources
83+
// 5. Always close the client to release resources
7284
client.close();
7385
}
7486
} catch (AMaasException err) {
@@ -100,6 +112,15 @@ public static void main(String[] args) {
100112

101113
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.
102114

115+
### Enable Active Content Detection
116+
117+
Enables active content detection for scanning operations. This feature allows the scanner to detect potentially malicious active content within files, specifically:
118+
119+
- **PDF scripts**: Detects embedded JavaScript and other scripting content in PDF files
120+
- **Office macros**: Detects VBA macros and other executable content in Microsoft Office documents
121+
122+
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.
123+
103124
#### Verbose Format
104125

105126
```json
@@ -191,58 +212,38 @@ Creates a new instance of the `AmaasClient` class, and provisions essential sett
191212
**_Return_**
192213
An AmaasClient instance
193214

194-
#### ```public String scanFile(final String fileName) throws AMaasException```
215+
#### ```public String scanRun(final AMaasReader reader, final AMaasScanOptions options) throws AMaasException```
195216

196-
Scan a file for malware and retrieves response data from the API.
217+
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.
197218

198219
**_Parameters_**
199220

200221
| Parameter | Description |
201222
| ------------- | ---------------------------------------------------------------------------------------- |
202-
| fileName | The name of the file with path of directory containing the file to scan. |
223+
| reader | `AMaasReader` to be scanned. This can be an `AMaasFileReader` or any custom implementation you develop to support your specific data sources. |
224+
| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). |
203225

204226
**_Return_**
205227
String the scanned result in JSON format.
206228

207-
#### ```public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException```
229+
**_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.
208230

209-
Scan a file for malware, add a list of tags to the scan result and retrieves response data from the API.
231+
#### ```public String scanFile(final String fileName, final boolean digest, final AMaasScanOptions options) throws AMaasException```
232+
233+
Scan a file for malware and retrieves response data from the API.
210234

211235
**_Parameters_**
212236

213237
| Parameter | Description |
214238
| ------------- | ---------------------------------------------------------------------------------------- |
215239
| fileName | The name of the file with path of directory containing the file to scan. |
216-
| tagList | A list of strings to be used to tag the scan result. At most 8 tags with the maximum length of 63 characters. |
217-
| pml | A flag to indicate whether to enable predictive machine learning detection. |
218-
| feedback | A flag to indicate whether to enable Trend Micro Smart Protection Network's Smart Feedback. |
219-
| verbose | A flag to enable log verbose mode. |
220240
| digest | A flag to enable/disable calculation of digests for cache search and result lookup. |
241+
| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). |
221242

222243
**_Return_**
223244
String the scanned result in JSON format.
224245

225-
#### ```public String scanRun(final AMaasReader reader, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose, final boolean digest) throws AMaasException```
226-
227-
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.
228-
229-
**_Parameters_**
230-
231-
| Parameter | Description |
232-
| ------------- | ---------------------------------------------------------------------------------------- |
233-
| reader | `AMaasReader` to be scanned. This can be an `AMaasFileReader` or any custom implementation you develop to support your specific data sources. |
234-
| tagList | A list of strings to be used to tag the scan result. At most 8 tags with the maximum length of 63 characters. |
235-
| pml | A flag to indicate whether to use predictive machine learning detection. |
236-
| feedback | A flag to indicate whether to use Trend Micro Smart Protection Network's Smart Feedback. |
237-
| verbose | A flag to enable log verbose mode. |
238-
| digest | A flag to enable calculation of digests for cache search and result lookup. |
239-
240-
**_Return_**
241-
String the scanned result in JSON format.
242-
243-
**_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.
244-
245-
#### ```public String scanBuffer(final byte[] buffer, final String identifier) throws AMaasException```
246+
#### ```public String scanBuffer(final byte[] buffer, final String identifier, final boolean digest, final AMaasScanOptions options) throws AMaasException```
246247

247248
Scan a buffer for malware and retrieves response data from the API.
248249

@@ -252,28 +253,54 @@ Scan a buffer for malware and retrieves response data from the API.
252253
| ------------- | ----------------------------------------------------------------------------------------- |
253254
| buffer | The byte buffer to scan. |
254255
| identifier | A unique name to identify the buffer. |
256+
| digest | A flag to enable/disable calculation of digests for cache search and result lookup. |
257+
| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). |
255258

256259
**_Return_**
257260
String the scanned result in JSON format.
258261

259-
#### ```public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback, final boolean verbose) throws AMaasException```
262+
---
260263

261-
Scan a buffer for malware, add a list of tags to the scan result, and retrieves response data from the API.
264+
### ```AMaasScanOptions```
262265

263-
**_Parameters_**
266+
The AMaasScanOptions class provides a convenient way to configure scan parameters using the builder pattern. This class encapsulates all scan-related configuration options.
264267

265-
| Parameter | Description |
266-
| ------------- | ----------------------------------------------------------------------------------------- |
267-
| buffer | The byte buffer to scan. |
268-
| identifier | A unique name to identify the buffer. |
269-
| tagList | A list of strings to be used to tag the scan result. At most 8 tags with maximum length of 63 characters. |
270-
| pml | A flag to indicate whether to enable predictive machine learning detection. |
271-
| feedback | A flag to indicate whether to enable Trend Micro Smart Protection Network's Smart Feedback. |
272-
| verbose | A flag to enable log verbose mode. |
273-
| digest | A flag to enable/disable calculation of digests for cache search and result lookup. |
268+
#### Creating Scan Options
274269

275-
**_Return_**
276-
String the scanned result in JSON format.
270+
```java
271+
// Create scan options with default values (all flags disabled, no tags)
272+
AMaasScanOptions defaultOptions = AMaasScanOptions.builder().build();
273+
274+
// Create scan options with specific configuration
275+
AMaasScanOptions customOptions = AMaasScanOptions.builder()
276+
.pml(true) // Enable predictive machine learning
277+
.feedback(true) // Enable Smart Feedback
278+
.verbose(false) // Disable verbose logging
279+
.activeContent(true) // Enable active content scanning
280+
.tagList(new String[]{"tag1", "tag2"}) // Add custom tags
281+
.build();
282+
```
283+
284+
**_Builder Methods_**
285+
286+
| Method | Parameter | Description |
287+
| ------------- | --------- | ---------------------------------------------------------------------------------------- |
288+
| `pml(boolean)` | pml | Enable or disable predictive machine learning detection. Default: false. |
289+
| `feedback(boolean)` | feedback | Enable or disable Trend Micro Smart Protection Network's Smart Feedback. Default: false. |
290+
| `verbose(boolean)` | verbose | Enable or disable verbose logging mode. Default: false. |
291+
| `activeContent(boolean)` | activeContent | Enable or disable active content scanning. Default: false. |
292+
| `tagList(String[])` | tagList | Set the list of tags for the scan. At most 8 tags with maximum length of 63 characters. Default: null. |
293+
| `build()` | - | Build and return the AMaasScanOptions instance. |
294+
295+
**_Getter Methods_**
296+
297+
| Method | Return Type | Description |
298+
| --------------------- | ----------- | --------------------------------------------------------------- |
299+
| `isPml()` | boolean | Returns true if PML detection is enabled. |
300+
| `isFeedback()` | boolean | Returns true if Smart Feedback is enabled. |
301+
| `isVerbose()` | boolean | Returns true if verbose mode is enabled. |
302+
| `isActiveContent()` | boolean | Returns true if active content scanning is enabled. |
303+
| `getTagList()` | String[] | Returns the array of tags, or null if no tags are set. |
277304

278305
---
279306

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.5.0
1+
1.6.0

‎examples/filescan/App.java‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
import com.trend.cloudone.amaas.AMaasClient;
1313
import com.trend.cloudone.amaas.AMaasException;
14+
import com.trend.cloudone.amaas.AMaasScanOptions;
1415

1516

1617
public final class App {
@@ -34,12 +35,13 @@ private static String[] listFiles(final String pathName) {
3435
.collect(Collectors.toList()).toArray(new String[] {});
3536
}
3637

37-
static void scanFilesInSequential(final AMaasClient client, final String[] fList, final String[] tagList, final boolean pmlFlag, final boolean feedbackFlag, final boolean verbose, final boolean digest) {
38+
static void scanFilesInSequential(final AMaasClient client, final String[] fList, final boolean digest, final AMaasScanOptions options) {
3839
for (String fileName: fList) {
3940
try {
4041
info("===============> Scanning file {0}", fileName);
4142
long startTS = System.currentTimeMillis();
42-
String scanResult = client.scanFile(fileName, tagList, pmlFlag, feedbackFlag, verbose, digest);
43+
44+
String scanResult = client.scanFile(fileName, digest, options);
4345
long endTS = System.currentTimeMillis();
4446
info("{0}", scanResult);
4547
info("===============> File scan time {0}", endTS - startTS);
@@ -62,6 +64,7 @@ private static Options getCmdOptions() {
6264
optionList.addOption("v", "verbose", true, "Enable log verbose mode");
6365
optionList.addOption(null, "ca_cert", true, "CA Certificate of hosted AMaaS Scanner server");
6466
optionList.addOption(null, "digest", true, "Enable/Disable calculation of digests for cache search and result lookup");
67+
optionList.addOption(null, "active_content", true, "Enable active content scanning. Default to false");
6568
return optionList;
6669
}
6770

@@ -79,6 +82,7 @@ private static Options getCmdOptions() {
7982
* -v enable log verbose mode. default to false
8083
* --ca_cert CA certificate of self hosted AMaaS server
8184
* --digest Enable/Disable calculation of digests for cache search and result lookup
85+
* --active_content Enable active content scanning. Default to false
8286
*/
8387
public static void main(final String[] args) {
8488
String pathname = "";
@@ -92,6 +96,7 @@ public static void main(final String[] args) {
9296
boolean verbose = false;
9397
String caCertPath = null;
9498
boolean digest = true;
99+
boolean activeContent = false;
95100

96101
DefaultParser parser = new DefaultParser();
97102
HelpFormatter helper = new HelpFormatter();
@@ -139,6 +144,13 @@ public static void main(final String[] args) {
139144
digest = false;
140145
}
141146
}
147+
148+
if (cmd.hasOption("active_content")) {
149+
if (cmd.getOptionValue("active_content").equals("true")) {
150+
activeContent = true;
151+
}
152+
}
153+
142154
String[] tagList = null;
143155
if (tags != null) {
144156
info("tags to used {0}", tags);
@@ -149,8 +161,15 @@ public static void main(final String[] args) {
149161
try {
150162
String[] listOfFiles = listFiles(pathname);
151163
long totalStartTs = System.currentTimeMillis();
164+
AMaasScanOptions options = AMaasScanOptions.builder()
165+
.pml(pmlFlag)
166+
.feedback(feedbackFlag)
167+
.verbose(verbose)
168+
.tagList(tagList)
169+
.activeContent(activeContent)
170+
.build();
152171

153-
scanFilesInSequential(client, listOfFiles, tagList, pmlFlag, feedbackFlag, verbose, digest);
172+
scanFilesInSequential(client, listOfFiles, digest, options);
154173

155174
long totalEndTs = System.currentTimeMillis();
156175
info("*************** Total scan time {0}", totalEndTs - totalStartTs);

‎examples/s3app/S3App.java‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
import com.trend.cloudone.amaas.AMaasClient;
1919
import com.trend.cloudone.amaas.AMaasException;
20+
import com.trend.cloudone.amaas.AMaasScanOptions;
2021

2122
public final class S3App {
2223
private static final Logger logger = Logger.getLogger(S3App.class.getName());
@@ -119,7 +120,14 @@ public static void main(final String[] args) {
119120
AMaasClient client = new AMaasClient(amaasRegion, apikey, timeout);
120121
try {
121122
long totalStartTs = System.currentTimeMillis();
122-
client.scanBuffer(bytes, keyName);
123+
AMaasScanOptions options = AMaasScanOptions.builder()
124+
.pml(true) // Predictive Machine Learning detection
125+
.feedback(true) // Smart Feedback
126+
.verbose(false) // Verbose mode
127+
.activeContent(true) // Active content scanning
128+
.build();
129+
130+
client.scanBuffer(bytes, keyName, true, options);
123131
long totalEndTs = System.currentTimeMillis();
124132
info("*************** Total scan time {0}", totalEndTs - totalStartTs);
125133
} finally {

0 commit comments

Comments
 (0)