---
title: "VMware Carbon Black Cloud collector"
canonical: "https://docs.devo.com/space/latest/94657410/VMware%20Carbon%20Black%20Cloud%20collector"
format: markdown
---
> Macro (toc)

## <span style="color: #172b4d">Overview</span>

[VMware Carbon Black](https://www.vmware.com/) is a cloud-native endpoint, workload, and container protection platform that combines the intelligent system hardening and behavioral prevention needed to keep emerging threats at bay, using a single, easy-to-use console. By analyzing more than 1 trillion security events per day, VMware CBC proactively uncovers attackers’ behavior patterns and empowers defenders to detect and stop emerging attacks. 

This Devo collector helps to extend CBC's rich analytics and response actions to the rest of our customers' security stack.

# Devo Collector features

| **Feature** | **Details** |
| --- | --- |
| Allow parallel downloading (`multipod`) | - `Not allowed` |
| Running Environments | - `Collector Server`
- `On Premise` |

## API Limits, Delays, Known Issues

With the credentials used, an intermittent 401(Principal is not authenticated) issue was being seen in the setup  logs. This, however, gets resolved on its own and the puller recovers after some retries. 

## <span style="color: #172b4d">Data source description</span>

| **Data source** | **Table** | **Collector service** | **Remote endpoint** | **Description** |
| --- | --- | --- | --- | --- |
| Alerts | `endpoint.vmware.cbc_api.alerts` | `event_alerts` | <u>[https://defense.conferdeploy.net/api/alerts/v7/orgs/{org_key}/alerts/_search](https://defense.conferdeploy.net/api/alerts/v7/orgs/org_key/alerts/_search)</u> | Alerts Data Source indicates suspicious behavior and known threats in your environment. |
| Audit Logs | `endpoint.vmware.cbc_defender.audit_logs` | `event_audit_logs` | [https://defense.conferdeploy.net/integrationServices/v3/auditlogs](https://defense.conferdeploy.net/integrationServices/v3/auditlogs) | Audit Logs returns audit events in a system, such as when a user signs-in or updates a policy |
| Live Query | `endpoint.vmware.cbc_liveops.live_query` | `event_live_query` | [https://defense.conferdeploy.net//livequery/v1/orgs/{org_key}/runs](https://defense.conferdeploy.net//livequery/v1/orgs/%7Borg_key%7D/runs)/ | Live Query allows users to send custom OSquery based SQL queries to get specific performance and security data |

## Vendor setup

In order to configure the Devo - VMware Carbon Black Cloud collector, you need to create API credentials that will be used to authenticate API requests.

| **Required setup actions by collector services** | **event_alerts** | **event_audit_logs** | **event_live_query** |
| --- | --- | --- | --- |
| Open your API Access console | :check_mark: | :check_mark: | :check_mark: |
| Create a new `audit_token` |  | :check_mark: |  |
| Create a new `generic_token` | :check_mark: |  | :check_mark: |

### Open your API Access console

VMware Carbon Black API Access console allows you to create, remove and edit your API credentials.

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> Log in to your Carbon Black Cloud console.
> 
> ![image](media://911e6718-0a04-43cb-a549-b7b512904e16)
> 
> > Macro (rw-step)
> 
> Now navigate to **Settings** **→ API Access**.
> 
> ![image](media://b4727047-e61b-4631-b2b0-d0e74fe8c6a8)
> 
> > Macro (rw-step)
> 
> Note down your **Org Key**, which is displayed at the top left of the console.
> 
> ![image](media://12e5b593-df13-4c4b-ba28-3fee6c25aaf6)

### Create a new `audit_token`

This token is required to run the `event_audit_logs` service and retrieve the **Audit Logs** data source.

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> On the top right, click **Add API Key** to open the creation screen. 
> 
> ![image](media://6859f1d6-7eea-4856-912a-c89cab8a4848)
> 
> > Macro (rw-step)
> 
> Fill out the **Add API Key** creation form:
> 
> | **Name** | Type in a unique name for your API key. |
> | --- | --- |
> | **Description** | Enter an optional detailed description of the purpose of the credentials. |
> | **Access level type** | Select `API` |
> | **Authorized IP address** | Enter an optional list of authorized IP addresses that this API key can use. |
> 
> ![image](media://7a333fd9-45cb-400f-9e3d-77787abb5885)
> 
> > Macro (rw-step)
> 
> Click **Save**. You will be prompted with a window displaying your API credentials (API ID and API Secret Key). Note them down.
> 
> ![image](media://447706b3-2e1b-4c90-8ff2-12ad9308430c)
> 
> > Macro (rw-step)
> 
> Finally, generate the final token by mixing your `API secret` key + “/” + `API ID` as follows:
> 
> - **API Secret Key** →* *`012345`
> - **API ID** → `ABCDEFGHIJKLMNOPQ`
> 
> The final audit token would be → `012345/ABCDEFGHIJKLMNOPQ`

### Create a new `generic_token`

This token is required to run the `event_alert` service and retrieve the **Alert** data source.

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> Generic tokens require an associated **Access Level**. On the top left, click the **Access Levels** tab.
> 
> > Macro (rw-step)
> 
> On the top right, click on **Add Access Level **to open the creation screen.
> 
> ![image](media://f0ba7c5a-6e6a-4c78-9531-cb007189fe2a)
> 
> > Macro (rw-step)
> 
> Fill out the **Add Access Level** creation form.
> 
> | **Name** | Type in a unique name for your API key. |
> | --- | --- |
> | **Description** | Type in a detailed description of the purpose of the credentials. |
> | **Required permissions** | Add the following permission levels to enable the `event_alert` service:<br>- **org.retention** → `Read`
> - **org.alerts.notes** → `Read`
> - **org.alerts** → `Read`
> - **device** → `Read`<br>Add the following permission levels to enable the `event_live_query` service:<br>- **Live Query** → `Create Read Update Delete Execute` |
> 
> ![image](media://96c9f4f8-d909-4cfd-8d04-2b8a169fac54)
> 
> > Macro (rw-step)
> 
> Click **Save**. Now, go to the **API Keys** tab and click **Add API Key** at the top right area.
> 
> > Macro (rw-step)
> 
> Fill out the **Add API Key** creation form:
> 
> | **Name** | Type in a unique name for your API key. |
> | --- | --- |
> | **Description** | Enter an optional detailed description of the purpose of the credentials. |
> | **Access level type** | Select `Custom`. In the **Custom Access Level **dropdown that appears, choose the **Access Level** role defined |
> | **Authorized IP address** | Enter an optional list of authorized IP addresses that this API key can use. |
> 
> ![image](media://f02ee378-54e2-4941-baaf-1e17e4bdbc85)
> 
> > Macro (rw-step)
> 
> Click **Save**. You will be prompted with a window displaying your API credentials (API ID and API Secret Key). Note them down.
> 
> > Macro (rw-step)
> 
> Finally, generate the final token by mixing your `API secret` key + “/” + `API ID` as follows:
> 
> - **API Secret Key** →* *`012345`
> - **API ID** → `ABCDEFGHIJKLMNOPQ`
> 
> The final audit token would be → `012345/ABCDEFGHIJKLMNOPQ`

## Run the collector

> Macro (rw-ui-tabs-macro)
> 
> > Macro (rw-tab)
> 
> We use a piece of software called Collector Server to host and manage all our available collectors.
> 
> To enable the collector for a customer:
> 
> 1. In the **Collector Server** **GUI**, access the **domain** in which you want this instance to be created
> 2. Click **Add Collector** and find **MVware Carbon Black Cloud - Integrations Factory**.
> 3. In the **Version** field, select the latest value.
> 4. In the **Collector Name** field, set the value you prefer (this name must be unique inside the same Collector Server domain).
> 5. In the sending method select **Direct Send. Direct Send** configuration is optional for collectors that create `Table` events, but mandatory for those that create `Lookups`.
> 6. In the **Parameters** section, establish the **Collector Parameters** as follows below:
> 
> ### Editing the JSON configuration
> 
> ```
> {
>   "inputs":{
>     "carbonblackcloud":{
>       "id": <input_id>,
>       "enabled": <input_status>,
>       "requests_per_second": <request_per_seconds>,
>       "override_base_url": "<override_base_url>",
>       "credentials": {
>         "generic_token": "<generic_token>",
>         "audit_token": "<audit_token>",
>         "org_key": "<org_key>"
>       },
>       "services":{
>         "event_alerts":{
>           "request_period_in_seconds": <request_period_in_second>,
>           "initial_start_time_in_utc": "<start>"
>         },
>         "event_audit_logs":{
>           "request_period_in_seconds": <request_period_in_second>
>         },
>         "event_live_query":{
>           "initial_start_time_in_utc": "<start>",
>           "request_period_in_seconds": <request_period_in_second>,
>           "query_name": "<query_name>",
>           "query": "<query_in_sql>",
>           "query_id": "<query_id>",
>           "soft_timeout_seconds": <soft_timeout_seconds>,
>           "hard_timeout_seconds": <hard_timeout_seconds>,
>           "minimum_percent": <minimum_percent>,
>           "device_filter": <device_filter>
>         }
>       }
>     }
>   }
> }
> ```
> 
> > ℹ️ All defined service entities will be executed by the collector. If you do not want to run any of them, just remove the entity from the `services` object.
> 
> Please replace the placeholders with real world values following the description table below:
> 
> |  |  |  |  |  |
> | --- | --- | --- | --- | --- |
> | **Parameter** | **Data type** | **Type** | **Value range / Format** | **Details** |
> | `input_id` | `int` | `Mandatory` | Minimum length: 1  
> Maximum length: 5 | Use this param to give an unique id to this input service. |
> | `input_status` | `bool` | `Mandatory` | false / true | If the value is true, the input definition will be executed. If the value is false, the service will be ignored. |
> | `requests_per_second` | `int` | `Optional` | Minimum value: 1 | Customize the maximum number of API requests per second. If not used, the default setting will be used: `100000` requests/sec.<br>> 📝 This parameter can be left blank, removed or commented. |
> | `override_base_url` | `str` | `Optional` | Valid URL<br>Regex: `("((http|https)://)(www.)?" + "[a-zA-Z0-9@:%._\\+~#?&//=]" + "{2,256}\\.[a-z]" +     "{2,6}\\b([-a-zA-Z0-9@:%" + "._\\+~#?&//=]*)")` | Set a custom value to override the default URL `https://defense.conferdeploy.net`.<br>> 📝 This parameter can be left blank, removed or commented. |
> | `generic_token` | `str` | `Mandatory` | Minimum length: 1 | Required when running `event_alerts` and `event_live_query_service` service. |
> | `audit_token` | `str` | `Mandatory` | Minimum length: 1 | Required when running `event_audit_logs` service. |
> | `org_key` | `str` | `Mandatory` | Minimum length: 1 | This is your Carbon Black Cloud **Org Key**. |
> | `request_period_in_seconds` | `int` | `Optional` | Minimum length: 1 | Period in seconds used between each data pulling, this value will overwrite the default value (300 seconds)<br>> 📝 This parameter can be left blank, removed or commented. |
> | `start` | `str` | `Mandatory` | Format expected: `YYYY-MM-DD HH:MM:SS` | Parameter used by the collector as the starting `UTC` point when it first pulls data. (Required for event_live_query and event_alerts services)<br>> ⚠️ Updating this value will produce the lost of all persisted data and current pipelines. |
> | `query_name` | `str` | `Mandatory` | Minimum length: 1 | Name to identify the query in the Carbon Black Cloud platform. |
> | `query_in_sql` | `str` | `Mandatory` | Valid SQL query | Query that will be executed must be written in SQL format. |
> | `query_id` | `str` | `Optional` | ID as provided by Osquery | If the user already has a started query from which it wants to extract data from they can write the ID of said query here.<br>> 📝 This parameter can be left blank, removed or commented. |
> | `soft_timeout_seconds` | `int` | `Mandatory` | Minimum length: 1<br>Practical value: between 60 and 300 seconds | Time that the program will wait before reaching minimum percent of completion. |
> | `hard_timeout_seconds` | `int` | `Mandatory` | Minimum length: 1<br>Practical value: between 120 and 400 seconds | Maximum time that collector will wait before sending queries data to Devo. |
> | `minimum_percent` | `int` | `Mandatory` | Minimum length: 1<br>Example value: 40 or 50, meaning 40% or 50% | Minimum percentage of completion that the query needs in order to activate the sending data to Devo. |
> | `device_filter` | `object` | `Optional` | contains criteria to filter devices by, for example: a list of OS types like “LINUX”, “WINDOWS” | Provides the option to run the query on certain devices which match with the criteria defined in it. |
> 
> > Macro (rw-tab)
> 
> This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.
> 
> ### > Macro (anchor)
> 
> Structure
> 
> <span style="color: #172b4d">The following directory structure should be created for being used when running the collector:</span>
> 
> ```
> <any_directory>
> └── devo-collectors/
>     └── <product_name>/
>         ├── certs/
>         │   ├── chain.crt
>         │   ├── <your_domain>.key
>         │   └── <your_domain>.crt
>         ├── state/
>         └── config/ 
>             └── config.yaml
> ```
> 
> ### > Macro (anchor)
> 
> Devo credentials
> 
> In Devo, go to **Administration → Credentials → X.509 Certificates**, download the **Certificate**, **Private key** and **Chain CA** and save them in `devo-collector-vmware-/certs/`. Learn more about security credentials in Devo [here](https://devodocs.atlassian.net/wiki/spaces/latest/pages/94763701).
> 
> ![image](media://935aa67a-eb60-49c8-81fb-726b86236a5e)
> 
> ### > Macro (anchor)
> 
> Editing the config.yaml file
> 
> ```
> globals:
>   debug: true
>   id: <collector_id>
>   name: <collector_name>
>   persistence:
>     type: filesystem
>     config:
>       directory_name: state
>   multiprocessing: <multiprocessing_mode>
> 
> outputs:
>   devo_1:
>     type: devo_platform
>     config:
>       address: <devo_address>
>       port: 443
>       type: SSL
>       chain: <chain_filename>
>       cert: <cert_filename>
>       key: <key_filename>
> inputs:
>   carbonblackcloud:
>     id: <input_id>
>     enabled: <input_status>
>     requests_per_second: <request_per_seconds>
>     override_base_url:  <override_base_url>
>     credentials:
>       generic_token: <generic_token>
>       audit_token: <audit_token>
>       org_key: <org_key>
>     services:
>       event_alerts:
>         request_period_in_seconds: <request_period_in_seconds>
>         initial_start_time_in_utc: <start>
>       event_audit_logs:
>         request_period_in_seconds: <request_period_in_seconds>
>       event_live_query:
>         initial_start_time_in_utc: <start>
>         request_period_in_seconds: <request_period_in_second>
>         query_name: <query>                    
>         query: <query_in_sql>                          
>         query_id: <query_id>                          
>         soft_timeout_seconds: <soft_timeout_second>   
>         hard_timeout_seconds: <hard_timeout_seconds>  
>         minimum_percent: <minimum_percent>
>         device_filter: <device_filter>            
> ```
> 
> Replace the placeholders with your required values:
> 
> |  |  |  |  |  |
> | --- | --- | --- | --- | --- |
> | **Parameter** | **Data type** | **Type** | **Value range** | **Details** |
> | `collector_id` | `int` | `Mandatory` | Minimum length: 1  
> Maximum length: 5 | Use this param to give an unique id to this collector. |
> | `collector_name` | `str` | `Mandatory` | Minimum length: 1  
> Maximum length: 10 | Use this param to give a valid name to this collector. |
> | `multiprocessing_mode` | `bool` | `Mandatory` | false / true | If the value is true, the collector will run using a multiprocessing architecture. If the value is false, the collector will use only one CPU. |
> | `devo_address` | `str` | `Mandatory` | `collector-us.devo.io`  
> `collector-eu.devo.io` | Use this param to identify the Devo Cloud where the events will be sent. |
> | `chain_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the chain.cert  file downloaded from your Devo domain. Usually this file's name is: `chain.crt` |
> | `cert_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the `file.cert` downloaded from your Devo domain. |
> | `key_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the `file.key` downloaded from your Devo domain. |
> | `input_id` | `int` | `Mandatory` | Minimum length: 1  
> Maximum length: 5 | Use this param to give an unique id to this input service. |
> | `input_status` | `bool` | `Mandatory` | false / true | If the value is true, the input definition will be executed. If the value is false, the service will be ignored. |
> | `requests_per_second` | `int` | `Optional` | Minimum value: 1 | Customize the maximum number of API requests per second. If not used, the default setting will be used: `100000` requests/sec.<br>> ℹ️ This parameter can be left blank, removed or commented. |
> | `override_base_url` | `str` | `Optional` | Valid URL<br>Regex: `("((http|https)://)(www.)?" + "[a-zA-Z0-9@:%._\\+~#?&//=]" + "{2,256}\\.[a-z]" +     "{2,6}\\b([-a-zA-Z0-9@:%" + "._\\+~#?&//=]*)")` | Set a custom value to override the default URL `https://defense.conferdeploy.net`.<br>> ℹ️ This parameter can be left blank, removed or commented. |
> | `generic_token` | `str` | `Mandatory` | Minimum length: 1 | Required when running `event_alerts` and `event_live_query_service` service. |
> | `audit_token` | `str` | `Mandatory` | Minimum length: 1 | Required when running `event_audit_logs` service. |
> | `org_key` | `str` | `Mandatory` | Minimum length: 1 | This is your Carbon Black Cloud **Org Key**. |
> | `request_period_in_seconds` | `int` | `Optional` | Minimum length: 1 | Period in seconds used between each data pulling, this value will overwrite the default value (300 seconds)<br>> ℹ️ This parameter can be left blank, removed or commented. |
> | `start` | `str` | `Mandatory` | Format expected: `YYYY-MM-DD HH:MM:SS` | Parameter used by the collector as the starting `UTC` point when it first pulls data. (Required for event_live_query and event_alerts services)<br>> ⚠️ Updating this value will produce the lost of all persisted data and current pipelines. |
> | `query_name` | `str` | `Mandatory` | Minimum length: 1<br>Example: Test_query | Name to identify the query in the Carbon Black Cloud platform. |
> | `query_in_sql` | `str` | `Mandatory` | Valid SQL query<br>Example: `SELECT * FROM carbon_black_info;` | Query that will be executed must be written in SQL format. |
> | `query_id` | `str` | `Optional` | ID as provided by Osquery | If the user already has a started query from which it wants to extract data from they can write the ID of said query here.<br>> ℹ️ This parameter can be left blank, removed or commented. |
> | `soft_timeout_seconds` | `int` | `Mandatory` | Minimum length: 1<br>Practical value: between 60 and 300 seconds | Time that the program will wait before reaching minimum percent of completion. |
> | `hard_timeout_seconds` | `int` | `Mandatory` | Minimum length: 1<br>Practical value: between 120 and 400 seconds | Maximum time that collector will wait before sending queries data to Devo. |
> | `minimum_percent` | `int` | `Mandatory` | Minimum length: 1<br>Example value: 40 or 50, meaning 40% or 50% | Minimum percentage of completion that the query needs in order to activate the sending data to Devo. |
> | `device_filter` | `object` | `Optional` | contains criteria to filter devices by, for example: a list of OS types like “LINUX”, “WINDOWS” | Provides the option to run the query on certain devices which match with the criteria defined in it. |
> 
> ### Download the Docker image
> 
> The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:
> 
> | **Collector Docker image** | **SHA-256 hash** |
> | --- | --- |
> | [collector-vmware-carbonblackcloud-docker-image-1.5.0.tgz](https://drive.google.com/file/d/1QRF8SyCZKohCO7vx8rUz1y2y4ClNHDOJ/view?usp=drive_link) | `8f78421821f911aaf7e7ccb987b59f495a3f199f977dba9b71c9ee07260b62e4` |
> 
> <span style="color: #282828">Use the following command to add the Docker image to the system:</span>
> 
> ```
> gunzip -c collector-vmware-carbonblackcloud-docker-image-<version>.tgz | docker load
> ```
> 
> > ℹ️ <span style="color: #5c5c5c">Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace "</span>`<version>`<span style="color: #5c5c5c">" with a proper value</span><span style="color: #333333">.</span>
> 
> The Docker image can be deployed on the following services:
> 
> #### > Macro (anchor)
> 
> Docker
> 
> Execute the following command on the root directory `<any_directory>/devo-collectors/<product_name>/`
> 
> ```
> docker run 
> --name collector-<product_name> 
> --volume $PWD/certs:/devo-collector/certs 
> --volume $PWD/config:/devo-collector/config 
> --volume $PWD/state:/devo-collector/state 
> --env CONFIG_FILE=config.yaml 
> --rm 
> --interactive 
> --tty 
> <image_name>:<version>
> ```
> 
> > ⚠️ Replace `product_name>`, `<image_name>` and `<version>` with the required values.
> 
> #### > Macro (anchor)
> 
> Docker Compose
> 
> The following Docker Compose file can be used to execute the Docker container. It must be created in the `<any_directory>/devo-collectors/<product_name>/` directory.
> 
> ```
> version: '3'
> services:
>   collector-<product_name>:
>     image: <image_name>:${IMAGE_VERSION:-latest}
>     container_name: collector-<product_name>
>     volumes:
>       - ./certs:/devo-collector/certs
>       - ./config:/devo-collector/config
>       - ./credentials:/devo-collector/credentials
>       - ./state:/devo-collector/state
>     environment:
>       - CONFIG_FILE=${CONFIG_FILE:-config.yaml}
> ```
> 
> <span style="color: #091e42">To run the container using docker-compose, execute the following command from the </span>`<any_directory>/devo-collectors/<product_name>/`<span style="color: #091e42"> directory:</span>
> 
> ```
> IMAGE_VERSION=<version> docker-compose up -d
> ```
> 
> > ⚠️ Replace `product_name>`, `<image_name>` and `<version>` with the required values.

## API limitations

Rate limiting is currently not enforced. However, excessive usage is monitored. Excessive usage can result in temporary enforcement of rate-limiting.

## Change log

| **Release** | **Released on** | **Release type** | **Recommendations** |
| --- | --- | --- | --- |
| `v1.5.0` | 11/28/2024 | [improvements]  
[bug fixing] | `Recommended version` |
|  |
| `v1.4.2` | 8/15/2024 | [improvements]  
[bug fixing] | `Upgrade` |
|  |
| `v1.4.1` | 7/5/2023 | [improvements] | `Upgrade` |
|  |
| `v1.3.0` | 4/5/2023 | [improvements] | `Upgrade` |
|  |
| `v1.2.0` | 8/5/2022 | [INITIAL RELEASE] | `Initial version` |
|  |