Sensor Update Services API

Introduction

This API lets you batch sensor updates automatically across your organization and provides visibility into the update jobs progress. This API can update large quantities of devices — up to 10k — without putting your network at risk

Requirements

  • Any Carbon Black Cloud product
  • API Key with appropriate permissions

Quick Setup

Typical use of the API follows this sequence:

  1. Create a Sensor Update Job using https://{cbc-hostname}/sus/v2/orgs/{org_key}/jobs?job_type={job_type}
  2. Receive the job ID
  3. Call https://{cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id} route to get job progress
  4. If needed call https://{cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id}/status to cancel an in progress job

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Sensor jobs: {cbc-hostname}/sus/v2/orgs/{org_key}/jobs/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Device > Sensor kits > org.kits, allow permission to EXECUTE
  • Device > General information > device, allow permission to READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Sensor jobs:{cbc-hostname}/sus/v2/orgs/{org_key}/jobs/

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Device:org.kits, allow permission to EXECUTE
  • _API.Device:device, allow permission to READ

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

API Calls

Create a Sensor Update Job

Create a job that will update all sensors that match either the search_definition or a list of device_ids. Only one of these criteria may be used.

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.kits EXECUTE Majority of environments
VMware Cloud Services Platform _API.Device:org.Kits:execute N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

POST {cbc-hostname}/sus/v2/orgs/{org_key}/jobs?job_type={job_type}

Request Body

{
  "action_type": "UPDATE_SENSOR_VERSION",
  "device_id": [
    0
  ],
  "options": {
    "sensor_version": {
      "WINDOWS": "3.4.0.1",
      "MAC": "2.1.1.1"
    }
  },
  "search_definition": {
    "criteria": {
      "ad_group_id": [
        0
      ],
      "id": [
        0
      ],
      "last_contact_time": {
        "range": "string"
      },
      "policy_id": [
        0
      ],
      "status": [
        "string"
      ],
      "target_priority": [
        "string"
      ]
    },
    "query": "string",
    "rows": 0,
    "sort": [
      {
        "field": "string",
        "order": "ASC"
      }
    ],
    "start": 0
  }
}

Query Schema

Field Definition Data Type Values
job_type The type of sensor update job. String Default: ENDPOINT
Options: ENDPOINT

Body Schema

Field Definition Data Type Values
action_type REQUIRED Indicates the action that is being taken by the job. String Options: UPDATE_SENSOR_VERSION
device_id The list of devices to be updated. This is mutually exclusive if search_definition parameter is provided. Array 
[ 0, 1, 2, 3 ]
options.sensor_version REQUIRED A map between sensor kit types such as WINDOWS, UBUNTU, etc. to the desired sensor version. The sensor version is the version that the sensor will be updated too. Options: XP, WINDOWS, MAC, RHEL, UBUNTU, SUSE, AMAZON_LINUX, MAC_OSX, OTHER Object 
{
  "WINDOWS": "3.4.0.1016",
  "MAC": "2.1.1.1"
}
search_definition A device search to apply a sensor update to matching devices. This is mutually exclusive if device_id list is provided. Object See below properties.
search_definition.criteria A map of searchable device properties to limit the which sensors will be updated. Support properties: ad_group_id, id, last_contact_time, policy_id, status, target_priority. Object 
{
  "policy_id": [ 0, 1, 2 ],
  "last_contact_time": {
    "range": "2w"
  }
}
last_contact_time supports 3h, 1d, 1w, 2w, and 1m

status supports PENDING, REGISTERED, UNINSTALLED, DEREGISTERED, ACTIVE, INACTIVE, ERROR, ALL, BYPASS_ON, BYPASS, QUARANTINE, SENSOR_OUTOFDATE, DELETED, LIVE

target_priority supports LOW, MEDIUM, HIGH, and MISSION_CRITICAL
search_definition.query A plaintext search query String N/A
search_definition.sort A list of sorts to apply to the search. Each sort must contain a field and order. Order supports asc or desc Array 
[{
  "field": "last_contact_time",
  "order": "desc"
}]
search_definition.rows Limits the number of devices returned that matched the criteria. Integer Default: 10k
Max: 10k
search_definition.start The index of the search to start returning matched devices. Integer Default: 0

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/sus/v2/orgs/ABCD1234/jobs?job_type=ENDPOINT

Request Body 

{
  "device_id": [
    0, 1, 2, 3
  ],
  "options": {
    "sensor_version": {
      "WINDOWS": "3.4.0.1016"
    }
  },
  "action_type": "UPDATE_SENSOR_VERSION"
}

Response

