Sensor Lifecycle Management

Overview

This API lets you install Carbon Black Cloud sensors onto vSphere-based cloud workloads and get sensor kit and config file URL for integration with WorkspaceONE. You can asynchronously install Carbon Black Cloud sensors onto vSphere-based workloads, and you can stagger installation to reduce performance impact on vSphere and the client network.

Use Cases

Life cycle management from cloud
This API allows users to asynchronously install Carbon Black Cloud sensors on vSphere based workloads
Allows staggering of installation to reduce load on vSphere and client network

Requirements

Appliance and vSphere configured to communicate with the Carbon Black Cloud see Installation Guide for more information
Carbon Black Cloud Workload - You must have purchased one of the Carbon Black Cloud Workload packages
All API calls require an API key with appropriate permissions see Authentication

Quick Start Instructions

Multipart/Form-Data API Requests

This API includes two API routes, Request Workload Sensor Installation and Get Sensor Kit and Configuration Links, that use multipart/form-data in order to make a request. Multipart/form-data utilizes blocks of data to send each component of the request with a variable name assigned to each block. The blocks of data are expected as text or binary data.

The following examples show how to make a multipart/form-data using either cURL or Postman.

cURL

curl --location --request POST 'https://defense.conferdeploy.net/lcm/v1/orgs/ABCD1234/workloads/actions' \
--header 'X-auth-token: API_SECRET_KEY/API_ID' \
--form 'action_type=INSTALL' \
--form 'file=@/Users/john.doe/Desktop/Config.ini' \
--form 'install_request={
   "compute_resources":[
      {
         "resource_manager_id":"0bc37979-162b-4bf7-84eb-3b24959d6574",
         "compute_resource_id":"1234"
      }
   ],
   "sensor_types":[
      {
         "device_type":"WINDOWS",
         "architecture":"64",
         "type":"WINDOWS",
         "version":"3.7.0.1253"
      }
   ]
};type=application/json'

Postman

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.

Workload: {cbc-hostname}/lcm/v1/orgs/{org_key}/workloads/
Sensor: {cbc-hostname}/lcm/v1/orgs/{org_key}/sensor/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:

Workload Management > Install sensor on vCenter workload > workloads.vcenter.vm_sensor_install, allow permission to EXECUTE
Device > Sensor kits > org.kits, allow permission to EXECUTE

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.

Workload: {cbc-hostname}/lcm/v1/orgs/{org_key}/workloads/
Sensor: {cbc-hostname}/lcm/v1/orgs/{org_key}/sensor/

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.Workload.Management:workloads.Vcenter.Vm_sensor_install, allow permission to EXECUTE
_API.Device:org.Kits, allow permission to EXECUTE

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

Note: when you insert your org_key, you must also remove the { } brackets.

Request Workload Sensor Installation

Starts the install process of Carbon Black Cloud sensors on VMs

RBAC Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`workloads.vcenter.vm_sensor_install`	`EXECUTE`	Majority of environments
VMware Cloud Services Platform	`_API.Workload.Management:workloads.Vcenter.Vm_sensor_install:execute`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/lcm/v1/orgs/{org_key}/workloads/actions

Request Body - multipart/form-data

action_type: <string>

install_request

{
  "compute_resources": [
    {
      "resource_manager_id": "<string>",
      "compute_resource_id": "<string>"
    }
  ],
  "sensor_types": [
    {
      "device_type": "<string>",
      "architecture": "<string>",
      "type": "<string>",
      "version": "<string>"
    }
  ]
}

file

[customer]
EncodedCompanyCode = ALSK12KHG83B110DKK
CompanyCode = ABCD1234
BackendServer = dev-eap01.conferdeploy.net

Field	Definition	Data Type	Values
`action_type` REQUIRED	The action to perform on the specified workloads	String	`INSTALL`
`install_request` REQUIRED	The compute resources to install Carbon Black Cloud sensors and the sensor version to install	application/json	See Install Request Schema
`file`	A Config.ini file with a list of sensor properties to configure on installation	Config File	See `Windows Sensor Supported Commands` in the Sensor Installation Guide. The guide can be found on the Carbon Black Cloud console under Help

