The AMaaS Java Client SDK allows developers to build applications that interface with cloud-based Cloud One Antimalware Service (AMaaS), so data and artifacts handled by the applications can be scanned to determine whether they are malicious or not.
This guide shows how to set up your dev environment and project before using the AMaaS Java Client SDK.
- Have Java 8 and above installed in your dev/build environment.
- Trend Cloud One account with a chosen region - for more information, see the Trend Cloud One account document.
- A Trend Cloud One API key - for more information, see the Trend Cloud One API key documentation.
Download the jar from Maven Central Repository. Or for Maven, add this dependency to your pom.xml:
<dependency>
<groupId>com.trend</groupId>
<artifactId>cloud-one-vsapi-sdk</artifactId>
<version>1.0.0</version>
</dependency>To authenticate with the API, you need an Trend Cloud One API key. Sign up for a Trend Cloud One account and follow the instructions on Manage Trend Cloud One API Keys to obtain an API key.
When creating a Trend Cloud One account, choose a region for the account. All of the account data, as well as the security data for the Trend Cloud One security services in the account, is stored in that region. For more information, see the Trend Cloud One regions documentation.
Using AMaaS SDK to scan for malwares involves the following basic steps:
- Creating an AMaaS Client object by specifying preferred Cloud One region where scanning should be done and a valid API key.
- Invoking file scan or buffer scan method to scan the target data.
- Parsing the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
import com.trend.cloudone.amaas.AMaasClient;
public static void main(String[] args) {
try {
// 1. Create an AMaaS Client object and configure it to carry out the scans in Cloud One "us-1" region.
AMaasClient client = new AMaasClient("us-1", "your-api-key");
// 2. Call ScanFile() to scan the content of a file.
String scanResult = client.scanFile(""path-of-file-to-scan"");
if (scanResult != null) {
// 3. Print out the JSON response from ScanFile()
System.out.println("scan result " + scanResult);
}
} catch (AMaasException err) {
info("Exception {0}", err.getMessage());
}
}{
"version": "1.0",
"scanId": "25072030425f4f4d68953177d0628d0b",
"scanResult": 1,
"scanTimestamp": "2022-11-02T00:55:31Z",
"fileName": "EICAR_TEST_FILE-1.exe",
"filePath": "AmspBvtTestSamples/BVT_RightClickScan_DS/unclean/EICAR_TEST_FILE-1.exe",
"foundMalwares": [
{
"fileName": "Eicar.exe",
"malwareName": "Eicar_test_file"
}
]
}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.
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
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 Cloud One regions, e.g. us-1, in-1, de-1, sg-1, au-1, jp-1, gb-1, ca-1, etc. |
| apikey | Your own Cloud 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. |
Return An AmaasClient instance
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 Cloud One regions, e.g. us-1, in-1, de-1, sg-1, au-1, jp-1, gb-1, ca-1, etc. |
| apikey | Your own Cloud One API Key. |
| timeoutInSecs | Timeout to cancel the connection to server in seconds. 0 default to 180 seconds. |
Return An AmaasClient instance
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. |
Return String the scanned result in JSON format.
Scan a buffer for malware and retrieves response data from the API.
Parameters
| Parameter | Description |
|---|---|
| buffer | The byte buffer to scan. |
| identifier | A unique name to identify the buffer. |
Return String the scanned result in JSON format.
The AmaasScanResult has the data elements of the response data that is retrieved from our API. The class has the following private members. There are getter and setter methods for each of the members.
public class AmaasScanResult {
private String version; // API version
private int scanResult; // Number of malwares found. A value of 0 means no malware was found
private String scanId; // ID of the scan
private String scanTimestamp; // Timestamp of the scan in ISO 8601 format
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.
}The MalwareItem contains a detected malware information in the response data that is retrieved from our API. The class has the following private members. There are getter and setter methods for each of the members.
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.
}The AMaasException class is the AMaaS SDK exception class.
public final class AMaasException extends Exception {
private AMaasErrorCode erroCode;
public AMaasException(AMaasErrorCode erroCode, Object... params) {
...
}
}AMaasErrorCode is a enum type containing all the error conditions thrown by the AMaasException class. The error conditions are as follows:
| Enum Type | Error Message Templates | Description |
|---|---|---|
| MSG_ID_ERR_INVALID_REGION | %s is not a supported region. | The region code provided to the AMaasClient constructor is not a valid region. |
| MSG_ID_ERR_MISSING_AUTH | Must provide an API key to use the client. | The API Key provided to the AMaasClient constructor cannot be empty or null. |
| MSG_ID_ERR_KEY_AUTH_FAILED | You are not authenticated. Invalid C1 token or Api Key | The API key is invalid. Please make sure a correct Cloud One Api key or Bearer token is used. |
| MSG_ID_ERR_FILE_NOT_FOUND | Failed to open file. No such file or directory %s. | The given file cannot be found. Please make sure the file exists. |
| MSG_ID_ERR_FILE_NO_PERMISSION | Failed to open file. Permission denied to open %s. | There is a file access permission issue. Please make sure the SDK has read permission to the file. |
| MSG_ID_GRPC_ERROR | Received gRPC status code: %d, msg: %s. | gRpc error was reported with the status code. For details, please refer to published gRPC Status Codes |
| MSG_ID_ERR_UNEXPECTED_INTERRUPT | Unexpected interrupt encountered. | An unexpected interrupt signal was received at the client. |
- 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.