Skip to content

Commit 546bb67

Browse files
chucklin-tmchucklin-tm
authored
Merge pull request #13 from trendmicro/update_to_latest_version_v1.1.1
update to latest version: v1.1.1
2 parents 087ef34 + a50007b commit 546bb67

File tree

7 files changed

+134
-86
lines changed

7 files changed

+134
-86
lines changed

‎CHANGELOG.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# CHANGELOG
22

3+
## 1.1.1 - 2024-04-10
4+
5+
- Update README.md
6+
- Extend the scan default timeout to 300s
7+
38
## 1.1.0 - 2024-04-03
49

510
- Update protos

‎README.md

+124-81
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,159 @@
1-
# Trend Vision One File Security Node.js SDK User Guide
1+
# Trend Vision One™ File Security Node.js SDK User Guide
22

3-
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.
3+
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.
4+
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.
5+
File Security can also scan objects across your environment in any application, whether on-premises or in the cloud.
46

5-
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.
7+
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.
8+
Follow the steps below to set up your development environment and configure your project, laying the foundation to effectively use File Security.
69

7-
## Prerequisites
10+
## Checking prerequisites
811

9-
Before installing the SDK, ensure that the following prerequisites are met:
12+
Before installing the SDK, ensure you have the following:
1013

11-
- NodeJS version 16.20.1+, 18.x or above
12-
- 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).
13-
- 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).
14+
- Node.js 16.20.1+, 18.x or later
15+
- 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).
16+
- Custom role with File Security permissions
1417

15-
## Installation
18+
When you have all the prerequisites, continue with creating an API key.
1619

17-
To install the SDK's NodeJS package, run the following commands in your NodeJS application folder.
20+
## Creating an API Key
21+
22+
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).
23+
24+
### Procedure
25+
26+
- Go to Administrations > API Keys.
27+
- Click Add API Key.
28+
- Configure the API key to use the role with the 'Run file scan via SDK' permission.
29+
- Verify that the API key is associated with the region you plan to use.
30+
- Set an expiry time for the API key and make a record of it for future reference.
31+
32+
## Installing the SDK
33+
34+
To install the SDK's Node.js package, run the following commands in your Node.js application folder.
1835

1936
```sh
2037
npm install file-security-sdk
2138
```
2239

23-
## Authentication
40+
## Using File Security Node.js SDK
2441

25-
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.
42+
Using File Security Node.js SDK to scan for malware involves the following basic steps:
2643

27-
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).
44+
1. Create an AMaaS client instance by specifying preferred Vision One region where scanning should be done and a valid API key.
45+
2. Replace `__YOUR_OWN_VISION_ONE_API_KEY__` and `__REGION__` with your actual API key and the desired region.
46+
3. Invoke file scan method to scan the target data.
47+
4. Parse the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
2848

29-
### Usage
49+
### Steps
3050

31-
To initiate a new instance of the AmaasGrpcClient, we need to supply the AMaaSHostName and Vision One API Key.
51+
- Supply the AMaaSHostName and API Key to initiate a new instance of the AmaasGrpcClient.
3252

3353
```typescript
3454
import { AmaasGrpcClient } from "file-security-sdk";
55+
```
3556

36-
// Use region. Replace __REGION__ with the region of your Vision One account
57+
- Use a fully qualified domain name (FQDN) with or without a port -- Replace `__REGION__` with the region of your Trend Vision One account.
58+
59+
```typescript
60+
const amaasHostName = "antimalware.__REGION__.cloudone.trendmicro.com:443";
61+
```
62+
63+
- Use the region -- Replace `__REGION__` with the region of your Trend Vision One account.
64+
65+
```typescript
3766
const amaasHostName = __REGION__;
67+
```
3868

39-
// Replace __YOUR_OWN_VISION_ONE_API_KEY__ with your own Visioin One API key
69+
- Replace `__YOUR_OWN_VISION_ONE_API_KEY__` with your own Trend Vision One API key.
70+
71+
```typescript
4072
const key = __YOUR_OWN_VISION_ONE_API_KEY__;
73+
```
74+
75+
- Create a new instance of the AmaasGrpcClient class using the preferred region and key.
4176