Install Request Schema

Field	Definition	Data Type	Values
`compute_resources`	The list of compute resources to install a Carbon Black Cloud sensor. `compute_resource_id` is the `id` and `resource_manager_id` is the `vcenter_uuid` from VM Workload Search	Array	`[ { "resource_manager_id": "<string>", "compute_resource_id": "<string>" } ]`
sensor_types	The list of sensor types and version to install based on the Workload’s operating system	Array	`[ { "device_type": "<string>", "architecture": "<string>", "type": "<string>", "version": "<string>" } ]` `device_type` supports `WINDOWS`, `LINUX`, `MAC` `architecture` supports `32`, `64`, `OTHER` `type` supports `WINDOWS`, `MAC`, `RHEL`, `UBUNTU`, `SUSE`, `AMAZON_LINUX`

Response

Code	Description	Content-Type	Content
200	Successfully return compute resource	application/json	View example response below
400	The JSON body was malformed, or some part of the JSON body included an invalid value	application/json	N/A
403	Forbidden	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

HTTP

Request

POST https://defense.conferdeploy.net/lcm/v1/orgs/ABCD1234/workloads/actions

Request Headers

X-AUTH-TOKEN: "ABCD1234/DEFG12354"
Content-Type: multipart/form-data

action_type

INSTALL

install_request

{
  "compute_resources": [
    {
      "resource_manager_id": "2581bda7-71fa-400d-a713-b32c16762ad7",
      "compute_resource_id": "5678"
    }
  ],
  "sensor_types": [
    {
      "device_type": "WINDOWS",
      "architecture": "64",
      "type": "WINDOWS",
      "version": "3.7.0.1253"
    }
  ]
}

Response Body

{
  type: "INFO",
  code: "INSTALL_SENSOR_REQUEST_PROCESSED"
}

cURL

Request

$ curl --request POST 'https://defense.conferdeploy.net/lcm/v1/orgs/ABCD1234/workloads/actions' \
--header 'x-auth-token: ABCD1234/DEFG12354' \
--form 'action_type="INSTALL"' \
--form 'install_request={
   "compute_resources":[
      {
         "resource_manager_id":"0ea37979-162b-4bf7-84eb-3b24959d6574",
         "compute_resource_id":"15788644"
      }
   ],
   "sensor_types":[
      {
         "device_type":"WINDOWS",
         "architecture":"64",
         "type":"WINDOWS",
         "version":"3.7.0.1253"
      }
   ]
};type=application/json'

Response Body

{
  type: "INFO",
  code: "INSTALL_SENSOR_REQUEST_PROCESSED"
}

Get Sensor Kit and Configuration Links

Generates a sensor and config download link

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}/lcm/v1/orgs/{org_key}/sensor/_download

Request Body - multipart/form-data

sensor_url_request

{
  "sensor_types": [
    {
      "device_type": "<string>",
      "architecture": "<string>",
      "type": "<string>",
      "version": "<string>"
    }
  ],
  "expires_at": "<string>"
}

configParams

[customer]
EncodedCompanyCode = ALSK12KHG83B110DKK
CompanyCode = ABCD1234
BackendServer = dev-eap01.conferdeploy.net

Field	Definition	Data Type	Values
`sensor_url_request` REQUIRED	The Carbon Black Cloud sensors with version and the expiration time	application/json	See Sensor URL Request Schema
`configParams`	A Config.ini file with a list of sensor properties to configure on installation	Config File	See `Windows Sensor Supported Commands` in the Sensor Installation Guide. The guide can be found on the Carbon Black Cloud console under Help

Sensor URL Request Schema

Field	Definition	Data Type	Values
sensor_types	The list of sensor types and version to install based on the Workload’s operating system	Array	`[ { "device_type": "<string>", "architecture": "<string>", "type": "<string>", "version": "<string>" } ]` `device_type` supports `WINDOWS`, `LINUX`, `MAC` `architecture` supports `32`, `64`, `OTHER` `type` supports `WINDOWS`, `MAC`, `RHEL`, `UBUNTU`, `SUSE`, `AMAZON_LINUX`
`expires_at`	The time at which the sensor download link will expire	String	ISO 8601 UTC timestamp

