REST API Reference CBR 7.7+

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
  • block_type : possible values are 0 (not blocked) or 1 (blocked due to isolation). Most netconns will have block_type:0. Netconns that were attempted by an endpoint that has been isolated from the EDR console will have block_type:1.

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: IP address as a 32-bit signed long (host byte order), local for inbound and remote for outbound as indicated by field 5
  • field 2: port, local for inbound and remote for outbound as indicated by field 5
  • 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"
}

Process Analysis

The 7.5.0 release of VMware Carbon Black EDR introduces a new set of API endpoints (v6/process) to assist in the analysis of processes and their events. The endpoints share a new strategy to load, process, and return small portions of process data at one time. The strategy allows greater efficiency. On average the endpoints are faster and more predictable. There is a tradeoff in API usage. The new endpoints work differently as a whole compared to process/v5. Your code will need to adapt to the new conventions.

Stream API

Process events are now viewed using the metaphor of a stream, much like streaming video online. The whole timeline of events exists on the server, not all events are viewed at once. A stream tracks your position as you view individual pages of events. You can seek forward and backward by any number of events. You can also jump forward and backward by any number of process segments. If you know a particular segment id, you can jump directly to it.

Streams are stateful. They must be created, used, then deleted. Streams are referenced by their STREAM_ID.

Create a Stream

To create a stream, you need a PROCESS_ID and SEGMENT_ID. By default, the new stream will expire after StreamTTLSecs (a cb.conf option). You may specify persistent: true to prevent the stream from expiring automatically. Streams do not store much state - only a handful of fields are stored to track stream progress. Nevertheless, it is a good idea to delete streams when you are done with them.

Request

curl -X POST "$SERVER/api/v6/process/stream" \
  -H "X-Auth-Token: $TOKEN"  \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d"
{
  \"process_id\": \"$PROCESS_ID\",
  \"segment_id\": \"$SEGMENT_ID\",
  \"persistent\": true  # or false
}"

Response 

{
"stream_id": "727cdaed-fc91-4f48-a00b-08dfe6aec4da",
"status_fw": "ready",
"status_bw": "ready",
"ref_segment_id": 1621882944903,
"cur_segment_id": 1621882944903,
"head_as_ref_segment_offset": 0,
"head_as_cur_segment_offset": 0,
"events": []
}

Use a Stream

Once you have obtained a STREAM_ID, you can perform several operations. First, consider your current position. When you create a stream, the initial position will be the first event of the segment you provided. If you request ten rows, you’ll get back ten rows starting from your current position. The position does not move unless you perform a seek or jump operation. If you seek by 10 rows and request 10 rows in one call, you’ll move the stream position forward by ten rows, and then get back ten rows starting from your new position.

Several status fields are returned after each operation. status_fw/status_bw are of particular interest. For instance, status_fw will be “ready” if you could perform the same operation again without reaching the end of the process. It will be “current” if you have reached the end of the process. It will be “complete” if you have reached the end of the process, and the process is terminated (there will never be more events). In the latter two cases you may retrieve fewer events than you requested. The status will be “void” if the operation moved the position out of bounds, e.g. there are only 100 events but you tried to seek forward by one thousand.

Requests

# View ten rows
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?rows=10"\
  -H "X-Auth-Token: $TOKEN"

# Seek forward by ten rows
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?seek&by=10&rows=10" \
  -H "X-Auth-Token: $TOKEN"

# Seek backward by ten rows
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?seek&by=-10&rows=10" \
  -H "X-Auth-Token: $TOKEN"

# Jump forward by one segment
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?jump&by=1&rows=10" \
  -H "X-Auth-Token: $TOKEN"

# Jump backward by one segment
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?jump&by=-1&rows=10" \
  -H "X-Auth-Token: $TOKEN"

# Jump to a specific segment
curl -X GET "$SERVER/api/v6/process/stream/$STREAM_ID?jump&to=$SEGMENT_ID&rows=10" \
  -H "X-Auth-Token: $TOKEN"

Sometimes you want to view events of a certain type, or events that mach certain criteria. You may use the following PATCH request to modify the criteria that are used to filter events in the stream. The criteria structure may specify fields mentioned in Facet Fields below. Multiple values per field are allowed.

