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://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs?job_type={job_type}
  2. Receive the job ID
  3. Call https://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs/{job_id} route to get job progress
  4. If needed call https://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs/{job_id}/status to cancel an in progress job

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

  • Access Level: Before you create your API Key, you need to create one or two “Custom” Access Levels
    • for the category Device > Sensor kits > “org.kits” allow permission for “EXECUTE”
    • for the category Device > General information > “device” allow permission for “READ”
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
  • API Route: /sus/v2/orgs/{org_key}/jobs Note: when you insert your org_key, you must also remove the { } brackets.

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

Permission (.notation name) Operation(s)
org.kits EXECUTE

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

Permission (.notation name) Operation(s)
device READ

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

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

Permission (.notation name) Operation(s)
device READ

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

Permission (.notation name) Operation(s)
org.kits EXECUTE

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 July 21, 2020