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.

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.

• 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.
• A Trend Vision One API key with proper role - for more information, see the Trend Vision 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>file-security-java-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

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.

When obtaining the API Key, ensure that the API Key is associated with the region that you plan to use. It is important to note that Trend Vision One API Keys are associated with different regions, please refer to the region flag below to obtain a better understanding of the valid regions associated with the respective API Key.

If you plan on using a Trend Vision One region, be sure to pass in region parameter when running custom program with File Security SDK to specify the region of that API key and to ensure you have proper authorization. The list of supported Trend Vision One regions can be found at API Reference section below.

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.

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.

import com.trend.fs.AMaasClient;

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");

        // 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.

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

Parameters

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

Return An AmaasClient instance

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

Parameters

Return String the scanned result in JSON format.

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

Parameters

Return String the scanned result in JSON format.

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

Parameters

Return String the scanned result in JSON format.

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

Parameters

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:

• 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.