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

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:

    • for the category Workload Management > Install sensor on vCenter workload > “workloads.vcenter.vm_sensor_install”, allow permission to EXECUTE (or see each call below for individual requirements)

  • 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: {cbc-hostname}/lcm/view/v1/orgs/{org_key}/compute_resources/{id}

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

Permission (.notation name) Operation(s)
workloads.vcenter.vm_sensor_install EXECUTE

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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 June 8, 2021