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