Merge pull request #10 from trendmicro/update_to_latest_version_v1.1.2

update to latest version: v1.1.2

Author: kentchen-tm

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 1.1.2 - 2024-04-10
+
+* Update README.md
+* Extend default timeout to 300s
+ 
 ## 1.1.1 - 2024-04-04
 
 * Fix bug in SPN smart feedback

README.md

@@ -1,18 +1,22 @@
-# Trend Vision One File Security Go SDK User Guide
+# Trend Vision One™ File Security Go SDK User Guide
 
-The Trend Vision One File Security Go SDK empowers developers to craft applications seamlessly integrating with the cloud-based Trend Vision One anti-malware file scanning service. This ensures a thorough scan of data and artifacts within the applications, identifying potential malicious elements.
+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.
 
-This guide outlines the steps to establish your development environment and configure your project, laying the foundation for utilizing the File Security Go SDK effectively.
+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](https://docs.trendmicro.com/en-us/enterprise/trend-micro-xdr-help/Home).
-- A Trend Vision One API key with proper role - for more information, see the [Trend Vision One API key documentation](https://docs.trendmicro.com/en-us/enterprise/trend-vision-one/administrative-setti/accountspartfoundati/api-keys.aspx).
+- Trend Vision One account with a chosen region - for more information, see the [Trend Vision One documentation](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-trend-micro-xdr-abou_001).
+- A Trend Vision One API key with proper role - for more information, see the [Trend Vision One API key documentation](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-api-keys).
 
 ## 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:
 
@@ -42,9 +46,9 @@ If you plan on using a Trend Vision One region, be sure to pass in region parame
 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.
+- 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
 
@@ -60,14 +64,8 @@ if err != nil {
     panic(err)
 }
 ```
-Replace "YOUR_API_KEY_OR_TOKEN" and "YOUR_REGION" with your actual API key or token and the desired region.
-
-**_Parameters_**
 
-| Parameter | Description                                                                                                                                                                                             |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| region    | The region you obtained your api key.  Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, `ap-south-1`, etc. |
-| apikey    | Your own Vision One API Key.                                                                                                                                                                            |
+Replace "YOUR_API_KEY_OR_TOKEN" and "YOUR_REGION" with your actual API key or token and the desired region.
 
 ## Basic Usage
 
@@ -105,6 +103,7 @@ if err != nil {
 ```
 
 **_Note_**
+
 - Max number of tags is 8. And the length of each tag can't exceed 63.
 
 ## Additional Functions
@@ -144,7 +143,120 @@ 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_**
+
+```json
+{
+  "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.
@@ -156,13 +268,14 @@ You can refer to these files for a deeper understanding of how to integrate and
 ## 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
+- scanfiles
 
 ### client
 
@@ -173,7 +286,7 @@ This program is located in the `tools/` folder. It supports the gRPC-based serve
 The following flags are supported:
 
 `-tls`
-Specify to enable server authentication by client for gRPC
+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
@@ -214,7 +327,7 @@ Specify if scanning good/non-malicious files.
 Specify if scanning of multiple files should be carried out simultaneously instead of sequentially.
 
 `-tls`
-Specify to enable server authentication by client for gRPC
+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
@@ -234,15 +347,38 @@ 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`                                                                                                                                      |
+| `HTTP_PROXY`        | Optional          | `http://proxy.example.com`                                                                                                                                      |
 | `HTTPS_PROXY`        | Optional          | `https://proxy.example.com`<br><br>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.

VERSION

@@ -1 +1 @@
-1.1.0
+1.1.2

sdk.go

@@ -9,7 +9,7 @@ import (
 
 const (
 	_defaultCommPort    = 443 // Port used by AMaaS Client to communicate with server.
-	_defaultTimeoutSecs = 180 // 3 minutes
+	_defaultTimeoutSecs = 300 // 5 minutes
 )
 
 const (