{"id":21359339,"url":"https://github.com/trendmicro/tm-v1-fs-nodejs-sdk","last_synced_at":"2025-07-13T01:31:10.219Z","repository":{"id":207304443,"uuid":"715466793","full_name":"trendmicro/tm-v1-fs-nodejs-sdk","owner":"trendmicro","description":"Trend Vision One File Security Node.js SDK","archived":false,"fork":false,"pushed_at":"2024-08-28T03:36:48.000Z","size":473,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-09-28T10:46:42.308Z","etag":null,"topics":["antimalware","antivirus","api","cloud","cnapp","developer-tools","devsecops","security","threat-detection","trend","trendvisionone"],"latest_commit_sha":null,"homepage":"https://docs.trendmicro.com/en-us/enterprise/trend-vision-one.aspx","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trendmicro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-07T07:48:02.000Z","updated_at":"2024-08-28T03:31:35.000Z","dependencies_parsed_at":"2023-11-15T05:26:30.641Z","dependency_job_id":"340996ea-5905-4f72-a33f-81b5bd24a30f","html_url":"https://github.com/trendmicro/tm-v1-fs-nodejs-sdk","commit_stats":{"total_commits":15,"total_committers":6,"mean_commits":2.5,"dds":0.6,"last_synced_commit":"cca0562a0eeb69c48a61c2878daab289d0a36170"},"previous_names":["trendmicro/tm-v1-fs-nodejs-sdk"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trendmicro%2Ftm-v1-fs-nodejs-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trendmicro%2Ftm-v1-fs-nodejs-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trendmicro%2Ftm-v1-fs-nodejs-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trendmicro%2Ftm-v1-fs-nodejs-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trendmicro","download_url":"https://codeload.github.com/trendmicro/tm-v1-fs-nodejs-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225245330,"owners_count":17443642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antimalware","antivirus","api","cloud","cnapp","developer-tools","devsecops","security","threat-detection","trend","trendvisionone"],"created_at":"2024-11-22T05:27:50.657Z","updated_at":"2025-07-13T01:31:10.203Z","avatar_url":"https://github.com/trendmicro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trend Vision One™ File Security Node.js SDK User Guide\n\nTrend 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.\nFile 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.\nFile Security can also scan objects across your environment in any application, whether on-premises or in the cloud.\n\nThe 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.\nFollow the steps below to set up your development environment and configure your project, laying the foundation to effectively use File Security.\n\n## Checking prerequisites\n\nBefore installing the SDK, ensure you have the following:\n\n- Node.js version 20.19.0 or above\n- 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).\n- Custom role with File Security permissions\n\nWhen you have all the prerequisites, continue with creating an API key.\n\n## Creating an API Key\n\nThe 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).\n\n### Procedure\n\n- Go to Administrations \u003e API Keys.\n- Click Add API Key.\n- Configure the API key to use the role with the 'Run file scan via SDK' permission.\n- Verify that the API key is associated with the region you plan to use.\n- Set an expiry time for the API key and make a record of it for future reference.\n\n## Installing the SDK\n\nTo install the SDK's Node.js package, run the following commands in your Node.js application folder.\n\n```sh\nnpm install file-security-sdk\n```\n\n## Using File Security Node.js SDK\n\nUsing File Security Node.js SDK to scan for malware involves the following basic steps:\n\n1. Create an AMaaS client instance by specifying preferred Vision One region where scanning should be done and a valid API key.\n2. Replace `__YOUR_OWN_VISION_ONE_API_KEY__` and `__REGION__` with your actual API key and the desired region.\n3. Invoke file scan method to scan the target data.\n4. Parse the JSON response returned by the scan APIs to determine whether the scanned data contains malware or not.\n\n### Steps\n\n- Supply the AMaaSHostName and API Key to initiate a new instance of the AmaasGrpcClient.\n\n```typescript\nimport { AmaasGrpcClient } from \"file-security-sdk\";\n```\n\n- Use a fully qualified domain name (FQDN) with or without a port -- Replace `__REGION__` with the region of your Trend Vision One account.\n\n```typescript\nconst amaasHostName = \"antimalware.__REGION__.cloudone.trendmicro.com:443\";\n```\n\n- Use the region -- Replace `__REGION__` with the region of your Trend Vision One account.\n\n```typescript\nconst amaasHostName = __REGION__;\n```\n\n- Replace `__YOUR_OWN_VISION_ONE_API_KEY__` with your own Trend Vision One API key.\n\n```typescript\nconst key = __YOUR_OWN_VISION_ONE_API_KEY__;\n```\n\n- Create a new instance of the AmaasGrpcClient class using the preferred region and key.\n\n```typescript\nconst scanClient = new AmaasGrpcClient(amaasHostName, key);\n```\n\n## Code Example\n\nThe 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.\n\n```typescript\nimport { AmaasGrpcClient, LogLevel } from \"file-security-sdk\";\nimport { readFileSync } from \"fs/promises\";\n\n// Use region. Replace __REGION__ with the region of your Vision One account\nconst amaasHostName = __REGION__;\n\nconst credent = __YOUR_OWN_VISION_ONE_API_KEY__;\n\nlet scanClient = undefined;\n\ntry {\n  scanClient = new AmaasGrpcClient(amaasHostName, credent);\n\n  const logCallback = (level: LogLevel, message: string): void =\u003e {\n    console.log(`logCallback is called, level: ${level}, message: ${message}`);\n  };\n  scanClient.setLoggingLevel(LogLevel.DEBUG);\n  scanClient.configLoggingCallback(logCallback);\n\n  // Example of scanFile\n  const fileToScan = \"path/to/file.ext\";\n  const fileScanResult = await scanClient.scanFile(\n  fileToScan, \n  [\"tag1\", \"tag2\", \"tag3\"],\n  pml,\n  feedback\n  );\n  console.log(`Number of malware found: ${result.scanResult}`); // Scan result handling\n\n  // Example of scanBuffer\n  const buff = await readFileSync(fileToScan);\n  const pml = true\n  const feedback = true\n  const bufferScanResult = await scanClient.scanBuffer(\n    \"THE_FILE_NAME_OR_IDENTIFIER\",\n    buff,\n    [\"tag1\", \"tag2\", \"tag3\"],\n    pml,\n    feedback\n  );\n  console.log(\n    `Number of malware found in buffer: ${bufferScanResult.scanResult}`\n  );\n} catch (error) {\n  // Error handling\n  console.error(\"Error occurred:\", error.message);\n} finally {\n  if (typeof scanClient !== \"undefined\") {\n    scanClient.close();\n  }\n}\n```\n\n## API Reference\n\n### `AmaasGrpcClient`\n\nThe AmaasGrpcClient class is the main class of the SDK and provides methods to interact with the API.\n\n#### `constructor( amaasHostName: string, credent: string, timeout: number | undefined = 300, enableTLS: boolean | undefined = true, caCert: string | undefined = null)`\n\nCreate a new instance of the `AmaasGrpcClient` class.\n\n**_Parameters_**\n\n| Parameter     | Description                                                                                                                                                                                                                                          | Default value |\n| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |\n| 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`, `me-central-1`, etc. |               |\n| credent       | Your own Vision One API Key.                                                                                                                                                                                                                         |               |\n| timeout       | Timeout to cancel the connection to server in seconds.                                                                                                                                                                                               | 300           |\n| 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          |\n| caCert        | full path name of CA certificate pem file for self hosted scanner server. null if using Trend scanner services.                                                                                     | null          |\n\n**_Return_**\nAn AmaasGrpcClient instance\n\n#### `scanFile(name: string, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise\u003cAmaasScanResultObject | AmaasScanResultVerbose\u003e`\n\nScan a file for malware and retrieves response data from the API.\n\n**_Parameters_**\n\n| Parameter | Description                                                                                                              | Default value |\n| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |\n| name      | The name of the file with path of directory containing the file to scan.                                                 |               |\n| 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. |               |\n| pml       | This flag is to enable Trend's predictive machine learning detection.                                                    | false         |\n| feedback  | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback.                                            | false         |\n| verbose   | This flag is to enable verbose format for returning scan result.                                                         | false         |\n| digest    | This flag is to enable calculation of digests for cache search and result lookup.                                        | true          |\n\n**_Return_**\nA Promise that resolves to the API response data.\n\n#### `scanBuffer(fileName: string, buff: Buffer, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise\u003cAmaasScanResultObject | AmaasScanResultVerbose\u003e`\n\nScan a buffer for malware and retrieves response data from the API.\n\n**_Parameters_**\n\n| Parameter | Description                                                                                                              | Default value |\n| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |\n| fileName  | The name of the file or object the buffer is created from. The name is used to identify the buffer.                      | |\n| buff      | The buffer to scan.                                                                                                      |               |\n| 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. |               |\n| pml       | This flag is to enable Trend's predictive machine learning detection.                                                    | false         |\n| feedback  | This flag is to enable Trend Micro Smart Protection Network's Smart Feedback.                                            | false         |\n| verbose   | This flag is to enable verbose format for returning scan result.                                                         | false         |\n| digest    | This flag is to enable calculation of digests for cache search and result lookup.                                        | true          |\n\n**_Return_**\nA Promise that resolves to the API response data.\n\n#### `close(): void`\n\nClose connection to the AMaaS server.\n\n**_Parameters_**\nNone\n\n**_Return_**\nvoid\n\n#### `setLoggingLevel(level: LogLevel): void`\n\nFor 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.\n\n**_Parameters_**\n\n| Parameter        | Description                                                                                                                                    |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| level (LogLevel) | Valid values are LogLevel.OFF, LogLevel.FATAL, LogLevel.ERROR, LogLevel.WARN, LogLevel.INFO, and LogLevel.DEBUG; default level is LogLevel.OFF |\n\n---\n\n**_Return_**\nvoid\n\n#### `configLoggingCallback(LogCallback: Function): void`\n\nFor setting up custom logging by provisioning the SDK with a custom callback function that is invoked whether the SDK wants to record a log.\n\n**_Parameters_**\n\n| Parameter   | Description                                                          |\n| ----------- | -------------------------------------------------------------------- |\n| LogCallback | A function with the type `(level LogLevel, message: string) =\u003e void` |\n\n**_Return_**\nvoid\n\n### `AmaasScanResultObject`\n\nThe AmaasScanResultObject interface defines the structure of the response data that is retrieved from our API in regular format (i.e. verbose flag is off).\nThe following are the fields in the interface.\n\n```typescript\ninterface AmaasScanResultObject {\n  scannerVersion: string; // Scanner version\n  schemaVersion: string; // Scan result schema version\n  scanResult: number; // Number of malwares found. A value of 0 means no malware was found\n  scanTimestamp: string; // Timestamp of the scan in ISO 8601 format\n  fileName: string; // Name of the file scanned\n  scanId: string; // ID of the scan\n  \n  foundMalwares: [\n    // A list of malware names and the filenames found by AMaaS\n    {\n      fileName: string; // File name which found the malware\n      malwareName: string; // Malware name\n    }\n  ];\n  foundErrors?: [\n    name: string; // Name of the error\n    description: string // Description of the error\n  ]\n  \"fileSHA1\": string;\n  \"fileSHA256\": string\n}\n```\n\n### `AmaasScanResultVerbose`\n\nThe AmaasScanResultVerbose interface defines the structure of the response data that is retrieved from our API in verbose format.\nThe following are the fields in the interface.\n\n```typescript\n\ninterface AmaasScanResultVerbose {\n  scanType: string\n  objectType: string\n  timestamp: {\n    start: string\n    end: string\n  }\n  schemaVersion: string\n  scannerVersion: string\n  fileName: string\n  rsSize: number\n  scanId: string\n  accountId: string\n  result: {\n    atse: {\n      elapsedTime: number\n      fileType: number\n      fileSubType: number\n      version: {\n        engine: string\n        lptvpn: number\n        ssaptn: number\n        tmblack: number\n        tmwhite: number\n        macvpn: number\n      }\n      malwareCount: number\n      malware: Array\u003c\n        {\n          name: string\n          fileName: string\n          type: string\n          fileType: number\n          fileTypeName: string\n          fileSubType: number\n          fileSubTypeName: string\n        }\n      \u003e | null\n      error: Array\u003c\n        {\n          code: number\n          message: string\n        }\n      \u003e | null\n      fileTypeName: string\n      fileSubTypeName: string\n    }\n    trendx?: {\n      elapsedTime: number\n      fileType: number\n      fileSubType: number\n      version: {\n        engine: string\n        tmblack: number\n        tmwhite: number\n        trendx: number\n      }\n      malwareCount: number\n      malware: Array\u003c\n        {\n          name: string\n          fileName: string\n          type: string\n          fileType: number\n          fileTypeName: string\n          fileSubType: number\n          fileSubTypeName: string\n        }\n      \u003e | null\n      error: Array\u003c\n        {\n          code: number\n          message: string\n        }\n      \u003e | null\n      fileTypeName: string\n      fileSubTypeName: string\n    }\n  }\n  tags?: [ string ]\n  fileSHA1: string\n  fileSHA256: string\n  appName: string\n}\n\n```\n\n\n### `LogLevel`\n\n```typescript\nenum LogLevel {\n  OFF, // 0\n  FATAL, // 1\n  ERROR, // 2\n  WARN, // 3\n  INFO, // 4\n  DEBUG, // 5\n}\n```\n\n## Errors\n\nThe built-in JavaScript `Error` object with name \"`Error`\" will be thrown when error occurs.\n\n### Common errors\n\nThe actual message in the following table may be vary in different environment.\n\n| Sample Message                                                                  | Description and handling                                                                                                                                        |\n| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 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. |\n| 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.                             |\n| 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.                                                                                  |\n| 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.                                 |\n| 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`.                               |\n| Error: Invalid region: {region}                                                 | The region is invalid. Please make sure a correct region is used.                                                                                               |\n\n## Ensuring Secure Communication with TLS\n\nThe 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.\nThe 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.\n\nThe 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.\n\n## Disabling certificate verification\n\nFor 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`.\n\nWhen `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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrendmicro%2Ftm-v1-fs-nodejs-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrendmicro%2Ftm-v1-fs-nodejs-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrendmicro%2Ftm-v1-fs-nodejs-sdk/lists"}