JSDoc: Class: MarClient

Constructor

new MarClient(dxlClient)

Parameters:

Name	Type	Description
`dxlClient`	external:DxlClient	The DXL client to use for communication with the MAR DXL service.

Source:

mar-client.js, line 40

Members

pollInterval

Properties:

Type	Description
Number	The amount of time to wait (in seconds) before polling the MAR server for results. Defaults to `5`. If a value less than `5` is specified, a `RangeError` is thrown.

Source:

mar-client.js, line 86

Methods

search(projections, conditions, callback)

Executes a search via McAfee Active Response.

Once the search has completed a ResultsContext object is returned which is used to access the search results.

Client Authorization

The OpenDXL JavaScript client invoking this method must have permission to send messages to the /mcafee/mar/service/api/search topic.

See the following page for details on authorizing a client to perform MAR searches:

https://opendxl.github.io/opendxl-client-python/pydoc/marsendauth.html

Execution of a MAR search requires an array of projections and an optional object containing the search conditions.

Projections

Projections are used to describe the information to collect in the search. Each projection consists of a collector name and a list of output names from the collector. For example, the Processes collector includes output names such as name, sha1, md5, etc.

For a complete list of collectors and their associated output names refer to the McAfee Active Response Product Guide.

Each projection specified must contain the following fields:

name: The name of the collector to project
outputs: An array of output names of the collector to project

The JavaScript array below is equivalent to the projections within the following textual search:

Processes name, id where Processes name equals "csrss" and Processes name contains "exe" or Processes size not greater than 200

[{
  name: "Processes",
  outputs: ["name", "id"]
}]

Conditions

Conditions are used to restrict which items are included in the search results. For example, a search that collects process-related information could be limited to those processes which match a specified name.

A condition has a fixed structure starting with an or conditional operator and allowing only one level of and conditions.

The JavaScript object below is equivalent to the conditions within the following textual search:

Processes name, id where Processes name equals "csrss" and Processes name contains "exe" or Processes size not greater than 200

{
  or: [{
    and: [{
      name: 'Processes',
      output: 'name',
      op: 'EQUALS',
      value: 'csrss'
    },
    {
      name: 'Processes',
      output: 'name',
      op: 'CONTAINS',
      value: 'exe'
    }]
  },
  {
    and: [{
      name: 'Processes',
      output: 'size',
      op: 'GREATER_THAN',
      value: '200',
      negated: 'true'
    }]
  }]
}

The following fields are used for each condition:

name: The name of the collector from which to retrieve a value for comparison
output: The output name from the collector that selects the specific value to use for comparison
op: The comparison operator
value: The value to compare with the value from the collector
negated: (optional) Indicates if the comparison is negated

The operators available for each value data type are as follows:

Operator	NUMBER	STRING	BOOLEAN	DATE	IPV4IPV6	REG_STR
GREATER_EQUAL_THAN	x
GREATER_THAN	x
LESS_EQUAL_THAN	x
LESS_THAN	x
EQUALS	x	x	x	x	x	x `(*)`
CONTAINS		x			x	x `(*)`
STARTS_WITH		x				x `(*)`
ENDS_WITH		x				x `(*)`
BEFORE				x
AFTER				x

(*) Negated field is not supported in those cases.

Parameters:

Name	Type	Description
`projections`	Array.<Object>	An object containing the `projections` for the search.
`conditions`	Object	An object containing the `conditions` for the search.
`callback`	function	Callback function to invoke with the results of the search. If an error occurs when performing the lookup, the first parameter supplied to the callback contains an `Error` object with failure details. On successful completion of the search, a ResultsContext object is provided as the second parameter to the callback.

Source:

mar-client.js, line 283

Example

// Create the client
var client = new dxl.Client(config)

// Connect to the fabric, supplying a callback function which is invoked
// when the connection has been established
client.connect(function () {
  var marClient = new MarClient(client)

  marClient.search(
    [{
      name: 'Processes',
      outputs: ['name', 'id']
    }],
    {
      or: [{
        and: [{
          name: 'Processes',
          output: 'name',
          op: 'EQUALS',
          value: 'csrss'
        },
        {
          name: 'Processes',
          output: 'name',
          op: 'CONTAINS',
          value: 'exe'
        }]
      },
      {
        and: [{
          name: 'Processes',
          output: 'size',
          op: 'GREATER_THAN',
          value: '200',
          negated: 'true'
        }]
      }]
    },
    function (searchError, resultContext) {
      if (resultContext && resultContext.hasResults) {
        // Process results
      } else {
        // Handle searchError
      }
    }
  )
})