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.

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.

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.

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.

{

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

Carbon Black Cloud

Page Contents

Appliance Service API

Overview

Requirements

Authentication

API calls

Appliance Overview

Get Appliances

Get Appliance by UUID

Get Appliance Health

NSX Remediation

Get Job Status