Merge pull request #13 from trendmicro/update_to_latest_version_v1.1.1

update to latest version: v1.1.1

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 1.1.1 - 2024-04-10
+
+- Update README.md
+- Extend the scan default timeout to 300s
+
 ## 1.1.0 - 2024-04-03
 
 - Update protos

README.md

@@ -1,66 +1,159 @@
-# Trend Vision One File Security Node.js SDK User Guide
+# Trend Vision One™ File Security Node.js SDK User Guide
 
-The Trend Vision One File Security Node.js 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 Node.js SDK effectively.
+The Node.js 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.
 
-## Prerequisites
+## Checking prerequisites
 
-Before installing the SDK, ensure that the following prerequisites are met:
+Before installing the SDK, ensure you have the following:
 
-- NodeJS version 16.20.1+, 18.x or above
-- Trend Vision One account with a chosen region - for more information, see the [Trend Vision One account document](https://docs.trendmicro.com/en-us/enterprise/trend-micro-xdr-help/Home).
-- A Trend Vision One API key - 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).
+- Node.js 16.20.1+, 18.x or later
+- Trend Vision One account associated with your region - for more information, see the [Trend Vision One account document](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-accountspartfoundati).
+- Custom role with File Security permissions
 
-## Installation
+When you have all the prerequisites, continue with creating an API key.
 
