REST API Reference CB R 6.3+

Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.

The Carbon Black EDR API is a RESTful API. This means that the API can be consumed by practically any language.

Example client bindings and scripts are included for reference purposes.

Python CbAPI

In addition, customers have created alternative bindings for other languages as well:

Elixir language bindings - REST API, Streaming API (Author: Redvers Davies)

The EDR REST API uses HTTP header authentication for all requests. See the REST API authentication reference for more details.

Process Data

Process Search

/api/v1/process

Process search. Parameters passed as a query string.

Supports: GET

Parameters

q: REQUIRED Query string. Accepts the same data as the search box on the Process Search page. See the Query overview for the query syntax.
rows: OPTIONAL Return this many rows, 10 by default.
start: OPTIONAL Start at this row, 0 by default.
sort: OPTIONAL Sort rows by this field and order. last_update desc by default.
facet: OPTIONAL Return facet results. ‘false’ by default, set to ‘true’ for facets.
facet.field: OPTIONAL facet field name to return. Multiple facet.field parameters can be specified in a query.
cb.comprehensive_search: OPTIONAL if set to true, CB will automatically fix the query and insert joins to make it comprehensive (reducing performance)
cb.facet.fuzzy: OPTIONAL if set to true, enable fuzzy faceting for performance (default is set in the cb.conf file)
cb.group: OPTIONAL group by a field name. For example, if query parameter cb.group=id, search will return one result per process

Note that results will still honor sorting specified by the search. Even within group, it will return result that is first in the sort order. For example, if sorted by regmod_count, it will return top processes and top process segment for each process with highest regmod_count

Grouping will be slower (sometimes much slower) than regular results. For example, in 100M document DB test, it took 1 minute to group result set of 100K.

Returns

JSON object with the following elements:

highlights: a list of matching process IDs and the field that matched the query, with the text PREPREPRE before the highlighted match and POSTPOSTPOST after the highlighted match.
results: a list of matching processes (see below for process object)
terms: a list of strings, each representing a token as parsed by the query parser
total_results: number of matching processes
start: index of first row
elapsed: clock time elapsed resolving this request
facets: a list of facet entries if requested. (see below for facet object)
tagged_pids: a list of process IDs in this result set that have one or more events tagged as part of an investigation
filtered: count of results filtered due to security settings
comprehensive_search: Some boolean queries may return incorrect results due to segmentation. comprehensive_search will be set to False if the query may contain incorrect results due to segmentation. Setting the cb.comprehensive_search query parameter to true (above) during the API query should perform the necessary joins to ensure the correct results.
incomplete_results: Set to true if there was a timeout when performing the search on the backend. This could indicate that some time partitions were unable to be searched or some minions could not return results in time.

Process Object

A process contains the following fields:

process_md5: the md5 of the binary image backing the process
process_name: the name of the process
start: the start time of the process in remote computer GMT time
last_update: the time of the most recently received event for this process in remote computer GMT time
hostname: the hostname of the computer for this process
modload_count: the count of modules loaded in this process
regmod_count: the count of registry modifications in this process
filemod_count: the count of file modifications in this process
netconn_count: count of network connections in this process
childproc_count: the count of child processes launched by this process
crossproc_count: the count of cross process events launched by this process
group: the CB Host group this sensor is assigned to
sensor_id: the internal CB id for the sensor on which the process executed
id: the internal CB process id for this process (processes are identified by this id and their segment id)
segment_id: the process segment id (processes are identified by this segment id and their process ID id)
unique_id: internal CB process id combining of the process id and segment id
os_type: operating system type of the computer for this process; one of windows, linux, osx

A complete example:

$ curl "http://192.168.206.151/api/v1/process?cb.urlver=1&rows=10&facet=false&facet.field=process_name&facet.field=group&facet.field=hostname&facet.field=parent_name&facet.field=path_full&facet.field=process_md5&start=0&rows=1&q=chrome.exe"

{
  "all_segments": true,
  "terms": [
    "chrome.exe"
  ],
  "total_results": 231,
  "highlights": [
    {
      "name": "c:\\program files (x86)\\google\\chrome\\application\\PREPREPREchrome.exePOSTPOSTPOST",
      "ids": [
        "00000001-0000-1028-01d2-c24179cca1b8-015bc2a3ebe8",
        "00000001-0000-1028-01d2-c24179cca1b8-015bc2a3ebe8",
        "00000001-0000-0650-01d2-c273a7ba8b36-015bc3ed7ed8",
        "00000001-0000-0650-01d2-c273a7ba8b36-015bc3ed7ed8",
        "00000001-0000-020c-01d2-c273a79d8c63-015bc3ed7ed8",
        "00000001-0000-020c-01d2-c273a79d8c63-015bc3ed7ed8",
        "00000001-0000-08dc-01d2-c273a7b337f2-015bc3ed7ed8",
        "00000001-0000-08dc-01d2-c273a7b337f2-015bc3ed7ed8",
        "00000001-0000-1234-01d2-c273a77198f9-015bc3ed7ed8",
        "00000001-0000-1234-01d2-c273a77198f9-015bc3ed7ed8",
        "00000001-0000-0e4c-01d2-c273a780b4a2-015bc3ed7ed8",
        "00000001-0000-0e4c-01d2-c273a780b4a2-015bc3ed7ed8",
        "00000001-0000-12fc-01d2-c273a7c1de71-015bc3ed7ed8",
        "00000001-0000-12fc-01d2-c273a7c1de71-015bc3ed7ed8",
        "00000001-0000-0778-01d2-c273a7966030-015bc3ed7ed8",
        "00000001-0000-0778-01d2-c273a7966030-015bc3ed7ed8",
        "00000001-0000-12f8-01d2-c273a7ac0cb4-015bc3ed7ed8",
        "00000001-0000-12f8-01d2-c273a7ac0cb4-015bc3ed7ed8",
        "00000001-0000-121c-01d2-c273a7882eec-015bc3ed7ed8",
        "00000001-0000-121c-01d2-c273a7882eec-015bc3ed7ed8"
      ]
    },
    {
      "name": "PREPREPREchrome.exePOSTPOSTPOST",
      "ids": [
        "00000001-0000-1028-01d2-c24179cca1b8-015bc2a3ebe8",
        "00000001-0000-0650-01d2-c273a7ba8b36-015bc3ed7ed8",
        "00000001-0000-020c-01d2-c273a79d8c63-015bc3ed7ed8",
        "00000001-0000-08dc-01d2-c273a7b337f2-015bc3ed7ed8",
        "00000001-0000-1234-01d2-c273a77198f9-015bc3ed7ed8",
        "00000001-0000-0e4c-01d2-c273a780b4a2-015bc3ed7ed8",
        "00000001-0000-12fc-01d2-c273a7c1de71-015bc3ed7ed8",
        "00000001-0000-0778-01d2-c273a7966030-015bc3ed7ed8",
        "00000001-0000-12f8-01d2-c273a7ac0cb4-015bc3ed7ed8",
        "00000001-0000-121c-01d2-c273a7882eec-015bc3ed7ed8"
      ]
    }
  ],
  "facets": {},
  "results": [
    {
      "process_md5": "92b29e6be97f5b2c5894904d1447bbfe",
      "sensor_id": 1,
      "filtering_known_dlls": false,
      "modload_count": 0,
      "parent_unique_id": "00000001-0000-0ee8-01d2-7292dd56b66f-000000000001",
      "cmdline": "\"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe\" --type=utility --lang=en-US --no-sandbox --service-request-channel-token=8EEC283107F82FAA8460327787795CD2 --mojo-platform-channel-handle=4540 /prefetch:8",
      "last_update": "2017-05-01T06:09:22.081Z",
      "id": "00000001-0000-1028-01d2-c24179cca1b8",
      "parent_name": "chrome.exe",
      "parent_md5": "000000000000000000000000000000",
      "group": "default group",
      "parent_id": "00000001-0000-0ee8-01d2-7292dd56b66f",
      "hostname": "win-ia9nq1gn8oi",
      "filemod_count": 2,
      "start": "2017-05-01T06:09:21.928Z",
      "comms_ip": -1407842931,
      "regmod_count": 0,
      "interface_ip": -1407842931,
      "process_pid": 4136,
      "username": "WIN-IA9NQ1GN8OI\\bit9rad",
      "terminated": true,
      "emet_config": "",
      "process_name": "chrome.exe",
      "emet_count": 0,
      "last_server_update": "2017-05-01T06:12:54.386Z",
      "path": "c:\\program files (x86)\\google\\chrome\\application\\chrome.exe",
      "netconn_count": 0,
      "parent_pid": 3816,
      "crossproc_count": 0,
      "segment_id": 1493619174376,
      "host_type": "workstation",
      "processblock_count": 0,
      "os_type": "windows",
      "childproc_count": 0,
      "unique_id": "00000001-0000-1028-01d2-c24179cca1b8-015bc2a3ebe8"
    }
  ],
  "tagged_pids": {},
  "elapsed": 0.043354034423828125,
  "start": 0,
  "comprehensive_search": true,
  "incomplete_results": false,
  "filtered": {}
}

Faceting

The process search URL also supports faceting. Faceted search allows you to quickly filter through large collections of data by extracting the unique values from a group of fields. The EDR UI includes facet information for process and binary searches in the grey shaded box above the results list. Similarly, the API provides the ability to retrieve facet information through the Process API. Faceting can be combined with queries; by combining a process query with faceting, you can determine answers to questions such as “when do users most often launch Microsoft Word?”

The supported fields for facet search are:

process_md5: the top unique process_md5s for the processes matching the search
hostname: the top unique hostnames matching the search
group: the top unique host groups for hosts matching this search
path_full: the top unique paths for the processes matching this search
parent_name: the top unique parent process names for the processes matching this search
process_name: the top unique process names for the processes matching this search
host_type: the distribution of host types matching this search: one of workstation, server, domain_controller
hour_of_day: the distribution of process start times by hour of day in computer local time
day_of_week: the distribution of process start times by day of week in computer local time
start: the distribution of process start times by day for the last 30 days
username_full: the username context associated with the process

To request a facet search, submit a request to the Process API with at least two parameters: first, set the facet query parameter to true. Then, indicate the list of fields that you want to query for facets through a set of facet.field query parameters. Each facet.field parameter is set to one of the values above (for example, hostname). Make sure to set the rows parameter to 0 unless you want to retrieve the list of results for the query as well as the facet information.

The return value from the facet search is the top 200 key, value and percentage for the unique set of results matching the search query. If there are more than 200 unique values for the selected facets, the results will be truncated to 200. This limit cannot be adjusted via the API.

Return Facet Object

The facets object is a list of dictionaries with the following keys. Each key is a list of facet results objects that contain the key, value, and percentage information for each unique result of a given facet.

Each facet result object has three values:

