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.


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.


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

API 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


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"
}

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"
}

Generates a sensor and config download link

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}/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


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
    }
  ]
}

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

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

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 February 15, 2023