McAfee Active Response 2.3.0

Comprehensive endpoint detection and response

McAfee Active Response delivers continuous detection of and response to advanced security threats to help security practitioners monitor security posture, improve threat detection, and expand incident response capabilities through forward-looking discovery, detailed analysis, forensic investigation, comprehensive reporting, and prioritized alerts and actions



McAfee Active Response is proof of the effectiveness of the integrated McAfee security architecture, which is designed to resolve more threats faster and with fewer resources in a more complex world. McAfee Active Response gives you continuous visibility and powerful insights into your endpoints so you can identify breaches faster. And it provides you with the tools you need to correct issues faster and in the way that makes the most sense for your business. All of this power is managed via McAfee® ePolicy Orchestrator® (McAfee ePO™) software leveraging McAfee Data Exchange Layer—this provides unified scalability and extensibility without the need for incremental staff to administer the product.


  • Version 2.3.0

Bootprint

McAfee Active Response (MAR)

Version: 0.1

McAfee® Active Response is an endpoint detection and response tool that finds and responds to advanced threats.

Solutions

Services

McAfee MAR Service

DXL service hosted by the McAfee MAR Server. The MAR Search topic operates similarly to a RESTful API, and supports multiple request formats. As such, the definition of the Request/Response supported by '/mcafee/mar/service/api/search' is split into several subsections.

Version:

2.3.0

/mcafee/mar/service/api/search - Create Search
/mcafee/mar/service/api/search - Search Results
/mcafee/mar/service/api/search - Search Status
/mcafee/mar/service/api/search - Start Search

Requests

/mcafee/mar/service/api/search - Search Results

Retrieves the results of a completed search. Results can be filtered by specifying the desired output

McAfee Active Response 2.3.0 Product Guide - Collecting Endpoint Data

payload:

{
"body": {
}
,
"method": "GET",
"parameters": {
"$limit": 10,
"$offset": 1,
"filter": "iexplorer.exe",
"sortBy": "count",
"sortDirection": "desc"
}
,
"target": "/v1/{searchId}/results"
}

Each search result has the following fields: 'id', 'count', 'created_at', 'output'. The output is in the form of a dictionary, where the key is '|' and the value corresponds to those identifiers.

payload: object

{
"body": {
"currentItemCount": 5,
"items": [
{
"count": 12,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)ext4-dio-unwrit#_##_##_##_#",
"output": {
"Processes|name": "ext4-dio-unwrit"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)System#_##_##_##_#",
"output": {
"Processes|name": "System"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "3c79b8b28ea7be20ae86c5dfe934e45b",
"output": {
"Processes|cmdline": "%SystemRoot%\\\\system32\\\\csrss.exe",
"Processes|imagepath": "C:\\\\Windows\\\\System32\\\\csrss.exe",
"Processes|md5": "60C2862B4BF0FD9F582EF344C2B1EC72",
"Processes|name": "csrss.exe",
"Processes|sha1": "17542707A3D9FA13C569450FD978272EF7070A77"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)[System Process]#_##_##_##_#",
"output": {
"Processes|name": "[System Process]"
}
},
{
"count": 9,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "39b094a90fbc3e9da49ce60188933dd0",
"output": {
"Processes|cmdline": "/sbin/udevd -d",
"Processes|imagepath": "/sbin/udevd",
"Processes|md5": "D8757C969BA6682D61BD83047FD88E39",
"Processes|name": "udevd",
"Processes|sha1": "2DB1894DD68FF9923CB3466FE21EF5C47CCBC3E4"
}
}
]
,
"itemsPerPage": 5,
"startIndex": 1,
"totalItems": 65
}
,
"code": 200
}
code: integer

Response code. Possible codes match basic HTTP RESTful response codes. (Example: '200')

body: object
startIndex: integer
itemsPerPage: integer
currentItemCount: integer
totalItems: integer
items: object[]

/mcafee/mar/service/api/search - Search Status

Retrieves the status of a previously-started search.

payload:

{
"body": {
}
,
"method": "PUT",
"parameters": {
}
,
"target": "/v1/{searchId}/start"
}

The response contains the current search status, including the number of unique results for the search, the number of errors reported by endpoints, the number of responding hosts, the number of hosts that were present on the DXL fabric when the search began, and the status of the search execution.

payload: object

{
"body": {
"errors": 0,
"hosts": 2,
"results": 105,
"status": "FINISHED",
"subscribedHosts": 2
}
,
"code": 200
}
code: integer
body: object
results: integer
errors: integer
hosts: integer
subscribedHosts: integer
status: string

Definitions

Active Response Create Search Request Payload:

