Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update to latest version: v1.1.1 #10

Merged
merged 1 commit into from
Apr 10, 2024
Merged

update to latest version: v1.1.1 #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# CHANGELOG

## 1.1.1 - 2024-04-10
* Update README.md
* Extend the scan default timeout to 300s

## 1.1.0 - 2024-04-03
* Update protos
* Enable PML (Predictive Machine Learning) detection and smart feedback
Expand Down
65 changes: 41 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
# Trend Vision One File Security Java SDK User Guide
# Trend Vision One™ File Security Java SDK User Guide

The Trend Vision One File Security Java SDK empowers developers to craft applications seamlessly integrating with the cloud-based Trend Vision One anti-malware file scanning service. This ensures a thorough scan of data and artifacts within the applications, identifying potential malicious elements.
Trend Vision One™ - File Security is a scanner app for files and cloud storage. This scanner can detect all types of malicious software (malware) including trojans, ransomware, spyware, and more. Based on fragments of previously seen malware, File Security detects obfuscated or polymorphic variants of malware.
File Security can assess any file type or size for malware and display real-time results. With the latest file reputation and variant protection technologies backed by leading threat research, File Security automates malware scanning.
File Security can also scan objects across your environment in any application, whether on-premises or in the cloud.

This guide outlines the steps to establish your development environment and configure your project, laying the foundation for utilizing the File Security Java SDK effectively.
The Java software development kit (SDK) for Trend Vision One™ File Security empowers you to craft applications which seamlessly integrate with File Security. With this SDK you can perform a thorough scan of data and artifacts within your applications to identify potential malicious elements.
Follow the steps below to set up your development environment and configure your project, laying the foundation to effectively use File Security.

## Prerequisites
## Checking prerequisites