# Filter a Stream
curl -X PATCH "$SERVER/api/v6/process/stream/$STREAM_ID?&rows=10" \
-H "Content-Type: application/json" \
-H "Accept: application/json"  \
-d '
{
  "criteria": {
    "event_type": [
      "filemod"
    ],
    "directory": [
      "/var/run",
      "/tmp"
    ]
  }
}'

The query argument end_time may be used with the above requests to omit all events with a timestamp occurring after the specified time.

end_time=YYYY-MM-DDThh:mm:ss.sssZ

Data will be returned in the following format. Events may contain additional binary info, alliance hit information, and on demand hit information if threat intelligence has been configured appropriately.

Response 

{
"stream_id": "508c8e5b-5ffd-40a0-97cc-b31414298667",
"status_fw": "ready",
"status_bw": "ready",
"ref_segment_id": 1621882944903,
"cur_segment_id": 1621882944903,
"head_as_ref_segment_offset": 0,
"head_as_cur_segment_offset": 0,
"events": [
{
"type": "childproc",
"time": "2021-05-24 19:01:56.564000",
"data": {
"md5": "b6fe756bf9828f05bd6c4d300f93ab91",
"path": "/usr/libexec/nm-dispatcher",
"commandLine": "",
"userName": "",
"sha256": "",
"pid": 26885,
"processId": "00000001-0000-6905-01d7-50cf4455dc1e-000000000001",
"is_tampered": false,
"type": "start",
"start": "2021-05-24T19:01:56.564000Z"
},
"segment_id": 1621882944903,
"binary_info": {
"digsig_result": null,
"digsig_publisher": null
},
"alliance_hits": null,
"ondemand_feeds": null,
"ondemand_classification": null
}
]
}

Delete a Stream

You should take care to delete persistent streams you create. You may also delete transient streams (those that expire due to being created with “persistent”: false).

Request

curl -X POST "$SERVER/api/v6/process/stream/$STREAM_ID" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"result": "success"
}

Summary Stream API

The summary stream API can be used to obtain an overview of the event types represented in the whole process. It works similarly to the v5 route of the same name with one difference. Batches of segment summary info are streamed from the server in a single HTTP request using the ndjson format. You can handle each incoming batch while the request is ongoing.

Request

# Retrieve batches of summary data pertaining to the segments of a process
curl -X GET "$SERVER/api/v6/process/$PROCESS_ID/$SEGMENT_ID/segment" \
-X "Accept: application/x-ndjson"

Response

Notice each line is a JSON document with its own batch of segment summary data. 

{"elapsed":2.1457672119140625e-06,"process":{"segments":[{"unique_id":"00000001-0000-0001-01d6-eea15d60d4c4-0179b1c541a3","segment_id":1622185165219,"last_update":"2021-05-28T06:59:12.748Z","last_server_update":"2021-05-28T06:59:25.288Z","event_counts":{"filemod":7}},{"unique_id":"00000001-0000-0001-01d6-eea15d60d4c4-0179b1c62cce","segment_id":1622185225422,"last_update":"2021-05-28T07:00:01.775Z","last_server_update":"2021-05-28T07:00:25.492Z","event_counts":{"filemod":35}}]}}
{"elapsed":2.6226043701171875e-06,"process":{"segments":[{"unique_id":"00000001-0000-0001-01d6-eea15d60d4c4-0179b257a6ac","segment_id":1622194759340,"last_update":"2021-05-28T09:38:59.097Z","last_server_update":"2021-05-28T09:39:19.424Z","event_counts":{"childproc":1}}]}}

Bulk API

The bulk API provides information about large portions of a process. It consolidates two previous features: alliance feed hits and on demand feed hits. It introduces one new feature: event faceting across all events. Some limitations have been introduced to ensure these features can be used reliably.

  • Processing begins at the specified SEGMENT_ID
  • Processing ends after a configurable timeout (BulkDataTimeoutSecs in cb.conf)
  • Processing ends if an end_time is provided (see end_time format specification above)