42-
// Create a new instance of the AmaasGrpcClient class using the key
77+
```typescript
4378
const scanClient = new AmaasGrpcClient(amaasHostName, key);
4479
```
4580

81+
## Code Example
82+
83+
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.
84+
85+
```typescript
86+
import { AmaasGrpcClient, LogLevel } from "file-security-sdk";
87+
import { readFileSync } from "fs/promises";
88+
89+
// Use region. Replace __REGION__ with the region of your Vision One account
90+
const amaasHostName = __REGION__;
91+
92+
const credent = __YOUR_OWN_VISION_ONE_API_KEY__;
93+
94+
let scanClient = undefined;
95+
96+
try {
97+
scanClient = new AmaasGrpcClient(amaasHostName, credent);
98+
99+
const logCallback = (level: LogLevel, message: string): void => {
100+
console.log(`logCallback is called, level: ${level}, message: ${message}`);
101+
};
102+
scanClient.setLoggingLevel(LogLevel.DEBUG);
103+
scanClient.configLoggingCallback(logCallback);
104+
105+
// Example of scanFile
106+
const fileToScan = "path/to/file.ext";
107+
const fileScanResult = await scanClient.scanFile(
108+
fileToScan,
109+
["tag1", "tag2", "tag3"],
110+
pml,
111+
feedback
112+
);
113+
console.log(`Number of malware found: ${result.scanResult}`); // Scan result handling
114+
115+
// Example of scanBuffer
116+
const buff = await readFileSync(fileToScan);
117+
const pml = true
118+
const feedback = true
119+
const bufferScanResult = await scanClient.scanBuffer(
120+
"THE_FILE_NAME_OR_IDENTIFIER",
121+
buff,
122+
["tag1", "tag2", "tag3"],
123+
pml,
124+
feedback
125+
);
126+
console.log(
127+
`Number of malware found in buffer: ${bufferScanResult.scanResult}`
128+
);
129+
} catch (error) {
130+
// Error handling
131+
console.error("Error occurred:", error.message);
132+
} finally {
133+
if (typeof scanClient !== "undefined") {
134+
scanClient.close();
135+
}
136+
}
137+
```
138+
46139
## API Reference
47140

48141
### `AmaasGrpcClient`
49142

50143
The AmaasGrpcClient class is the main class of the SDK and provides methods to interact with the API.
51144

52-
#### `constructor( amaasHostName: string, credent: string, timeout: number | undefined = 180, enableTLS: boolean | undefined = true)`
145+
#### `constructor( amaasHostName: string, credent: string, timeout: number | undefined = 300, enableTLS: boolean | undefined = true)`
53146

54147
Create a new instance of the `AmaasGrpcClient` class.
55148

56149
**_Parameters_**
57150

58151
| Parameter | Description | Default value |
59152
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
60-
| 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. | |
153+
| 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. | |
61154
| credent | Your own Vision One API Key. | |
62-
| timeout | Timeout to cancel the connection to server in seconds. | 180 |
63-
| enableTLS | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. | true |
155+
| timeout | Timeout to cancel the connection to server in seconds. | 300 |
156+
| 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 |
64157

65158
**_Return_**
66159
An AmaasGrpcClient instance
@@ -74,7 +167,7 @@ Scan a file for malware and retrieves response data from the API.
74167
| Parameter | Description | Default value |
75168
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
76169
| name | The name of the file with path of directory containing the file to scan. | |
77-
| 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. | |
170+
| 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. | |
78171
| pml | This flag is to enable Trend's predictive machine learning detection. | false |
79172
| feedback | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback. | false |
80173

@@ -91,7 +184,7 @@ Scan a buffer for malware and retrieves response data from the API.
91184
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
92185
| fileName | The name of the file or object the buffer is created from. The name is used to identify the buffer. | |
93186
| buff | The buffer to scan. | |
94-
| 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. | |
187+
| 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. | |
95188
| pml | This flag is to enable Trend's predictive machine learning detection. | false |
96189
| feedback | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback. | false |
97190

