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.
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.
Before installing the SDK, ensure you have the following:
- 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.
- Custom role with File Security permissions
When you have all the prerequisites, continue with 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.
- 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.
To install the SDK's Node.js package, run the following commands in your Node.js application folder.
npm install file-security-sdkUsing File Security Node.js SDK to scan for malware involves the following basic steps:
- Create an AMaaS client instance by specifying preferred Vision One region where scanning should be done and a valid API key.
- Replace
__YOUR_OWN_VISION_ONE_API_KEY__and__REGION__with your actual API key and the desired region. - Invoke file scan method to scan the target data.
- Parse the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.
- Supply the AMaaSHostName and API Key to initiate a new instance of the AmaasGrpcClient.
import { AmaasGrpcClient } from "file-security-sdk";- Use a fully qualified domain name (FQDN) with or without a port -- Replace
__REGION__with the region of your Trend Vision One account.
const amaasHostName = "antimalware.__REGION__.cloudone.trendmicro.com:443";- Use the region -- Replace
__REGION__with the region of your Trend Vision One account.
const amaasHostName = __REGION__;- Replace
__YOUR_OWN_VISION_ONE_API_KEY__with your own Trend Vision One API key.
const key = __YOUR_OWN_VISION_ONE_API_KEY__;- Create a new instance of the AmaasGrpcClient class using the preferred region and key.
const scanClient = new AmaasGrpcClient(amaasHostName, key);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.
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();
}
}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 = 300, enableTLS: boolean | undefined = true, caCert: string | undefined = null)
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. 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. | 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 |
| caCert | full path name of CA certificate pem file for self hosted scanner server. null if using Trend scanner services. | null |
Return An AmaasGrpcClient instance
scanFile(name: string, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise<AmaasScanResultObject | AmaasScanResultVerbose>
Scan a file for malware and retrieves response data from the API.
Parameters
| Parameter | Description | Default value |
|---|---|---|
| name | The name of the file with path of directory containing the file to scan. | |
| 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 |
| verbose | This flag is to enable verbose format for returning scan result. | false |
| digest | This flag is to enable calculation of digests for cache search and result lookup. | true |
Return A Promise that resolves to the API response data.
scanBuffer(fileName: string, buff: Buffer, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise<AmaasScanResultObject | AmaasScanResultVerbose>
Scan a buffer for malware and retrieves response data from the API.
Parameters
| Parameter | Description | Default value |
|---|---|---|
| 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 | 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 |
| verbose | This flag is to enable verbose format for returning scan result. | false |
| digest | This flag is to enable calculation of digests for cache search and result lookup. | true |
Return A Promise that resolves to the API response data.
Close connection to the AMaaS server.
Parameters None
Return void
For configuring the SDK's active logging level. The change is applied globally to all AMaaS Client instances. Default level is LogLevel.OFF, 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 LogLevel.OFF, LogLevel.FATAL, LogLevel.ERROR, LogLevel.WARN, LogLevel.INFO, and LogLevel.DEBUG; default level is LogLevel.OFF |
Return void
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 |
|---|---|
| LogCallback | A function with the type (level LogLevel, message: string) => void |
Return void
The AmaasScanResultObject interface defines the structure of the response data that is retrieved from our API in regular format (i.e. verbose flag is off). The following are the fields in the interface.
interface AmaasScanResultObject {
scannerVersion: string; // Scanner version
schemaVersion: string; // Scan result schema version
scanResult: number; // Number of malwares found. A value of 0 means no malware was found
scanTimestamp: string; // Timestamp of the scan in ISO 8601 format
fileName: string; // Name of the file scanned
scanId: string; // ID of the scan
foundMalwares: [
// A list of malware names and the filenames found by AMaaS
{
fileName: string; // File name which found the malware
malwareName: string; // Malware name
}
];
foundErrors?: [
name: string; // Name of the error
description: string // Description of the error
]
"fileSHA1": string;
"fileSHA256": string
}The AmaasScanResultVerbose interface defines the structure of the response data that is retrieved from our API in verbose format. The following are the fields in the interface.
interface AmaasScanResultVerbose {
scanType: string
objectType: string
timestamp: {
start: string
end: string
}
schemaVersion: string
scannerVersion: string
fileName: string
rsSize: number
scanId: string
accountId: string
result: {
atse: {
elapsedTime: number
fileType: number
fileSubType: number
version: {
engine: string
lptvpn: number
ssaptn: number
tmblack: number
tmwhite: number
macvpn: number
}
malwareCount: number
malware: Array<
{
name: string
fileName: string
type: string
fileType: number
fileTypeName: string
fileSubType: number
fileSubTypeName: string
}
> | null
error: Array<
{
code: number
message: string
}
> | null
fileTypeName: string
fileSubTypeName: string
}
trendx?: {
elapsedTime: number
fileType: number
fileSubType: number
version: {
engine: string
tmblack: number
tmwhite: number
trendx: number
}
malwareCount: number
malware: Array<
{
name: string
fileName: string
type: string
fileType: number
fileTypeName: string
fileSubType: number
fileSubTypeName: string
}
> | null
error: Array<
{
code: number
message: string
}
> | null
fileTypeName: string
fileSubTypeName: string
}
}
tags?: [ string ]
fileSHA1: string
fileSHA256: string
appName: string
}enum LogLevel {
OFF, // 0
FATAL, // 1
ERROR, // 2
WARN, // 3
INFO, // 4
DEBUG, // 5
}The built-in JavaScript Error object with name "Error" will be thrown when error occurs.
The actual message in the following table may be vary in different environment.
| Sample Message | Description and handling |
|---|---|
| Error: Name resolution failed for target dns:{server_address} | There is a network issue. Please verify the network connection to AMaaS server, and make sure the server address specified in the AmaasGrpcClient is correct. |
| Error: Failed to create scan client. Could not parse target name "" | The AMaaS server address is not set or is empty. Please make sure the server address specified in the AmaasGrpcClient is correct. |
| Error: You are not authenticated. Invalid C1 token or Api Key | The API key is invalid. Please make sure a correct Vision One Api key is used. |
| 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. |
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.
For customers who need to enable TLS channel encryption without verifying the provided CA certificate, the Node.js environment variable NODE_TLS_REJECT_UNAUTHORIZED can be set to 0.
When NODE_TLS_REJECT_UNAUTHORIZED is set to 0, certificate validation is disabled for TLS connections, which compromises the security of the connection. Therefore, this configuration should only be used in testing environments.