Merge pull request #16 from trendmicro/update_to_latest_version_v1.2.0

update to latest version: v1.2.0

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 1.2.0 - 2024-08-08
+
+- Support verbose scan result
+
 ## 1.1.1 - 2024-04-10
 
 - Update README.md

README.md

@@ -158,7 +158,7 @@ Create a new instance of the `AmaasGrpcClient` class.
 **_Return_**
 An AmaasGrpcClient instance
 
-#### `scanFile(name: string, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise<AmaasScanResultObject>`
+#### `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.
 
@@ -170,11 +170,12 @@ Scan a file for malware and retrieves response data from the API.
 | 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         |
 
 **_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>`
+#### `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.
 
@@ -187,6 +188,7 @@ Scan a buffer for malware and retrieves response data from the API.
 | 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         |
 
 **_Return_**
 A Promise that resolves to the API response data.
@@ -231,26 +233,129 @@ void
 
 ### `AmaasScanResultObject`
 
-The AmaasScanResultObject interface defines the structure of the response data that is retrieved from our API.
+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.
 
 ```typescript
 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
-  version: string; // Scan result schema version
   fileName: string; // Name of the file scanned
   scanId: string; // ID of the scan
-  scanResult: number; // Number of malwares found. A value of 0 means no malware was found
+
   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
+}
+```
+
+### `AmaasScanResultVerbose`
+
+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.
+
+```typescript
+
+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
 }
+
 ```
 
