client

package module
v1.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 4, 2025 License: MIT Imports: 27 Imported by: 1

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

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
Scanning with AmaasClientReader
type CustomReader struct {
    ...
}

func newCustomReader() *CustomReader {
    ...
}

func (r *CustomReader) Identifier() string {
    // It returns the name of the file.
}

func (r *CustomReader) DataSize() (int64, error) {
    // It should return the true size of the file in Reader.
}

func (r *CustomReader) ReadBytes(offset int64, length int32) (data []byte, err error) {
    // It should return required number of data bytes starting from certain offset.
}

reader := newCustomReader()

// It is recommended to disable digest when using AmaasReader.
// Because it will trigger ReadBytes to read whole file,
// network traffic will increase if it reads from the Internet.
client.SetDigestDisable()

response, err := client.ScanReader(reader, 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.
  • If user wants to take a look how to scan a S3 file without downloading the whole to the ground, please refer to the example code for further detail.

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()
Enable Verbose Scan Result

You can enable verbose scan result by calling the SetVerboseEnable function:

client.SetVerboseEnable()
Disable Digest Calculation

You can disable digest calculation by calling the SetDigestDisable function:

client.SetDigestDisable()

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, me-central-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

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

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

  • client
  • scanfiles
client

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

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

-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

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.

Disabling certificate verification

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.

Documentation

Index

Constants

View Source 
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"
	AWS_AE_REGION   = "me-central-1"
	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"
	C1_AE_REGION    = "ae-1"
)

Variables

View Source 
var AllRegions []string = append(C1Regions, V1Regions...)
View Source 
var AllValidRegions []string = append(SupportedC1Regions, SupportedV1Regions...)
View Source 
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}
View Source 
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}
View Source 
var SupportedV1Regions []string = []string{AWS_AU_REGION, AWS_DE_REGION, AWS_IN_REGION, AWS_JP_REGION, AWS_SG_REGION, AWS_US_REGION, AWS_AE_REGION}
View Source 
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, AWS_AE_REGION}
View Source 
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,
	AWS_AE_REGION: C1_AE_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, caCert string) (*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) ScanReader added in v1.5.0 

func (ac *AmaasClient) ScanReader(reader AmaasClientReader, tags []string) (resp string, e error)

func (*AmaasClient) SetAppName 

func (ac *AmaasClient) SetAppName(appName string)

func (*AmaasClient) SetDigestDisable added in v1.4.0 

func (ac *AmaasClient) SetDigestDisable()

func (*AmaasClient) SetFeedbackEnable added in v1.1.1 

func (ac *AmaasClient) SetFeedbackEnable()

func (*AmaasClient) SetPMLEnable 

func (ac *AmaasClient) SetPMLEnable()

func (*AmaasClient) SetVerboseEnable added in v1.2.0 

func (ac *AmaasClient) SetVerboseEnable()

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 {
	// Return the identifier of the data source. For example, name of the file being read.
	Identifier() string

	// Return the total size of the data source.
	DataSize() (int64, error)

	// Return requested number of bytes from the data source starting at the specified offset.
	ReadBytes(offset int64, length int32) ([]byte, error)
}

type ErrMsg added in v1.2.0 

type ErrMsg struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

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

type MalwareDetail added in v1.2.0 

type MalwareDetail struct {
	FileName    string `json:"fileName"`
	MalwareName string `json:"malwareName"`
	Engine      string `json:"engine,omitempty"`
}

type ScanResult2Client added in v1.2.0 

type ScanResult2Client struct {
	ScannerVersion string          `json:"scannerVersion"`
	SchemaVersion  string          `json:"schemaVersion"`
	ScanResult     int32           `json:"scanResult"`
	ScanId         string          `json:"scanId"`
	ScanTimestamp  string          `json:"scanTimestamp"`
	FileName       string          `json:"fileName"`
	FoundMalwares  []MalwareDetail `json:"foundMalwares"`
	FoundErrors    []ErrMsg        `json:"foundErrors,omitempty"`
	FileSha1       string          `json:"fileSHA1,omitempty"`
	FileSha256     string          `json:"fileSHA256,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
examples
client
scanfiles

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.