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.

Appliance Overview

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

RBAC 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

Example

Request

POST https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/overview

Request Body

[
  "JWN58JV6IT"
]

Response

[
  {
    "api_id": "JWN58JV6IT",
    "appliance_name": "example-appliance",
    "appliance_uuid": "60d7daec-617d-443f-bae5-fee9627639ba"
  }
]

Get Appliances

Get a list of appliances.

RBAC 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

Example

Request

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances

Response

[
    {
        "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
    }
]

Get Appliance by UUID

Get an appliance by uuid

RBAC 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

Example

Request

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0

Response

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

Get Appliance Health

Obtain health details of the specified appliance.

RBAC 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

Example

Request

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0/health

Response

{
  "appliance_health": "CONNECTED",
  "gateway": "CONNECTED",
  "apw": "CONNECTED",
  "vsw": "CONNECTED",
  "acs": "CONNECTED",
  "vc_connectivity": "CONNECTED",
  "inventory": "CONNECTED",
  "ip_address": "10.0.0.12"
}

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.

RBAC 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

Example

Request

POST https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/device_actions

Request Body

{
  "device_ids": [
    1,
    2,
    3
  ],
  "action_type": "NSX_REMEDIATION",
  "options": {
    "toggle": "ON",
    "tag": "CB-NSX-Quarantine"
  }
}

Response

{
  "job_ids": [
    "NSX_REMEDIATE_28555395-b563-4f5d-be5a-26b84e12c1c0"
  ]
}

Get Job Status

Checks the status of the specified job id

RBAC 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

Example

Request

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/jobs/NSX_REMEDIATE_28555395-b563-4f5d-be5a-26b84e12c1c0/status

Response

{
  "error_code": "err_404",
  "reason": "Job is completed successfully but response was not delievered.",
  "status": "SUCCESSFUL_UNDELIVERED"
}

Supported Statuses:

  • UNASSIGNED
  • SCHEDULED
  • SUCCESSFUL
  • RUNNING
  • SUCCESSFUL_UNDELIVERED
  • RUNNING_UNDELIVERED
  • FAILED_UNDELIVERED
  • FAILED
  • EXCEPTION
  • TIMEOUT
  • RETRYABLE
  • HANDLER_EXECUTION_COMPLETED
Last modified on September 6, 2022