Carbon Black Cloud

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

Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
- for the category Appliances Registration > “appliances.registration”, allow permission to CREATE, READ and UPDATE (or see each call below for individual requirements)
- for the category Appliances Details > “appliances.details”, allow permission to READ (or see each call below for individual requirements)
- for the category Appliances > “appliance.nsx.remediate”, allow permission to EXECUTE for NSX Remediation
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}/applianceservice/v1/orgs/{org_key}

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

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

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

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

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

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

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 June 21, 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