{
"body": {
"condition": {
"or": [
{
"and": [
{
"name": "Processes",
"op": "EQUALS",
"output": "name",
"value": "csrss"
},
{
"name": "Processes",
"op": "CONTAINS",
"output": "name",
"value": "exe"
}
]
},
{
"and": [
{
"name": "Processes",
"negated": true,
"op": "GREATER_THAN",
"output": "size",
"value": "200"
}
]
}
]
}
,
"projections": [
{
"name": "Processes",
"outputs": [
"name",
"id"
]
}
]
}
,
"method": "POST",
"parameters": {
}
,
"target": "/v1/simple"
}
body: object

Object containing the set of projections and conditions used to define the parameters of the search.

condition: Or Condition Object
projections: Projections Object

Active Response Create Search Response Payload: Search Response Object

Active Response Search Results Request Payload:

{
"body": {
}
,
"method": "GET",
"parameters": {
"$limit": 10,
"$offset": 1,
"filter": "iexplorer.exe",
"sortBy": "count",
"sortDirection": "desc"
}
,
"target": "/v1/{searchId}/results"
}

Active Response Search Results Response Payload: object

{
"body": {
"currentItemCount": 5,
"items": [
{
"count": 12,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)ext4-dio-unwrit#_##_##_##_#",
"output": {
"Processes|name": "ext4-dio-unwrit"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)System#_##_##_##_#",
"output": {
"Processes|name": "System"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "3c79b8b28ea7be20ae86c5dfe934e45b",
"output": {
"Processes|cmdline": "%SystemRoot%\\\\system32\\\\csrss.exe",
"Processes|imagepath": "C:\\\\Windows\\\\System32\\\\csrss.exe",
"Processes|md5": "60C2862B4BF0FD9F582EF344C2B1EC72",
"Processes|name": "csrss.exe",
"Processes|sha1": "17542707A3D9FA13C569450FD978272EF7070A77"
}
},
{
"count": 10,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "(1)[System Process]#_##_##_##_#",
"output": {
"Processes|name": "[System Process]"
}
},
{
"count": 9,
"created_at": "2015-07-06T17:53:23.722Z",
"id": "39b094a90fbc3e9da49ce60188933dd0",
"output": {
"Processes|cmdline": "/sbin/udevd -d",
"Processes|imagepath": "/sbin/udevd",
"Processes|md5": "D8757C969BA6682D61BD83047FD88E39",
"Processes|name": "udevd",
"Processes|sha1": "2DB1894DD68FF9923CB3466FE21EF5C47CCBC3E4"
}
}
]
,
"itemsPerPage": 5,
"startIndex": 1,
"totalItems": 65
}
,
"code": 200
}
code: integer

Response code. Possible codes match basic HTTP RESTful response codes. (Example: '200')

body: object
startIndex: integer
itemsPerPage: integer
currentItemCount: integer
totalItems: integer
items: object[]

Active Response Search Status Request Payload:

{
"body": {
}
,
"method": "PUT",
"parameters": {
}
,
"target": "/v1/{searchId}/start"
}

Active Response Search Status Response Payload: object

{
"body": {
"errors": 0,
"hosts": 2,
"results": 105,
"status": "FINISHED",
"subscribedHosts": 2
}
,
"code": 200
}
code: integer
body: object
results: integer
errors: integer
hosts: integer
subscribedHosts: integer
status: string

Active Response Start Search Request Payload:

{
"body": {
}
,
"method": "PUT",
"parameters": {
}
,
"target": "/v1/{searchId}/start"
}

Active Response Start Search Response Payload: Search Response Object

And Condition Object: object

Comparison operator for a MAR search. Returns 'true' if the both of the comparisons included in the condition array return 'true', otherwise returns 'false'.

and: object[]

Base Catalog Properties: object

catalogVersion: integer

The catalog version.

dbVersion: integer

Database version.

id: string

The property ID.

name: string

The name of the property.

Base Condition Object: object

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.

name: string

The name of the collector from which to retrieve a value for comparison.

output: string

The output name from the collector that selects the specific value to use for comparison.

op: string

The comparison operator.

value: string

The value to compare with the value from the collector.

negated: boolean

(optional) Indicates if the comparison is negated.

General Request Objects: object

method: string

A RESTful-style declaration ('POST', 'GET', etc.) of the type of request being made to the MAR Server. Please see the payload examples of each request format for the correct method to use.

parameters: object

An object containing additional parameters for the request. In most cases, this will be left as an empty object.

object
target: string

The MAR API version targeted by this request.

Not Condition Object: object

Negative comparison operator for a MAR search. Returns 'true' if the comparision presented in the properties of this object are 'false', and vice-versa.

not: object[]

Or Condition Object: object

Comparison operator for a MAR search. Returns 'true' if the either of the comparisons included in the condition array return 'true', otherwise returns 'false'.

or: []

Output Object: object

name: string

Name of the property.

type: string

The property data type.

Platform Object: object

catalogVersion: integer

Catalog version.

