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.
Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
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}
Note: when you insert your org_key, you must also remove the { } brackets.
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 |
|
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 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 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
}
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
.
The device actions endpoint allows you to create and execute an action on devices associated with an appliance.
Prerequisites
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:
|
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"
]
}
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