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
Typical use of the API follows this sequence:
https://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs?job_type={job_type}
https://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs/{job_id}
route to get job progresshttps://defense-<environment>.conferdeploy.net/sus/v2/orgs/{org_key}/jobs/{job_id}/status
to cancel an in progress jobUse the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.
/sus/v2/orgs/{org_key}/jobs
Note: when you insert your org_key, you must also remove the { } brackets.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 |
|
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 |
|
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 |
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 |
|
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 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 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"
}
}]
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
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"
}
}
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 |
|
sensors |
A map of the device’s sensor state for the sensor update. See below for details | Object |
|
job_type |
The type of sensor job. | String | ENDPOINT |
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 |
|
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 |
|
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 |
|
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 |