Sensor Update Services API

This API will be deactivated on September 5, 2024.

The v2 Sensor Update Services API has been deprecated and replaced by the v3 Sensor Update Services API.

Migration information is available here.

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

Guides and Resources

Quick Setup

Typical use of the API follows this sequence:

Create a Sensor Update Job using https://{cbc-hostname}/sus/v2/orgs/{org_key}/jobs?job_type={job_type}
Receive the job ID
Call https://{cbc-hostname}/sus/v2/orgs/{org_key}/jobs/{job_id} route to get job progress
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.

CBC Managed Identity

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.

CSP Managed Identity

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.

API 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

API 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

API 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.

API 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

API 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 August 16, 2023

Carbon Black Cloud

Page Contents

Sensor Update Services API

Introduction

Requirements

Guides and Resources

Quick Setup

Authentication

API Calls

Create a Sensor Update Job

Get the details of a job

Get all jobs

Get a list of all the Sensors in the given Job

Cancel an in progress Job

Fields

Job

Job Status

Sensor Status