-To install the SDK's NodeJS package, run the following commands in your NodeJS application folder.
+## Creating an API Key
+
+The File Security SDK requires a valid application programming interface (API) key provided as a parameter to the SDK client object. Trend Vision One API keys are associated with different regions. Refer to the region flag below to obtain a better understanding of the valid regions associated with the API key. For more information, see the [Trend Vision One API key documentation](https://docs.trendmicro.com/en-us/documentation/article/trend-vision-one-api-keys).
+
+### Procedure
+
+- Go to Administrations > API Keys.
+- Click Add API Key.
+- Configure the API key to use the role with the 'Run file scan via SDK' permission.
+- Verify that the API key is associated with the region you plan to use.
+- Set an expiry time for the API key and make a record of it for future reference.
+
+## Installing the SDK
+
+To install the SDK's Node.js package, run the following commands in your Node.js application folder.
 
 ```sh
 npm install file-security-sdk
 ```
 
-## Authentication
+## Using File Security Node.js SDK
 
-To authenticate with the API, you need an Trend Vision One API key. Sign up for a [Trend Vision One account](https://docs.trendmicro.com/en-us/enterprise/trend-vision-one.aspx) and follow the instructions on [Manage Trend Vision One API Keys](https://docs.trendmicro.com/en-us/enterprise/trend-vision-one/administrative-setti/accountspartfoundati/api-keys.aspx) to obtain an API key.
+Using File Security Node.js SDK to scan for malware involves the following basic steps:
 
-When creating a Trend Vision One account, choose a region for the account. All of the account data, as well as the security data for the Trend Vision One security services in the account, is stored in that region. For more information, see the [Trend Vision One regions documentation](https://docs.trendmicro.com/en-us/enterprise/trend-vision-one.aspx).
+1. Create an AMaaS client instance by specifying preferred Vision One region where scanning should be done and a valid API key.
+2. Replace `__YOUR_OWN_VISION_ONE_API_KEY__` and `__REGION__` with your actual API key and the desired region.
+3. Invoke file scan method to scan the target data.
+4. Parse the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
 
-### Usage
+### Steps
 
-To initiate a new instance of the AmaasGrpcClient, we need to supply the AMaaSHostName and Vision One API Key.
+- Supply the AMaaSHostName and API Key to initiate a new instance of the AmaasGrpcClient.
 
 ```typescript
 import { AmaasGrpcClient } from "file-security-sdk";
+```
 
-// Use region. Replace __REGION__ with the region of your Vision One account
+- Use a fully qualified domain name (FQDN) with or without a port -- Replace `__REGION__` with the region of your Trend Vision One account.
+
+```typescript
+const amaasHostName = "antimalware.__REGION__.cloudone.trendmicro.com:443";
+```
+
+- Use the region -- Replace `__REGION__` with the region of your Trend Vision One account.
+
+```typescript
 const amaasHostName = __REGION__;
+```
 
-// Replace __YOUR_OWN_VISION_ONE_API_KEY__ with your own Visioin One API key
+- Replace `__YOUR_OWN_VISION_ONE_API_KEY__` with your own Trend Vision One API key.
+
+```typescript
 const key = __YOUR_OWN_VISION_ONE_API_KEY__;
+```
+
+- Create a new instance of the AmaasGrpcClient class using the preferred region and key.
 
-// Create a new instance of the AmaasGrpcClient class using the key
+```typescript
 const scanClient = new AmaasGrpcClient(amaasHostName, key);
 ```
 
+## Code Example
+
+The following is an example of how to use the SDK to scan a file or buffer for malware and retrieve the scan results from our API.
+
+```typescript
+import { AmaasGrpcClient, LogLevel } from "file-security-sdk";
+import { readFileSync } from "fs/promises";
+
+// Use region. Replace __REGION__ with the region of your Vision One account
+const amaasHostName = __REGION__;
+
+const credent = __YOUR_OWN_VISION_ONE_API_KEY__;
+
+let scanClient = undefined;
+
+try {
+  scanClient = new AmaasGrpcClient(amaasHostName, credent);
+
+  const logCallback = (level: LogLevel, message: string): void => {
+    console.log(`logCallback is called, level: ${level}, message: ${message}`);
+  };
+  scanClient.setLoggingLevel(LogLevel.DEBUG);
+  scanClient.configLoggingCallback(logCallback);
+
+  // Example of scanFile
+  const fileToScan = "path/to/file.ext";
+  const fileScanResult = await scanClient.scanFile(
+  fileToScan, 
+  ["tag1", "tag2", "tag3"],
+  pml,
+  feedback
+  );
+  console.log(`Number of malware found: ${result.scanResult}`); // Scan result handling
+
+  // Example of scanBuffer
+  const buff = await readFileSync(fileToScan);
+  const pml = true
+  const feedback = true
+  const bufferScanResult = await scanClient.scanBuffer(
+    "THE_FILE_NAME_OR_IDENTIFIER",
+    buff,
+    ["tag1", "tag2", "tag3"],
+    pml,
+    feedback
+  );
+  console.log(
+    `Number of malware found in buffer: ${bufferScanResult.scanResult}`
+  );
+} catch (error) {
+  // Error handling
+  console.error("Error occurred:", error.message);
+} finally {
+  if (typeof scanClient !== "undefined") {
+    scanClient.close();
+  }
+}
+```
+
 ## API Reference
 
 ### `AmaasGrpcClient`
 
 The AmaasGrpcClient class is the main class of the SDK and provides methods to interact with the API.
 
-#### `constructor( amaasHostName: string, credent: string, timeout: number | undefined = 180, enableTLS: boolean | undefined = true)`
+#### `constructor( amaasHostName: string, credent: string, timeout: number | undefined = 300, enableTLS: boolean | undefined = true)`
 
 Create a new instance of the `AmaasGrpcClient` class.
 
 **_Parameters_**
 
 | Parameter     | Description                                                                                                                                                                                                                                          | Default value |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| amaasHostName | The region of your Vision One account. The region is the location where you acquire 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`, etc. |               |
+| amaasHostName | The region of your Vision One account. The region is the location where you acquire your api key. Value provided must be one of the Vision One regions, e.g. `ap-northeast-1`, `ap-south-1`, `ap-southeast-1`, `ap-southeast-2`, `eu-central-1`, `us-east-1`, etc. |               |
 | credent       | Your own Vision One API Key.                                                                                                                                                                                                                         |               |
-| timeout       | Timeout to cancel the connection to server in seconds.                                                                                                                                                                                               | 180           |
-| enableTLS     | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server.                                                                                                                                                             | true          |
+| timeout       | Timeout to cancel the connection to server in seconds.                                                                                                                                                                                               | 300           |
+| enableTLS     | Enable or disable TLS. TLS should always be enabled when connecting to the File Security service. For more information, see the 'Ensuring Secure Communication with TLS' section.                                                                                                                                                            | true          |
 
 **_Return_**
 An AmaasGrpcClient instance
@@ -74,7 +167,7 @@ Scan a file for malware and retrieves response data from the API.
 | Parameter | Description                                                                                                              | Default value |
 | --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
 | name      | The name of the file with path of directory containing the file to scan.                                                 |               |
-| tags      | `(Optional)` The list of tags which can be used to tag the scan. Max size of tags list is 8. Max size of each tag is 63. |               |
+| tags      | The list of tags which can be used to tag the scan. Max size of tags list is 8. Max size of each tag is 63. |               |
 | pml       | This flag is to enable Trend's predictive machine learning detection.                                                    | false         |
 | feedback  | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback.                                            | false         |
 
@@ -91,7 +184,7 @@ Scan a buffer for malware and retrieves response data from the API.
 | --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
 | fileName  | The name of the file or object the buffer is created from. The name is used to identify the buffer.                      | |
 | buff      | The buffer to scan.                                                                                                      |               |
-| tags      | `(Optional)` The list of tags which can be used to tag the scan. Max size of tags list is 8. Max size of each tag is 63. |               |
+| tags      | The list of tags which can be used to tag the scan. Max size of tags list is 8. Max size of each tag is 63. |               |
 | pml       | This flag is to enable Trend's predictive machine learning detection.                                                    | false         |
 | feedback  | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback.                                            | false         |
 
@@ -171,63 +264,6 @@ enum LogLevel {
 }
 ```
 
-## Code Example
-
-The following is an example of how to use the SDK to scan a file or buffer for malware and retrieve the scan results from our API.
-
-```typescript
-import { AmaasGrpcClient, LogLevel } from "file-security-sdk";
-import { readFileSync } from "fs/promises";
-
-// Use region. Replace __REGION__ with the region of your Vision One account
-const amaasHostName = __REGION__;
-
-const credent = __YOUR_OWN_VISION_ONE_API_KEY__;
-
-let scanClient = undefined;
-
-try {
-  scanClient = new AmaasGrpcClient(amaasHostName, credent);
-
-  const logCallback = (level: LogLevel, message: string): void => {
-    console.log(`logCallback is called, level: ${level}, message: ${message}`);
-  };
-  scanClient.setLoggingLevel(LogLevel.DEBUG);
-  scanClient.configLoggingCallback(logCallback);
-
-  // Example of scanFile
-  const fileToScan = "path/to/file.ext";
-  const fileScanResult = await scanClient.scanFile(fileToScan, [
-    "tag1",
-    "tag2",
-    "tag3",
-  ]);
-  console.log(`Number of malware found: ${result.scanResult}`); // Scan result handling
-
-  // Example of scanBuffer
-  const buff = await readFileSync(fileToScan);
-  const pml = true
-  const feedback = true
-  const bufferScanResult = await scanClient.scanBuffer(
-    "THE_FILE_NAME_OR_IDENTIFIER",
-    buff,
-    ["tag1", "tag2", "tag3"],
-    pml,
-    feedback
-  );
-  console.log(
-    `Number of malware found in buffer: ${bufferScanResult.scanResult}`
-  );
-} catch (error) {
-  // Error handling
-  console.error("Error occurred:", error.message);
-} finally {
-  if (typeof scanClient !== "undefined") {
-    scanClient.close();
-  }
-}
-```
-
 ## Errors
 
 The built-in JavaScript `Error` object with name "`Error`" will be thrown when error occurs.
@@ -244,3 +280,10 @@ The actual message in the following table may be vary in different environment.
 | Error: Failed to open file. ENOENT: no such file or directory, stat {file_path} | The {file_path} specified in `scanFile` cannot be found. Please make sure the file exists and {file_path} specified is correct.                                 |
 | Error: Failed to open file. EACCES: permission denied, open {file_path}         | There is a file access permission issue. Please make sure the SDK has read permission of the {file_path} specified in `scanFile`.                               |
 | Error: Invalid region: {region}                                                 | The region is invalid. Please make sure a correct region is used.                                                                                               |
+
+## 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.1

__tests__/amaasSDK.test.ts

@@ -111,7 +111,7 @@ const scanImpls = {
 
 // Mock server does not use TLS protocol. Set enableTLS to false.
 const enableTLS = false
-const grpcConnectionTimeout = 3 * 60 // seconds
+const grpcConnectionTimeout = 5 * 60 // seconds
 const amaasHostName = 'localhost:50051'
 const authKey = ''
 const credent: AmaasCredentials = {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-security-sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Vision One File Security API library in TypeScript",
   "main": "index.js",
   "engines": {

src/lib/amaasGrpcClient.ts

@@ -32,7 +32,7 @@ export class AmaasGrpcClient {
   constructor (
     amaasHostName: string,
     credent: AmaasCredentials | string,
-    timeout = 180,
+    timeout = 300,
     enableTLS = true,
     appName = 'V1FS'
   ) {

src/lib/scanRun.ts

@@ -25,7 +25,7 @@ export class ScanRun {
     this.logger = logger
     this.finalResult = Object.create(null) as AmaasScanResultObject
     this.tags = tags ?? []
-    this.bulk = true
+    this.bulk = false
   }
 
   private async streamRun (fileName: string, fileSize: number, hashes: string[], pml: boolean, feedback: boolean, buff?: Buffer): Promise<AmaasScanResultObject> {