The API response will indicate if the result is partial due to timeout. Reaching the specified end_time is not considered a timeout. The API may handle a process with few segments in one call. A larger process with thousands of segments may need to be processed in chunks. In fact the EDR Console uses a combination of SEGMENT_ID and END_TIME to limit processing to the timeline window selection.

Request

curl -X GET "$SERVER/api/v6/process/$PROCESS_ID/$SEGMENT_ID/bulk?end_time=$END_TIME" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"alliance_hits": {...},
"on_demand_hits": {
"threatintel": {...}
},
"facets": {
"terms": [...],
"num_found": n,
"processed_segments": n
},
"partial_results": false
}

The following is an example of what can be expected in facets:

{
"terms": [
{
"field": "event_type",
"values": [
{
"id": "modload",
"name": "modload",
"total": 46
},
{
"id": "crossproc",
"name": "crossproc",
"total": 2
}
]
},
{
"field": "directory",
"values": [
{
"id": "c:\\windows\\syswow64",
"name": "c:\\windows\\syswow64",
"total": 40
},
{
"id": "c:\\windows\\system32",
"name": "c:\\windows\\system32",
"total": 6
},
{
"id": "c:\\users\\user1\\downloads\\dir_1\\file_x",
"name": "c:\\users\\user1\\downloads\\dir_1\\file_x",
"total": 1
},
{
"id": "c:\\windows\\dir_2\\file_y",
"name": "c:\\windows\\dir_2\\file_y",
"total": 1
}
]
}
],
"num_found": 48,
"processed_segments": 1
}

There are two properties in addition to terms: num_found indicates the number of filterable items found and processed_segments is the number of segments that were searched to find all the items.

Facet Fields

The following are valid values for the event_type field: filemod, childproc, netconn, regmod, processblock. Note that childproc includes events of types exec, fork, and other_exec as well as childproc.

The following fields are possible for each event type:

  • filemod
    • directory
    • filemod_action
    • filemod_filetype
  • childproc
    • directory
    • childproc_filepath
    • childproc_md5
    • childproc_sha256
  • netconn
    • ipv4_address
    • ipv6_address
    • domain
    • ja3_fingerprint
    • ja3s_fingerprint
  • regmod
    • regmod_action
    • regmod_hive
  • processblock
    • directory
  • crossproc
    • directory
  • modload
    • directory

Metadata API

The metadata API will return all non-event fields of the process.

Request

curl -X GET "$SERVER/api/v6/process/$PROCESS_ID/metadata" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"process_metadata": {
"unique_id": "00000008-0000-1778-01d7-531d279b5c07-0179aedb558a",
"sensor_id": 8,
"hostname": "tl-750-rhel83-w",
"group": "default group",
"os_type": "windows",
"host_type": "workstation",
"interface_ip": 181100788,
"comms_ip": 181100788,
"parent_unique_id": "00000008-0000-04b0-01d7-4ccd83f8de79-000000000001",
"start": "2021-05-27T17:24:31.436Z",
"day_of_week": 4,
"hour_of_day": 13,
"process_pid": [
6008
],
"parent_pid": 1200,
"process_md5": "ccee2e1a4672697747d199fb7e0caa37",
"process_sha256": "f75345665bf69e4a5beb0525b80b714f1b2d8b25a7ece8c88f48607b46f5d7f9",
"cmdline": [
"\"C:\\Users\\user_1\\Downloads\\dir_1\\dir_2\\file_x.exe\" "
],
"uid": "s-1-5-21-601375543-4271196527-4255210300-1001",
"username": [
"TL-750-RHEL83-W\\user_1"
],
"parent_name": "explorer.exe",
"path": "c:\\users\\user_1\\downloads\\dir_1\\dir_2\\file_x.exe",
"process_name": "file_x.exe",
"logon_type": 2,
"creation_observed": false,
"alliance_score_srsthreat": 100,
"alliance_link_srsthreat": "https://services.bit9.com/Services/extinfo.aspx?ak=b8b4e631d4884ad1c56f50e4a5ee9279&sg=0313e1735f6cec221b1d686bd4de23ee&md5=ccee2e1a4672697747d199fb7e0caa37",
"alliance_data_srsthreat": [
"ccee2e1a4672697747d199fb7e0caa37"
],
"alliance_updated_srsthreat": "2021-05-26T23:19:19Z",
"facet_id": 201654,
"last_update": "2021-05-27T17:24:31.518Z",
"last_server_update": "2021-05-27T17:24:40.553Z",
"terminated": false,
"server_added_timestamp": "2021-05-27T17:24:40.553Z",
"id": "00000008-0000-1778-01d7-531d279b5c07",
"parent_id": "00000008-0000-04b0-01d7-4ccd83f8de79",
"segment_id": 1622136280458,
"filtering_known_dlls": false,
"tampered": false,
"has_emet_event": false,
"has_emet_config": false
}
}

