External provider

doc/index.md

@@ -25,6 +25,7 @@ to access the features of TIE.
       * {@tutorial basic-get-file-reputation-example}
       * {@tutorial basic-get-cert-reputation-example}
       * {@tutorial basic-set-file-reputation-example}
+      * {@tutorial basic-set-external-file-reputation-example}
       * {@tutorial basic-set-cert-reputation-example}
       * {@tutorial basic-get-file-first-ref-example}
       * {@tutorial basic-get-cert-first-ref-example}

doc/sdk/basic-set-external-file-reputation-example.md

@@ -0,0 +1,125 @@
+This sample demonstrates invoking the McAfee Threat Intelligence Exchange (TIE)
+DXL service to set the External Provider `trust level` of a file (as identified by its hashes).
+
+
+
+### Prerequisites
+
+* The samples configuration step has been completed (see {@tutorial samples}).
+
+* A McAfee Threat Intelligence Exchange (TIE) Service is available on the DXL
+  fabric.
+
+* The JavaScript DXL client must be authorized to send messages to the
+  `/mcafee/event/external/file/report` topic, which is part of the 
+  `TIE Server Set External Reputation` authorization group.
+
+  The following page provides an example of authorizing a Python client to send
+  messages to an `authorization group`. While the example is based on McAfee
+  Active Response (MAR), the instructions are the same with the exception of
+  swapping the `TIE Server Set External Reputation` `authorization group` in
+  place of `Active Response Server API`:
+
+  <https://opendxl.github.io/opendxl-client-python/pydoc/marsendauth.html>
+
+### Running
+
+To run this sample execute the `sample/basic/basic-set-external-file-reputation-example.js`
+script as follows:
+
+```sh
+$ node sample/basic/basic-set-external-file-reputation-example.js
+```
+
+If the `External Reputation` operation succeeds the following message will be
+displayed:
+
+```
+Event Sent.
+```
+
+### Details
+
+The majority of the sample code is shown below:
+
+```js
+var client = new dxl.Client(config)
+
+// Hashes for the file whose reputation will be set.
+var FILE_MD5 = '<FILE MD5>'
+var FILE_SHA1 = '<FILE SHA1>'
+var FILE_SHA256 = '<FILE SHA256>'
+
+
+client.connect(function () {
+  var tieClient = new TieClient(client)
+  // The trust level that the external provider wants to set to a specific file
+  var externalTrustLevel = TrustLevel.KNOWN_TRUSTED
+
+  var hashes = {}
+  hashes[HashType.MD5] = FILE_MD5
+  hashes[HashType.SHA1] = FILE_SHA1
+  hashes[HashType.SHA256] = FILE_SHA256
+
+  // Request reputation for file
+  tieClient.getFileReputation(
+    function (error, fileReputation) {
+      if (error) {
+        // Destroy the client - frees up resources so that the application
+        // stops running
+        client.destroy()
+        console.error('Error getting file reputations: ' + error.message)
+      } else {
+        //
+        // Check if there's any definitive reputation (different to Not Set [0] and Unknown [50])
+        // for any provider except for External Provider (providerId=15)
+        //
+        var hasDefinitiveReputation = Object.values(fileReputation).some(function (r) {
+          return r.trustLevel !== TrustLevel.NOT_SET &&
+            r.trustLevel !== TrustLevel.UNKNOWN &&
+            r.providerId !== FileProvider.EXTERNAL
+        })
+
+        if (hasDefinitiveReputation) {
+          console.error('Abort: There is a reputation from another provider for the file, ' +
+            'External Reputation is not necessary.')
+          client.destroy()
+        } else {
+          tieClient.setExternalFileReputation(
+            function () {
+              // Destroy the client - frees up resources so that the application
+              // stops running
+              client.destroy()
+              console.log('Event Sent')
+            },
+            externalTrustLevel,
+            hashes,
+            FileType.PEEXE,
+            'file.exe',
+            'External Reputation set via OpenDXL'
+          )
+        }
+      }
+    },
+    hashes
+  )
+})
+
+```
+
+Once a connection is established to the DXL fabric, the callback function
+supplied to the DXL client instance's
+[connect()](https://opendxl.github.io/opendxl-client-javascript/jsdoc/Client.html#connect)
+method will be invoked. From within the callback function, a {@link TieClient}
+instance is created. The TieClient instance will be used to communicate with the
+TIE DXL services.
+
+The External Reputation `trust level` is established for the file by invoking
+the TieClient instance's
+[setExternalFileReputation()]{@link TieClient#setExternalFileReputation} method, along with the 
+`hash values` used to identify the file.
+
+The `filename`, `filetype` and `comment` are
+optional but useful in identifying the particular file that is associated
+with the hashes (especially if the file did not previously exist in the TIE
+repository).

doc/sdk/basic-set-file-reputation-example.md

@@ -2,6 +2,10 @@ This sample demonstrates invoking the McAfee Threat Intelligence Exchange (TIE)
 DXL service to set the enterprise-specific `trust level` of a file (as
 identified by its hashes).
 
+
+>From **TIE Server 3.0.0** and above it's recommended for automated integrations to set an External Reputation (see {@tutorial basic-set-external-file-reputation-example}) instead of an Enterprise Override.
+
+
 ### Prerequisites
 
 * The samples configuration step has been completed (see {@tutorial samples}).

doc/sdk/tutorials.json

@@ -17,6 +17,9 @@
       "basic-set-file-reputation-example": {
         "title": "Basic Set File Reputation Example"
       },
+      "basic-set-external-file-reputation-example": {
+        "title": "Basic Set External File Reputation Example"
+      },
       "basic-set-cert-reputation-example": {
         "title": "Basic Set Certificate Reputation Example"
       },

index.js

@@ -22,3 +22,4 @@ exports.FirstInstanceEventProp = require('./lib/constants/first-instance-event-p
 exports.FirstRefProp = require('./lib/constants/first-ref-prop')
 exports.HashType = require('./lib/constants/hash-type')
 exports.TrustLevel = require('./lib/constants/trust-level')
+exports.FileType = require('./lib/constants/file-type')

lib/constants/file-provider.js

@@ -29,5 +29,9 @@ module.exports = {
   /**
    * McAfee Web Gateway (MWG).
    */
-  MWG: 7
+  MWG: 7,
+  /**
+   * External Reputation Providers.
+   */
+  EXTERNAL: 15
 }

lib/constants/file-type.js

@@ -0,0 +1,204 @@
+/**
+ * @module FileType
+ * @description Constants that are used to indicate the `file type` of a file
+ *
+ * | Type       | Long Value  | Description |
+ * | ---------- | ----------- | ----------- |
+ * | None       | 0           | Unrecognized piece of data |
+ * | COM        | 1           | Plain binary, less than 64K |
+ * | EXE        | 2           | EXE file (Consider that old DOS executable are not PE) |
+ * | DRV        | 4           | DOS Driver |
+ * | BOOT       | 8           | BOOT-sector image |
+ * | PE         | 1           | 16 PE file |
+ * | PE         | 18          | EXE & PE file (Windows Portable Executable) |
+ * | NE         | 32          | NE file |
+ * | VXD        | 64          | LE / W4 file (normally Windows-VxD) |
+ * | DLL non PE | 128         | Old Windows DLL (Consider that old 16bit DLL might not be PE) |
+ * | PE DLL     | 144         | Windows DLL & PE |
+ * | PE WIN     | 272         | Windows Executable |
+ * | MZSTUB     | 512         | Windows program with non-trivial DOS stub |
+ * | NLM        | 1024        | PE / NE / LE file |
+ * | ELF        | 2048        | Linux binary file Linux ELF |
+ * | JS         | 4096        | Javascript file Javascript |
+ * | VBS        | 8192        | VB script file |
+ * | SCRIPT     | 12288       | |
+ * | PIC        | 65536       | Picture file |
+ * | TEXT       | 131072      | Text file |
+ * | BAT        | 143360L     | Batch script (.cmd .bat) |
+ * | HTML       | 262144      | Hypertext file |
+ * | HTA        | 524288      | Hypertext application |
+ * | RTF        | 1048576     | Rich text file |
+ * | PDF        | 2097152     | Adobe Acrobat file |
+ * | MMEDIA     | 4194304     | Music, movie or other MM file |
+ * | URL        | 8388608     | Text file with URL extension |
+ * | PE         | 16777232    | Portable executable system driver (WIN, sys extension) |
+ * | ARC        | 33587200    | ZIP Archive file |
+ * | ARC        | 67141632    | CAB Archive file |
+ * | ARC        | 134250496   | RAR Archive file |
+ * | OOXMLPK    | 268435456   | OOXML in ZIP (office format for pptx, docx, etc) Office |
+ * | MACH_O     | 536870912   | MAC-O binary |
+ * | APK        | 1073741824  | Android application package |
+ * | CLASS      | 2147483648  | Java class |
+ * | JAR        | 4328554496  | Java package |
+ */
+
+'use strict'
+
+module.exports = {
+    /**
+     * Unknown, not recognized.
+     */
+  NONE: 0,
+    /**
+     * Plain binary, less than 64K.
+     */
+  COM: 1,
+    /**
+     * EXE file.
+     */
+  EXE: 2,
+    /**
+     * DOS driver.
+     */
+  DRV: 4,
+    /**
+     * BOOT-sector image.
+     */
+  BOOT: 8,
+    /**
+     * PE file.
+     */
+  PE: 16,
+    /**
+     * PE-EXE file (PE + EXE).
+     */
+  PEEXE: 18,
+    /**
+     * LE/W4 file (normally Windows-VxD).
+     */
+  VXD: 64,
+    /**
+     * Windows DLL (16 bits).
+     */
+  DLLNONPE: 128,
+    /**
+     * Windows DLL.
+     */
+  DLL: 144,
+    /**
+     * Windows Executable (PE + NE + LE).
+     */
+  WIN: 272,
+    /**
+     * Windows program with non-trivial DOS stub (EXE + MZSTUB).
+     */
+  MZSTUB: 512,
+    /**
+     * Netware Loadable Module (MZSTUB << 1).
+     */
+  NLM: 1024,
+    /**
+     * ELF (linux binary) file.
+     */
+  ELF: 2048,
+    /**
+     * J-script (ELF << 1).
+     */
+  JS: 4096,
+    /**
+     * VB-script (JS << 1).
+     */
+  VBS: 8192,
+    /**
+     * Script (JS | VBS).
+     */
+  SCRIPT: 12288,
+    /**
+     * OLE document (VBS << 1).
+     */
+  OLE: 16384,
+    /**
+     * Picture file (ARC << 1).
+     */
+  PIC: 65536,
+    /**
+     * Text file (PIC << 1).
+     */
+  TEXT: 131072,
+    /**
+     * Batch script (.cmd .bat) file : TEXT + Script).
+     */
+  BAT: 143360,
+    /**
+     * Hyper-text : TEXT << 1).
+     */
+  HTML: 262144,
+    /**
+     * Hyper-text file : HTML + TEXT).
+     */
+  HTMLTEXT: 393216,
+    /**
+     * Hyper-text application : HTML << 1).
+     */
+  HTA: 524288,
+    /**
+     * Rich-text : HTA << 1).
+     */
+  RTF: 1048576,
+    /**
+     * Adobe Acrobat (RTF << 1).
+     */
+  PDF: 2097152,
+    /**
+     * Music, movie or other MM (PDF << 1).
+     */
+  MMEDIA: 4194304,
+    /**
+     * Text file with url extension (MMEDIA << 1).
+     */
+  URL: 8388608,
+    /**
+     * Portable system driver (PE + URL<<1).
+     */
+  SYS: 16777232,
+    /**
+     * ZIP (starts with pk) file (ARC + ZIP).
+     */
+  ZIP: 33587200,
+    /**
+     * CAB (starts with mscf) file (ARC + CAB).
+     */
+  CAB: 67141632,
+    /**
+     * RAR file (RAR) --> ARCHIVE flag is disabled.
+     */
+  RARNOARC: 134217728,
+    /**
+     * RAR file (ARC + RAR).
+     */
+  RAR: 134250496,
+    /**
+     * MS Office document (Legacy - Backward Compatible - ENS 10.5.1).
+     */
+  OOXML: 167772160,
+    /**
+     * MS Office document (ZIP + RAR << 1).
+     */
+  OOXMLPK: 301989888,
+    /**
+     * MAC-O binary (OOXMLPK << 1).
+     */
+  MACHO: 536870912,
+    /**
+     * Android application package (MACHO << 1).
+     */
+  APK: 1073741824,
+    /**
+     * Java class file (APK.value << 1).
+     */
+  CLASS: 2147483648,
+    /**
+     * Java package (ZIP + ARC + CLASS << 1).
+     */
+  JAR: 4328554496
+}