> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Carbon Black

> Connect ThreatAware to Carbon Black Cloud for endpoint security and threat detection

## Overview

The Carbon Black integration enables ThreatAware to collect read-only data from your Carbon Black Cloud environment, providing visibility into endpoint security status and helping validate your endpoint protection controls.

<Info>
  **Connection Method**: API
  **Setup Time**: 20 minutes
  **Access Required**: Carbon Black Cloud Administrator account
</Info>

## Data collected

The Carbon Black integration provides:

* Device security status
* Threat detection and response metrics
* Endpoint compliance data
* Security policy enforcement details

## Use cases

<CardGroup cols={2}>
  <Card title="Endpoint Security Tracking" icon="shield-check">
    Monitor endpoint security status across all managed devices
  </Card>

  <Card title="Compliance Validation" icon="clipboard-check">
    Verify endpoint protection controls are properly configured
  </Card>

  <Card title="Threat Monitoring" icon="eye">
    Track threats and security incidents across your environment
  </Card>

  <Card title="Audit Support" icon="file-contract">
    Generate reports showing endpoint protection coverage
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Log in to ThreatAware Dashboard">
    Open the ThreatAware dashboard and navigate to **Settings** > **Systems**.
  </Step>

  <Step title="Search for Carbon Black">
    Use the search bar to find **Carbon Black** and click **Connect**.
  </Step>

  <Step title="Obtain Carbon Black API Configuration">
    Log in to the Carbon Black Cloud Dashboard and obtain your API URL from the [Carbon Black Knowledge Base](https://community.carbonblack.com/t5/Knowledge-Base/Carbon-Black-Cloud-What-URLs-are-used-to-access-the-APIs/ta-p/67346).
  </Step>

  <Step title="Create Custom Access Level">
    In Carbon Black Cloud:

    * Navigate to **Settings** > **API Access** > **Access Levels**
    * Click **Add Access Level** and name it "ThreatAware"
    * Add the **Device READ** permission
    * Save the access level
  </Step>

  <Step title="Create API Key">
    In Carbon Black Cloud:

    * Go to **Settings** > **API Access** > **API Keys**
    * Click **Add API Key** and name it "ThreatAware"
    * Select **Access Level Type: Custom** and choose the "ThreatAware" access level
    * Enter the current ThreatAware allowlist IP addresses, available in-product under **Settings → Integrations → AWS Account / IP Whitelist Info**
    * Click **Save**
    * Copy the **API Secret Key** and **API ID**
  </Step>

  <Step title="Retrieve Organisation Key">
    From the **Settings** > **API Access** > **API Keys** section:

    * Locate and copy your **Org Key** (ensure it does not include any `< >` or `{}` brackets)
  </Step>

  <Step title="Configure in ThreatAware">
    In the ThreatAware integration form, enter the required details:

    * **API URL**: Paste the URL obtained from Carbon Black
    * **API Secret Key**: Paste the secret key
    * **API ID**: Paste the API ID
    * **Org Key**: Paste the organisation key
    * Click **Connect** to establish the integration
  </Step>

  <Step title="Verify Connection">
    After connecting, verify that the integration status shows as **Active** in ThreatAware.
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="API URL" icon="link">
    **Field Name**: Carbon Black API URL
    **Type**: String
    **Description**: The URL endpoint for the Carbon Black Cloud API

    Obtain this from your Carbon Black Cloud dashboard settings.
  </Accordion>

  <Accordion title="API ID" icon="key">
    **Field Name**: Carbon Black API ID
    **Type**: String
    **Description**: The API ID generated in Carbon Black Cloud

    This is used to identify your API key.
  </Accordion>

  <Accordion title="API Secret Key" icon="lock">
    **Field Name**: Carbon Black API Secret Key
    **Type**: Password (encrypted)
    **Description**: The secret associated with your Carbon Black API key

    <Tip>
      Store this credential securely in your organisation's password manager for future reference.
    </Tip>
  </Accordion>

  <Accordion title="Org Key" icon="building">
    **Field Name**: Carbon Black Org Key
    **Type**: String
    **Description**: Your Carbon Black organisation key

    Found in **Settings** > **API Access** > **API Keys**. Do not include `< >` or `{}` brackets.
  </Accordion>
</AccordionGroup>

## Verification and testing

After setup, verify the integration is working correctly:

1. **Check Integration Status**
   * Navigate to **Settings** > **Integrations** in ThreatAware
   * Confirm the Carbon Black integration shows **Active** status

2. **Verify Data Collection**
   * Wait 60 minutes for the initial data poll
   * Search for a known device in ThreatAware
   * Check device details for Carbon Black security data

3. **Test Queries**
   * Create a test query to filter devices by Carbon Black security status
   * Verify the data matches your expectations

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed - Invalid Credentials" icon="triangle-exclamation">
    **Symptoms**: Integration fails to connect with authentication error

    **Solutions**:

    * Verify all credentials are correct and complete
    * Ensure there are no typos in the IP addresses or API keys
    * Confirm the API URL is correct for your region
    * Check that the API key has not expired
  </Accordion>

  <Accordion title="Permission Issues" icon="ban">
    **Symptoms**: Integration connects but no device data appears

    **Solutions**:

    * Verify the API key permissions are set correctly
    * Ensure the **Device READ** permission is enabled
    * Review the access level configuration in Carbon Black
    * Check if there are organisational policies restricting API access
  </Accordion>

  <Accordion title="No Data After 1 Hour" icon="database">
    **Symptoms**: Integration shows active but no endpoint data appears

    **Solutions**:

    * Verify there are managed devices in your Carbon Black environment
    * Check the API access level scope
    * Ensure devices are properly enrolled in Carbon Black
    * Review ThreatAware integration logs (contact support if needed)
  </Accordion>

  <Accordion title="Network Connectivity Issues" icon="wifi">
    **Symptoms**: Integration fails with timeout errors

    **Solutions**:

    * Verify the API URL is accessible from ThreatAware
    * Check firewall rules allow outbound HTTPS (443) to Carbon Black
    * Confirm the IP addresses are correctly configured in the firewall
    * Test API URL connectivity using a web browser
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="Carbon Black API Documentation" icon="book" href="https://developer.carbonblack.com/reference/latest">
    Official Carbon Black API documentation for detailed configuration
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **Credential Management**

  * Create a dedicated API key specifically for ThreatAware
  * Document credentials in your organisation's password manager
  * Rotate credentials annually or per your security policy
  * Monitor for authentication failures in ThreatAware regularly
</Tip>

<Tip>
  **Security Considerations**

  * Only grant read-only permissions (Device READ)
  * Limit API key scope to necessary devices and data
  * Review audit logs in Carbon Black periodically
  * Follow your organisation's least privilege principles
</Tip>