Response

Code	Description	Content-Type	Content
200	Successfully return compute resource	application/json	View example response below
400	The JSON body was malformed, or some part of the JSON body included an invalid value	application/json	N/A
403	Forbidden	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

HTTP

Request

POST https://defense.conferdeploy.net/lcm/v1/orgs/ABCD1234/sensor/_download

Request Headers

X-AUTH-TOKEN: "ABCD1234/DEFG12354"
Content-Type: multipart/form-data

sensor_url_request

{
  "sensor_types": [
    {
      "device_type": "WINDOWS",
      "architecture": "64",
      "type": "WINDOWS",
      "version": "3.7.0.1253"
    }
  ],
  "expires_at": "2021-06-05T23:39:52Z"
}

Response Body

{
  "sensor_infos": [
    {
      "sensor_type": {
        "device_type": "WINDOWS",
        "architecture": "64",
        "type": "WINDOWS",
        "version": "3.7.0.1253"
      },
      "sensor_url": "https://dev.content.carbonblack.io/eap01/windows/installer_vista_win7_win8-64-3.7.0.1253.msi?Expires=1604619740&Signature=FAKE_SIGNATURE",
      "sensor_config_url": "https://dev.content.carbonblack.io/eap01-installer-config/ebf7ff940f1a148e79adbb7be9e980d8f408454af576c571cc2d979c04218f7b/config-blob.ini?Expires=1604619592&Signature=FAKE_SIGNATURE",
      "error_code": null,
      "message": null
    }
  ]
}

cURL

Request

$ curl --request POST 'https://defense.conferdeploy.net/lcm/v1/orgs/ABCD1234/sensor/_download' \
--header 'x-auth-token: ABCD1234/DEFG12354' \
--form 'sensor_url_request={
  "sensor_types": [
    {
      "device_type": "WINDOWS",
      "architecture": "64",
      "type": "WINDOWS",
      "version": "3.7.0.1253"
    }
  ],
  "expires_at": "2021-06-05T23:39:52Z"
};type=application/json'

Response Body

{
  "sensor_infos": [
    {
      "sensor_type": {
        "device_type": "WINDOWS",
        "architecture": "64",
        "type": "WINDOWS",
        "version": "3.7.0.1253"
      },
      "sensor_url": "https://dev.content.carbonblack.io/eap01/windows/installer_vista_win7_win8-64-3.7.0.1253.msi?Expires=1604619740&Signature=FAKE_SIGNATURE",
      "sensor_config_url": "https://dev.content.carbonblack.io/eap01-installer-config/ebf7ff940f1a148e79adbb7be9e980d8f408454af576c571cc2d979c04218f7b/config-blob.ini?Expires=1604619592&Signature=FAKE_SIGNATURE",
      "error_code": null,
      "message": null
    }
  ]
}

Get Sensor Configuration Template

Gets a sample Config.ini file with the required properties populated

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

GET {cbc-hostname}/lcm/v1/orgs/{org_key}/sensor/config_template

Response

Code	Description	Content-Type	Content
200	Successfully return compute resource	application/octet-stream	View example response below
403	Forbidden	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/lcm/v1/orgs/ABCD1234/sensor/config_template

Response

[customer]
EncodedCompanyCode = ALSK12KHG83B110DKK
CompanyCode = ABCD1234
BackendServer = dev-eap01.conferdeploy.net

Last modified on September 6, 2022

Carbon Black Cloud

Page Contents

Sensor Lifecycle Management

Overview

Use Cases

Requirements

Quick Start Instructions

Multipart/Form-Data API Requests

Authentication

API calls

Request Workload Sensor Installation

Install Request Schema

Get Sensor Kit and Configuration Links

Sensor URL Request Schema

Get Sensor Configuration Template