Views:

An API reference for the Go SDK for Trend Vision One™ File Security

Creating a new instance

Create a new instance of the client object, and provision the essential settings, including authentication/authorization credentials (API key) and preferred service region.
func NewClient(key string, region string) (c *AmaasClient, e error)

Parameters

Parameter
 Description
key (string)
A valid API key must be provided if the environment variable TM_AM_AUTH_KEY is not set.
region
The region you obtained your api key. Value provided must be one of the Vision One regions:
  • ap-northeast-1
  • ap-south-1
  • ap-southeast-1
  • ap-southeast-2
  • eu-central-1
  • us-east-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.
Error conditions
  • Invalid authentication
  • Invalid region

Submitting content

Submit the content of a file or buffer to be scanned.
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)

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 . The maximum number tags that you can use is 8, and the length of each tag cannot exceed 63.

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

Freeing up internal resources used by client

Free up internal resources used by the client. It should only be invoked after one has finished scanning and no longer needs the client object.
func (ac *AmaasClient) Destroy()

Configuring the logging level

You can configure 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
  • LogLevelDebug
. The default level is LogLevelOff.

Setting up custom logging

You can set up a custom logging by provisioning the SDK with a custom callback function that is invoked whether the SDK wants to record a log.
func ConfigLoggingCallback(f func(level LogLevel, levelStr string, format string, a ...interface{}))

Parameters

Parameter
Description
f (function)
A function with the prototype 
func(level LogLevel, levelStr string, format string, a
    ...interface{})

Thread safety

ScanFile() or ScanBuffer() are designed to be thread-safe. You 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.