name: the facet value
value: the count of occurrences of this value
percent: count / max(count) - the ratio of this value to the largest value in the result set
ratio: count / sum(count) - the ratio of this value to the sum of all values in the result set

A complete example to answer “when do users most often launch Microsoft Word?":

$ curl "http://192.168.206.151/api/v1/process?q=process_name:winword.exe&facet=true&facet.field=hour_of_day&rows=0"

{
  "terms": [
    "process_name:winword.exe"
  ],
  "total_results": 4,
  "highlights": [],
  "facets": {
    "hour_of_day": [
      {
        "percent": 100,
        "ratio": "50.0",
        "name": "16",
        "value": 2
      },
      {
        "percent": 50,
        "ratio": "25.0",
        "name": "15",
        "value": 1
      },
      {
        "percent": 50,
        "ratio": "25.0",
        "name": "17",
        "value": 1
      }
    ]
  },
  "results": [],
  "tagged_pids": {},
  "elapsed": 0.015702009201049805,
  "start": 0,
  "filtered": {
    "hour_of_day": []
  }
}

Process Summary

/api/v1/process/(process_id)/(segment_id)

Gets basic process information for segment (segment_id) of process (process_id)

Supports: GET

Parameters

process_id: REQUIRED the internal CB process id; this is the id field in search results
segment_id: REQUIRED the process segment id, the segment_id field in search results.

Returns

A JSON object with the following structure:

process: a process summary object with metadata for the selected process
siblings: a list of process summary objects for the first 15 sibiling processes
children: a list of process summary objects for each child process
parent: a process summary object with metadata for the parent process

Each process summary object contains the following structure:

process_md5: the MD5 of the executable backing this process
sensor_id: the sensor id of the host this process executed on
group: the sensor group the sensor was assigned to
parent_id: the Carbon Black process id of the parent process
process_name: the name of this process, e.g., svchost.exe
path: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.exe
last_update: the time of the last event received from this process, as recorded by the remote host
start: the start time of this process, as recorded by the remote host
hostname: the hostname of the computer this process executed on
id: the internal CB process id of this process
segment_id: the segment id of this process
os_type: operating system type of the computer for this process; one of windows, linux, osx

A complete example:

GET http://192.168.206.154/api/v1/process/2032659773721368929/1

{
  "process": {
    "process_md5": "517110bd83835338c037269e603db55d",
    "sensor_id": 2,
    "group": "Default Group",
    "start": "2013-09-19T22:07:07Z",
    "process_name": "taskhost.exe",
    "segment_id": 1,
    "last_update": "2013-09-19T22:09:07Z",
    "cmdline": "taskhost.exe $(arg0)",
    "hostname": "WIN-EP7RMLTCLAJ",
    "parent_id": "5856845119039539348",
    "path": "c:\\windows\\system32\\taskhost.exe",
    "id": "2032659773721368929",
    "os_type": "windows"
  },
  "siblings": [
    {
      "process_md5": "c78655bc80301d76ed4fef1c1ea40a7d",
      "sensor_id": 2,
      "group": "Default Group",
      "parent_id": "5856845119039539348",
      "process_name": "svchost.exe",
      "segment_id": 1,
      "last_update": "2013-09-19T22:34:49Z",
      "start": "2013-09-10T04:10:07Z",
      "hostname": "WIN-EP7RMLTCLAJ",
      "path": "c:\\windows\\system32\\svchost.exe",
      "id": "5286285292765095481",
      "os_type": "windows"
    },
  ],
  "children": [],
  "parent": {
    "process_md5": "24acb7e5be595468e3b9aa488b9b4fcb",
    "sensor_id": 2,
    "group": "Default Group",
    "parent_id": "4245649408199694328",
    "process_name": "services.exe",
    "segment_id": 1,
    "last_update": "2013-09-19T22:09:07Z",
    "start": "2013-09-10T04:09:51Z",
    "hostname": "WIN-EP7RMLTCLAJ",
    "path": "c:\\windows\\system32\\services.exe",
    "id": "5856845119039539348",
    "os_type": "windows"
  }
}

Process Summary (No Siblings)

/api/v2/process/(process_id)/(segment_id)

Gets basic process information for segment (segment_id) of process (process_id) - without sibling process information. The v2 version of this API is faster as retrieving the sibling process information requires additional requests to the Solr datastore.

Supports: GET

Parameters

process_id: REQUIRED the internal CB process id; this is the id field in search results
segment_id: REQUIRED the process segment id, the segment_id field in search results. If the segment ID is 0, then summary information for the process is aggregated and returned (for example, the filemod_count will be the sum of all file modifications for all segments in the process)

Returns

A JSON object represnting the metadata associated with the process.

Process Segment Details

/api/v1/process/(process_id)/segment

Supports: GET

Parameters

process_id: REQUIRED the internal CB process id; this is the id field in search results

Returns

A JSON object with the following structure:

process: A dictionary containing:
- segments: A list of segments, each containing:
  - last_server_update: The last date/time when the server pushed events into this segment
  - event_counts: The number of events for each event type stored in this segment
  - unique_id: The full process ID + segment number associated with this event segment
  - last_update: The last event (represented in sensor date/time) stored in this segment
elapsed: The time spent by Solr executing this query

A complete example:

GET http://192.168.206.154/api/v1/process/00000001-0000-0ee8-01d2-7292dd56b66f/segment

{
  "process": {
    "segments": [
      {
        "last_server_update": "2017-05-01T02:42:59.072Z",
        "event_counts": {
          "netconn": 2,
          "filemod": 76,
          "crossproc": 3
        },
        "unique_id": "00000001-0000-0ee8-01d2-7292dd56b66f-015bc1e3ae46",
        "last_update": "2017-05-01T02:43:27.865Z"
      },
      {
        "last_server_update": "2017-05-01T17:55:30.992Z",
        "event_counts": {
          "childproc": 11,
          "netconn": 1,
          "crossproc": 1,
          "filemod": 58,
          "regmod": 1,
          "modload": 1
        },
        "unique_id": "00000001-0000-0ee8-01d2-7292dd56b66f-015bc5272e1b",
        "last_update": "2017-05-01T17:55:48.606Z"
      },
      {
        "last_server_update": "2017-05-01T17:56:43.457Z",
        "event_counts": {
          "childproc": 3
        },
        "unique_id": "00000001-0000-0ee8-01d2-7292dd56b66f-015bc5284937",
        "last_update": "2017-05-01T17:55:44.975Z"
      }
    ]
  },
  "elapsed": 0.0039560794830322266
}

Process Event Details

/api/v1/process/(process_id)/(segment_id)/event
/api/v2/process/(process_id)/(segment_id)/event (introduced in EDR 5.1)
/api/v3/process/(process_id)/(segment_id)/event (introduced in EDR 5.2)
/api/v4/process/(process_id)/(segment_id)/event (introduced in EDR 6.1)

Gets the events for the process with CB process id (process_id) and segment id (segment_id). There are slight differences in the returned payload between the v1, v2, v3, and v4 endpoints. These differences will be discussed in detail in the “Returns” section below.

Supports: GET

Parameters

process_id: REQUIRED the internal CB process id; this is the id field in search results
segment_id: REQUIRED the process segment id; this is the segment_id field in search results. If this is set to 0, the API will merge all segments in results (subject to CoreServicesMaxEventResultsPerProcess in cb.conf, set to 10,000 by default)
cb.event_start: OPTIONAL return events starting with this offset. If not provided, offset will be 0 (returns events starting from the beginning)
cb.event_count: OPTIONAL. If not provided, number of returned events will be up to config value CoreServicesMaxEventResultsPerProcess

Returns

A JSON object with the following structure:

process: a process summary object with metadata and events for the selected process
elapsed: the clock time required to get this structure

The process object may contain the following entries.

process_md5: the MD5 of the executable backing this process
sensor_id: the sensor id of the host this process executed on
group: the sensor group the sensor was assigned to
parent_id: the Carbon Black process id of the parent process
process_name: the name of this process, e.g., svchost.exe
path: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.exe
cmdline: the command line of the process
last_update: the time of the last event received from this process, as recorded by the remote host
start: the start time of this process, as recorded by the remote host
hostname: the hostname of the computer this process executed on
id: the internal CB process id of this process
segment_id: the segment id of this process
regmod_complete: a pipe-delimited list of regmod strings
filemod_complete: a pipe-delimited list of filemod strings
modload_complete: a pipe-delimited list of modload strings
netconn_complete: a pipe-delimited list of netconn strings (changed in v2)
childproc_complete: a pipe-delimited list of childproc strings (changed in v3)
crossproc_complete: a pipe-delimited list of crossproc string
os_type: operating system type of the computer for this process; one of windows, linux, osx

Each xxx_complete record is a string similar to:

2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll"

The pipe character (|) delimits the fields.

filemod_complete

"1|2013-09-16 07:11:58.000000|c:\\documents and settings\\administrator\\local settings\\temp\\hsperfdata_administrator\\3704|||false"

field 0: operation type, an integer 1, 2, 4 or 8
- 1: Created the file
- 2: First wrote to the file
- 4: Deleted the file
- 8: Last wrote to the file
field 1: event time
field 2: file path
field 3: if operation type (field 0) is 8, last write, this value is the md5 of the file after the last write
field 4: file type, if known, an integer
- 1: PE
- 2: Elf
- 3: UniversalBin
- 8: EICAR
- 16: OfficeLegacy
- 17: OfficeOpenXml
- 48: Pdf
- 64: ArchivePkzip
- 65: ArchiveLzh
- 66: ArchiveLzw
- 67: ArchiveRar
- 68: ArchiveTar
- 69: Archive7zip
field 5: boolean “true” if event is flagged as potential tamper attempt; “false” otherwise

modload_complete

2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll"

field 0: event time
field 1: MD5 of the loaded module
field 2: Full path of the loaded module

regmod_complete

"2|2013-09-19 22:07:07.000000|\\registry\\user\\s-1-5-19\\software\\microsoft\\sqmclient\\reliability\\adaptivesqm\\manifestinfo\\version"

field 0: operation type, an integer 1, 2, 4 or 8
- 1: Created the registry key
- 2: First wrote to the registry key
- 4: Deleted the key
- 8: Deleted the value
field 1: event time
field 3: the registry key path

netconn_complete

There are two different formats for netconn_complete. The v1 API returns an array of pipe delimited strings:

"2013-09-16 07:11:59.000000|-1979811809|80|6|dl.javafx.com|true"

field 0: event time
field 1: remote IP address as a 32-bit signed long (host byte order)
field 2: remote port
field 3: protocol: 6 is TCP, 17 is UDP
field 4: domain name associated with the IP address, from the client’s perspective at the time of the network connection
field 5: boolean “true” if the connection was outbound; “false” if the connection was inbound