{
	"success": true,
	"message": "Sensor update job started",
	"job": {
		"id": "c0c790dd-4c97-4847-a93e-19674c7b9b68",
		"org_key": "ABCD1234",
		"login_name": "tester@scargoinc.com",
		"status": "IN_PROGRESS",
		"create_time": "2020-07-16T15:31:27.105Z",
		"start_time": "2020-07-16T15:31:27.690Z",
		"end_time": null,
		"sensor_versions": {
			"WINDOWS": "3.4.0.1",
			"MAC": "2.1.1.1"
		},
		"sensors": {},
		"job_type": "ENDPOINT"
	}
}

Get the details of a job

Get the details of a sensor update service job

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud device READ Majority of environments
VMware Cloud Services Platform _API.Device:device:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/sus/v2/orgs/ABCD1234/jobs/c0c790dd-4c97-4847-a93e-19674c7b9b68

Response

{
	"id": "c0c790dd-4c97-4847-a93e-19674c7b9b68",
	"org_key": "ABCD1234",
	"login_name": "tester@scargoinc.com",
	"status": "IN_PROGRESS",
	"create_time": "2020-07-16T15:31:27.105Z",
	"start_time": "2020-07-16T15:31:27.690Z",
	"end_time": null,
	"sensor_versions": {
		"MAC": "2.1.1.1",
		"WINDOWS": "3.4.0.1"
	},
	"sensors": {
		"445721": {
			"sensor_state": "NOT_HINTED",
			"reason": "",
			"initial_version": "",
			"updated_version": "",
			"hinted_time": "-999999999-01-01T00:00:00",
			"sensor_kit_type": "WINDOWS"
		},
		"464838": {
			"sensor_state": "NOT_HINTED",
			"reason": "",
			"initial_version": "",
			"updated_version": "",
			"hinted_time": "-999999999-01-01T00:00:00",
			"sensor_kit_type": "WINDOWS"
		}
	},
	"job_type": "ENDPOINT"
}

Get all jobs

Get a list of all the sensor update service jobs for a specified job type in the provided organization

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud device READ Majority of environments
VMware Cloud Services Platform _API.Device:device:read N/A - included in permission name Prod UK and AWS GovCloud (US)
Permission (.notation name) Operation(s)
device READ

Request

GET {cbc-hostname}/sus/v2/orgs/{org_key}/jobs?job_type={job_type}

Query Schema

Field Definition Data Type Values
job_type The type of sensor update job. String Default: ENDPOINT
Options: ENDPOINT

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/sus/v2/orgs/ABCD1234/jobs

Response 

[{
	"id": "4e97a0fc-e9b0-431f-ab94-34432f7cc540",
	"create_time": "2020-07-16T15:48:18.169Z",
	"start_time": null,
	"end_time": null,
	"status": "PENDING",
	"percent_complete": 0,
	"targeted": 200,
	"updated": 0,
	"updated_sensors": [],
	"failed": 0,
	"failed_sensors_per_reason": {
		"JOB_CANCELLED": [],
		"NO_DATA_FOUND": [],
		"JOB_EXPIRED": [],
		"JOB_INITIALIZATION": []
	},
	"sensor_versions": {
		"MAC": "2.1.1.1",
		"WINDOWS": "3.4.0.1"
	}
},
{
	"id": "c0c790dd-4c97-4847-a93e-19674c7b9b68",
	"create_time": "2020-07-16T15:31:27.105Z",
	"start_time": "2020-07-16T15:31:27.690Z",
	"end_time": null,
	"status": "IN_PROGRESS",
	"percent_complete": 0,
	"targeted": 200,
	"updated": 0,
	"updated_sensors": [],
	"failed": 0,
	"failed_sensors_per_reason": {
		"JOB_CANCELLED": [],
		"NO_DATA_FOUND": [],
		"JOB_EXPIRED": [],
		"JOB_INITIALIZATION": []
	},
	"sensor_versions": {
		"MAC": "2.1.1.1",
		"WINDOWS": "3.4.0.1"
	}
}]

Get a list of all the Sensors in the given Job

Returns a list of sensors to be updated by the job and the current status of each sensors. Data is returned in either json or csv.

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud device READ Majority of environments
VMware Cloud Services Platform _API.Device:device:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id}/sensors

Query Schema

Field Definition Data Type Values
format The format to return the sensors String Default: json
Options: csv or json
download Indicates that the response should be marked for download. A Content-Disposition header will be included in the response when true. Boolean Default: false

Response

Code Description Content-Type Content
200 Successful Request application/json or text/csv View example response below
400 Invalid request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/sus/v2/orgs/ABCD1234/jobs/c0c790dd-4c97-4847-a93e-19674c7b9b68/sensors?format=csv

Response

Device ID,Update Status,Failure Reason,Initial Device Version,Update Device Version,Initiated Update Time UTC,OS
1,NOT_HINTED,,,,-999999999-01-01T00:00,WINDOWS
2,NOT_HINTED,,,,-999999999-01-01T00:00,WINDOWS
3,NOT_HINTED,,,,-999999999-01-01T00:00,WINDOWS