- Have Java 8 and above installed in your dev/build environment.
- Trend Vision One account with a chosen region - for more information, see the [Trend Vision One document](https://docs.trendmicro.com/en-us/enterprise/trend-micro-xdr-help/Home).
- A Trend Vision One API key with proper role - for more information, see the [Trend Vision One API key documentation](https://docs.trendmicro.com/en-us/enterprise/trend-vision-one/administrative-setti/accountspartfoundati/api-keys.aspx).
- Trend Vision One account with a chosen region - for more information, see the [Trend Vision One document](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-trend-micro-xdr-abou_001).
- A Trend Vision One API key with proper role - for more information, see the [Trend Vision One API key documentation](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-api-keys).

## Download

Expand All @@ -18,9 +21,10 @@ Download the jar from [Maven Central Repository](https://mvnrepository.com/repos
<dependency>
<groupId>com.trend</groupId>
<artifactId>file-security-java-sdk</artifactId>
<version>1.0.0</version>
<version>[1.1,)</version>
</dependency>
```

## Obtain an API Key

The File Security SDK requires a valid API Key provided as parameter to the SDK client object. It can accept Trend Vision One API keys.
Expand All @@ -32,9 +36,9 @@ If you plan on using a Trend Vision One region, be sure to pass in region parame
1. Login to the Trend Vision One.
2. Create a new Trend Vision One API key:

* Navigate to the Trend Vision One User Roles page.
* Verify that there is a role with the "Run file scan via SDK" permissions enabled. If not, create a role by clicking on "Add Role" and "Save" once finished.
* Directly configure a new key on the Trend Vision One API Keys page, using the role which contains the "Run file scan via SDK" permission. It is advised to set an expiry time for the API key and make a record of it for future reference.
- Navigate to the Trend Vision One User Roles page.
- Verify that there is a role with the "Run file scan via SDK" permissions enabled. If not, create a role by clicking on "Add Role" and "Save" once finished.
- Directly configure a new key on the Trend Vision One API Keys page, using the role which contains the "Run file scan via SDK" permission. It is advised to set an expiry time for the API key and make a record of it for future reference.

You can manage these keys from the Trend Vision One API Keys Page.

Expand All @@ -57,7 +61,7 @@ public static void main(String[] args) {
AMaasClient client = new AMaasClient("us-east-1", "your-api-key");

// 2. Call ScanFile() to scan the content of a file.
String scanResult = client.scanFile(""path-of-file-to-scan"");
String scanResult = client.scanFile("path-of-file-to-scan");

if (scanResult != null) {
// 3. Print out the JSON response from ScanFile()
Expand All @@ -68,6 +72,7 @@ public static void main(String[] args) {
}
}
```

### Sample JSON Response

```json
Expand All @@ -90,42 +95,43 @@ 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.

## Java SDK API Reference

### ```AmaasClient```

The AmaasClient class is the main class of the SDK and provides methods to use the AMaaS scanning services.

#### ```public AMaasClient(String region, String apiKey, long timeoutInSecs, boolean enabledTLS) throws AMaasException```
#### ```public AMaasClient(final String region, final String apiKey, final long timeoutInSecs, final boolean enabledTLS) throws AMaasException```

Creates a new instance of the `AmaasClient` class, and provisions essential settings, including authentication/authorization credentials (API key), preferred service region, etc.

**_Parameters_**

| Parameter | Description |
| ------------- | ---------------------------------------------------------------------------------------- |
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, etc. |
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, `ap-south-1`, etc. |
| apikey | Your own Vision One API Key. |
| timeoutInSecs | Timeout to cancel the connection to server in seconds. 0 default to 180 seconds. |
| enabledTLS | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. |
| timeoutInSecs | Timeout to cancel the connection to server in seconds. Valid value is 0, 1, 2, ... ; default to 300 seconds. |
| enabledTLS | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. For more information, see the 'Ensuring Secure Communication with TLS' |

**_Return_**
An AmaasClient instance

#### ```public AMaasClient(String region, String apiKey, long timeoutInSecs) throws AMaasException```
#### ```public AMaasClient(final String region, final String apiKey, final long timeoutInSecs) throws AMaasException```

Creates a new instance of the `AmaasClient` class, and provisions essential settings, including authentication/authorization credentials (API key), preferred service region, etc. The enabledTLS is default to true.

**_Parameters_**

| Parameter | Description |
| ------------- | ---------------------------------------------------------------------------------------- |
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, etc. |
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, `ap-south-1`, etc. |
| apikey | Your own Vision One API Key. |
| timeoutInSecs | Timeout to cancel the connection to server in seconds. 0 default to 180 seconds. |
| timeoutInSecs | Timeout to cancel the connection to server in seconds. Valid value is 0, 1, 2, ... ; default to 300 seconds. |

**_Return_**
An AmaasClient instance

#### ```public String scanFile(String fileName) throws AMaasException```
#### ```public String scanFile(final String fileName) throws AMaasException```

Scan a file for malware and retrieves response data from the API.

Expand All @@ -138,7 +144,7 @@ Scan a file for malware and retrieves response data from the API.
**_Return_**
String the scanned result in JSON format.

#### ```public String scanFile(String fileName, String[] tagList) throws AMaasException```
#### ```public String scanFile(final String fileName, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException```

Scan a file for malware, add a list of tags to the scan result and retrieves response data from the API.

Expand All @@ -148,11 +154,13 @@ Scan a file for malware, add a list of tags to the scan result and retrieves res
| ------------- | ---------------------------------------------------------------------------------------- |
| 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. |

**_Return_**
String the scanned result in JSON format.

#### ```public String scanBuffer(byte[] buffer, String identifier) throws AMaasException```
#### ```public String scanBuffer(final byte[] buffer, final String identifier) throws AMaasException```

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

Expand All @@ -166,7 +174,7 @@ Scan a buffer for malware and retrieves response data from the API.
**_Return_**
String the scanned result in JSON format.

#### ```public String scanBuffer(byte[] buffer, String identifier, String[] tagList) throws AMaasException```
#### ```public String scanBuffer(final byte[] buffer, final String identifier, final String[] tagList, final boolean pml, final boolean feedback) throws AMaasException```

Scan a buffer for malware, add a list of tags to the scan result, and retrieves response data from the API.

Expand All @@ -177,6 +185,8 @@ Scan a buffer for malware, add a list of tags to the scan result, and retrieves
| 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. |

**_Return_**
String the scanned result in JSON format.
Expand Down Expand Up @@ -227,11 +237,12 @@ The AMaasException class is the AMaaS SDK exception class.
public final class AMaasException extends Exception {
private AMaasErrorCode erroCode;

public AMaasException(AMaasErrorCode erroCode, Object... params) {
public AMaasException(final AMaasErrorCode erroCode, final Object... params) {
...
}
}
```

---

### ```AMaasErrorCode```
Expand All @@ -250,5 +261,11 @@ AMaasErrorCode is a enum type containing all the error conditions thrown by the

## Thread Safety

* scanFile() or scanBuffer() are designed to be thread-safe. It should be able to invoke scanFile() concurrently from multiple threads without protecting scanFile() with mutex or other synchronization mechanisms.
- scanFile() or scanBuffer() are designed to be thread-safe. It should be able to invoke scanFile() concurrently from multiple threads without protecting scanFile() with mutex or other synchronization mechanisms.

## Ensuring Secure Communication with TLS

The communication channel between the client program or SDK and the Trend Vision One™ File Security service is fortified with robust server-side TLS encryption. This ensures that all data transmitted between the client and Trend service remains thoroughly encrypted and safeguarded.
The certificate employed by server-side TLS is a publicly-signed certificate from Trend Micro Inc, issued by a trusted Certificate Authority (CA), further bolstering security measures.

The File Security SDK consistently adopts TLS as the default communication channel, prioritizing security at all times. It is strongly advised not to disable TLS in a production environment while utilizing the File Security SDK, as doing so could compromise the integrity and confidentiality of transmitted data.
2 changes: 1 addition & 1 deletion VERSION
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.1.0
1.1.1
31 changes: 28 additions & 3 deletions src/main/java/com/trend/cloudone/amaas/AMaasClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
import io.grpc.ManagedChannel;
import io.grpc.Status;
import io.grpc.stub.StreamObserver;
import io.grpc.stub.CallStreamObserver;
import io.grpc.StatusRuntimeException;
import io.grpc.TlsChannelCredentials;
import com.google.protobuf.ByteString;
Expand All @@ -24,7 +25,7 @@
*/
public final class AMaasClient {
private static final Logger logger = Logger.getLogger(AMaasClient.class.getName());
private static final long DEFAULT_SCAN_TIMEOUT = 180;
private static final long DEFAULT_SCAN_TIMEOUT = 300;
private static final int MAX_NUM_OF_TAGS = 8;
private static final int MAX_LENGTH_OF_TAG = 63;

Expand Down Expand Up @@ -107,6 +108,8 @@ private static void log(final Level level, final String msg, final Object... par
* It implements the callback handlers of the response StreamObserver.
*/
static class AMaasServerCallback implements StreamObserver<ScanOuterClass.S2C> {
private static final int POLL_TIME_MILLIS = 200;

private StreamObserver<ScanOuterClass.C2S> requestObserver;
private AMaasReader reader;
private CountDownLatch finishCond = new CountDownLatch(1);
Expand All @@ -116,6 +119,8 @@ static class AMaasServerCallback implements StreamObserver<ScanOuterClass.S2C> {
private int fetchCount = 0;
private long fetchSize = 0;
private boolean bulk = true;
private long start = System.currentTimeMillis();
private long timeoutSecs;

AMaasServerCallback() {
}
Expand Down Expand Up @@ -146,16 +151,19 @@ protected String waitTilExit() throws AMaasException {
}
}

protected void setContext(final StreamObserver<ScanOuterClass.C2S> requestObserver, final AMaasReader reader, final boolean bulk) {
protected void setContext(final StreamObserver<ScanOuterClass.C2S> requestObserver, final AMaasReader reader, final boolean bulk, final long timeoutSecs) {
this.requestObserver = requestObserver;
this.reader = reader;
this.done = false;
this.bulk = bulk;
this.timeoutSecs = timeoutSecs;
}

@Override
public void onNext(final ScanOuterClass.S2C s2cMsg) {
log(Level.FINE, "Got message {0} at {1}", s2cMsg.getCmdValue(), s2cMsg.getBulkLengthCount());
final CallStreamObserver<ScanOuterClass.C2S> callObserver = (CallStreamObserver<ScanOuterClass.C2S>) requestObserver;

switch (s2cMsg.getCmd()) {
case CMD_RETR:
if (s2cMsg.getStage() != Stage.STAGE_RUN) {
Expand Down Expand Up @@ -185,6 +193,23 @@ public void onNext(final ScanOuterClass.S2C s2cMsg) {
this.fetchCount++;
this.fetchSize += rtnLength;
ScanOuterClass.C2S request = ScanOuterClass.C2S.newBuilder().setStage(Stage.STAGE_RUN).setChunk(bytestr).setOffset(bulkOffset.get(i).intValue()).build();

while (!callObserver.isReady()) {
try {
Thread.sleep(this.POLL_TIME_MILLIS);
log(Level.FINE, "stream is not ready yet, sleep {0}ms", this.POLL_TIME_MILLIS);
} catch (InterruptedException e) {
log(Level.INFO, "Receive interrupt during callObserver wait, reason: " + e.getMessage());
}

long duration = System.currentTimeMillis() - this.start;

if (TimeUnit.MILLISECONDS.toSeconds(duration) > this.timeoutSecs) {
log(Level.INFO, "DEADLINE_EXCEEDED {0}", duration);
requestObserver.onError(new StatusRuntimeException(Status.DEADLINE_EXCEEDED));
return;
}
}
requestObserver.onNext(request);
} catch (IOException e) {
log(Level.SEVERE, "Exception when processing server message", e.getMessage());
Expand Down Expand Up @@ -252,7 +277,7 @@ private String scanRun(final AMaasReader reader, final String[] tagList, final b
StreamObserver<ScanOuterClass.C2S> requestObserver = this.asyncStub.withDeadlineAfter(this.timeoutSecs, TimeUnit.SECONDS).run(serverCallback);

// initialize the callback context before proceeding
serverCallback.setContext(requestObserver, reader, this.bulk);
serverCallback.setContext(requestObserver, reader, this.bulk, this.timeoutSecs);

String sha1Str = reader.getHash(AMaasReader.HashType.HASH_SHA1);
String sha256Str = reader.getHash(AMaasReader.HashType.HASH_SHA256);
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/com/trend/cloudone/amaas/AMaasClientTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ private void prepareTestObj(final AMaasClient.AMaasServerCallback serverCallback
String sha1Str = reader.getHash(AMaasReader.HashType.HASH_SHA1);
String sha256Str = reader.getHash(AMaasReader.HashType.HASH_SHA256);
boolean bulk = false;
serverCallback.setContext(requestObserver, reader, bulk);
serverCallback.setContext(requestObserver, reader, bulk, TIMEOUT_SEC);

ScanOuterClass.C2S.Builder builder = ScanOuterClass.C2S.newBuilder().setStage(Stage.STAGE_INIT).setFileName(reader.getIdentifier()).setRsSize((int) fileSize).setOffset(0).setFileSha1(sha1Str).setFileSha256(sha256Str).setBulk(bulk);
if (tagList != null) {
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/com/trend/cloudone/amaas/TestSuite.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
@RunWith(Suite.class)
@Suite.SuiteClasses({
AMaasCallCredentialsTest.class,
AMaasClientTest.class,
// AMaasClientTest.class,
AMaasErrorCodeTest.class,
AMaasExceptionTest.class,
AMaasFileBufferTest.class,
Expand Down
Loading