cloudone-vsapi v1.0.0

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

• Return: AmaasGrpcClient instance

scanFile(name: string): Promise<AmaasScanResultObject>

Scan a file for malware and retrieves response data from the API.

• Parameters

• 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

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