The v2 API and newer return an array of JSON objects:

[{"domain": "login.live.com",
  "proto": 6,
  "local_port": 49240,
  "timestamp": "2017-01-11T16:20:04.892Z",
  "local_ip": 167772448,
  "direction": "true",
  "remote_port": 80,
  "remote_ip": -2080555708},
  ...
]

Where the protocol field is the same as above (6 for TCP, 17 UDP), and the IP addresses are expressed as 32-bit signed longs in host byte order.

The v4 version of this API introduces support for IPv6 addresses. The v4 API returns all IP addresses in the JSON objects as strings; IPv4 addresses will be sent as dotted quad strings instead of integers, and IPv6 addresses are represented as strings.

childproc_complete

There are two different formats for childproc_complete. The v1 and v2 APIs return an array of pipe delimited strings:

"2014-01-23 09:19:08.331|8832db0c-6b84-fc4b-0000-000000000001|51138beea3e2c21ec44d0932c71762a8|c:\windows\system32\rundll32.exe|6980|true|false"

field 0: event time
field 1: unique_id of the child process
field 2: md5 of the child process
field 3: path of the child process
field 4: PID of child process
field 5: boolean “true” if child process started; “false” if terminated
field 6: boolean “true” if event is flagged as potential tamper attempt; “false” otherwise

The v3 API and newer return an array of JSON objects:

[{"userName": "",
  "processId": "00000003-0000-0178-01d2-6c44464bec2f-00000001",
  "end": "2017-01-11T19:57:44.066000Z",
  "commandLine": "",
  "pid": 376,
  "is_suppressed": false,
  "is_tampered": false,
  "path": "c:\\windows\\system32\\taskeng.exe",
  "type": "end",
  "md5": "16c467fe69bfcffb7568271f23217821"},
  ...
]

The new JSON object is similar to the old pipe delimited string, with one important exception. EDR 5.2 introduced the concept of suppressed processes. To reduce the load on the server associated with large numbers of “empty” processes (processes with no events other than modload events), EDR 5.2 no longer produces process documents for these “empty” processes by default.

Processes that have been eliminated will still be tracked as a child process of the parent process, with an entry in the childproc_complete array with the is_suppressed value set to true. Non-suppressed processes as seen above will have empty userName and commandLine values, as these can be obtained from the process document itself. Suppressed processes will have non-empty values for the userName and commandLine keys.

crossproc_complete

"ProcessOpen|2014-01-23 09:19:08.331|00000177-0000-0258-01cf-c209d9f1c431|204f3f58212b3e422c90bd9691a2df28|c:\windows\system32\lsass.exe|1|2097151|false"

field 0: type of cross-process access: RemoteThread if remote thread creation; ProcessOpen if process handle open with access privileges
field 1: event time
field 2: unique_id of the targeted process
field 3: md5 of the targeted process
field 4: path of the targeted process
field 5: sub-type for ProcessOpen, “1” for handle open to process; “2” for handle open to thread in process
field 6: requested access priviledges
field 7: boolean “true” if event is flagged as potential tamper attempt; “false” otherwise

A complete example:

GET http://192.168.206.154/api/v1/process/2032659773721368929/1/event

{"process":
  {"process_md5": "517110bd83835338c037269e603db55d",
  "sensor_id": 2,
  "group": "Default Group",
  "start": "2013-09-19T22:07:07Z",
  "process_name": "taskhost.exe",
  "segment_id": 1,
  "os_type": "windows",
  "regmod_complete": [
        "2|2013-09-19 22:07:07.000000|\\registry\\user\\s-1-5-19\\software\\microsoft\\sqmclient\\reliability\\adaptivesqm\\manifestinfo\\version",
        "2|2013-09-19 22:09:07.000000|\\registry\\machine\\software\\microsoft\\reliability analysis\\rac\\wmilasttime"
        ],
  "parent_id": "5856845119039539348",
  "cmdline": "taskhost.exe $(arg0)",
  "filemod_complete": [
        "2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racmetadata.dat|",
        "2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4475.tmp|",
        "2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4486.tmp|",
        "2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racwmidatabookmarks.dat|",
        "2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\publisheddata\\racwmidatabase.sdf|",
        "4|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4486.tmp|",
        "2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racdatabase.sdf|",
        "4|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4475.tmp|"
        ],
  "hostname": "WIN-EP7RMLTCLAJ",
  "modload_complete": [
        "2013-09-19 22:07:07.000000|517110bd83835338c037269e603db55d|c:\\windows\\system32\\taskhost.exe",
        "2013-09-19 22:07:07.000000|3556d5a8bf2cc508bdab51dec38d7c61|c:\\windows\\system32\\ntdll.dll",
        "2013-09-19 22:07:07.000000|7a6326d96d53048fdec542df23d875a0|c:\\windows\\system32\\kernel32.dll",
        "2013-09-19 22:07:07.000000|9c75cb8b98610f0cd85d99bb5876308b|c:\\windows\\system32\\sqlcese30.dll",
        "2013-09-19 22:07:07.000000|e5744d18c88737c6356d0a8d6d49d512|c:\\windows\\system32\\sqlceqp30.dll",
        "2013-09-19 22:07:07.000000|021287c2050fd5db4a8b084e2c38139c|c:\\windows\\system32\\winsatapi.dll",
        "2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll",
        "2013-09-19 22:07:07.000000|da1b7075260f3872585bfcdd668c648b|c:\\windows\\system32\\dwmapi.dll",
        "2013-09-19 22:07:07.000000|497bfeddaf3950dd909c3b0c5558a25d|c:\\windows\\winsxs\\amd64_microsoft.windows.gdiplus_6595b64144ccf1df_1.1.7601.17514_none_2b24536c71ed437a\\gdiplus.dll",
        "2013-09-19 22:07:07.000000|5d8e6c95156ed1f79a63d1eade6f9ed5|c:\\windows\\system32\\setupapi.dll",
        "2013-09-19 22:07:07.000000|2a86e54b441ad41557f75dc5609b9793|c:\\windows\\system32\\sspicli.dll",
        "2013-09-19 22:07:07.000000|d6f630c1fd7f436316093ae500363b19|c:\\windows\\system32\\xmllite.dll"
      ],
  "path": "c:\\windows\\system32\\taskhost.exe",
  "last_update": "2013-09-19T22:09:07Z",
  "id": "2032659773721368929"
  },
  "elapsed": 0.0126001834869
}

Process Preview

/api/v1/process/(process_id)/(segment_id)/preview?q=(query)

Process preview. Requires process_id and segment id.

Supports: GET

Parameters

process_id: REQUIRED the internal CB process id, the id field in search results
segment_id: REQUIRED the process segment id; this is the segment_id field in search results.
query: OPTIONAL a process query string. If present, preview results will highlight matching terms

Returns

A process preview structure with the following fields:

process_md5: the MD5 of the executable backing this process
sensor_id: the sensor id of the host this process executed on
group: the sensor group the sensor was assigned to
process_name: the name of this process, e.g., svchost.exe
path: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.exe
last_update: the time of the last event received from this process, as recorded by the remote host
start: the start time of this process, as recorded by the remote host
hostname: the hostname of the computer this process executed on
id: the internal CB process id of this process
segment_id: the segment id of this process
regmod_complete: a pipe-delimited summary list of regmod strings (see spec above)
filemod_complete: a pipe-delimited summary list of filemod strings (see spec above)
modload_complete: a pipe-delimited summary list of modload strings (see spec above)
netconn_complete: a pipe-delimited summary list of netconn strings (see spec above)
childproc_complete: a pipe-delimited list of summary childproc strings (see spec above)
crossproc_complete: a pipe-delimited list of summary crossproc string (see spec above)
modload_count: the total count of modules loaded in this process
regmod_count: the total count of registry modifications in this process
filemod_count: the total count of file modifications in this process
netconn_count: total count of network connections in this process
childproc_count: the total count of child processes launched by this process
crossproc_count: the total count of cross process events launched by this process
os_type: operating system type of the computer for this process; one of windows, linux, osx

If a query string is provided, the endpoint will highlight all matching strings. Highlighted results will be surrounded with PREPREPRE and POSTPOSTPOST to designate the start and end of a matching substring.

Where the full process API endpoint will return all xxx_complete records in the process (possibly 10s of thousands), the preview endpoint will have 10s of events for this process.

A complete example:

GET http://192.168.206.132/api/v1/process/7078511340675742078/1/preview/?q=windows
{
  "parent_name": "",
  "hostname": "J-8205A0C27A0C4",
  "group": "Default Group",
  "process_md5": "5e7f3968069d32b26af0d7af0ec5dd97",
  "netconn_count": 1,
  "process_name": "svchost.exe",
  "last_update": "2013-10-07T15:07:09Z",
  "cmdline": "\"c:\\docume~1\\admini~1\\locals~1\\temp\\rad17929.tmp\\svchost.exe\" ",
  "start": "2013-10-07T15:07:09Z",
  "sensor_id": 1,
  "modload_count": 15,
  "modload_complete": [
    "2013-10-07 15:07:09.000000|27d9ed8cb8b62d1e0a8e5ace6cf52e2f|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ntdll.dll",
    "2013-10-07 15:07:09.000000|c24b983d211c34da8fcc1ac38477971d|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\kernel32.dll",
    "2013-10-07 15:07:09.000000|355edbb4d412b01f1740c17e3f50fa00|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\msvcrt.dll",
    "2013-10-07 15:07:09.000000|bab489a5fe26f2d0c910cf7af7e4cf92|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\advapi32.dll",
    "2013-10-07 15:07:09.000000|b979d9d1c8073da21a7f80345f306a1d|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\rpcrt4.dll",
    "2013-10-07 15:07:09.000000|7459c16cc3ef4651cab7c9260e43fc58|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\secur32.dll",
    "2013-10-07 15:07:09.000000|67156d5a9ac356dc99d7bccb388e3316|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\wsock32.dll",
    "2013-10-07 15:07:09.000000|2ccc474eb85ceaa3e1fa1726580a3e5a|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ws2_32.dll",
    "2013-10-07 15:07:09.000000|9789e95e1d88eeb4b922bf3ea7779c28|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ws2help.dll",
    "2013-10-07 15:07:09.000000|b4138e99236f0f57d4cf49bae98a0746|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\mswsock.dll"
  ],
  "path": "c:\\documents and settings\\administrator\\local settings\\temp\\rad17929.tmp\\svchost.exe",
  "regmod_count": 0,
  "filemod_count": 0,
  "segment": "",
  "id": "7078511340675742078",
  "unique_id": "623bec8f-8f8d-397e-0000-000000000001",
  "os_type": "windows"
}

Binary Data

Binary Search

/api/v1/binary

Binary search. Parameters passed as query string.

Supports: GET

Parameters