@@ -171,63 +264,6 @@ enum LogLevel {
171264
}
172265
```
173266

174-
## Code Example
175-
176-
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.
177-
178-
```typescript
179-
import { AmaasGrpcClient, LogLevel } from "file-security-sdk";
180-
import { readFileSync } from "fs/promises";
181-
182-
// Use region. Replace __REGION__ with the region of your Vision One account
183-
const amaasHostName = __REGION__;
184-
185-
const credent = __YOUR_OWN_VISION_ONE_API_KEY__;
186-
187-
let scanClient = undefined;
188-
189-
try {
190-
scanClient = new AmaasGrpcClient(amaasHostName, credent);
191-
192-
const logCallback = (level: LogLevel, message: string): void => {
193-
console.log(`logCallback is called, level: ${level}, message: ${message}`);
194-
};
195-
scanClient.setLoggingLevel(LogLevel.DEBUG);
196-
scanClient.configLoggingCallback(logCallback);
197-
198-
// Example of scanFile
199-
const fileToScan = "path/to/file.ext";
200-
const fileScanResult = await scanClient.scanFile(fileToScan, [
201-
"tag1",
202-
"tag2",
203-
"tag3",
204-
]);
205-
console.log(`Number of malware found: ${result.scanResult}`); // Scan result handling
206-
207-
// Example of scanBuffer
208-
const buff = await readFileSync(fileToScan);
209-
const pml = true
210-
const feedback = true
211-
const bufferScanResult = await scanClient.scanBuffer(
212-
"THE_FILE_NAME_OR_IDENTIFIER",
213-
buff,
214-
["tag1", "tag2", "tag3"],
215-
pml,
216-
feedback
217-
);
218-
console.log(
219-
`Number of malware found in buffer: ${bufferScanResult.scanResult}`
220-
);
221-
} catch (error) {
222-
// Error handling
223-
console.error("Error occurred:", error.message);
224-
} finally {
225-
if (typeof scanClient !== "undefined") {
226-
scanClient.close();
227-
}
228-
}
229-
```
230-
231267
## Errors
232268

233269
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.
244280
| 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. |
245281
| 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`. |
246282
| Error: Invalid region: {region} | The region is invalid. Please make sure a correct region is used. |
283+
284+
## Ensuring Secure Communication with TLS
285+
286+
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.
287+
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.
288+
289+
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
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.1.0
1+
1.1.1

‎__tests__/amaasSDK.test.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ const scanImpls = {
111111

112112
// Mock server does not use TLS protocol. Set enableTLS to false.
113113
const enableTLS = false
114-
const grpcConnectionTimeout = 3 * 60 // seconds
114+
const grpcConnectionTimeout = 5 * 60 // seconds
115115
const amaasHostName = 'localhost:50051'
116116
const authKey = ''
117117
const credent: AmaasCredentials = {

‎package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "file-security-sdk",
3-
"version": "1.1.0",
3+
"version": "1.1.1",
44
"description": "Vision One File Security API library in TypeScript",
55
"main": "index.js",
66
"engines": {

‎src/lib/amaasGrpcClient.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ export class AmaasGrpcClient {
3232
constructor (
3333
amaasHostName: string,
3434
credent: AmaasCredentials | string,
35-
timeout = 180,
35+
timeout = 300,
3636
enableTLS = true,
3737
appName = 'V1FS'
3838
) {

‎src/lib/scanRun.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ export class ScanRun {
2525
this.logger = logger
2626
this.finalResult = Object.create(null) as AmaasScanResultObject
2727
this.tags = tags ?? []
28-
this.bulk = true
28+
this.bulk = false
2929
}
3030

3131
private async streamRun (fileName: string, fileSize: number, hashes: string[], pml: boolean, feedback: boolean, buff?: Buffer): Promise<AmaasScanResultObject> {

0 commit comments

Comments
 (0)