Trend Cloud One VSAPI SDK JavaScript Documentation

The Trend Cloud One VSAPI SDK JavaScript is a software development kit used for interacting with Trend Cloud One AMaaS service. It is used to build applications on top of the Trend Cloud One AMaaS platform.

Prerequisites

Before installing the SDK, ensure that the following prerequisites are met:

• NodeJS version 16.x, 18.x or above
• Trend Cloud One account with a chosen region - for more information, see the Trend Cloud One account document.
• A Trend Cloud One API key - for more information, see the Trend Cloud One API key documentation.

Installation

To install the SDK's NodeJS package, run the following commands in your NodeJS application folder.

npm install cloudone-vsapi

Authentication

To authenticate with the API, you need an Trend Cloud One API key. Sign up for a Trend Cloud One account and follow the instructions on Manage Trend Cloud One API Keys to obtain an API key.

When creating a Trend Cloud One account, choose a region for the account. All of the account data, as well as the security data for the Trend Cloud One security services in the account, is stored in that region. For more information, see the Trend Cloud One regions documentation.

Usage

To initiate a new instance of the AmaasGrpcClient, we need to supply the AMaaSHostName and Cloud One API Key.

import { AmaasGrpcClient } from 'cloudone-vsapi'

// Replace {REGION} with the region of your Cloud One account
const amaasHostName = 'antimalware.{REGION}.cloudone.trendmicro.com:443'

// Replace {YOUR_OWN_CLOUD_ONE_API_KEY} with your own Cloud One API key
const key = {YOUR_OWN_CLOUD_ONE_API_KEY}

// Create a new instance of the AmaasGrpcClient class using the key
const scanClient = new AmaasGrpcClient(amaasHostName, key)

API Reference

AmaasGrpcClient

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

constructor( amaasHostName: string, key: string, timeout: number | undefined = 180, enableTLS: boolean | undefined = true)

Create a new instance of the AmaasGrpcClient class.

• Parameters

| Parameter | Description | Default value | | ------------- | ---------------------------------------------------------------------------------------- | ------------- | | amaasHostName | The AMaaS server address. | | | key | Your own Cloud 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 |

• Return: AmaasGrpcClient instance

scanFile(name: string): Promise<AmaasScanResultObject>

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

• Return: a Promise that resolves to the API response data.

scanBuffer(fileName: string, buff: Buffer): Promise<AmaasScanResultObject>

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

• Return: a Promise that resolves to the API response data.

close(): void

Close connection to the AMaaS server.

• Parameter: void
• Return: void

AmaasScanResultObject

The AmaasScanResultObject interface defines the structure of the response data that is retrieved from our API. The following are the fields in the interface.

interface AmaasScanResultObject {
  version: string              // API version
  scanResult: number           // Number of malwares found. A value of 0 means no malware was found
  scanId: string               // ID of the scan
  scanTimestamp: string        // Timestamp of the scan in ISO 8601 format
  filePath: string             // Path of the directory containing the file scanned
  fileName: string             // Name of the file scanned
  foundMalwares: [             // A list of malware names and the filenames found by AMaaS
    {
      fileName: string         // File name which found the malware
      malwareName: string      // Malware name
    }
  ]
}

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.

import { AmaasGrpcClient } from 'cloudone-vsapi'
import { readFileSync } from 'fs' // Import for scanBuffer usage

// Replace {REGION} with the region of your Cloud One account
const amaasHostName = 'antimalware.{REGION}.cloudone.trendmicro.com:443'
// Replace {YOUR_OWN_CLOUD_ONE_API_KEY} with your own Cloud One API key
const key = {YOUR_OWN_CLOUD_ONE_API_KEY}

const scanClient = new AmaasGrpcClient(amaasHostName, key)
const fileName = 'the_file_to_scan'

try {
  // Example of scanFile
  const result = await scanClient.scanFile(fileName)
  console.log(`Number of malware found: ${result.scanResult}`)

  // Example of scanBuffer
  const buff = readFileSync(fileName)
  const result = await scanClient.scanBuffer(fileName, buff)
  console.log(`Number of malware found: ${result.scanResult}`)
} catch (error) {
  console.error(`Error occurred: ${error.message}`)
} finally {
  scanClient.close()
}

Errors

The built-in JavaScript Error object with name "Error" will be thrown when error occurs.

Common errors

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 Cloud One Api key or Bearer token 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. |