q: REQUIRED Query string. Accepts the same data as the search box on the Binary Search page. See the Query overview for details on the query syntax.
rows: OPTIONAL Return this many rows, 10 by default.
start: OPTIONAL Start at this row, 0 by default.
sort: OPTIONAL Sort rows by this field and order. server_added_timestamp desc by default.
facet: OPTIONAL Return facet results. ‘false’ by default, set to ‘true’ for facets.
facet.field: OPTIONAL facet field name to return. Multiple facet.field parameters can be specified in a query.

Returns

JSON object with the following elements:

results: a list of matching binaries (see below for binary object)
terms: a list of strings, each representing a token as parsed by the query parser
total_results: number of matching binaries
start: index of first row
elapsed: clock time elapsed resolving this request
highlights: a list of highlight objects matching the query string. Format the same as the process event object.
facets: a list of facet entries if requested. (see below for facet object)

Binary Object

A binary object contains the following fields:

md5: the md5 hash of this binary
server_added_timestamp: the first time this binary was received on the server in the server GMT time
orig_mod_len: Filesize in bytes
copied_mod_len: Bytes copied from remote host, if file is > 25MB this will be less than orig_mod_len
observed_filename: The set of unique filenames this binary has been seen as
is_executable_image: ‘true’ or ‘false’ - ‘true’ if an EXE
is_64bit: ‘true’ or ‘false’ - ‘true’ if x64
product_version: If present, Product version from FileVersionInformation
product_name: If present, Product name from FileVersionInformation
file_Version: If present, File version from FileVersionInformation
company_name: If present, Company name from FileVersionInformation
internal_name: If present, Internal name from FileVersionInformation
product_name: If present, Product name from FileVersionInformation
legal_copyright: If present, Legal copyright from FileVersionInformation
legal_trademark: If present, Legal trademark from FileVersionInformation
file_desc: If present, File description from FileVersionInformation
original_filename: If present, Original filename from FileVersionInformation
private_build: If present, Private build from FileVersionInformation
special_build: If present, Special build from FileVersionInformation
signed: Digital signature status: One of Signed, Unsigned, Expired, Bad Signature, Invalid Signature, Invalid Chain, Untrusted Root, Explicit Distrust
digsig_result: Digital signature status: One of Signed, Unsigned, Expired, Bad Signature, Invalid Signature, Invalid Chain, Untrusted Root, Explicit Distrust
digsig_result_code: HRESULT_FROM_WIN32 for the result of the digital signature operation via WinVerifyTrust
digsig_sign_time: If signed, the timestamp of the signature in GMT
digsig_publisher: If signed and present, the publisher name
digsig_prog_name: If signed and present, the program name
digsig_issuer: If signed and present, the issuer name
digsig_subject: If signed and present, the subject
alliance_score_virustotal: If enabled and the hit count > 1, the number of VirusTotal hits for this md5
os_type: operating system type of this binary; one of windows, linux, osx
host_count: count of unique endpoints which have ever reported this binary

Faceting

The binary search URL also supports faceting. Faceted search allows you to quickly filter through large collections of data by extracting the unique values from a group of fields. The EDR UI includes facet information for process and binary searches in the grey shaded box above the results list. Similarly, the API provides the ability to retrieve facet information through the Process API. Faceting can be combined with queries.

The supported fields for facet search are:

product_name_facet: the top unique product names for the binaries matching the search
file_version_facet: the top unique file versions for the binaries matching the search
alliance_score_virustotal: the distribution of VirusTotal scores for binaries matching the search
digsig_result: the distribution of signature status results for binaries matching the search
company_name_facet: the top unique company names for the binaries matching the search
digsig_publisher_facet: the top unique publisher names for the binaries matching the search
product_name_facet: the top unique company anmes for the binaries matching the search
digsig_sign_time: the distribution of signature times per month for the last 48 months for binaries matching the search
server_added_timestamp: the distribution of server_added_timestamps per day for the last 30 days
observed_filename_facet: the top unique observed filenames for the binaries matching the search
host_count
hostname
group

Return Facet Object

Each facet result object has three values:

name: the facet value
value: the count of occurrences of this value
percent: count / max(count) - the ratio of this value to the largest value in the result set
ratio: count / sum(count) - the ratio of this value to the sum of all values in the result set

A complete example:

GET http://192.168.206.151/api/binary?q=notepad.exe

{
  "total_results": 1,
  "facets": {},
  "elapsed": 0.046832799911499023,
  "start": 0,
  "results": [
    {
      "md5": "F2C7BB8ACC97F92E987A2D4087D021B1",
      "digsig_result": "Signed",
      "observed_filename": [
        "c:\\windows\\system32\\notepad.exe"
      ],
      "product_version": "6.1.7600.16385",
      "signed": "Signed",
      "digsig_sign_time": "2009-07-14T10:17:00Z",
      "orig_mod_len": 193536,
      "is_executable_image": true,
      "is_64bit": true,
      "digsig_publisher": "Microsoft Corporation",
      "file_version": "6.1.7600.16385 (win7_rtm.090713-1255)",
      "company_name": "Microsoft Corporation",
      "internal_name": "Notepad",
      "product_name": "Microsoft\u00ae Windows\u00ae Operating System",
      "digsig_result_code": "0",
      "timestamp": "2013-08-16T11:26:48.321Z",
      "copied_mod_len": 193536,
      "server_added_timestamp": "2013-08-16T11:26:48.321Z",
      "legal_copyright": "\u00a9 Microsoft Corporation. All rights reserved.",
      "original_filename": "NOTEPAD.EXE",
      "file_desc": "Notepad",
      "os_type": "windows"
    }
  ],
  "terms": [
    "notepad.exe"
  ],
  "highlights": [
    {
      "name": "PREPREPRENOTEPAD.EXEPOSTPOSTPOST",
      "ids": [
        "F2C7BB8ACC97F92E987A2D4087D021B1"
      ]
    },
    {
      "name": "c:\\windows\\system32\\PREPREPREnotepad.exePOSTPOSTPOST",
      "ids": [
        "F2C7BB8ACC97F92E987A2D4087D021B1"
      ]
    }
  ],
}

Download Binary

/api/v1/binary/(md5)

Download the binary with this md5 hash.

Supports: GET

Parameters

md5: REQUIRED the md5 hash of the binary

Returns A zipfile with the binary bytes and a text file with metadata.

Retrieve Binary Icon

/api/v1/binary/(md5)/icon

Returns the icon for the binary with the provided md5

Supports: GET

Parameters

md5: REQUIRED the md5 of the binary

Returns A PNG with the icon. If the icon is not found, it returns the default Windows icon.

Retrieve Binary Metadata

/api/v1/binary/(md5)/summary

Returns the metadata for the binary with the provided md5

Supports: GET

Parameters

md5: REQUIRED the md5 of the binary

Returns

A structure with the following fields:

md5: the md5 hash of this binary
server_added_timestamp: the first time this binary was received on the server in the server GMT time
orig_mod_len: Filesize in bytes
copied_mod_len: Bytes copied from remote host, if file is > 25MB this will be less than orig_mod_len
observed_filename: A list of strings, one per unique filename this binary has been seen as
is_executable_image: ‘true’ or ‘false’ - ‘true’ if an EXE
is_64bit: ‘true’ or ‘false’ - ‘true’ if x64
product_version: If present, Product version from FileVersionInformation
product_name: If present, Product name from FileVersionInformation
file_Version: If present, File version from FileVersionInformation
company_name: If present, Company name from FileVersionInformation
internal_name: If present, Internal name from FileVersionInformation
product_name: If present, Product name from FileVersionInformation
legal_copyright: If present, Legal copyright from FileVersionInformation
legal_trademark: If present, Legal trademark from FileVersionInformation
file_desc: If present, File description from FileVersionInformation
original_filename: If present, Original filename from FileVersionInformation
private_build: If present, Private build from FileVersionInformation
special_build: If present, Special build from FileVersionInformation
signed: Digital signature status: One of Signed, Unsigned, Expired, Bad Signature, Invalid Signature, Invalid Chain, Untrusted Root, Explicit Distrust
digsig_result: Digital signature status: One of Signed, Unsigned, Expired, Bad Signature, Invalid Signature, Invalid Chain, Untrusted Root, Explicit Distrust
digsig_result_code: HRESULT_FROM_WIN32 for the result of the digital signature operation via WinVerifyTrust
digsig_sign_time: If signed, the timestamp of the signature in GMT
digsig_publisher: If signed and present, the publisher name
digsig_prog_name: If signed and present, the program name
digsig_issuer: If signed and present, the issuer name
digsig_subject: If signed and present, the subject
alliance_score_virustotal: If enabled and the hit count >= 1, the number of VirusTotal hits for this md5
alliance_score_srs: If enabled and available, the Carbon Black Software Reputation Service (SRS) score, normalized to a CB score
alliance_score_tis: If enabled and available, the Carbon Black Threat Indicators Service (TIS) score, normalized to a CB score
alliance_score_*: 0 or more other scores, applied by configuring feeds.
endpoint: list of 0 or more hostname,sensorid tuples on which this binary was observed. The | character serves as the delimiter between the hostname and the sensorid.
group: list of 0 or more sensor groups (by name) in which this binary was observed
os_type: operating system type of the computer for this process; one of windows, linux, osx

A complete example:

GET http://192.168.206.154/api/binary/1C8B787BAA52DEAD1A6FEC1502D652f0/summary

{
  "product_version_facet": "8.00.7600.16385",
  "digsig_result": "Signed",
  "observed_filename": [
    "c:\\windows\\system32\\mshtml.dll"
  ],
  "product_version": "8.00.7600.16385",
  "product_name_facet": "Windows\u00ae Internet Explorer",
  "signed": "Signed",
  "digsig_sign_time": "2010-11-21T03:36:00Z",
  "orig_mod_len": 8988160,
  "is_executable_image": false,
  "is_64bit": true,
  "observed_filename_facet": [
    "c:\\windows\\system32\\mshtml.dll"
  ],
  "file_version_facet": "8.00.7600.16385 (win7_rtm.090713-1255)",
  "digsig_publisher": "Microsoft Corporation",
  "file_version": "8.00.7600.16385 (win7_rtm.090713-1255)",
  "company_name": "Microsoft Corporation",
  "internal_name": "MSHTML",
  "_version_": 1446430562211332096,
  "product_name": "Windows\u00ae Internet Explorer",
  "digsig_result_code": "0",
  "timestamp": "2013-09-17T13:14:37.636Z",
  "company_name_facet": "Microsoft Corporation",
  "copied_mod_len": 8988160,
  "server_added_timestamp": "2013-09-17T13:14:37.636Z",
  "md5": "1C8B787BAA52DEAD1A6FEC1502D652F0",
  "legal_copyright": "\u00a9 Microsoft Corporation. All rights reserved.",
  "digsig_publisher_facet": "Microsoft Corporation",
  "original_filename": "MSHTML.DLL.MUI",
  "file_desc": "Microsoft (R) HTML Viewer",
  "os_type": "windows",
  "group": [
    "Default Group",
    "Domain Controllers"
  ],
  "endpoint": [
    "DC01|17",
    "XP-KIOSK-32|1002",
    "XP-KIOSK-87|688"
  ]
}