Cancel an in progress Job

Cancels a sensor update service job that is in progress

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.kits EXECUTE Majority of environments
VMware Cloud Services Platform _API.Device:org.Kits:execute N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id}/status

Request Body

 {
   "status": "CANCELLED"
 }

Body Schema

Field Definition Data Type Values
status REQUIRED The status to update the sensor job String Options: CANCELLED

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/sus/v2/orgs/ABCD1234/jobs/c0c790dd-4c97-4847-a93e-19674c7b9b68/status

Request Body

{
  "status": "CANCELLED"
}

Response 

{
	"success": true,
	"message": "Job cancelled",
	"job": {
		"id": "c0c790dd-4c97-4847-a93e-19674c7b9b68",
		"org_key": "ABCD1234",
		"login_name": "tester@scargoinc.com",
		"status": "CANCELLED",
		"create_time": "2020-07-16T15:31:27.105Z",
		"start_time": "2020-07-16T15:31:27.690Z",
		"end_time": "2020-07-16T15:50:56.448Z",
		"sensor_versions": {
			"MAC": "2.1.1.1",
			"WINDOWS": "3.4.0.1"
		},
		"sensors": {
			"445721": {
				"sensor_state": "FAILED",
				"reason": "Job cancelled before sensor updated",
				"initial_version": "",
				"updated_version": "",
				"hinted_time": "-999999999-01-01T00:00:00",
				"sensor_kit_type": "WINDOWS"
			},
			"464838": {
				"sensor_state": "FAILED",
				"reason": "Job cancelled before sensor updated",
				"initial_version": "",
				"updated_version": "",
				"hinted_time": "-999999999-01-01T00:00:00",
				"sensor_kit_type": "WINDOWS"
			}
		},
		"job_type": "ENDPOINT"
	}
}

Fields

Job

Field Definition Data Type Values
id The identifier for the job. String N/A
org_key The organization’s key identifier. String N/A
login_name The user or API ID that created the Sensor Job. String N/A
status The state of the job. String PENDING, IN_PROGRESS, CANCELLED, or COMPLETED
create_time The time at which the job was created as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
start_time The time at which the job was started as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
end_time The time at which the job completed or was cancelled as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
sensor_versions The versions that the sensor will be updated too based on OS. Object 
{
	"MAC": "2.1.1.1",
	"WINDOWS": "3.4.0.1"
}
sensors A map of the device’s sensor state for the sensor update. See below for details Object 
{
	"445721": {
		"sensor_state": "NOT_HINTED",
		"reason": "",
		"initial_version": "",
		"updated_version": "",
		"hinted_time": "-999999999-01-01T00:00:00",
		"sensor_kit_type": "WINDOWS"
	}
}
job_type The type of sensor job. String ENDPOINT

Job Status

Field Definition Data Type Values
id The identifier for the job. String N/A
status The state of the job. String PENDING, IN_PROGRESS, CANCELLED, or COMPLETED
create_time The time at which the job was created as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
start_time The time at which the job was started as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
end_time The time at which the job completed or was cancelled as an ISO 8601 UTC timestamp. String Example: 2021-04-07T17:49:58.792Z
sensor_versions The versions that the sensor will be updated too based on OS. Object 
{
	"MAC": "2.1.1.1",
	"WINDOWS": "3.4.0.1"
}
percent_complete A percentage number indicating the sensors that have failed or updated. Integer [ 0 - 100]
targeted The number of sensors which are being targeted for update. Integer N/A
updated The number of sensors that have successfully updated. Integer N/A
updated_sensors The sensors that have successfully updated. Array 
[ 0, 1, 2, 3 ]
failed The number of sensors which failed to update. Integer N/A
failed_sensors_per_reason The sensors that have failed grouped by reason. Object 
{
	"JOB_CANCELLED": [ 0, 1, 2, 3 ],
	"NO_DATA_FOUND": [ 0, 1, 2, 3 ],
	"JOB_EXPIRED": [ 0, 1, 2, 3 ],
	"JOB_INITIALIZATION": [ 0, 1, 2, 3 ]
}

Sensor Status

Field Definition Data Type Values
sensor_state The state of the update on sensor. String NOT_HINTED, HINTED, DOWNLOADED, UPDATED, FAILED
reason The description behind the current sensor state. String N/A
initial_version The current version of the sensor before the update. String "#.#.#.#"
updated_version The version to update the sensor too. String "#.#.#.#"
hinted_time The time at which the sensor was told to update. String ISO 8601 UTC timestamp
sensor_kit_type The sensor’s type based on OS. String XP, WINDOWS, MAC, RHEL, UBUNTU, SUSE, AMAZON_LINUX, MAC_OSX, OTHER
Last modified on September 6, 2022