---
title: Vmware Carbon Black App Control
slug: connectors/vmware-carbon-black-app-control
docTags: 
createdAt: 2026-06-09T16:30:05.654Z
---

The VMware Carbon Black App Control connector allows for seamless integration with Swimlane Turbine, providing automated security orchestration and response capabilities.

VMWare Carbon Black App Control is a leading endpoint security platform that provides comprehensive protection against advanced threats. This connector enables Swimlane Turbine users to automate critical security tasks such as file approvals, rule changes, and threat investigations. By integrating with VMWare Carbon Black App Control, users can streamline their security operations, enforce compliance, and respond to threats with speed and precision.

### Limitations

None to date.

### Supported Versions

This VMware Carbon Black App Control connector uses the Version 1 API.

### Additional Docs

- [VMware Carbon Black App Control Authentication Link](https://developer.carbonblack.com/reference/enterprise-protection/authentication)
- [VMware Carbon Black App Control API Documentation Link](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api)

## Prerequisites

To effectively utilize the VMware Carbon Black App Control connector with Swimlane Turbine, ensure you have the following prerequisites:

- API Key Authentication with the following parameters:
  - URL: The endpoint URL for the VMWare Carbon Black App Control API.
  - API key: Your personal API key provided by VMWare Carbon Black App Control for secure access.

## Authentication Methods

### API Key Authentication:

- URL: Endpoint URL for the VMware Carbon Black App Control API.
- API key: Unique identifier to authenticate with the VMware Carbon Black App Control API. That API key confers all rights and capabilities assigned to that user to anyone possessing the API key.

**Setup Instructions**

1. To find a API key corresponding with a particular Carbon Black App Control user account, log into the console as an administrator, then select Administration -> Login Accounts.
2. Find the user in the list then click the “Edit” button on the left hand side of the row containing their username.
3. This will show the details for the selected user. At the bottom of the details page, click the checkbox next to “Show API Token” in the API section.
4. This will reveal the API token associated with the given user. If no API token is revealed, click the “Generate” button.
5. If a new API token was created, it must be saved with the “Save” button before it becomes active.
6. Add this API key to the asset.

## Capabilities

This VMware Carbon Black App Control Connector provides the following capabilities:

- Approve File
- Change File Rule by Hash
- Change Publisher State
- Change Rule or Ban/Accept File Hash
- Close Approval Request
- File Upload
- Local File Approval
- Lookup File Instance
- Query to Get User or Device Details
- Searching or Query Tickets

### Approve File

- Approves a file in VMware Carbon Black App Control using the file instance ID and local state provided. Change local file instance state.
- Required permissions: ‘View files’, ‘Change local state’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#fileinstance).

### Change File Rule by Hash

- Create or edit a file rule, or change the file state in VMware Carbon Black App Control using a specific hash and policy IDs.
- Required permissions: ‘View files’, ‘Manage files’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#filerule).

### Change Publisher State

- Alters the state of a publisher in VMware Carbon Black App Control using the specified 'ID' and 'Publisher State'.
- Required permissions: ‘View software rules pages’, ‘Manage publisher rules’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#publisher).

### Change Rule or Ban/Accept File Hash

- Updates an existing file rule in VMware Carbon Black App Control using the file's hash, desired state, and policy IDs.
- Required permissions: ‘View files’, ‘Manage files’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#filerule).

### Close Approval Request

- Closes an approval request in VMware Carbon Black App Control using a specified ID and status update.
- Required permissions: ‘View approval requests’, ‘Manage approval requests’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#approvalrequest).

### File Upload

- Upload a file to a specified computer within VMware Carbon Black App Control using the computer ID.
- Required permissions: ‘View file uploads’, ‘Manage uploads of inventoried files’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#fileupload).

### Local File Approval

- Approve or change the state of a local file instance in VMware Carbon Black App Control using file ID, acknowledgment status, and target computer ID.
- Required permissions: ‘View files and applications’, ‘Manage files’.

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#filecatalog).

### Lookup File Instance

- Retrieves objects matching specified criteria from VMware Carbon Black App Control.
- Required permissions: ‘View files’.
- Searching functionality can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#searching).

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#fileinstance).

### Query to Get User or Device Details

- Retrieve detailed information on users or devices from VMware Carbon Black App Control.
- Required permissions: ‘View login accounts and user roles’.
- Searching functionality can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#searching).

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#user).

### Searching or Query Tickets

- Executes a search in VMware Carbon Black App Control to return objects matching specified criteria.
- Required permissions: ‘View events’.
- Searching functionality can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#searching).

VMware Carbon Black App Control's documentation for this action can be found [here](https://developer.carbonblack.com/reference/enterprise-protection/8.0/rest-api/#event).

# Configurations

## Carbon Black App Control API Key Authentication

Authenticates using an API Key.

### Configuration Parameters

| **Parameter** | **Description**                    | **Type** | **Required** |
| ------------- | ---------------------------------- | -------- | ------------ |
| url           | A URL to the target host.          | string   | Required     |
| X-Auth-Token  | API key.                           | string   | Required     |
| verify\_ssl   | Verify SSL certificate.            | boolean  | Optional     |
| http\_proxy   | A proxy to route requests through. | string   | Optional     |

# Actions

## Approve File

Approves a file in VMWare Carbon Black App Control with specified ID and local state, updating its status.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileInstance`
- **Method:** `POST`

### Input

| **Argument Name** | **Type** | **Required** | **Description**                                                                                                                                                                                              |
| ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | number   | Optional     | Unique ID of this file instance.                                                                                                                                                                             |
| `localState`      | number   | Optional     | Target local state for the file on the agent. Can be one of 1=Unapproved 2=Approved. Note that changed local state might not be reflected in the object immediately, but only after agent reports new state. |

### Input Example

`{"json_body":{"id":1,"localState":2}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Fri, 14 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Change File Rule by Hash

Create or update a file rule and its state in VMware Carbon Black App Control using the specified hash and policy IDs.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileRule`
- **Method:** `POST`

### Input

| **Argument Name** | **Type** | **Required** | **Description**                                                                            |
| ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------ |
| `hash`            | string   | Optional     | Hash of file to update File State.                                                         |
| `fileState`       | number   | Optional     | File state for hash, defaults to 3 which is banning the hash. 1 = Un-approve, 2 = Approve. |
| `policyIds`       | string   | Optional     | Comma Separated list of Policy IDs to add banned hash to. 0 for global rule.               |

### Input Example

`{"json_body":{"hash":"64a4f54d6863d59f1121a91554b55e9a","fileState":3,"policyIds":"10,11"}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Fri, 14 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Change Publisher State

Alters the state of a publisher in VMWare Carbon Black App Control using the specified 'ID' and 'Publisher State'.

### Endpoint

- **URL:** `/api/bit9platform/v1/publisher/{{id}}`
- **Method:** `PUT`

### Input

| **Argument Name**    | **Type** | **Required** | **Description**                                                                                                       |
| -------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `path_parameters.id` | number   | Required     | ID of publisher to change.                                                                                            |
| `publisherState`     | number   | Optional     | State for this publisher. Can be one of 1=Unapproved, 2=Approved, 3=Banned, 4=Approved By Policy, 5=Banned By Policy. |

### Input Example

`{"json_body":{"publisherState":2},"path_parameters":{"id":1}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Change Rule or Ban/Accept File Hash

Updates or sets a file rule status to ban/accept based on the hash in VMware Carbon Black App Control, using the file's ID and policy IDs.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileRule/{{id}}`
- **Method:** `PUT`

### Input

| **Argument Name**    | **Type** | **Required** | **Description**                                                                                                                           |
| -------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `path_parameters.id` | number   | Required     | ID of file rule to create or update.                                                                                                      |
| `fileState`          | number   | Optional     | File state for hash, defaults to 3 which is banning the hash. File state for this rule. Can be one of 1=Unapproved, 2=Approved, 3=Banned. |
| `hash`               | string   | Optional     | Hash of file to update File State.                                                                                                        |
| `policyIds`          | string   | Optional     | Comma Separated list of Policy IDs to add banned hash to. 0 for global rule.                                                              |

### Input Example

`{"json_body":{"fileState":"Banned","hash":"64a4f54d6863d59f1121a91554b55e9a","policyIds":"10,11"},"path_parameters":{"id":1}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 19 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Close Approval Request

Closes an existing approval request in VMWare Carbon Black App Control by setting the status for a given ID.

### Endpoint

- **URL:** `/api/bit9platform/v1/approvalRequest`
- **Method:** `POST`

### Input

| **Argument Name**    | **Type** | **Required** | **Description**                                                                                                                |
| -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`                 | number   | Optional     | Unique approval request ID.                                                                                                    |
| `resolutionComments` | string   | Optional     | Comments by request resolver.                                                                                                  |
| `status`             | number   | Optional     | Request status. Can be one of 1=New, 2=Open, 3=Closed, 4=Escalated. Prohibited transitions are from any status back to 0 or 1. |

### Input Example

`{"json_body":{"id":1,"resolutionComments":"","status":3}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Tue, 18 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## File Upload

Uploads a file to a specified computer in VMware Carbon Black App Control using the provided computer ID.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileUpload`
- **Method:** `POST`

### Input

| **Argument Name** | **Type** | **Required** | **Description**                                                                                                                                                                                                                         |
| ----------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `computerId`      | number   | Optional     | ID of computer from which to upload the file. If 0, system will find best computer to get the file from.                                                                                                                                |
| `fileCatalogId`   | number   | Optional     | ID of fileCatalog entry for file to upload.                                                                                                                                                                                             |
| `priority`        | number   | Optional     | Upload priority in range \[-2, 2], where 2 is highest priority. Default priority is 0.                                                                                                                                                  |
| `uploadStatus`    | number   | Optional     | Status of upload. Status of upload in progress can be changed to 5 (Cancelled). Any upload can be changed to 6 (Deleted). Can be one of 0 = Queued, 1 = Initiated, 2 = Uploading, 3 = Completed, 4 = Error, 5 = Cancelled, 6 = Deleted. |

### Input Example

`{"json_body":{"computerId":2,"fileCatalogId":3,"priority":2,"uploadStatus":5}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 19 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Local File Approval

Approve or modify the state of a local file on VMWare Carbon Black App Control using file ID, acknowledgment status, and target computer ID.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileCatalog/{{id}}`
- **Method:** `PUT`

### Input

| **Argument Name**                          | **Type** | **Required** | **Description**                                                    |
| ------------------------------------------ | -------- | ------------ | ------------------------------------------------------------------ |
| `path_parameters.id`                       | number   | Required     | ID of file catalog object.                                         |
| `parameters.acknowledge`                   | boolean  | Required     | New acknowledge flag. Default value is false.                      |
| `parameters.changeLocalStateForComputerId` | number   | Required     | Change local approval state for this computer ID.                  |
| `parameters.newApprovalState`              | number   | Required     | The new approval state to change to. 1 = Unapproved, 2 = Approved. |

### Input Example

`{"parameters":{"acknowledge":false,"changeLocalStateForComputerId":1,"newApprovalState":2},"path_parameters":{"id":1}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Fri, 14 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Lookup File Instance

Retrieves matching objects from VMWare Carbon Black App Control based on specified criteria.

### Endpoint

- **URL:** `/api/bit9platform/v1/fileInstance`
- **Method:** `GET`

### Input

| **Argument Name**   | **Type** | **Required** | **Description**                                                                                                                 |                                                                                                                            |
| ------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `parameters.q`      | array    | Optional     | Query condition (Optional - multiple query conditions are supported). For more details See Readme.                              |                                                                                                                            |
| `parameters.group`  | string   | Optional     | Field name to group by.                                                                                                         |                                                                                                                            |
| `parameters.sort`   | string   | Optional     | Field name to sort by. Sorting is optional and can be defined with a single attribute \&sort=xyz \[ASC                          | DESC]. There can be only one sorting field. Default sort order (if omitted) is ASC. xyz is field name from the result set. |
| `parameters.offset` | number   | Optional     | Offset in query results.                                                                                                        |                                                                                                                            |
| `parameters.limit`  | number   | Optional     | Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. |                                                                                                                            |

### Input Example

`{"parameters":{"q":["fileCatalogId:1","computerId:1"],"group":"","sort":"","offset":0,"limit":0}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Query to Get User or Device Details

Retrieve detailed information on users or devices from VMware Carbon Black App Control.

### Endpoint

- **URL:** `/api/bit9platform/v1/user`
- **Method:** `GET`

### Input

| **Argument Name**      | **Type** | **Required** | **Description**                                                                                                                 |                                                                                                                            |
| ---------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `parameters.q`         | array    | Optional     | Query condition (Optional - multiple query conditions are supported). For more details See Readme.                              |                                                                                                                            |
| `parameters.group`     | string   | Optional     | Field name to group by.                                                                                                         |                                                                                                                            |
| `parameters.groupType` | string   | Optional     | Field name to sort by. Sorting is optional and can be defined with a single attribute \&sort=xyz \[ASC                          | DESC]. There can be only one sorting field. Default sort order (if omitted) is ASC. xyz is field name from the result set. |
| `parameters.groupStep` | number   | Optional     | Step for windowed grouping (Optional, for time-based fields only).                                                              |                                                                                                                            |
| `parameters.sort`      | string   | Optional     | Field name to sort by.                                                                                                          |                                                                                                                            |
| `parameters.offset`    | number   | Optional     | Offset in query results.                                                                                                        |                                                                                                                            |
| `parameters.limit`     | number   | Optional     | Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. |                                                                                                                            |
| `parameters.expand`    | array    | Optional     | Foreign key fields to expand.                                                                                                   |                                                                                                                            |

### Input Example

`{"parameters":{"q":["fileCatalogId:1","computerId:1"],"group":"","groupType":"","groupStep":2,"sort":"","offset":0,"limit":0,"expand":["eMailAddress"]}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 19 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Searching or Query Tickets

Executes a search in VMware Carbon Black App Control to return objects matching specified criteria.

### Endpoint

- **URL:** `/api/bit9platform/v1/event`
- **Method:** `GET`

### Input

| **Argument Name**   | **Type** | **Required** | **Description**                                                                                                                 |                                                                                                                            |
| ------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `parameters.q`      | array    | Optional     | Query condition (Optional - multiple query conditions are supported). For more details See Readme.                              |                                                                                                                            |
| `parameters.group`  | string   | Optional     | Field name to group by.                                                                                                         |                                                                                                                            |
| `parameters.sort`   | string   | Optional     | Field name to sort by. Sorting is optional and can be defined with a single attribute \&sort=xyz \[ASC                          | DESC]. There can be only one sorting field. Default sort order (if omitted) is ASC. xyz is field name from the result set. |
| `parameters.offset` | number   | Optional     | Offset in query results.                                                                                                        |                                                                                                                            |
| `parameters.limit`  | number   | Optional     | Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. |                                                                                                                            |

### Input Example

`{"parameters":{"q":["fileCatalogId:1","computerId:1"],"group":"","sort":"","offset":0,"limit":0}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Feb 2025 20:37:23 GMT"},"reason":"OK","json_body":{}}`

# Response Headers

| **Header**     | **Description**                                       | **Example**                   |
| -------------- | ----------------------------------------------------- | ----------------------------- |
| content-length | The length of the response body in bytes              | 140                           |
| content-type   | The media type of the resource                        | application/json              |
| Date           | The date and time at which the message was originated | Fri, 14 Feb 2025 20:37:23 GMT |