# Carbon black

SureCloud connects to VMware Carbon Black Cloud to retrieve device inventory, sensor deployment status, and threat detection alert data. This allows SureCloud to confirm that EDR agents are deployed and active across the endpoint estate, that devices meet compliance baselines, and that the threat detection capability is functioning — providing continuous evidence for endpoint security controls.

## Authentication and setup

Carbon Black Cloud authenticates API requests using an API Key and Connector ID. SureCloud uses a custom-level API key scoped to read-only access.

{% stepper %}
{% step %}
**Create a read-only API key in Carbon Black Cloud**

Log in to the Carbon Black Cloud console. Navigate to **Settings → API Access → API Keys** and click **Add API Key**. Give it a name such as `SureCloud CCM`. For **Access Level Type**, select **Custom**. Click **Save** and copy both the **API ID** (Connector ID) and **API Secret Key** — the secret is only shown once.
{% endstep %}

{% step %}
**Assign a custom access level**

In **Settings → API Access → Access Levels**, create a custom access level named `SureCloud Read Only`. Enable read permissions for: **Devices** (Device general information, read), **Alerts** (Alerts, read), and **Audit Log** (read). Assign this access level to the API key created in step 1.
{% endstep %}

{% step %}
**Identify your Carbon Black Cloud environment URL**

Your Carbon Black Cloud tenant is hosted on a specific backend. Navigate to **Settings → API Access** to find your **ORG KEY** and note the console URL (e.g. `https://defense.conferdeploy.net`). You will need both the environment URL and your Organisation Key for the SureCloud connection.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Carbon Black → Connect**. Enter your Carbon Black Cloud environment URL, Organisation Key, API ID, and API Secret Key. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API Secret Key securely — it is not shown again in the Carbon Black console. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days and update it in **SureCloud → Integrations → Carbon Black → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                              | Use Case                                                                    |
| ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `GET /appservices/v6/orgs/{org_key}/devices/_search`  | Enumerate all endpoints with sensor status, OS, and last check-in time      |
| `POST /appservices/v6/orgs/{org_key}/devices/_search` | Filter devices by policy, status, or operating system for targeted evidence |
| `GET /appservices/v6/orgs/{org_key}/alerts/_search`   | Retrieve threat alerts and detection events across the endpoint estate      |
| `GET /appservices/v6/orgs/{org_key}/policies`         | Enumerate endpoint policies to confirm policy assignment coverage           |
| `GET /appservices/v6/orgs/{org_key}/audit_log/export` | Retrieve audit log entries for administrative activity evidence             |

## Pagination

`POST /appservices/v6/orgs/{org_key}/devices/_search` and the alerts search endpoint use `start` (row offset) and `rows` (page size) parameters. SureCloud increments the `start` value by the page size until the total rows returned equals the `num_found` count in the initial response.

```json
POST /appservices/v6/orgs/{org_key}/devices/_search
{
  "criteria": {},
  "rows": 500,
  "start": 500
}
```

`GET /appservices/v6/orgs/{org_key}/policies` returns all policies in a single response.

## Required permissions

SureCloud requires a Carbon Black Cloud API key with a custom access level granting:

| Resource                   | Permission |
| -------------------------- | ---------- |
| Device general information | Read       |
| Alerts                     | Read       |
| Policies                   | Read       |
| Audit Log                  | Read       |

No write, delete, or Live Response permissions are required.

## Polling frequency

| Data Type                          | Interval       |
| ---------------------------------- | -------------- |
| Device inventory and sensor status | Every 24 hours |
| Threat alerts and detection events | Every 4 hours  |
| Endpoint policies                  | Every 24 hours |
| Audit log entries                  | Every 6 hours  |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API ID, API Secret Key, or Organisation Key is incorrect, or the API key has been deleted. Navigate to **Carbon Black Cloud → Settings → API Access → API Keys**, confirm the key exists and is active, and re-enter all credentials in **SureCloud → Integrations → Carbon Black → Edit Connection**. Ensure the Organisation Key matches the org the API key was created in.

</details>

<details>

<summary>Device count in SureCloud is lower than expected</summary>

If the custom access level does not include **Device general information (read)**, the devices search endpoint will return empty results without an explicit error. Verify the access level assigned to the SureCloud API key in **Carbon Black Cloud → Settings → API Access → Access Levels**. Also confirm the correct environment URL is configured — using the wrong backend URL will return an empty org.

</details>

<details>

<summary>Alerts are missing for a specific time range</summary>

Carbon Black Cloud alert search results are filtered by time range. SureCloud uses a rolling lookback window defined by the polling interval. If the polling cycle was interrupted, some alerts from the gap period may not be captured. Trigger a manual refresh from **SureCloud → Integrations → Carbon Black** to re-collect recent data.

</details>

<details>

<summary>403 Forbidden on specific endpoints</summary>

A 403 response indicates the API key's custom access level does not include permission for that specific resource. Review the access level permissions in **Carbon Black Cloud → Settings → API Access → Access Levels** and add read permission for any missing resource types.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/carbon-black.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.