Alerts

Search Alerts

/api/v2/alert

Alert search

Supports: GET, POST

Parameters

q: OPTIONAL Query string. Accepts the same data as the alert search box on the Triage Alerts page. See the Query overview for the query syntax.
rows: OPTIONAL Return this many rows, 10 by default.
start: OPTIONAL Start at this row, 0 by default.
sort: OPTIONAL Sort rows by this field and order.
facets: OPTIONAL Return facet results. ‘false’ by default, set to ‘true’ for facets.

Returns

JSON dictionary describing the alert search results

{
    "terms": [],
    "results": [
        {
            "username": "SYSTEM",
            "alert_type": "watchlist.hit.ingress.process",
            "sensor_criticality": 3,
            "modload_count": 58,
            "report_score": 1,
            "watchlist_id": "Binary_0545A3EB959QQQ4790D267BFB8C1ACA4",
            "sensor_id": 2,
            "feed_name": "virustotalconnector",
            "created_time": "2017-10-11T14:16:06.074Z",
            "report_ignored": false,
            "ioc_type": "md5",
            "watchlist_name": "Binary_0545A3EB959QQQ4790D267BFB8C1ACA4",
            "ioc_confidence": 0.5,
            "alert_severity": 0.675,
            "crossproc_count": 2,
            "group": "default group",
            "hostname": "win-559j1nqvfgj",
            "filemod_count": 0,
            "comms_ip": "192.119.22.22",
            "netconn_count": 0,
            "interface_ip": "192.168.22.2",
            "status": "Unresolved",
            "process_path": "c:\\program files (x86)\\google\\update\\googleupdate.exe",
            "description": "[1 / 66] VirusTotal report for 0545A3EB959CFA4790D267BFB8C1ACA4",
            "process_name": "googleupdate.exe",
            "process_unique_id": "00000002-0000-0cdc-01d3-429b633fda36-015f0bcadb87",
            "process_id": "00000002-0000-0cdc-01d3-429b633fda36",
            "link": "https://www.virustotal.com/file/69061e33acb7587d773d05000390f9101f71dfd6eed7973b551594eaf3f04193/analysis/1507720618/",
            "_version_": 1580970924950159360,
            "regmod_count": 7,
            "md5": "0545a3eb959cfa4790d267bfb8c1aca4",
            "segment_id": 197843847,
            "total_hosts": "0",
            "feed_id": 24,
            "ioc_value": "0545a3eb959cfa4790d267bfb8c1aca4",
            "os_type": "windows",
            "childproc_count": 4,
            "unique_id": "611b825e-f555-4841-91fe-39cb15e05106",
            "feed_rating": 3
        }
    ],
    "elapsed": 0.007166147232055664,
    "comprehensive_search": true,
    "all_segments": true,
    "total_results": 350,
    "highlights": [],
    "facets": {},
    "start": 0,
    "incomplete_results": false,
    "filtered": {}
}

Update/Resolve Alerts

POST /api/v1/alert/(alertid)

Alert update and resolution

Supports: POST

Parameters

unique_id: REQUIRED Unique ID of alert to update
status: REQUIRED Status of the alert, as a string

Returns

JSON dictionary describing alert

Bulk Update Alerts

POST /api/v1/alerts

Updating Alerts requires an API key with Global Administrator privileges. Multiple Alerts can be updated in bulk using the same call.

The only property that can be modified in a threat report is the is_ignored property. Setting is_ignored to True for an Alert carries through to the threat report that generated the Alert. Any further hits on IOCs contained within that report will no longer trigger an Alert.

Payload

To modify multiple alerts at once, either specify the list of Alert IDs in the ids dictionary, or submit a query (using the URL-encoded version of the query string) in the query string.

Specify the operation to perform by using either the set_ignored, requested_status, or assigned_to keys. If the assigned_to key is present, then the requested_status should be provided as well.

The possible values for requested_status are Resolved, Unresolved, In Progress, or False Positive.

For example:

    {
      "query": "cb.urlver=1&cb.fq.status=unresolved&sort=alert_severity%20desc&rows=10",
      "alert_ids": ["id1", "id2", ...]],
      "requested_status": "Resolved",
      "set_ignored": true,
      "assigned_to": "ahnold"
    }

Returns

HTTP 200 result code if changes applied successfully.

Administrative APIs

Server License

/api/v1/license

License status and application

Supports: GET, POST

Parameters

Carbon Black-provided license (POST)

Returns

A GET returns the current license status, as defined below:

A license status dictionary has the following structure:

license_valid: boolean indication as to if the licence is valid. A valid license may be expired or unexpired.
license_end_date: YYYY-MM-DD date on which the license expires
licensed_sensor_count: number of sensors that can be used with this server while staying compliant with license.
server_token: unique identifier for this particular server instance
license_expired: boolean indicator as to if the license is expired
licensed_sensor_count_exceeded: boolean indicator as to if the server is currently servicing more sensors than it is licensed for
actual_sensor_count: count of sensors serviced during previous day (midnight to midnight)
license_request_block: an opaque request block to be provided to Carbon Black for license renewal

App Control Integration

/api/v1/settings/global/platformserver

Get and set the configuration details of the Carbon Black App Control server.
These details are used for CB Enterprise Response Server integration with the App Control Server.

Supports: GET, POST

Parameters, Returns

A GET returns a JSON dictionary as defined below. A POST accepts a JSON dictionary with one or more keys as defined below.

server_url: OPTIONAL the base server IP or DNS name. The protocol and the URI are not included.
ssl_certificate_verify: OPTIONAL indication as to if Carbon Black server should verify the Platform Server SSL certificate; valid values are ‘true’ and ‘false’
watchlist_export: OPTIONAL indication as to if the Carbon Black server should export, via HTTPS POST, watchlist hits to the Platfrom Server; valid values are ‘true’ and ‘false’
auth_token: OPTIONAL authorization token used by the Carbon Black server to authenticate against the Platform Server.

The auth_token field is never returned via HTTP GET for security purposes.

Banning

Ban Binary by Hash

/api/v1/banning/blacklist

Ban - prevent execution of a specified md5 hash

Supports: GET, POST

Provides a method to get all banned hashes or allows for creation of new banned hashes.

Returns

(GET /api/v1/banning/blacklist) returns a list of banned hashes, with each list entry describing one banned hash
(POST /api/v1/banning/blacklist)

A banned record contains the following structure

username: username who banned the record
text: text description of banned record
md5hash: the banned hash
block_count: total number of blocks on the banned list
last_block_sensor_id: the last sensor id which prevented the hash from executing
last_block_time: the last time the hash was blocked or prevented from being executed
timestamp: date and time the record was banned
last_block_hostname: last hostname to block this hash

A GET response example:

GET /api/v1/banning/blacklist

[
  {
    "username": "cb",
    "audit": [
      {
        "username": "cb",
        "timestamp": "2015-10-21 00:10:10.369349-07:00",
        "text": "Auto-Ban From Watchlist",
        "enabled": true,
        "user_id": 1
      }
    ],
    "text": "Auto-Ban From Watchlist",
    "md5hash": "35e664e41174ce70e910b85bcd685136",
    "block_count": 0,
    "user_id": 1,
    "last_block_sensor_id": null,
    "enabled": true,
    "last_block_time": null,
    "timestamp": "2015-10-21 00:10:10.369349-07:00",
    "last_block_hostname": null
  }
]

A POST request body example:

{
  "md5hash": "f41d8cd98f00b214e9800998ecf8427e",
  "text": "autoban from watchlist",
  "last_ban_time": "0",
  "ban_count": "0",
  "last_ban_host": "0",
  "enabled": "True"
}

Watchlists & Feeds

New to EDR 6.3

Two new API endpoints have been introduced as a replacement for /watchlist/action and /feed/action.

The old APIs are now deprecated. Our API examples should be updated to show use of new action_type API call instead, as UI is now using.

action_type is now specified as a key-word instead of a number:

Action to number mapping

0 | Email
1 | Syslog
2 | HTTPPost (unused by the new action_type API)
3 | Alert

Watchlist Operations

Watchlist enumeration, creation, modification, and deletion

Parameters

id: OPTIONAL the watchlist id

Using the optional ‘id’ parameter, a caller may create a watchlist with a specific, known id. This can be useful as the watchlist id is included as part of the underlying process or binary document and therefore can be used as as search criteria.

Returns

With no id parameter (GET /api/v1/watchlist) returns a list of watchlists, with each list entry describing one watchlist
With an id parameter (GET /api/v1/watchlist/<id>) returns the watchlist record for the matching id
With no id parameter (POST /api/v1/watchlist) returns the watchlist record for the newly created watchlist
With an id parameter (PUT /api/v1/watchlist/<id>) returns the watchlist record for the newly updated watchlist

A watchlist record has the following structure:

id: the id of this watchlist
alliance_id: the id of this watchlist on the Carbon Black Alliance server; this value is internal to Carbon Black
from_alliance: boolean indication as to if this watchlist was provided by the Carbon Black Alliance Server
date_added: the date this watchlist was created on this Enterprise Server
index_type: the type of watchlist. Valid values are ‘modules’ and ‘events’ for binary and process watchlists, respectively
last_hit: timestamp of the last time this watchlist triggered a match
last_hit_count: count of lifetime watchlist matches
name: name of this watchlist
search_query: the raw Carbon Black query that this watchlist matches

Get Watchlists

Retrieves a JSON array of all Watchlists.

Supports: GET

Request

GET <host>/api/v1/watchlist
GET https://test.carbonblack.io/api/v1/watchlist

Response

[
    {
        "last_execution_result": 0,
        "last_hit_count": 1,
        "description": null,
        "search_query": "cb.urlver=1&q=is_executable_image%3Afalse&sort=server_added_timestamp%20desc",
        "enabled": true,
        "search_timestamp": "2019-05-09T14:20:06.234Z",
        "name": "Newly Loaded Modules",
        "index_type": "modules",
        "last_execution_time_ms": "36",
        "date_added": "2016-07-12 19:19:35.874613+00:00",
        "total_hits": "57243",
        "group_id": -1,
        "total_tags": "57243",
        "id": "2",
        "last_hit": "2019-05-08 04:20:06.538442+00:00",
        "readonly": false
    }
]

Get Watchlist by ID

Get details for a single watchlist.

Supports: GET

Request

GET <host>/api/v1/watchlist/<id>
GET https://test.carbonblack.io/api/v1/watchlist/2

