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.

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

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


Process Data

/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

/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

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:

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