Segment Verification API

Several v6 API endpoints require valid segment IDs. This API may be used to verify the existence of those segment IDs. If the provided SEGMENT_ID exists, it will be returned unchanged.

Request

curl -X GET "$SERVER/api/v6/process/$PROCESS_ID/$SEGMENT_ID/verify" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"segment_id": $SEGMENT_ID
}

If the provided SEGMENT_ID does not exist, the id of the earliest available segment will be returned instead.

Request

curl -X GET "$SERVER/api/v6/process/$PROCESS_ID/$INVALID_SEGMENT_ID/verify" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"segment_id": $EARLIEST_SEGMENT_ID
}

Event Suppression Status

You may encounter a childproc event while browsing an event stream. To determine if the childproc is suppressed (or not), use this API endpoint. This operation will timeout after SuppressionStatusCheckTimeoutSecs (a cb.conf option).

Request

curl -X GET "$SERVER/api/v6/process/suppression_status?parent_guid=$PARENT_GUID&childproc_guid=$CHILDPROC_GUID&childproc_md5=$CHILDPROC_MD5" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json"

Response 

{
"is_suppressed": false,
"timeout": false
}

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

Note: In EDR 7.7 these API routes were changed to use the term banned. See earlier verions for prior route URLs.

Ban Binary by Hash

/api/v1/banning/bannedlist

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/bannedlist) returns a list of banned hashes, with each list entry describing one banned hash
  • (POST /api/v1/banning/bannedlist)

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/bannedlist

[
  {
    "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.

Note: The default field used for sorting is last_checkin_time. While the api is being used to page through all sensors with this default sorting, it is possible that sensors will continue to check in, which will change the results. This means that as successive pages of data are retrieved, new sensors may have moved to the top of the list, thereby pushing sensors from a previous page of results into the next page of results and causing it to appear that those sensors are being duplicated in the results. To overcome this possible source of confusion, a different sorting mechanism can be specified (e.g., sort.col=computer_name).

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 check-in time. Any bytes pushed post-check-in, 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.

Note: In EDR 7.7 these API routes were changed to use the term approvedlist. See earlier verions for prior route URLs.

  • api/v1/ingress_approvedlist
  • api/v1/ingress_approvedlist/{id}
  • api/v1/ingress_approvedlist/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_approvedlist/

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_approvedlist/{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_approvedlist

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_approvedlist/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 /approvedlist 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/v1/approvedlist/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.

Warning: Make sure your IP address is correct before you add it. All API requests will also have to originate from approved IP(s). The changes after adding an IP get applied after up to 30s.

Request

curl -X POST "https://cbrc.carbonblack.io/api/approvedlist/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

New to EDR 7.7

Bulk add new IP addresses

This request allows you to upload a list of 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 IDs that uniquely identifies the IP address entries.

Warning: Make sure your IP(s) is correct before you add it. All API requests will also have to originate from approved IP(s). The changes after adding IP(s) get applied after up to 30s.

Request

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

Response

IDs of the IP addresses 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.

Warning: Make sure your IP is correct before you delete it. All API requests will also have to originate from approved IP(s). The changes after deleting an IP get applied after up to 30s. Deleting an IP from which the API requests originate can result in getting locked out.

Request

curl -X DELETE "https://cbrc.carbonblack.io/api/v1/approvedlist/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/approvedlist/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/approvedlist/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 settings feature is deprecated. The changes from the APIs for example adding IP(s), deleting IP(s) are applied automatically after up to 30s.

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.

Parameters 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 March 1, 2023