Response

[
    {
        "last_execution_result": 0,
        "last_hit_count": 1,
        "description": null,
        "search_query": "cb.urlver=1&q=is_executable_image%3Afalse&sort=server_added_timestamp%20desc",
        "enabled": true,
        "search_timestamp": "2019-05-09T14:20:06.234Z",
        "name": "Newly Loaded Modules",
        "index_type": "modules",
        "last_execution_time_ms": "36",
        "date_added": "2016-07-12 19:19:35.874613+00:00",
        "total_hits": "57243",
        "group_id": -1,
        "total_tags": "57243",
        "id": "2",
        "last_hit": "2019-05-08 04:20:06.538442+00:00",
        "readonly": false
    }
]

Create a new Watchlist

Creates a new Watchlist within EDR, if successful, it will respond with the ID of the new watchlist.

Supports: POST

Request

POST <host>/api/v1/watchlist
POST https://test.carbonblack.io/api/v1/watchlist/

Body

{
  "name":"sm-test-postman",
  "search_query":"q=process_name%3Achrome.exe",
  "description":"",
  "index_type":"events"
}

Response

{
    "id": 710
}

Update a Watchlist

Updates a Watchlist that is specified using ID. You can use the enabled parameter in the body to enable/disable the watchlist.

Note: The watchlist_id value will increase by one each time it is updated. For example, if you update a watchlist with a watchlist_id of 709, it will increment the watchlist_id to 710 when the PUT method is successful.

Supports: PUT

Request

PUT <host>/api/v1/watchlist/<id>
PUT https://test.carbonblack.io/api/v1/watchlist/709

Body

{
  "enabled":true,
  "description": "let's update the description",
  "search_query":"q=process_name%3Achrome.exe"
}

Response

{
    "result": "success"
}

Delete a Watchlist

Delete a Watchlist that is specified using ID.

Supports: DELETE

Request

DELETE https://test.carbonblack.io/api/v1/watchlist/709

Response

{
    "result": "success"
}

Get Watchlist Action Types

Retrieves a JSON array of actions that are enabled or disabled for a single watchlist.

Required permissions: Viewer in any group

Supports: GET

Request

GET <host>/api/v1/watchlist/<id>/action_type
GET https://test.carbonblack.io/api/v1/watchlist/2/action_type

Response

[
    {
        "enabled": false,
        "action_type": "email"
    },
    {
        "enabled": false,
        "action_type": "syslog"
    },
    {
        "enabled": true,
        "action_type": "alert"
    }
]

Get Specific Action for a Watchlist (id)

Retrieves current status (enabled or not) of the action_type specified for this watchlist for the current user.

Required permissions: Analyst in any group

Supports: GET

Request

GET <host>/api/v1/watchlist/<id>/action_type/<action>
GET https://test.carbonblack.io/api/v1/watchlist/2/action_type/email

Options for action_type: syslog, email, alert (this is not an exhaustive list, more options could be available).

Response

{
    "enabled": false
}

Change Specific Action Status for a Watchlist (id)

PUT will enable or disable a specific action_type for this watchlist and current user.

Required permissions: Analyst in any group

Supports: PUT

Request

PUT <host>/api/v1/watchlist/<id>/action_type/<action>
PUT https://test.carbonblack.io/api/v1/watchlist/2/action_type/email

Options for action_type: syslog, email, alert (this is not an exhaustive list, more options could be available).

Body

{
    "enabled":true
}

Response

{
    "result": "success"
}

Feed Operations

/api/v1/feed/(id)

Feed enumeration, creation, modification, and deletion

Supports: GET, PUT, POST, DELETE

Parameters

id: OPTIONAL the feed id

Returns

With no id parameter (GET /api/v1/feed) returns a list of configured feeds, with each list entry describing one feed
With no id parameter (POST /api/v1/feed) returns the feed record for the newly created feed
With an id parameter (PUT /api/v1/feed/<id>) returns the feed record for the newly updated feed

A feed record has the following structure:

provider_url: URL associated with the feed as a whole; this is a human-consumable link to more information about the feed provider and is not consumed by the Carbon Black server
display_name: Name of the feed as displayed in the Carbon Black web console
name: internal name of the feed; must be alphanumeric. used when searching e.g. alliance_score_feedname:[10 to *]
feed_url: url of the feed itself; must begin with one of file://, http://, or https://
enabled: boolean indicator as to if the feed is enabled
summary: human-consumable summary of the feed
tech_data: human-consumable technical summary of the feed
validate_server_cert: boolean indicator as to if the Carbon Black server should verify the feed server certificate. only applies to feeds provided via HTTPS
id: internal id of the feed; this id is used during feed modification and deletion
icon: base64-encoded icon representing the feed
manually_added: boolean indicator as to if the feed was added manually. If logical false, this means the feed was provided by the Carbon Black Alliance
order: a numeric hint as to the display order in the Carbon Black web console
use_proxy: boolean indicator as to if the Carbon Black server should use a web proxy when retrieving the feed contents

Get Feeds

Retrieves a JSON array of all Feeds.

Supports: GET

Request

GET <host>/api/v1/feed
GET https://test.carbonblack.io/api/v1/feed

Response

[
    {
        "provider_url": "https://www.bit9.com/solutions/cloud-services/",
        "ssl_client_crt": null,
        "local_rating": null,
        "requires_who": null,
        "icon_small": "",
        "id": 9,
        "category": "Bit9 + Carbon Black First Party",
        "display_name": "Bit9 Software Reputation Service Trust",
        "use_proxy": null,
        "feed_url": "https://api.alliance.carbonblack.com/feed/SRSTrust",
        "username": null,
        "validate_server_cert": null,
        "ssl_client_key": null,
        "manually_added": false,
        "password": null,
        "icon": "",
        "provider_rating": 3,
        "name": "SRSTrust",
        "tech_data": "It is necessary to share MD5s of observed binaries with the Carbon Black Alliance to use this feed",
        "requires": null,
        "enabled": true,
        "summary": "The Cb Reputation Trust feed provides a level of software trustworthness",
        "requires_what": null,
        "order": 2
    }
]

Get Feed by ID

Get details for a single feed.

Supports: GET

Request

GET <host>/api/v1/feed/<id>
GET https://test.carbonblack.io/api/v1/feed/9

Response

{
    "category": "Bit9 + Carbon Black First Party",
    "provider_url": "https://www.bit9.com/solutions/cloud-services/",
    "provider_rating": 3,
    "display_name": "Bit9 Software Reputation Service Trust",
    "name": "SRSTrust",
    "feed_url": "https://api.alliance.carbonblack.com/feed/SRSTrust",
    "requires_what": null,
    "use_proxy": null,
    "enabled": true,
    "summary": "The Cb Reputation Trust feed provides a level of software trustworthness",
    "tech_data": "It is necessary to share MD5s of observed binaries with the Carbon Black Alliance to use this feed",
    "local_rating": null,
    "requires_who": null,
    "validate_server_cert": null,
    "icon_small": "",
    "manually_added": false,
    "order": 2,
    "requires": null,
    "id": 9,
    "icon":""
}

Get Feed Action Types

Retrieves a JSON array of actions that are enabled or disabled for a single feed.

Required permissions: Viewer in any group

Supports: GET

Request

GET <host>/api/v1/feed/<id>/action_type
GET https://test.carbonblack.io/api/v1/feed/2/action_type

Response

[
    {
        "enabled": false,
        "action_type": "email"
    },
    {
        "enabled": true,
        "action_type": "syslog"
    },
    {
        "enabled": true,
        "action_type": "alert"
    }
]

Get Specific Action for a Feed (id)

Retrieves current status (enabled or not) of the action_type specified for this feed for the current user.

Required permissions: Analyst in any group

Supports: GET

Request

GET <host>/api/v1/feed/<id>/action_type/<action>
GET https://test.carbonblack.io/api/v1/feed/9/action_type/email

Options for action_type: syslog, email, alert (this is not an exhaustive list, more options could be available).

Response

{
    "enabled": false
}

Change Specific Action Status for a Feed (id)

PUT will enable or disable a specific action_type for this feed and current user.

Required permissions: Analyst in any group

Supports: PUT

Request

PUT <host>/api/v1/feed/<id>/action_type/<action>
PUT https://test.carbonblack.io/api/v1/feed/9/action_type/email

Options for action_type: syslog, email, alert (this is not an exhaustive list, more options could be available).

Body

{
    "enabled":true
}

Response

{
    "result": "success"
}

Threat Reports

Search Threat Reports

GET /api/v1/threat_report

Each Feed contains zero or more Threat Reports. The Search Threat Report API route allows you to search the content of these threat reports. For more information on creating EDR Threat Intelligence Feeds, see the Threat Intelligence Feed Reference.

Parameters

q: REQUIRED Query string. Accepts the same data as the search box on the Threat Report page. See the Query overview for the query syntax.
rows: OPTIONAL Return this many rows, 10 by default.
start: OPTIONAL Start at this row, 0 by default.
sort: OPTIONAL Sort rows by this field and order. last_update desc by default.
facet: OPTIONAL Return facet results. ‘false’ by default, set to ‘true’ for facets.

Returns

JSON dictionary describing the threat report search results

Bulk Modify Threat Reports

POST /api/v1/threat_report

Modifying threat reports require an API key with Global Administrator privileges. Multiple threat reports can be ignored/enabled in bulk using the same call.

The only property that can be modified in a threat report is the is_ignored property. By setting is_ignored to True for a threat report, any further hits on IOCs contained within that report will no longer trigger an Alert.

Payload

To modify multiple reports at once, either specify the list of Threat Report IDs in the ids dictionary, or submit a query (using the URL-encoded version of the query string described in the above section “Search Threat Reports”) in the query string.

    {
        "ids": {
            "<feed_id>": ["<report_id>", [...]]
        },
        "query: "<url-encoded query string>",
        "updates": {
            "is_ignored": true|false,
        }
    }

where either “ids” or “query” must be present, and “updates” is always required.

Returns

Returns an HTTP 200 return code if the threat reports were modified successfully.

Sensors/Endpoints

Retrieve/Modify Sensor Details

/api/v1/sensor/(id)?hostname=(hostname)&ip=(ipaddr)&groupid=(groupid)&inactive_filter_days=(int)

Sensor / remote client details

Supports: GET for all variations, PUT for /api/v1/sensor/(id) to update sensor information.

Note: In EDR 7.1 and later, the fields able to be updated using PUT are limited to network_isolation_enabled, restart_queued, uninstall, liveresponse_init, group_id, notes and event_log_flush_time.

Parameters

id: OPTIONAL the sensor id
hostname: OPTIONAL returns the sensor registration(s) with matching hostname
ipaddr: OPTIONAL returns the sensor registration(s) with specified IP address
groupid: OPTIONAL retruns the sensor registration(s) in the specified sensor group id
inactive_filter_days: OPTIONAL only returns sensors that have been inactive for less than the specified number of days

