diff --git a/README.md b/README.md index 0df1c6a..2545b52 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ public static void main(String[] args) { "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" } @@ -175,93 +175,93 @@ When active content is detected, the scan result will include a type field with ## Java SDK API Reference -### ```AmaasClient``` +### `AmaasClient` The AmaasClient class is the main class of the SDK and provides methods to use the AMaaS scanning services. -#### ```public AMaasClient(final String region, final String host, final String apiKey, final long timeoutInSecs, final boolean enabledTLS, final string caCert) throws AMaasException``` +#### `public AMaasClient(final String region, final String host, final String apiKey, final long timeoutInSecs, final boolean enabledTLS, final string caCert) 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`, `ap-south-1`, `me-central-1`, etc. If host is given, region will be ignored. | -| host | The host ip address of self hosted AMaaS scanner. Ignore if to use Trend AMaaS service | -| apikey | Your own Vision One API Key. | -| 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' | -| caCert | File path of the CA certificate for hosted AMaaS Scanner server. null if using Trend AMaaS service. | +| 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`, `ap-south-1`, `me-central-1`,`eu-west-2`,`ca-central-1`, etc. If host is given, region will be ignored. | +| host | The host ip address of self hosted AMaaS scanner. Ignore if to use Trend AMaaS service | +| apikey | Your own Vision One API Key. | +| 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' | +| caCert | File path of the CA certificate for hosted AMaaS Scanner server. null if using Trend AMaaS service. | **_Return_** An AmaasClient instance -#### ```public AMaasClient(final String region, final String apiKey, final 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`, `ap-south-1`, `me-central-1`, etc. | -| apikey | Your own Vision One API Key. | -| timeoutInSecs | Timeout to cancel the connection to server in seconds. Valid value is 0, 1, 2, ... ; default to 300 seconds. | +| 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`, `ap-south-1`, `me-central-1`,`eu-west-2`,`ca-central-1` ,etc. | +| apikey | Your own Vision One API Key. | +| 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 scanRun(final AMaasReader reader, final AMaasScanOptions options) throws AMaasException``` +#### `public String scanRun(final AMaasReader reader, final AMaasScanOptions options) 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. | -| options | Scan options containing configuration for the scan operation (PML, feedback, verbose, activeContent, tags). | +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| 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. **_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 scanFile(final String fileName, final boolean digest, final AMaasScanOptions options) throws AMaasException``` +#### `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. | -| 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). | +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------- | +| fileName | The name of the file with path of directory containing the file to scan. | +| 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 boolean digest, final AMaasScanOptions options) 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. **_Parameters_** -| Parameter | Description | -| ------------- | ----------------------------------------------------------------------------------------- | -| 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). | +| Parameter | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------- | +| 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. --- -### ```AMaasScanOptions``` +### `AMaasScanOptions` The AMaasScanOptions class provides a convenient way to configure scan parameters using the builder pattern. This class encapsulates all scan-related configuration options. @@ -283,28 +283,28 @@ AMaasScanOptions customOptions = AMaasScanOptions.builder() **_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. | +| 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. | +| 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. | --- -### ```AmaasScanResult``` +### `AmaasScanResult` 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. @@ -324,7 +324,7 @@ public class AmaasScanResult { --- -### ```MalwareItem``` +### `MalwareItem` 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. @@ -338,7 +338,7 @@ public class MalwareItem { } ``` -### ```AMaasScanResultVerbose``` +### `AMaasScanResultVerbose` The AMaasScanResultVerbose has the data elements of the response data in verbose mode that is retrieved from our API. The class has the following private members. There are getter and setter methods for each of the members. See javaDoc for the class of each data element. @@ -365,7 +365,7 @@ public class AMaasScanResultVerbose { --- -### ```AMaasException``` +### `AMaasException` The AMaasException class is the AMaaS SDK exception class. @@ -381,19 +381,19 @@ public final class AMaasException extends Exception { --- -### ```AMaasErrorCode``` +### `AMaasErrorCode` 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 Vision One Api key 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. | +| 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 Vision One Api key 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](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) | -| MSG_ID_ERR_UNEXPECTED_INTERRUPT | Unexpected interrupt encountered. | An unexpected interrupt signal was received at the client. | +| MSG_ID_ERR_UNEXPECTED_INTERRUPT | Unexpected interrupt encountered. | An unexpected interrupt signal was received at the client. | ## Thread Safety @@ -418,23 +418,25 @@ The File Security Java SDK supports HTTP and SOCKS5 proxy configurations through ### Supported Environment Variables -| Environment Variable | Required/Optional | Description | -| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `HTTP_PROXY` | Optional | HTTP proxy URL for HTTP connections (e.g., `http://proxy.example.com:8080`) | -| `HTTPS_PROXY` | Optional | Proxy URL for HTTPS connections (e.g., `https://proxy.example.com:8443` or `socks5://socks.example.com:1080`) | -| `NO_PROXY` | Optional | Comma-separated list of host names to bypass proxy (e.g., `localhost,127.0.0.1,*.local`). Use `*` to bypass proxy for all hosts | -| `PROXY_USER` | Optional | Username for proxy authentication (used with `Proxy-Authorization` header) | -| `PROXY_PASS` | Optional | Password for proxy authentication (used only when `PROXY_USER` is configured) | +| Environment Variable | Required/Optional | Description | +| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `HTTP_PROXY` | Optional | HTTP proxy URL for HTTP connections (e.g., `http://proxy.example.com:8080`) | +| `HTTPS_PROXY` | Optional | Proxy URL for HTTPS connections (e.g., `https://proxy.example.com:8443` or `socks5://socks.example.com:1080`) | +| `NO_PROXY` | Optional | Comma-separated list of host names to bypass proxy (e.g., `localhost,127.0.0.1,*.local`). Use `*` to bypass proxy for all hosts | +| `PROXY_USER` | Optional | Username for proxy authentication (used with `Proxy-Authorization` header) | +| `PROXY_PASS` | Optional | Password for proxy authentication (used only when `PROXY_USER` is configured) | ### Proxy Configuration Examples #### Basic HTTP Proxy + ```bash export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 ``` #### SOCKS5 Proxy + ```bash export HTTPS_PROXY=socks5://socks-proxy.company.com:1080 ``` @@ -453,6 +455,7 @@ try { ``` #### Proxy with Authentication + ```bash export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=https://secure-proxy.company.com:8443 @@ -461,12 +464,14 @@ export PROXY_PASS=password ``` #### Bypassing Proxy for Specific Hosts + ```bash export HTTP_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,127.0.0.1,*.internal.company.com ``` #### Disabling Proxy for All Connections + ```bash export NO_PROXY=* ``` diff --git a/pom.xml b/pom.xml index 0571a5c..feaa0eb 100644 --- a/pom.xml +++ b/pom.xml @@ -96,7 +96,7 @@ io.netty netty-all - 4.2.6.Final + 4.2.9.Final io.grpc diff --git a/src/main/java/com/trend/cloudone/amaas/AMaasRegion.java b/src/main/java/com/trend/cloudone/amaas/AMaasRegion.java index f87ee31..615764e 100644 --- a/src/main/java/com/trend/cloudone/amaas/AMaasRegion.java +++ b/src/main/java/com/trend/cloudone/amaas/AMaasRegion.java @@ -38,7 +38,7 @@ final class AMaasRegion { static final List C1_REGIONS = Arrays.asList(new String[]{C1_AU_REGION, C1_CA_REGION, C1_DE_REGION, C1_GB_REGION, C1_IN_REGION, C1_JP_REGION, C1_SG_REGION, C1_US_REGION, C1_TREND_REGION}); static final List V1_REGIONS = Arrays.asList(new String[]{AWS_AU_REGION, AWS_CA_REGION, AWS_DE_REGION, AWS_GB_REGION, AWS_IN_REGION, AWS_JP_REGION, AWS_SG_REGION, AWS_US_REGION, AWS_AE_REGION}); - static final List SUPPORTED_V1_REGIONS = Arrays.asList(new String[]{AWS_AU_REGION, AWS_DE_REGION, AWS_JP_REGION, AWS_SG_REGION, AWS_US_REGION, AWS_IN_REGION, AWS_AE_REGION}); + static final List SUPPORTED_V1_REGIONS = Arrays.asList(new String[]{AWS_AU_REGION, AWS_DE_REGION, AWS_JP_REGION, AWS_SG_REGION, AWS_US_REGION, AWS_IN_REGION, AWS_AE_REGION, AWS_CA_REGION, AWS_GB_REGION}); static final List SUPPORTED_C1_REGIONS = Arrays.asList(new String[]{C1_AU_REGION, C1_CA_REGION, C1_DE_REGION, C1_GB_REGION, C1_IN_REGION, C1_JP_REGION, C1_SG_REGION, C1_US_REGION}); static final Map V1_TO_C1_REGION_MAPPING = new HashMap() { @@ -50,6 +50,8 @@ final class AMaasRegion { put(AWS_SG_REGION, C1_SG_REGION); put(AWS_US_REGION, C1_US_REGION); put(AWS_AE_REGION, C1_AE_REGION); + put(AWS_CA_REGION, C1_CA_REGION); + put(AWS_GB_REGION, C1_GB_REGION); } }; diff --git a/src/test/java/com/trend/cloudone/amaas/AMaasRegionTest.java b/src/test/java/com/trend/cloudone/amaas/AMaasRegionTest.java index 9d9909b..0228e66 100644 --- a/src/test/java/com/trend/cloudone/amaas/AMaasRegionTest.java +++ b/src/test/java/com/trend/cloudone/amaas/AMaasRegionTest.java @@ -16,6 +16,12 @@ public void testGetHostForRegion() { region = AMaasRegion.getServiceFqdn("me-central-1"); assertEquals("antimalware.ae-1.cloudone.trendmicro.com", region); + + region = AMaasRegion.getServiceFqdn("ca-central-1"); + assertEquals("antimalware.ca-1.cloudone.trendmicro.com", region); + + region = AMaasRegion.getServiceFqdn("eu-west-2"); + assertEquals("antimalware.gb-1.cloudone.trendmicro.com", region); }