dbVersion: integer

Database version.

id: string

The platform unique ID.

name: string

The platform name.

topic: string

DXL topic.

Projection Object: object

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.

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

The name of the collector to project.

outputs: string[]

An array of output names of the collector to project.

string

Projections Object: object[]

Array of projections.

Projection Object

Search Request Object:

Object containing relevant information to target a created and/or running search. The 'body' field should be left as an empty object. The 'parameters' object is only required for a subset of the requests formats that use this object.

body: object

Empty object.

Search Response Item Object: object

id: string

The identifier of the item within the search results.

count: integer

The number of times that the search result was reported.

created_at: string

The item timestamp.

output: object

The search result data where each key is composed of <CollectorName>|<OutputName> and the value that correspond to that 'collector' and 'output name'

string

Search Response Object: object

A complete Search object, including the search ID and the current status of the search ('CREATED', 'STARTED', 'IN_PROGRESS', 'FINISHING', or 'FINISHED').

{
"body": {
"aggregated": true,
"catalogVersion": 1,
"createdAt": 1433278293933,
"dbVersion": 1,
"executedAt": 1433278348963,
"id": "556e1755e4b0922fa5fd6e0c",
"name": "search",
"projections": [
{
"collector": {
"catalogVersion": 1,
"contents": [
{
"arguments": [
]
,
"capability": {
"arguments": [
]
,
"catalogItems": [
"COLLECTOR"
]
,
"catalogVersion": 1,
"contentEnabled": false,
"dbVersion": 1,
"description": "Obtains the list of the running processes",
"format": "BIN",
"formatArgs": {
}
,
"function": "CollectProcess",
"id": "551c500fe4b0d853c533a8b4",
"itemType": "BUILTIN",
"module": "SystemInfo",
"name": "Running Processes",
"outputs": [
{
"name": "name",
"type": "STRING"
},
{
"name": "id",
"type": "NUMBER"
},
{
"name": "threadCount",
"type": "NUMBER"
},
{
"name": "parentId",
"type": "NUMBER"
},
{
"name": "size",
"type": "NUMBER"
},
{
"name": "md5",
"type": "STRING"
},
{
"name": "sha1",
"type": "STRING"
}
]
,
"platforms": [
{
"catalogVersion": 1,
"dbVersion": 1,
"id": "551c500fe4b0d853c533a8b2",
"name": "windows",
"topic": "/mcafee/mar/agent/query/windows"
},
{
"catalogVersion": 1,
"dbVersion": 1,
"id": "551c500fe4b0d853c533a8b3",
"name": "linux",
"topic": "/mcafee/mar/agent/query/linux"
}
]
}
,
"platform": {
"catalogVersion": 1,
"dbVersion": 1,
"id": "551c500fe4b0d853c533a8b3",
"name": "linux",
"topic": "/mcafee/mar/agent/query/linux"
}
}
]
,
"dbVersion": 1,
"description": "Shows the running processes",
"id": "551c500fe4b0d853c533a8bd",
"name": "Processes",
"outputs": [
{
"name": "name",
"type": "STRING"
},
{
"name": "id",
"type": "NUMBER"
},
{
"name": "threadcount",
"type": "NUMBER"
},
{
"name": "parentid",
"type": "NUMBER"
},
{
"name": "size",
"type": "NUMBER"
},
{
"name": "md5",
"type": "STRING"
},
{
"name": "sha1",
"type": "STRING"
}
]
,
"type": "BUILTIN"
}
,
"output": [
{
"name": "name",
"type": "STRING"
},
{
"name": "id",
"type": "NUMBER"
}
]
,
"sequence": "1"
}
]
,
"running": false,
"status": "CREATED",
"subscribedHosts": 2,
"temporal": true,
"ttl": 15000
}
}
body:
temporal: boolean
aggregated: boolean

Whether the search results were aggregated from multiple searches.

projections: object[]
object
collector:
description: string

The description of the collector.

type: string

The type of the collector.

contents: object[]

There is one content per platform. This can be used to discover the platforms that a particular collector supports.

object
platform: Platform Object
capability: object

Details of the collector, including description, output details, collector version, etc.

description: string
module: string
function: string
contentEnabled: boolean
arguments: object[]
object
outputs: object[]

The output fields.

formatArgs: object
format: string
platforms: object[]
itemType: string
catalogItems: string[]
string
outputs: object[]

Name of collector's outputs and their type.

ttl: integer

The amount of time the search will wait for responses.

running: boolean

Whether or not the search is still running.

status: string

Status of the search execution.

createdAt: integer

The time at which the search was created.

executedAt: integer

the time at which the search was executed.

subscribedHosts: integer

The number of hosts that were present in the DXL fabric when the search started.

code: integer

Response code. Possible codes match basic HTTP RESTful response codes. (Example: '200')