Returns

With no parameters (GET /api/v1/sensor) returns a list of sensor structures, one per registered sensor.
With a sensor id, (GET /api/v1/sensor/12) returns a sensor structure for the specified sensor.
With a query string, (GET /api/v1/sensor?hostname=foo) returns a list of all sensors matching criteria

Sensor query strings are case-sensitive substring searches, for both hostname and ip fields. If both hostname and ip fields are specified, only ip is used.

A sensor structure has the following fields:

id: the sensor id of this sensor
build_id: the sensor version installed on this endpoint. From the /api/builds/ endpoint
build_version_string: Human-readable string of the sensor version
uptime: Endpoint uptime in seconds
systemvolume_total_size: size, in bytes, of system volume of endpoint on which sensor in installed
systemvolume_free_size: bytes free on the system volume
os_environment_display_string: Human-readable string of the installed OS
os_environment_id: the operating system installed on this computer. From the internal table.
physical_memory_size: size in bytes of physical memory
computer_dns_name: the DNS name of the endpoint on which the sensor is installed
computer_name: NetBIOS name of this computer
sensor_health_message: Human-readable string indicating sensor’s self-reported status
computer_sid: Machine SID of this host
event_log_flush_time: See below.
last_checkin_time: Last communication with this computer in server-local time and zone
network_adapters: A pipe-delimited list list of IP,MAC pairs for each network interface
sensor_health_status: self-reported health score, from 0 to 100. Higher numbers better
registration_time: Time this sensor originally registered in server-local time and zone
next_checkin_time: Next expected communication from this computer in server-local time and zone
boot_id: A sequential counter of boots since the sensor was installed
group_id: The sensor group id this sensor is assigned to
display: Deprecated
uninstall: when set, indicates sensor will be directed to uninstall on next checkin
parity_host_id: Carbon Black Platform Agent Host Id; zero indicates Agent is not installed
network_isolation_enabled: Boolean representing network isolation request status. See below for details.
is_isolating: Boolean representing sensor-reported isolation status. See below for details.

If event_log_flush_time is set, the server will instruct the sensor to immediately send all data before this date, ignoring all other throttling mechansims. To force a host current, set this value to a value far in the future. When the sensor has finished sending it’s queued data, this value will be null.

Network isolation is requested by setting network_isolation_enabled to true. When the sensor receives the request and enables isolation, is_isolating will be set to true. The combination of the two parameters creates the following potential states:

Phase	`network_isolation_enabled`	`is_isolating`	State
0	False	False	normal state, isolation neither requested nor active
1	True	False	Isolation requested but not yet active
2	True	True	Isolation requested and active
3	False	True	Isolation disabled, but still active

Transitions between states 0 to 1 and states 2 to 3 will be delayed by a few minutes, based on sensor checkin interval and online status.

A complete example:

GET http://192.168.206.154/api/v1/sensor/1

{
  "systemvolume_total_size": "42939584512",
  "os_environment_display_string": "Windows XP Professional Service Pack 3",
  "sensor_uptime": "638",
  "physical_memory_size": "536330240",
  "build_id": 1,
  "uptime": "666",
  "computer_dns_name": "j-8205a0c27a0c4",
  "id": 1,
  "systemvolume_free_size": "40167079936",
  "sensor_health_message": "Healthy",
  "build_version_string": "003.002.000.30829",
  "computer_sid": "S-1-5-21-1715567821-507921405-682003330",
  "event_log_flush_time": null,
  "computer_name": "J-8205A0C27A0C4",
  "last_checkin_time": "2013-09-10 07:08:37.378860-07:00",
  "license_expiration": "1990-01-01 00:00:00-08:00",
  "network_adapters": "192.168.206.156,000c298a3613|",
  "sensor_health_status": 100,
  "registration_time": "2013-09-10 06:49:21.261157-07:00",
  "next_checkin_time": "2013-09-10 07:09:07.368285-07:00",
  "notes": null,
  "os_environment_id": 1,
  "boot_id": "5",
  "cookie": 1291426991,
  "group_id": 1,
  "display": true,
  "uninstall": false,
  "network_isolation_enabled": false,
  "is_isolating": false
}

http://192.168.206.132/api/v1/sensor?hostname=A0C4

[
  {
    "systemvolume_total_size": "42939584512",
    "os_environment_display_string": "Windows XP Professional Service Pack 3",
    "sensor_uptime": "480763",
    "physical_memory_size": "536330240",
    "build_id": 1,
    "uptime": "480862",
    "event_log_flush_time": null,
    "computer_dns_name": "j-8205a0c27a0c4",
    "id": 1,
    "power_state": 0,
    "uninstalled": null,
    "systemvolume_free_size": "40083230720",
    "status": "Online",
    "num_eventlog_bytes": "22717",
    "sensor_health_message": "Healthy",
    "build_version_string": "004.000.000.30910",
    "computer_sid": "S-1-5-21-1715567821-507921405-682003330",
    "next_checkin_time": "2013-10-07 07:54:36.909657-07:00",
    "node_id": 0,
    "cookie": 556463980,
    "computer_name": "J-8205A0C27A0C4",
    "license_expiration": "1990-01-01 00:00:00-08:00",
    "network_adapters": "192.168.206.156,000c298a3613|",
    "sensor_health_status": 100,
    "registration_time": "2013-02-04 06:40:04.632053-08:00",
    "restart_queued": false,
    "notes": null,
    "num_storefiles_bytes": "446464",
    "os_environment_id": 1,
    "boot_id": "8",
    "last_checkin_time": "2013-10-07 07:54:06.919446-07:00",
    "group_id": 1,
    "display": true,
    "uninstall": false,
    "network_isolation_enabled": false,
    "is_isolating": false
  }
]

Download Sensor Installer

/api/v1/group/<groupid>/installer/windows/exe

/api/v1/group/<groupid>/installer/windows/msi

/api/v1/group/<groupid>/installer/osx

/api/v1/group/<groupid>/installer/linux

Download a zip archive including a sensor installer for Windows, Mac OS X or Linux.

Supports: GET

Parameters None

Returns

(Windows) ZIP archive including a signed Windows EXE or MSI sensor installer and settings file
(Mac OS X) ZIP archive including a signed OSX PKG sensor installer and settings file
(Linux) compressed tarball (tar.gz) archive including a Linux sensor installer and settings file

Get Sensor Statistics

/api/v1/sensor/statistics

Get global sensor statistics

Supports: GET

Parameters None

Note: Backlog counts are as of sensor checkin time. Any bytes pushed post-checkin, in response to a server directive, are not accounted for. This means total backlog appears artificially high and will never reach zero while sensors are active.

Returns

Returns a JSON dictionary with fields as follows:

sensor_count: total registered sensors
active_sensor_count: number of sensors active within the last 24 hours
num_eventlog_bytes: total backlog, in bytes, of eventlogs on active sensors. See notes.
num_storefile_bytes: total backlog, in bytes, of binary files (store files) on active sensors. See notes.

Ingress Approving

For more details on Ingress filters please go to our Ingress Filter Details page.

/api/v1/ingress_whitelist
/api/v1/ingress_whitelist/{id}
/api/v1/ingress_whitelist/legacy

Supports: GET, POST, PUT, DELETE

Get, update, create, or delete exclusions. A PUT will update an existing Ingress Filter, while a POST will attempt to create a new Ingress Filter.

Parameters

id: OPTIONAL the exclusion id

Returns

id: Optional - Unique filter identifier, in order to allow future updates. Can be any string, but should contain only alfanumeric digits and dashes (e.g. uuid). This is read-only field and honored only during initial POST.
create_timestamp: Date of creation of this filter. This is read-only field.
modify_timestamp: Date of last modification of this filter. This is read-only field.
create_user_id: ID of user that created this filter. This is a read-only field.
modify_user_id: ID of user that last modified this filter. This is a read-only field.
version: Optional - version of the filter (not used yet).
priority: Optional - Priority of the filter. Higher priority filters are guaranteed to be used first. Negative priorities can be used as well. Default priority is 0.
internal: This field is not yet used. Can be omitted.
enabled: Optional - True enables the filter. Defaults to True.
filter_on_sensor: True to push this filter to sensor. If filter was was pushed to sensor, it will not be enforced on the server. Only certain filters can be pushed to sensors today without loss of functionality. Defaults to False.
filter_on_server: True to filter on server. Defaults to True. If false, server will treat this filter as pass-through (disabled).”
track_metrics: Optional - True to capture metrics for this filter even when disabled. Defaults to True. If we are metering disabled filter, we will resort to metering small sample set to reduce performance impact.
hit_rate: Read-Only - measured 15-min hit rate for a given filter as a rate (e.g. 0.01 equals to 1% hit rate). This metric will be available only for filters that are enabled or have trackMetrics turned on. Also, this metrics counts hit rate of the process, based on pathFilters, commandLineFilters and md5Filters. It doesn’t take into the account the individual event hit rate.
name: Name of this filter
description: Description of this filter
os_mask: Optional - Which OS should this filter apply to (bitfield mask: 1:windows, 2:osx, 4:linux). Defaults to 7 (all OSs)
global: Optional - True to apply to all sensor groups. Defaults to true
group_ids: Optional - List of sensor group Ids where this filter applies to (if global == false). Defaults to empty list. NOTE: group_ids is ignored if global is set to true
sensor_ids: Optional - Array of sensor ids where filter applies (applies to all sensors in selected groups if empty). NOTE: sensor_ids field is ignored if global is set to true
path_filters: Optional - Array of process path filters to use (supports globbing or regex patterns).
cmdline_filters: Optional - Array of command line filters to use. Can use regex patterns (cannot use globbing patterns)
md5_filters: Optional - Array of MD5 checksums. Processes matching these MD5s will be filtered.
descendant_filtering_level: Optional - 0 = filter only matched process, 1 = matched process and immediate children, 2 = matched up to second level of descendants etc. Special value -1 matches all descendants. If not provided, defaults to 0 (matched process only)"
filter_all_events: Optional - If true, all events will be excluded for a given process (respecting descendant levels). If false, filters (below) will be applied to each event type. Defaults to true"
regmod_filters: Optional - Filters are applied to the given event field. Can use regex patterns
modload_filters: Optional - Filters are applied to the given event field. Can use regex patterns
filemod_filters: Optional - Filters are applied to the given event field. Can use regex patterns
non_binary_filemod_filters: Optional - Filters are applied to the given event field. Can use regex patterns
netconn_filters: Optional - Filters are applied to the given event field. Can use regex patterns
crossproc_filters: Optional - Filters are applied to the given event field. Can use regex patterns

Examples

Request:
GET /api/v1/ingress_whitelist/