+
 ### `LogLevel`
 
 ```typescript

VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

__tests__/amaasSDK.test.ts

@@ -11,6 +11,7 @@ import { randomUUID } from 'crypto'
 
 import { AmaasGrpcClient } from '../src/lib/amaasGrpcClient'
 import { AmaasScanResultObject } from '../src/lib/amaasScanResultObject'
+import { AmaasScanResultVerbose } from '../src/lib/amaasScanResultVerbose'
 import { AmaasCredentials } from '../src/lib/amaasCredentials'
 import { Logger, LogLevel } from '../src/lib/logger'
 import * as scanPb from '../src/lib/protos/scan_pb'
@@ -188,7 +189,7 @@ describe('AmaasGrpcClient scanFile function testing', () => {
   it('should successfully scan file sequentially', async () => {
     const amaasGrpcClient = new AmaasGrpcClient(amaasHostName, authKey, grpcConnectionTimeout, enableTLS)
     const filesArray = filesToScan.slice(1)
-    const results: AmaasScanResultObject[] = []
+    const results: (AmaasScanResultObject | AmaasScanResultVerbose)[] = []
     const lastResult = await filesArray.reduce(
       async (promised, current) => {
         await promised.then(result => {
@@ -220,14 +221,30 @@ describe('AmaasGrpcClient scanFile function testing', () => {
     amaasGrpcClient.close()
   })
 
-  it('should scan file with tags successfully without TrendX and feedback', async () => {
+  it('should scan file with tags successfully without TrendX and feedback and in non verbose format', async () => {
     const amaasGrpcClient = new AmaasGrpcClient(amaasHostName, authKey, grpcConnectionTimeout, enableTLS)
     const tags = ['tag1', 'tag2', 'tag3']
     const pml = false
     const feedback = false
-    await amaasGrpcClient.scanFile(filesToScan[0], tags, pml, feedback)
+    const verbose = false
+    await amaasGrpcClient.scanFile(filesToScan[0], tags, pml, feedback, verbose)
       .then(result => {
-        expect(result.scanResult).not.toEqual(-1)
+        const regularResult = result as AmaasScanResultObject
+        expect(regularResult.scanResult).not.toEqual(-1)
+      })
+    amaasGrpcClient.close()
+  })
+
+  it('should scan file with tags successfully without TrendX and feedback and in verbose format', async () => {
+    const amaasGrpcClient = new AmaasGrpcClient(amaasHostName, authKey, grpcConnectionTimeout, enableTLS)
+    const tags = ['tag1', 'tag2', 'tag3']
+    const pml = false
+    const feedback = false
+    const verbose = true
+    await amaasGrpcClient.scanFile(filesToScan[0], tags, pml, feedback, verbose)
+      .then(result => {
+        const verboseResult = result as AmaasScanResultVerbose
+        expect(verboseResult.result).not.toEqual(null)
       })
     amaasGrpcClient.close()
   })
@@ -237,9 +254,10 @@ describe('AmaasGrpcClient scanFile function testing', () => {
     const tags = ['tag1', 'tag2', 'tag3']
     const pml = true
     const feedback = true
-    await amaasGrpcClient.scanFile(filesToScan[0], tags, pml, feedback)
+    const verbose = false
+    await amaasGrpcClient.scanFile(filesToScan[0], tags, pml, feedback, verbose)
       .then(result => {
-        expect(result.scanResult).not.toEqual(-1)
+        expect((result as AmaasScanResultObject).scanResult).not.toEqual(-1)
       })
     amaasGrpcClient.close()
   })
@@ -256,7 +274,7 @@ describe('AmaasGrpcClient scanBuffer function testing', () => {
   it('should successfully scan buffer sequentially', async () => {
     const amaasGrpcClient = new AmaasGrpcClient(amaasHostName, authKey, grpcConnectionTimeout, enableTLS)
     const fileArray = filesToScan.slice(1)
-    const results: AmaasScanResultObject[] = []
+    const results: (AmaasScanResultObject | AmaasScanResultVerbose)[] = []
     const lastResult = await fileArray.reduce(
       async (promised, current) => {
         await promised.then(result => {
@@ -297,7 +315,7 @@ describe('AmaasGrpcClient scanBuffer function testing', () => {
     const tags = ['tag1', 'tag2', 'tag3']
     await amaasGrpcClient.scanBuffer(filesToScan[0], buff, tags)
       .then(result => {
-        expect(result.scanResult).not.toEqual(-1)
+        expect((result as AmaasScanResultObject).scanResult).not.toEqual(-1)
       })
     amaasGrpcClient.close()
   })
@@ -308,9 +326,10 @@ describe('AmaasGrpcClient scanBuffer function testing', () => {
     const tags = ['tag1', 'tag2', 'tag3']
     const pml = true
     const feedback = true
-    await amaasGrpcClient.scanBuffer(filesToScan[0], buff, tags, pml, feedback)
+    const verbose = false
+    await amaasGrpcClient.scanBuffer(filesToScan[0], buff, tags, pml, feedback, verbose)
       .then(result => {
-        expect(result.scanResult).not.toEqual(-1)
+        expect((result as AmaasScanResultObject).scanResult).not.toEqual(-1)
       })
     amaasGrpcClient.close()
   })
@@ -370,7 +389,7 @@ describe('error testing', () => {
     const tags = ['tag1', 'tag2', 'tag4']
     await amaasGrpcClient.scanFile(filesToScan[0], tags)
       .then(result => {
-        expect(result.scanResult).toEqual(-1)
+        expect((result as AmaasScanResultObject).scanResult).toEqual(-1)
       })
     amaasGrpcClient.close()
   })

examples/cli/src/fileScan.ts

@@ -21,9 +21,10 @@ const useKey = false
  * @param fileName - Name of the file to scan
  * @param tags - List of string to tag a scan
  * @param pml - Enable predictive machine learning detection
- * @param feedback: Enable Trend Micro Smart Protection Network's Smart Feedback
+ * @param feedback - Enable Trend Micro Smart Protection Network's Smart Feedback
+ * @param verbose - Flag to indicate whether return result in verbose format
  */
-const runFileScan = async (fileName: string, tags: string[], pml: boolean, feedback: boolean): Promise<void> => {
+const runFileScan = async (fileName: string, tags: string[], pml: boolean, feedback: boolean, verbose: boolean): Promise<void> => {
   console.log(`\nScanning '${fileName}'`)
   const amaasGrpcClient = useKey
     ? new AmaasGrpcClient(amaasHostName, key)
@@ -32,7 +33,7 @@ const runFileScan = async (fileName: string, tags: string[], pml: boolean, feedb
   loggerConfig(amaasGrpcClient)
 
   await amaasGrpcClient
-    .scanFile(fileName, tags, pml, feedback)
+    .scanFile(fileName, tags, pml, feedback, verbose)
     .then(result => {
       console.log(`${JSON.stringify(result)}`)
     })
@@ -49,5 +50,6 @@ void (async () => {
   const tags = ['example', 'test']
   const predictive_machine_learning = true
   const smart_feedback = true
-  await runFileScan('node_modules/@grpc/grpc-js/src/admin.ts', tags, predictive_machine_learning, smart_feedback)
+  const verbose = true
+  await runFileScan('node_modules/@grpc/grpc-js/src/admin.ts', tags, predictive_machine_learning, smart_feedback, verbose)
 })()

package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-security-sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Vision One File Security API library in TypeScript",
   "main": "index.js",
   "engines": {

protos/scan.proto

@@ -29,6 +29,7 @@ message C2S {
   repeated string tags = 9;
   bool bulk = 10;
   bool spn_feedback = 11;
+  bool verbose = 12;
 }
 
 enum Command {

src/lib/amaasGrpcClient.ts

@@ -4,6 +4,7 @@ import { status, credentials, Metadata, ServiceError } from '@grpc/grpc-js'
 import { ScanClient } from './protos/scan_grpc_pb'
 import { ScanRun } from './scanRun'
 import { AmaasScanResultObject } from './amaasScanResultObject'
+import { AmaasScanResultVerbose } from './amaasScanResultVerbose'
 import { AmaasCredentials } from './amaasCredentials'
 import { CallMetadataGenerator } from '@grpc/grpc-js/build/src/call-credentials'
 import {getFQDN, validateTags } from './utils'
@@ -152,8 +153,11 @@ export class AmaasGrpcClient {
    *
    * @param name - Filename
    * @param tags - Tags to be added to the scan request
+   * @param pml - Flag to enable predictive machine learning detection.
+   * @param feedback - Flag to use Trend Micro Smart Protection Network's Smart Feedback.
+   * @param verbose - Flag to enable verbose mode in returning scan result
    */
-  public async scanFile (name: string, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise<AmaasScanResultObject> {
+  public async scanFile (name: string, tags?: string[], pml: boolean = false, feedback: boolean = false, verbose: boolean = false): Promise<AmaasScanResultObject | AmaasScanResultVerbose> {
     let size: number
 
     try {
@@ -165,7 +169,7 @@ export class AmaasGrpcClient {
 
     const scanRun = this.initScanRun(tags)
     return await scanRun
-      .scanFile(name, size, pml, feedback)
+      .scanFile(name, size, pml, feedback, verbose)
       .then(result => result)
       .catch(err => {
         throw this.processError(err)
@@ -178,11 +182,14 @@ export class AmaasGrpcClient {
    * @param fileName - Filename
    * @param buff - Buffer to scan
    * @param tags - Tags to be added to the scan request
+   * @param pml - Flag to enable predictive machine learning detection.
+   * @param feedback - Flag to use Trend Micro Smart Protection Network's Smart Feedback.
+   * @param verbose - Flag to enable verbose mode in returning scan result
    */
-  public async scanBuffer (fileName: string, buff: Buffer, tags?: string[], pml: boolean = false, feedback: boolean = false): Promise<AmaasScanResultObject> {
+  public async scanBuffer (fileName: string, buff: Buffer, tags?: string[], pml: boolean = false, feedback: boolean = false, verbose: boolean = false): Promise<AmaasScanResultObject | AmaasScanResultVerbose> {
     const scanRun = this.initScanRun(tags)
     return await scanRun
-      .scanBuffer(fileName, buff, pml, feedback)
+      .scanBuffer(fileName, buff, pml, feedback, verbose)
       .then(result => result)
       .catch(err => {
         throw this.processError(err)