SOLD OUT - Cb Connect 2018 Developer Day | Power of You | Join the Waitlist

Cb Response REST API Quick Start

Introduction

The CbResponse REST API provides a RESTful API for CbResponse, which means that it can be consumed by practically any language. The API sends a HTTPS request to a CbResponse server (authenticated via the API key) and retrieves a JSON response. This quick start guide will show you how to use the REST API to with Cb Response using curl or Postman. We strongly recommend going through this guide on a workstation or server that is separate from your Carbon Black server.

Requirements

  • API key from your Cb Response instance.
  • Workstation or Server with curl or Postman installed on your workstation.

Get Your REST API token

To get started, you need to acquire a REST API token from the Carbon Black user interface. Log into your Carbon Black server and click your name on the black bar in the top right corner. A pop-up will appear; click Profile to jump to your user profile page. From there, on the left hand side, you will see a link for API Token. Click that link and a text box will appear populated with your user’s API token. Each user receives their own, unique API token. This token has the same power and privileges attached to your user and does not expire; so protect it like a password! If your API token is compromised, you can generate a new token by clicking the Reset API Token button; this will also revoke your old, compromised token so it can no longer be used to authenticate to the server.

Postman Example

Let’s go through a quick setup of Postman. Note: You don’t need to install Postman to use the REST API, the steps below can be done using curl on your command line.

Steps to configure Postman:

  1. Launch Postman.
  2. Create a new collection (folder) for your API requests.
  3. Create a new request and add it to the collection created in step 2.
  4. Select the request type as GET
  5. Enter the request URL - https://<CBRESPONSE-SERVER-URL>/api/v1/sensor
    • Example - https://cb-response-server.carbonblack.com/api/v1/sensor
  6. Under the API request, go to headers and add a new header:
    • Header key: X-Auth-Token
    • Header value: <API_KEY>
  7. Click send!
  8. If all goes well, view the response.

Here’s a screenshot of my postman instance:

Postman Config

Curl Example

Request

The following GET request returns a list of sensor structures, one per registered sensor.

curl "https://cb-response-server.carbonblack.com/api/v1/sensor" -H "X-Auth-Token: API_KEY"

Response

[
    {
        "systemvolume_total_size": "49359622144",
        "emet_telemetry_path": null,
        "os_environment_display_string": "Linux CentOS Linux release 7.4.1708 (Core) \n3.10.0-693.11.6.el7.x86_64",
        "emet_version": null,
        "emet_dump_flags": null,
        "clock_delta": "0",
        "supports_cblr": true,
        "sensor_uptime": "9162216",
        "last_update": "2018-06-27 14:43:22.166324+00:00",
        "physical_memory_size": "2985578496",
        "build_id": 6,
        "uptime": "9162222",
        "is_isolating": false,
        "event_log_flush_time": null,
        "computer_dns_name": "devr-test",
        "emet_report_setting": null,
        "id": 1,
        "emet_process_count": 0,
        "emet_is_gpo": false,
        "power_state": null,
        "network_isolation_enabled": false,
        "uninstalled": null,
        "systemvolume_free_size": "47095492608",
        "status": "Online",
        "num_eventlog_bytes": "0",
        "sensor_health_message": "Driver Failure",
        "build_version_string": "005.002.009.70606",
        "computer_sid": "bfdc8798315441859bcbd0d6c004b66e\n",
        "next_checkin_time": "2018-06-27 14:43:50.981411+00:00",
        "node_id": 0,
        "cookie": 915315129,
        "emet_exploit_action": null,
        "computer_name": "devr-test",
        "license_expiration": "1990-01-01 00:00:00+00:00",
        "supports_isolation": true,
        "parity_host_id": "0",
        "supports_2nd_gen_modloads": false,
        "network_adapters": "127.0.0.1,000000000000|10.210.33.7,0050568f47b9|",
        "sensor_health_status": 50,
        "registration_time": "2017-09-07 13:03:35.858637+00:00",
        "restart_queued": false,
        "notes": null,
        "num_storefiles_bytes": "35776",
        "os_environment_id": 3,
        "shard_id": 0,
        "boot_id": "0",
        "last_checkin_time": "2018-06-27 14:43:19.988396+00:00",
        "os_type": 3,
        "group_id": 1,
        "display": true,
        "uninstall": false
    }
]

Resources

Carbon Black Response REST API Reference: https://developer.carbonblack.com/reference/enterprise-response/6.1/rest-api/

Carbon Black API GitHub: https://github.com/carbonblack

Carbon Black Enterprise Response query language: https://github.com/carbonblack/cbapi/raw/master/client_apis/docs/query_overview.pdf

Carbon Black User eXchange Developer community: https://community.carbonblack.com/community/resources/developer-relations

Last modified on June 27, 2018