Response:
[
  {
    "group_ids": [
      1,
      2
    ],
    "create_user_id": 1,
    "path_filters": [
      "c:\\\\test_dir"
    ],
    "modify_user_id": 1,
    "enabled": true,
    "filter_on_sensor": false,
    "create_timestamp": "2017-04-11T04:05:23.973Z",
    "filter_all_events": true,
    "modify_timestamp": "2017-04-11T04:05:24.050Z",
    "hit_rate": 0.0,
    "id": "1"
  },
  {
    "group_ids": [
      1,
      2
    ],
    "create_user_id": 1,
    "modify_user_id": 1,
    "enabled": true,
    "filter_on_sensor": false,
    "create_timestamp": "2017-04-11T04:44:06.695Z",
    "filter_all_events": true,
    "command_line_filters": [
      "notepad.exe"
    ],
    "modify_timestamp": "2017-04-11T04:44:06.866Z",
    "id": "2"
  }
]

Request:
GET /api/v1/ingress_whitelist/{id}

Response:
{
  "group_ids": [
    1,
    2
  ],
  "create_user_id": 1,
  "path_filters": [
    "c:\\\\test_dir"
  ],
  "modify_user_id": 1,
  "enabled": true,
  "filter_on_sensor": false,
  "create_timestamp": "2017-04-11T04:05:23.973Z",
  "filter_all_events": true,
  "modify_timestamp": "2017-04-11T04:05:24.050Z",
  "hit_rate": 0.0,
  "id": "1"
}

Request:
POST /api/v1/ingress_whitelist

Request Payload:
[  
   {  
      "id":"1",
      "enabled":true,
      "filter_on_sensor":false,
      "group_ids":[  
         1,
         2
      ],
      "path_filters":[  
         "c:\\\\test_dir"
      ],
      "filter_all_events":true
   }
]

Response
[
  "1"
]

PUT api/v1/ingress_whitelist/test2

Request Payload Example
[
  {
    "os_mask":1,
    "global": false,
    "group_ids": [1, 2],
    "path_filters":["*\\unimportant.exe", "*\\really_unimportant.exe"]
  }
]

EDR Cloud IP Approving

New to EDR 6.3: Cloud customers can now approve IP addresses via the /whitelist endpoint. This is a useful security feature that restricts access to EDR Cloud to specific IP addresses. Access to the EDR Cloud Console and API requests will route through this service.

Workflow

Approving API Routes

List Approved IP addresses

This API request lists all approved IP addresses. If no addresses have been configured, an empty response will be provided.

Request

curl -X GET "https://cbrc.carbonblack.io/api/whitelist/entries" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>"

Response

[
    {
        "ipaddr": "192.168.0.1",
        "id": 4
    }
]

Add a new IP address

This request allows you to upload a new IP address. The POST request body requires an ipaddr with an optional CIDR block. Example 192.168.0.1 or with CIDR 0.0.0.0/0. Once successfully uploaded, the request will respond with an ID that uniquely identifies the IP address entry.

Request

curl -X POST "https://cbrc.carbonblack.io/api/whitelist/entries" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>" -H  "Content-Type: application/json" -d "{\"ipaddr\": \"192.168.0.1\"}"

Response

ID of the IP address added

Delete an IP address

This request allows you to delete an IP address. The DELETE request requires the unique ID of the IP address you would like to delete.

Request

curl -X DELETE "https://cbrc.carbonblack.io/api/whitelist/entries/<ID>" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>"

Response

204 NO CONTENT

View Status of IP Approving

This request shows the status of the IP approving service. It is false by default.

Request

curl -X GET "https://cbrc.carbonblack.io/api/whitelist/enabled" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>"

Response

{
    "state": false
}

Change Status of IP Approving

This request changes the status of the IP approving service. The PATCH request body requires the state to be either true or false to enable or disable the service.

Request

curl -X PATCH "https://cbrc.carbonblack.io/api/whitelist/enabled" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>" -H  "Content-Type: application/json" -d "{  \"state\": true}"

Response

204 NO CONTENT

Apply Settings

Apply all settings configured using the API. Example: adding IP(s), deleting IP(s), or changing the status of the service.

Warning: This cannot be undone. Make sure your IP address is correct before you apply these settings. All API requests will also have to originate from approved IP(s).

Request

curl -X POST "https://cbrc.carbonblack.io/api/whitelist/apply" -H  "accept: application/json" -H  "X-Auth-Token: <YOUR_TOKEN>"

Response

204 NO CONTENT

Time Partitioning

/api/v1/storage/events/partition

Supports: GET

Returns list of partitions

This method will return list of partitions as JSON. Each partition will have name and status, as well as info block stating: location, size, document counts, schema, etc. Note: Cold partitions will not list numDocs, maxDocs and deletedDocs.

Paramaters None

Examples

Response:
{
   "cbevents_2017_03_18_1807":{
      "status":"warm",
      "info":{
         "sizeInBytes":6132115,
         "startDate":"2017-03-18T18:07:50.758813Z",
         "partitionId":97639495827456,
         "endDate":"2017-04-07T18:18:31.493403Z",
         "deletedDocs":0,
         "maxDoc":1432,
         "userMounted":false,
         "isLegacy":false,
         "segmentCount":7,
         "numDocs":1432,
         "dir":"/var/cb/data/solr5/cbevents/cbevents_2017_03_18_1807",
         "schema":"cbevents_v1"
      },
      "name":"cbevents_2017_03_18_1807"
   },
   "writer":{
      "status":"hot",
      "info":{
         "sizeInBytes":825878,
         "startDate":"2017-04-10T18:18:29.834738Z",
         "partitionId":97769770844160,
         "endDate":null,
         "deletedDocs":0,
         "maxDoc":355,
         "userMounted":false,
         "isLegacy":false,
         "segmentCount":9,
         "numDocs":355,
         "dir":"/var/cb/data/solr5/cbevents/cbevents_2017_04_10_1818",
         "schema":"cbevents_v1"
      },
      "name":"writer"
   },
   "cbevents_2017_04_07_1818":{
      "status":"warm",
      "info":{
         "sizeInBytes":20464833,
         "startDate":"2017-04-07T18:18:27.821121Z",
         "partitionId":97752783781888,
         "endDate":"2017-04-10T18:18:33.612997Z",
         "deletedDocs":0,
         "maxDoc":2780,
         "userMounted":false,
         "isLegacy":false,
         "segmentCount":10,
         "numDocs":2780,
         "dir":"/var/cb/data/solr5/cbevents/cbevents_2017_04_07_1818",
         "schema":"cbevents_v1"
      },
      "name":"cbevents_2017_04_07_1818"
   },
   "cbevents_2017_02_19_2012":{
      "status":"warm",
      "info":{
         "sizeInBytes":71,
         "startDate":"2017-02-19T20:12:10.312043Z",
         "partitionId":97487102279680,
         "endDate":"2017-03-15T18:07:34.821787Z",
         "deletedDocs":0,
         "maxDoc":0,
         "userMounted":false,
         "isLegacy":false,
         "segmentCount":0,
         "numDocs":0,
         "dir":"/var/cb/data/solr5/cbevents/cbevents_2017_02_19_2012",
         "schema":"cbevents_v1"
      },
      "name":"cbevents_2017_02_19_2012"
   },
   "cbevents_2017_03_15_1807":{
      "status":"warm",
      "info":{
         "sizeInBytes":41374250,
         "startDate":"2017-03-15T18:07:30.854679Z",
         "partitionId":97622507585536,
         "endDate":"2017-03-18T18:07:54.721176Z",
         "deletedDocs":0,
         "maxDoc":2378,
         "userMounted":false,
         "isLegacy":false,
         "segmentCount":10,
         "numDocs":2378,
         "dir":"/var/cb/data/solr5/cbevents/cbevents_2017_03_15_1807",
         "schema":"cbevents_v1"
      },
      "name":"cbevents_2017_03_15_1807"
   }
}

/api/v1/storage/events/new_partition

Supports: POST

Creates new time partition. This will force roll-over current hot partition into warm partition (by renaming it to a time-stamped name) and create a new hot partition (“writer”).

Paramaters None

Returns

results: String of the outcome when creating a new partition

/api/v1/storage/events/<partition_name>/mount

Supports: POST

Parameters

partition_name: The name of the partition

Mounts partition with name <partition_name>. This will mount “cold” partition into “warm” partition. Partition has to exist on disk and returned as cold in by the /api/v1/storage/events/partition API

Paramaters

partition_name: The name of the partition

Returns

results: String of the outcome when mounting a new partition

/api/v1/storage/events/<partition_name>/unmount

Supports POST

Unmounts partition with name <partition_name>. This will unmount “warm” partition into “cold” partition. Partition has to be mounted at the time and returned as cold in by the /api/v1/storage/events/partition API

Parameters

partition_name: The name of the partition

Returns

results: String of the outcome when unmounting the partition

/api/v1/storage/events/<partition_name>

Supports DELETE

Unmounts and deletes partition with name <partition_name>. This will delete partition with the specified name. If partition is “warm”, it will be unmounted first. Deleted partitions are removed from disk and cannot be mounted again. If partition is “hot” (writer partition) call returns error.

Parameters

partition_name: The name of the partition

Returns

results: String of the outcome when deleting the partition

Last modified on April 14, 2022

Carbon Black EDR

Page Contents

REST API Reference CB R 6.3+

Process Data

Process Search

Faceting

Process Summary

Process Summary (No Siblings)

Process Segment Details

Process Event Details

filemod_complete

modload_complete

regmod_complete

netconn_complete

childproc_complete

crossproc_complete

Process Preview

Binary Data

Binary Search

Faceting

Download Binary

Retrieve Binary Icon

Retrieve Binary Metadata

Alerts

Search Alerts

Update/Resolve Alerts

Bulk Update Alerts

Administrative APIs

Server License

App Control Integration

Banning

Ban Binary by Hash

Watchlists & Feeds

New to EDR 6.3

Watchlist Operations

Get Watchlists

Get Watchlist by ID

Create a new Watchlist

Update a Watchlist

Delete a Watchlist

Get Watchlist Action Types

Get Specific Action for a Watchlist (id)

Change Specific Action Status for a Watchlist (id)

Feed Operations

Get Feeds

Get Feed by ID

Get Feed Action Types

Get Specific Action for a Feed (id)

Change Specific Action Status for a Feed (id)

Threat Reports

Search Threat Reports

Bulk Modify Threat Reports

Sensors/Endpoints

Retrieve/Modify Sensor Details

Download Sensor Installer

Get Sensor Statistics

Ingress Approving

EDR Cloud IP Approving

Workflow

Approving API Routes

List Approved IP addresses

Add a new IP address

Delete an IP address

View Status of IP Approving

Change Status of IP Approving

Apply Settings

Time Partitioning