client

README

Trend Vision One™ File Security Go SDK User Guide

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.

Environment

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

Installation

To integrate with our service using the Golang SDK, you need to import the SDK package into your project. Here are the installation steps:

1. Open your Go project or create a new one if you haven't already.

2. 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...
   )
   

3. Use go get to download the SDK package:

   go get github.com/trendmicro/tm-v1-fs-golang-sdk
   

4. You can now start using the SDK in your project.

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.

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.

Initialization

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.

Basic Usage

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:

Scanning a File

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 needed

Scanning a Buffer

data := []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 needed

Note

• Max number of tags is 8. And the length of each tag can't exceed 63.

Additional Functions

The SDK provides additional functions for advanced usage, such as dumping the configuration and cleaning up resources:

Dumping Configuration

You can dump the current SDK configuration for debugging purposes:

configDump := client.DumpConfig()
fmt.Println("SDK Configuration:\n", configDump)

Cleaning Up

Remember to destroy the SDK client when you are done using it to release any allocated resources:

client.Destroy()

Enable PML (Predictive Machine Learning) Detection

You can enable PML detection by calling the SetPMLEnable function:

client.SetPMLEnable()

Enable SPN feedback

You can enable SPN feedback by calling the SetFeedbackEnable function:

client.SetFeedbackEnable()

Golang Client SDK API Reference

func NewClient(key string, region string) (c *AmaasClient, e error)

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) ScanFile(filePath string, tags []string) (resp string, e error)

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

{
  "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"
}

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

---

func (ac *AmaasClient) Destroy()

Frees up internal resources used by client. It should only be invoked after one has finished scanning and no longer needs the client object.

---

func SetLoggingLevel(level LogLevel)

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{})

Usage Examples

As examples, you can find two important files in the tools/ 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.

Usage Instructions for File Security SDK Programs

Prerequisites

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 tools/ directory:

• client
• scanfiles

client

This program is located in the tools/ 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

-tag <string> Specify the tags to be used for scanning, separated by commas

scanfiles

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

-tag <string> Specify the tags to be used for scanning, separated by commas

Proxy Configuration

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.com If 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

Environment Variables

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

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.

• The Destroy() method is NOT thread-safe, so it should only be called upon completion of all the scan routines.

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.

Documentation

Index

• Constants
• Variables
• func ConfigLoggingCallback(f func(level LogLevel, levelStr string, format string, a ...interface{}))
• func MSG(id string) string
• func SetLoggingLevel(level LogLevel)
• type AmaasClient
  • func NewClient(key string, region string) (c *AmaasClient, e error)
  • func NewClientInternal(key string, addr string, useTLS bool) (*AmaasClient, error)
  • func (ac *AmaasClient) ConfigAppName(ctx context.Context) context.Context
  • func (ac *AmaasClient) ConfigAuth(ctx context.Context) context.Context
  • func (ac *AmaasClient) Destroy()
  • func (ac *AmaasClient) DumpConfig() (output string)
  • func (ac *AmaasClient) GetAppName() string
  • func (ac *AmaasClient) GetConnection() *grpc.ClientConn
  • func (ac *AmaasClient) GetTimeoutSetting() int
  • func (ac *AmaasClient) ScanBuffer(buffer []byte, identifier string, tags []string) (resp string, e error)
  • func (ac *AmaasClient) ScanFile(filePath string, tags []string) (resp string, e error)
  • func (ac *AmaasClient) SetAppName(appName string)
  • func (ac *AmaasClient) SetCacheDisable()
  • func (ac *AmaasClient) SetFeedbackEnable()
  • func (ac *AmaasClient) SetPMLEnable()
• type AmaasClientArchiveHandler
• type AmaasClientBufferReader
  • func InitBufferReader(memBuffer []byte, identifier string) (*AmaasClientBufferReader, error)
  • func (reader *AmaasClientBufferReader) Close()
  • func (reader *AmaasClientBufferReader) DataSize() (int64, error)
  • func (reader *AmaasClientBufferReader) Hash(algorithm string) (string, error)
  • func (reader *AmaasClientBufferReader) Identifier() string
  • func (reader *AmaasClientBufferReader) ReadBytes(offset int64, length int32) ([]byte, error)
• type AmaasClientFileReader
  • func InitFileReader(fileName string) (*AmaasClientFileReader, error)
  • func (reader *AmaasClientFileReader) Close()
  • func (reader *AmaasClientFileReader) DataSize() (int64, error)
  • func (reader *AmaasClientFileReader) Hash(algorithm string) (string, error)
  • func (reader *AmaasClientFileReader) Identifier() string
  • func (reader *AmaasClientFileReader) ReadBytes(offset int64, length int32) ([]byte, error)
• type AmaasClientReader
• type LogLevel
• type LoggerCallback

Constants

const (
	AWS_JP_REGION   = "ap-northeast-1"
	AWS_SG_REGION   = "ap-southeast-1"
	AWS_AU_REGION   = "ap-southeast-2"
	AWS_IN_REGION   = "ap-south-1"
	AWS_US_REGION   = "us-east-1"
	AWS_DE_REGION   = "eu-central-1"
	AWS_CA_REGION   = "ca-central-1"
	AWS_GB_REGION   = "eu-west-2"
	C1_JP_REGION    = "jp-1"
	C1_SG_REGION    = "sg-1"
	C1_AU_REGION    = "au-1"
	C1_IN_REGION    = "in-1"
	C1_US_REGION    = "us-1"
	C1_DE_REGION    = "de-1"
	C1_CA_REGION    = "ca-1"
	C1_GB_REGION    = "gb-1"
	C1_TREND_REGION = "trend-us-1"
)

