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