Appliance Service API

Overview

This API lets Carbon Black Cloud Workload users query appliance registration details and health status.

This also allows user to fine tune appliance configurations like heartbeat interval.

Requirements

  • Appliance and vSphere configured to communicate with the Carbon Black Cloud see Installation Guide for more information
  • Carbon Black Cloud Workload - You must be a Carbon Black Cloud Workload customer
  • All API calls require an API key with appropriate permissions see Authentication

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.
  • Applicance Information: {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/
  • Device Actions: {cbc-hostname}/applianceservice/v1/orgs/{org_key}/device_actions/
  • Job Status: {cbc-hostname}/applianceservice/v1/orgs/{org_key}/jobs/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Appliances Registration > appliances.registration, allow permission to CREATE, READ, UPDATE
  • Appliances Details > appliances.details, allow permission to READ
  • Appliances > appliance.nsx.remediate, 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.
  • {

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.Appliances:appliances.Registration, allow permission to CREATE, READ, UPDATE
  • _API.Appliances:appliances.details, allow permission to READ
  • _API.Appliances:appliance.Nsx.Remediate, 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.

Search Gateway Components (v2)

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.details READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.details:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/applianceservice/v2/orgs/{org_key}/gateway/components/_search

Request Body - application/json

{
  "query": "<string>",
  "criteria": {
    "type": [
      "<string>"
    ],
    "sensor_gateway_url": [
      "<string>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>,
  "rows": <integer>
}

Body Schema

Field Definition Data Type Values
query Query string that supports plaintext value searching String N/A
criteria Criteria is an object that represents values that must be in the results. Object 
{
    "type": [
      "<string>"
    ],
    "sensor_gateway_url": [
      "<string>"
    ]
}
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "heartbeat_timestamp",
  "order": "ASC"
}]
order supports ASC or DESC

Supported fields: api_id, container_id, heartbeat_timestamp, name, sensor_gateway_url
start First row to use for pagination Integer Default: 0
rows Number of rows to request, can be paginated Integer Default: 50

Response Codes

Code Description Content-Type Content
200 Successfully searched components application/json See example below
401 Unauthorized application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Forbidden application/json N/A
500 Internal Server Error application/json N/A

Examples

Request 
POST https://defense.conferdeploy.net/orgs/{org_key}/gateway/components/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "MY_GATEWAY",
  "criteria": {
    "type": [
      "SENSOR_GATEWAY"
    ]
  },
  "sort": [
    {
    "field": "heartbeat_timestamp",
    "order": "ASC"
    }
  ],
  "start": "0",
  "rows": "1"
}
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "type": "SENSOR_GATEWAY",
            "api_id": "YE9HK45678",
            "name": "MY_GATEWAY",
            "heartbeat_timestamp": "2022-12-20T09:19:17.831465Z",
            "version": "1.0.0",
            "plugin_version": null,
            "ip_address": "",
            "uuid": "6ca49d6f-bd99-48b0-99e8-ca1910b720ba",
            "group_uuid": "309fe855-755e-42fe-9dac-b151b7654977",
            "vcenter_connectivity": null,
            "status": "DISCONNECTED",
            "vcenter_uuid": null,
            "vcenter_name": null,
            "log_export": null,
            "nsx_connectivity": null,
            "system_information": null,
            "vcenter_type": null,
            "sensor_gateway_url": "https://10.0.0.5",
            "container_id": "e580b0ae974d",
            "access_key_name": "SGW_key",
            "certificate_exp_date": null
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Gateway Components (v2)

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud sensor.gateway.registration DELETE Majority of environments
VMware Cloud Services Platform _API.Sensor.Gateway:sensor.gateway.registration:delete N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/applianceservice/v2/orgs/{org_key}/gateway/components/_delete

Request Body - application/json

["<string>"]

Body Schema

Field Definition Data Type Values
Array List of component uuids to be deleted Array

Response Codes

Code Description Content-Type Content
200 application/json 
{
  "success": true,
  "message": "Component deleted successfully"
}

Examples

Request 
POST https://defense.conferdeploy.net/orgs/{org_key}/gateway/components/_delete
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
["6ca49d6f-bd99-48b0-99e8-ca1910b720ba"]
Response Body 
{
  "success": true,
  "message": "Component deleted successfully"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Appliance Overview

Get a list of appliances using the API Key IDs associated with each appliance

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.details READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.details:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/overview

Request Body

[
  "<string>"
]

Body Schema

Field Definition Data Type Values
Array List of API Key IDs Array 
[
  "JWN58JV6IT"
]

Response

Code Description Content-Type Content
200 Successfully fetch appliance ids application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
POST https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/overview
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
  "JWN58JV6IT"
]
Response Body 
[
  {
    "api_id": "JWN58JV6IT",
    "appliance_name": "example-appliance",
    "appliance_uuid": "60d7daec-617d-443f-bae5-fee9627639ba"
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Get Appliances

Get a list of appliances.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.details READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.details:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances

Query Schema

Field Definition Data Type Values
status Filter the results by the appliance status String Supported:
CONNECTED, DISCONNECTED, UNHEALTHY
vc_connectivity Filter the results by the vcenter connectivity String Supported:
CONNECTED, DISCONNECTED, UNHEALTHY
vc_uuid Fetch the appliance associated with the specified vcenter uuid String N/A

Response

Code Description Content-Type Content
200 Successfully registered appliance application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
[
    {
        "api_id": "CRER15EQ37",
        "name": "cwp-bucket-1-appliance",
        "heartbeat_timestamp": "2020-10-16T20:05:00.247953Z",
        "version": "1.0.0.0-17044458",
        "plugin_version": null,
        "ip_address": "10.0.0.88",
        "appliance_uuid": "b2c09f13-600c-4a76-b82b-737fa795a1b6",
        "appliance_group_uuid": "be9a29c8-1b5e-4d4b-9998-ee9da8c1436c",
        "vc_connectivity": "DISCONNECTED",
        "status": "DISCONNECTED",
        "vcenter_uuid": null
    },
    {
        "api_id": "ECGT1AWSZ9",
        "name": "my-custom-appliance",
        "heartbeat_timestamp": "2020-08-28T05:25:46.369Z",
        "version": "1.0.0.0-17044458",
        "plugin_version": null,
        "ip_address": "10.0.0.12",
        "appliance_uuid": "e4e0131b-d8ea-4a98-a752-7fbfb6c253e0",
        "appliance_group_uuid": "93f69b41-880d-4227-8e1d-8619de72da94",
        "vc_connectivity": "CONNECTED",
        "status": "CONNECTED",
        "vcenter_uuid": null
    }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Get Appliance by UUID

Get an appliance by uuid

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.details READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.details:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}

Response

Code Description Content-Type Content
200 Successfully fetch appliance N/A N/A
403 Forbidden N/A N/A
404 Appliance not found with the specified appliance ID N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "api_id": "ECGT1AWSZ9",
    "name": "my-custom-appliance",
    "heartbeat_timestamp": "2020-08-28T05:25:46.369Z",
    "version": "1.0.0.0-17044458",
    "plugin_version": null,
    "ip_address": "10.0.0.12",
    "appliance_uuid": "e4e0131b-d8ea-4a98-a752-7fbfb6c253e0",
    "appliance_group_uuid": "93f69b41-880d-4227-8e1d-8619de72da94",
    "vc_connectivity": "CONNECTED",
    "status": "CONNECTED",
    "vcenter_uuid": null
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Appliance Health

Obtain health details of the specified appliance.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.registration READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.Registration:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}/health

Response

Code Description Content-Type Content
200 Successful retrieved appliance health details application/json View example response below
403 Forbidden N/A N/A
404 Appliance not found with the specified appliance ID N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0/health
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "appliance_health": "CONNECTED",
  "gateway": "CONNECTED",
  "apw": "CONNECTED",
  "vsw": "CONNECTED",
  "acs": "CONNECTED",
  "vc_connectivity": "CONNECTED",
  "inventory": "CONNECTED",
  "ip_address": "10.0.0.12"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Health statuses can be one of CONNECTED, DISCONNECTED, UNHEALTHY.

NSX Remediation

The device actions endpoint allows you to create and execute an action on devices associated with an appliance.

Prerequisites

  • The VM workload must be associated with a Carbon Black Cloud Workload appliance that is registered with NSX, and has an active NSX connectivity. For information on registering the appliance with NSX, see VMware Carbon Black Cloud Workload Guide.
  • The VM workload must have a Carbon Black Cloud sensor installed with the following versions:
    • For Windows - 3.6 or later.
    • For Linux - 2.9 or later.
  • The VM workload must be on an NSX N-VDS (opaque network) to have the Apply NSX Tag option available.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.nsx.remediate EXECUTE Majority of environments
VMware Cloud Services Platform _API.Appliances:appliance.Nsx.Remediate:execute N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/applianceservice/v1/orgs/{org_key}/device_actions

Request Body

{
  "device_ids": [<integer>, <integer>],
  "action_type": "<string>",
  "options": {
    "toggle": "<string>",
    "tag": "<string>"
  }
}

Body Schema

Field Definition Data Type Values
action_type REQUIRED Action to perform on selected devices. String NSX_REMEDIATION
device_ids REQUIRED List of Device Ids Array
options.toggle Determines whether to enable or disable the action.

Required if action_type is set to NSX_REMEDIATION.		 String ON, OFF
options.tag The NSX tag to apply to specified devices String CB-NSX-Quarantine,
CB-NSX-Isolate,
CB-NSX-Custom

Supported NSX Tags

Option Description
CB-NSX-Quarantine With this policy, the VM workload associated with the pre-registered tag is quarantined from the network. This is a read only policy for NSX administrators. The policy only allows the following network flows:
  • DHCP for IP addresses and DNS traffic for name resolution.
  • HTTPS traffic to a list of FQDNs required by the sensor to remain connected to Carbon Black Cloud. The VM has a limited internet connectivity specified by the FQDNs in the policy definition.
CB-NSX-Isolate With this policy the VM workload associated with the pre-registered tag is completely isolated from the network. This is a read only policy for NSX administrators.
CB-NSX-Custom This policy is fully customizable. By applying this policy, the NSX administrator can enforce any rules on VM workloads. Thus, advanced users can create a custom security posture.

Response

Code Description Content-Type Content
201 Successfully created action application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
POST https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/device_actions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "device_ids": [
    1,
    2,
    3
  ],
  "action_type": "NSX_REMEDIATION",
  "options": {
    "toggle": "ON",
    "tag": "CB-NSX-Quarantine"
  }
}
Response Body 
{
  "job_ids": [
    "NSX_REMEDIATE_28555395-b563-4f5d-be5a-26b84e12c1c0"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Job Status

Checks the status of the specified job id

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud appliances.registration READ Majority of environments
VMware Cloud Services Platform _API.Appliances:appliances.Registration:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/jobs/{job_id}/status

Response

Code Description Content-Type Content
200 Successfully returned job status application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/jobs/NSX_REMEDIATE_28555395-b563-4f5d-be5a-26b84e12c1c0/status
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "error_code": "err_404",
  "reason": "Job is completed successfully but response was not delievered.",
  "status": "SUCCESSFUL_UNDELIVERED"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Supported Statuses:

  • UNASSIGNED
  • SCHEDULED
  • SUCCESSFUL
  • RUNNING
  • SUCCESSFUL_UNDELIVERED
  • RUNNING_UNDELIVERED
  • FAILED_UNDELIVERED
  • FAILED
  • EXCEPTION
  • TIMEOUT
  • RETRYABLE
  • HANDLER_EXECUTION_COMPLETED

Last modified on February 15, 2023