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.
The Go 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.
- Golang 1.19 or newer
- Trend Vision One account with a chosen region - for more information, see the Trend Vision One documentation.
- A Trend Vision One API key with proper role - for more information, see the Trend Vision One API key documentation.
To integrate with our service using the Golang SDK, you need to import the SDK package into your project. Here are the installation steps:
-
Open your Go project or create a new one if you haven't already.
-
Import the SDK package into your project by adding the following import statement:
import ( "github.com/trendmicro/tm-v1-fs-golang-sdk/client" // Other imports... )
-
Use
go getto download the SDK package:go get github.com/trendmicro/tm-v1-fs-golang-sdk
-
You can now start using the SDK in your project.
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.
- Login to the Trend Vision One.
- 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.
Before using the SDK to interact with our service, you need to initialize it with your API key or token and specify the region you want to connect to. Here's how to initialize the SDK:
apiKey := "YOUR_API_KEY_OR_TOKEN"
region := "YOUR_REGION"
client, err := client.NewClient(apiKey, region)
if err != nil {
// Handle initialization error
panic(err)
}Replace "YOUR_API_KEY_OR_TOKEN" and "YOUR_REGION" with your actual API key or token and the desired region.
Once you have initialized the SDK, you can start using it to interact with our service. Here are some basic examples of how to use the SDK:
filePath := "path/to/your/file.txt"
tags := []string{"tag1", "tag2"}
response, err := client.ScanFile(filePath, tags)
if err != nil {
// Handle scanning error
panic(err)
}
// Use the 'response' as neededdata := []byte("Your data to be scanned")
identifier := "UniqueIdentifier"
tags := []string{"tag1", "tag2"}
response, err := client.ScanBuffer(data, identifier, tags)
if err != nil {
// Handle scanning error
panic(err)
}
// Use the 'response' as neededNote
- Max number of tags is 8. And the length of each tag can't exceed 63.
The SDK provides additional functions for advanced usage, such as dumping the configuration and cleaning up resources:
You can dump the current SDK configuration for debugging purposes:
configDump := client.DumpConfig()
fmt.Println("SDK Configuration:\n", configDump)Remember to destroy the SDK client when you are done using it to release any allocated resources:
client.Destroy()You can enable PML detection by calling the SetPMLEnable function:
client.SetPMLEnable()You can enable SPN feedback by calling the SetFeedbackEnable function:
client.SetFeedbackEnable()You can enable verbose scan result by calling the SetVerboseEnable function:
client.SetVerboseEnable()You can disable digest calculation by calling the SetDigestDisable function:
client.SetDigestDisable()Creates a new instance of the client object, and provisions essential settings, including authentication/authorization credentials (API key), preferred service region, etc.
Parameters
| Parameter | Description |
|---|---|
| key (string) | A valid API key must be provided if the environment variable TM_AM_AUTH_KEY is not set. |
| region (string) | The region you obtained your api key. Value provided must be one of the Vision One regions: us-east-1, eu-central-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-south-1 |
Return values
| Parameter | Description |
|---|---|
| c (*AmaasClient) | Pointer to an client object. Nil if error encountered |
| e (error) | Nil if no error encountered; non-nil otherwise. |
Errors Conditions
- Invalid authentication
- Invalid region
func (ac *AmaasClient) ScanBuffer(buffer []byte, identifier string, tags []string) (resp string, e error)
Submit content of a file or buffer to be scanned.
Parameters
| Parameter | Description |
|---|---|
| filePath (string) | Path of the file to scan |
| buffer ([]byte) | Buffer containing the data to scan |
| identifier (string) | A caller-chosen string to associate with the scan that will be returned in JSON response as part of fileName name/value; can be empty |
| tags ([]string) | Tags to be used for scanning |
Return values
| Parameter | Description |
|---|---|
| resp (string) | JSON-formatted response describing the scan result |
| e (error) | Nil if no error encountered; non-nil otherwise. |
Sample JSON response
Concise Format
{
"scannerVersion":"1.0.0-27",
"schemaVersion":"1.0.0",
"scanResult": 1,
"scanId": "25072030425f4f4d68953177d0628d0b",
"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"
}
],
"fileSHA1":"fc7042d1d8bbe655ab950355f86a81ded9ee4903",
"fileSHA256":"1b9f8773919a1770fec35e2988650fde3adaae81a3ac2ad77b67cafd013afcdc"
}Verbose Format
{
"scanType": "sdk",
"objectType": "file",
"timestamp": {
"start": "2024-07-05T20:01:21.064Z",
"end": "2024-07-05T20:01:21.069Z"
},
"schemaVersion": "1.0.0",
"scannerVersion": "1.0.0-59",
"fileName": "eicar.com",
"rsSize": 68,
"scanId": "40d7a38e-a1d3-400b-a09c-7aa9cd62658f",
"accountId": "",
"result": {
"atse": {
"elapsedTime": 4693,
"fileType": 5,
"fileSubType": 0,
"version": {
"engine": "23.57.0-1002",
"lptvpn": 385,
"ssaptn": 731,
"tmblack": 253,
"tmwhite": 239,
"macvpn": 914
},
"malwareCount": 1,
"malware": [
{
"name": "Eicar_test_file",
"fileName": "eicar.com",
"type": "",
"fileType": 5,
"fileSubType": 0,
"fileTypeName": "COM",
"fileSubTypeName": "VSDT_COM_DOS"
}
],
"error": null,
"fileTypeName": "COM",
"fileSubTypeName": "VSDT_COM_DOS"
}
},
"fileSHA1": "3395856ce81f2b7382dee72602f798b642f14140",
"fileSHA256": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
"appName": "V1FS"
}When malicious content is detected in the scanned object, scanResult will show a non-zero value. Otherwise, the value will be 0. 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.
Errors Conditions
- Invalid authentication
- Invalid path specified
- Request timed out (deadline exceeded)
- Incompatible client used
- Service unreachable
- Client not ready for operation
Frees up internal resources used by client. It should only be invoked after one has finished scanning and no longer needs the client object.
For configuring the SDK's active logging level. The change is applied globally to all client instances. Default level is LogLevelOff, corresponding to all logging disabled. If logging is enabled, unless custom logging is configured using ConfigLoggingCallback() logs will be written to stdout.
Parameters
| Parameter | Description |
|---|---|
| level (LogLevel) | Valid values are LogLevelOff, LogLevelFatal, LogLevelError, LogLevelWarning, LogLevelInfo, and LogLevelDebug; default level is LogLevelOff |
func ConfigLoggingCallback(f func(level LogLevel, levelStr string, format string, a ...interface{}))
For setting up custom logging by provisioning the SDK with a custom callback function that is invoked whether the SDK wants to record a log.
Parameters
| Parameter | Description |
|---|---|
| f (function) | A function with the prototype func(level LogLevel, levelStr string, format string, a ...interface{}) |
As examples, you can find two important files in the examples/ directory of the SDK package:
client.go: This file contains the main client initialization logic and functions for scanning a single file.
scanfiles.go: This file provides examples of how to scan multiple files using the SDK.
You can refer to these files for a deeper understanding of how to integrate and use the SDK with our service.
Build the client tools requires the following:
Execute make build in the root directory to build the client tools.
The build process will produce the following inside the examples/ directory:
- client
- scanfiles
This program is located in the examples/ folder. It supports the gRPC-based server.
client [command-line flags]
The following flags are supported:
-tls
Specify to enable server authentication by client for gRPC. TLS should always be enabled when connecting to the File Security service. For more information, see the 'Ensuring Secure Communication with TLS' section.
-region <string>
Specify the region to connect to for gRPC
-addr <string>
the address to connect to for gRPC (default "localhost:50051")
-filename <string>
Path of file to scan
-apikey <string>
API key for service authentication if authentication is enabled
-pml
Specify to enable PML (Predictive Machine Learning) detection
-feedback
Specify to enable SPN feedback
-verbose
Specify to enable verbose scan result
-tag <string>
Specify the tags to be used for scanning, separated by commas
-digest=false
Specify to disable digest calculation
This is another program that uses the gRPC client library to communicate with our server. Depending on whether or not the -good flag is specified, and the scan result returned from the scan, the program will output result that shows the testing was successful or not.
If -good flag is specified, it indicates the files to be scanned are non-malicious. So if our server scan indicates a file is malicious, then the program will output result indicating the testing failed, for example.
The following flags are supported by the program:
-path <string>
Directory or file to scan. This flag must be specified in all scenarios.
-good
Specify if scanning good/non-malicious files.
-parallel
Specify if scanning of multiple files should be carried out simultaneously instead of sequentially.
-tls
Specify to enable server authentication by client for gRPC. TLS should always be enabled when connecting to the File Security service. For more information, see the 'Ensuring Secure Communication with TLS' section.
-region <string>
Specify the region to connect to for gRPC
-addr <string>
The address to connect to for gRPC (default "localhost:50051")
-apikey <string>
API key for service authentication if authentication is enabled
-pml
Specify to enable PML (Predictive Machine Learning) detection
-feedback
Specify to enable SPN feedback
-verbose
Specify to enable verbose scan result
-tag <string>
Specify the tags to be used for scanning, separated by commas
-digest=false
Specify to disable digest calculation
The cli tool loads the proxy configuration from the following set of optional environment variables
| Environment Variable | Required/Optional | Description |
|---|---|---|
NO_PROXY |
Optional | Add the endpoints to the comma-separated list of host names if you want to skip proxy settings. Note: only an asterisk, '*' matches all hosts |
HTTP_PROXY |
Optional | http://proxy.example.com |
HTTPS_PROXY |
Optional | https://proxy.example.comIf the proxy server is a SOCKS5 proxy, you must specify the SOCKS5 protocol in the URL as socks5://socks_proxy.example.com |
PROXY_USER |
Optional | Optional username for authentication header used in Proxy-Authorization |
PROXY_PASS |
Optional | Optional password for authentication header used in Proxy-Authorization, used only when PROXY_USER is configured |
The following environment variables are supported by Golang Client SDK and can be used in lieu of values specified as function arguments.
For example, the API key can be specified using the TM_AM_AUTH_KEY environment variable instead of hardcoded into the application.
| Variable Name | Description & Purpose | Valid Values |
|---|---|---|
TM_AM_SCAN_TIMEOUT_SECS |
Specify, in number of seconds, to override the default scan timeout period | 0, 1, 2, ... ; default=300 |
TM_AM_AUTH_KEY |
Can be used to specify the authorization key; overrides function call value | empty or string |
-
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.
-
The Destroy() method is NOT thread-safe, so it should only be called upon completion of all the scan routines.
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.
For customers who need to enable TLS channel encryption without verifying the provided CA certificate, the TM_AM_DISABLE_CERT_VERIFY environment variable can be set. However, this option is only recommended for use in testing environments.
When TM_AM_DISABLE_CERT_VERIFY is set to 1, certificate verification is disabled. By default, the certificate will be verified.