Variables

var AllRegions []string = append(C1Regions, V1Regions...)

var AllValidRegions []string = append(SupportedC1Regions, SupportedV1Regions...)

var C1Regions []string = []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}

var SupportedC1Regions []string = []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}

var SupportedV1Regions []string = []string{AWS_AU_REGION, AWS_DE_REGION, AWS_IN_REGION, AWS_JP_REGION, AWS_SG_REGION, AWS_US_REGION}

var V1Regions []string = []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}

var V1ToC1RegionMapping = map[string]string{
	AWS_AU_REGION: C1_AU_REGION,
	AWS_DE_REGION: C1_DE_REGION,
	AWS_IN_REGION: C1_IN_REGION,
	AWS_JP_REGION: C1_JP_REGION,
	AWS_SG_REGION: C1_SG_REGION,
	AWS_US_REGION: C1_US_REGION,
}

Functions

func ConfigLoggingCallback

func ConfigLoggingCallback(f func(level LogLevel, levelStr string, format string, a ...interface{}))

func MSG

func MSG(id string) string

func SetLoggingLevel

func SetLoggingLevel(level LogLevel)

Types

type AmaasClient

type AmaasClient struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(key string, region string) (c *AmaasClient, e error)

func NewClientInternal

func NewClientInternal(key string, addr string, useTLS bool) (*AmaasClient, error)

func (*AmaasClient) ConfigAppName

func (ac *AmaasClient) ConfigAppName(ctx context.Context) context.Context

func (*AmaasClient) ConfigAuth

func (ac *AmaasClient) ConfigAuth(ctx context.Context) context.Context

func (*AmaasClient) Destroy

func (ac *AmaasClient) Destroy()

func (*AmaasClient) DumpConfig

func (ac *AmaasClient) DumpConfig() (output string)

func (*AmaasClient) GetAppName

func (ac *AmaasClient) GetAppName() string

func (*AmaasClient) GetConnection

func (ac *AmaasClient) GetConnection() *grpc.ClientConn

func (*AmaasClient) GetTimeoutSetting

func (ac *AmaasClient) GetTimeoutSetting() int

func (*AmaasClient) ScanBuffer

func (ac *AmaasClient) ScanBuffer(buffer []byte, identifier string, tags []string) (resp string, e error)

func (*AmaasClient) ScanFile

func (ac *AmaasClient) ScanFile(filePath string, tags []string) (resp string, e error)

func (*AmaasClient) SetAppName

func (ac *AmaasClient) SetAppName(appName string)

func (*AmaasClient) SetCacheDisable

func (ac *AmaasClient) SetCacheDisable()

func (*AmaasClient) SetFeedbackEnable

func (ac *AmaasClient) SetFeedbackEnable()

func (*AmaasClient) SetPMLEnable

func (ac *AmaasClient) SetPMLEnable()

type AmaasClientArchiveHandler

type AmaasClientArchiveHandler struct {
}

type AmaasClientBufferReader

type AmaasClientBufferReader struct {
	// contains filtered or unexported fields
}

func InitBufferReader

func InitBufferReader(memBuffer []byte, identifier string) (*AmaasClientBufferReader, error)

func (*AmaasClientBufferReader) Close

func (reader *AmaasClientBufferReader) Close()

func (*AmaasClientBufferReader) DataSize

func (reader *AmaasClientBufferReader) DataSize() (int64, error)

func (*AmaasClientBufferReader) Hash

func (reader *AmaasClientBufferReader) Hash(algorithm string) (string, error)

return hash value of buffer

func (*AmaasClientBufferReader) Identifier

func (reader *AmaasClientBufferReader) Identifier() string

func (*AmaasClientBufferReader) ReadBytes

func (reader *AmaasClientBufferReader) ReadBytes(offset int64, length int32) ([]byte, error)

type AmaasClientFileReader

type AmaasClientFileReader struct {
	// contains filtered or unexported fields
}

func InitFileReader

func InitFileReader(fileName string) (*AmaasClientFileReader, error)

func (*AmaasClientFileReader) Close

func (reader *AmaasClientFileReader) Close()

func (*AmaasClientFileReader) DataSize

func (reader *AmaasClientFileReader) DataSize() (int64, error)

func (*AmaasClientFileReader) Hash

func (reader *AmaasClientFileReader) Hash(algorithm string) (string, error)

func (*AmaasClientFileReader) Identifier

func (reader *AmaasClientFileReader) Identifier() string

func (*AmaasClientFileReader) ReadBytes

func (reader *AmaasClientFileReader) ReadBytes(offset int64, length int32) ([]byte, error)

type AmaasClientReader

type AmaasClientReader interface {
	Identifier() string
	DataSize() (int64, error)
	ReadBytes(offset int64, length int32) ([]byte, error)
	Close()
	Hash(algorithm string) (string, error)
}

type LogLevel

type LogLevel int

const (
	LogLevelOff     LogLevel = iota
	LogLevelFatal   LogLevel = 1
	LogLevelError   LogLevel = 2
	LogLevelWarning LogLevel = 3
	LogLevelInfo    LogLevel = 4
	LogLevelDebug   LogLevel = 5
)

type LoggerCallback

type LoggerCallback func(level LogLevel, levelStr string, format string, a ...interface{})