Data Forwarder API

Overview

The Carbon Black Cloud Forwarder lets you send data about Alerts, Events and Watchlist Hits to an AWS S3 bucket or Azure Blob Storage Container where it can be consumed by other applications in your security stack, such as Splunk. The Data Forwarder is recommended over APIs for obtaining large amounts of data from Carbon Black Cloud in near real time.

A Forwarder can also be configured in the Carbon Black Cloud console under Settings > Data Forwarders. This is the recommended option unless you have a use case that needs Forwarders created regularly. See the User Guide for details.

New - February 2024: Auth Event Forwarder and Semantic Versioning Schema Validation

As an Enterprise EDR customer, you now have the option to add a new type of Forwarder to send all Authentication Events to a Forwarder destination (AWS S3, Azure Blob Storage Container) as they are reported by your Windows sensors.
Improved validation when using Endpoint Event filtering capability which ensures that all filters assigned to a single Endpoint Event forwarder instance only include those fields that are available in the schema version.
Read about it in the blog

NEW - January 2024: Azure Blob Storage Container as a Destination, also called Provider.

Azure BLOB storage option is available for customers to exfiltrate key CBC data to external integrations, applications and long-term storage.
New Destination Option when creating a Data Forwarder for Alerts or Watchlist Hits.
- Subscribe to our newsletter for updates on Auth Events and Endpoint Events.
Azure-specific configuration to capture Tenant ID, Client ID, Storage account, Container name.

NEW - December 2023: version_constraint has been added as an optional parameter to the Data Forwarder Endpoint Event Config and the Data Forwarder Alert Config.

The endpoint event type will default to 1.0.0 with a new available version 1.1.0 to support Extended Detection and Response (XDR) Fields.
The alert data type will default to 1.0.0 with a new available version 2.0.0 to support the latest Alert API v7 schema.
All other forwarder types do not currently support version_constraint and will ignore any value provided.

For more information on the future of Data versioning see Semantic Versioning Support in Carbon Black Cloud Data Forwarder

Available Forwarder Types

Data Forwarder Type	AWS S3 Bucket	Azure Blob Storage
alert	Yes	Yes
auth.event	Yes	Yes
endpoint.event	Yes	No
watchlist.hit	Yes	Yes

Requirements

Carbon Black Cloud Endpoint Standard or Enterprise EDR
API Key with appropriate permissions
Amazon Simple Storage Service (AWS S3) or Azure Blob Storage
- It is possible to work around the requirement for AWS S3 bucket to be in the same region as your Carbon Black Cloud organization using S3 Cross-Region Replication (CRR).

Guides and Resources

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.

CBC Managed Identity

Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

Schema information: {cbc-hostname}/data_forwarder/v2/schemas/
Configuration: {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/
Filter validation: {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/validate_filter/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:

Data Forwarder > Settings > event-forwarder.settings, allow permission to CREATE, READ, UPDATE, DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.

CSP Managed Identity

Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

Schema information: {cbc-hostname}/data_forwarder/v2/schemas/
Configuration: {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/
Filter validation: {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/validate_filter/

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:

_API.Data.Forwarder:event-Forwarder.Settings, allow permission to CREATE, READ, UPDATE, DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

Setup for new Data Forwarder

Information on setting up the AWS S3 Bucket and Azure Blob Storage is available on the Integrations > Data Forwarder page.. This includes information on AWS S3 policy configuration and equivalent security settings for the Azure Blob Storage.

Data Format

S3 Data Storage and Azure Blob Storage Format

The Carbon Black Cloud Data Forwarder supports output to both AWS S3 buckets and Azure Blob Storage Containers provided by customers. The Data Forwarder outputs gzip compressed single-event-per-line JSON format (sometimes known as “JSONL”) to the customer’s storage with the following folder structure:

org_key={org_key}/year={year}/month={month}/day={day}/hour={hour}/minute={minute}/second={second}/{uuid}.jsonl.gz

Therefore, if a batch of events occurred on August 27, 2019 at 12:36:53UTC for the organization with org_key ABCD1234, it can be located in:

org_key=ABCD1234/year=2019/month=8/day=27/hour=12/minute=36/second=53/ac203140-f0e2-48fe-90cf-05eb7289f628.jsonl.gz

Data Mapping

You can find the Event, Alert and Watchlist Hit schema as well as sample data in the Data Forwarder Schema section.

Data Filtering

EDR provides tremendous visibility into everything happening across your endpoints. This data may be prohibitively expensive in licensing or scale for some downstream SIEM, SOAR, or data lake solutions. To reduce the load, one or more filters can be applied to the events emitted by a data forwarder configuration.

For additional guidance see Syntax Tips for Custom Query Filters in the User Guide.

Data Filtering is only available for forwarders of type “endpoint.event”.

Filter Schema

Field	Definition	Data Type	Values
`action` REQUIRED	Whether the filter should include or exclude data from being forwarded	String	`INCLUDE`, `EXCLUDE`
`name` REQUIRED	Defined name for the filter	String	N/A
`query` REQUIRED	The query to match against the data	String	N/A
`enabled`	Boolean flag indicating whether the Data Forwarder will apply the filter to incoming data	Boolean	Default: `true`

Query Fields

The fields documented as FILTERABLE under endpoint.events can be used in filtering queries for both inclusion and exclusion. There are a few fields which are not supported because their values are not feasible to use as a filter for a stream of events.

All string-matching queries are case-insensitive – both your submitted values and the endpoint data will be lowercased before matching.

Event Atomicity

A query cannot include fields from different endpoint.events types as the Data Forwarder matches against individual events not the state of a process. e.g. scriptload_name:c\\:\\\\windows\\\\system32\\\\* AND netconn_domain:*.ru or childproc_reputation:REP_WHITE AND netconn_inbound:false would fail to match any events as no single event can include scriptload, netconn, and childproc fields

You can combine any number of the fields where Event Type is COMMON as long as the query does not exceed the complexity (“depth”) limit.

Wildcards

Wildcards are used in search terms to represent one or more other characters and are supported on all fields. A wildcard can be used as a leading or trailing match.

? wildcard will match a single character
* wildcard will match 0 or more characters

Tokenization

Fields that support tokenization will allow partial matches on each segment where a string is split at the space character. e.g. winword.exe c:\users\mike\file.txt has two tokens winword.exe and c:\users\mike\file.txt.

Do not use a trailing whitespace, “\\” or “\\ \\ ” at the end of a field query or filter. Instead, use one of the following:

A trailing wildcard
Tokenization to create a query
Filter by field name as described below

e.g. for copy c:\windows\system32\cacls.exe c:\users\mike, copy and c\\:\\\\users\\\\mike will match, as will c\\:\\\\windows\\\\system32\\\\* but not c\\:\\\\windows\\\\system32

Further information is also available in the Carbon Black Cloud User Guide.

See the Data Forwarder Data Guide for which fields support tokenization.

Examples

Note: JSON requires backslashes to be escaped, which is why you must submit query filters like the following 'process_path:*\\\\brave.exe'. The Carbon Black Cloud UI console will perform the escaping for the user when making the API call. If you copy an example and paste into the UI console ensure you remove half the slashes i.e. 'process_path:*\\brave.exe'.

Replicate a filter from v1 API

event_origin:NGAV AND sensor_action:DENY AND type:endpoint.event.procstart AND alert_id:*

Use complex boolean logic

event_origin:NGAV AND (process_path:*\\\\brave.exe OR process_path:*\\\\firefox.exe OR (process_reputation:REP_KNOWN_MALWARE AND NOT sensor_action:ACTION_ALLOW))

Use wildcards

local_port:80* OR process_path:c\\:\\\\windows\\\\system32*

Use tokenization

process_cmdline:powershell.exe OR process_cmdline:*.ps1

API Calls

Config

Use the following API calls for any type of forwarder (alert, endpoint.event, or watchlist.hit).

Create Forwarder

Use this call to create a new forwarder. The API will then make calls to check whether the Forwarder can write to the specified storage using the configuration supplied. It will attempt to write a test message called healthcheck.json to the specified bucket or container under a sub-folder called healthcheck. If the bucket is misconfigured (e.g. incorrect permissions, principle arn, etc.) or the configuration is incorrect (e.g. bucket prefix doesn’t match path specified in policy), the API will respond with a 400 error and message with information about what was incorrect and how to fix the issue. See Troubleshooting Errors for more info.

If you want to forward alert type data, endpoint.event type data and watchlist hit type data, you must create a separate forwarder for each.

The forwarder should be configured to send the data to its own subfolder in the S3 bucket using the S3 prefix property, and the subfolder you configure will be automatically added to the S3 bucket. A separate container should be used in Azure Blob Storage.

The following table shows which data types can be forwarded to each storage option.

Data Forwarder Type	AWS S3 Bucket	Azure Blob Storage
Alert	Yes	Yes
Auth Event	Yes	Yes
Endpoint Event	Yes	No
Watchlist Hit	Yes	Yes

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs

Request Body

{
  "azure_client_id": "<string>",
  "azure_container_name": "<string>",
  "azure_storage_account": "<string>",
  "azure_tenant_id": "<string>",
  "destination": "<string>",
  "enabled": <boolean>,
  "name": "<string>",
  "s3_bucket_name": "<string>",
  "s3_prefix": "<string>",
  "type": "<string>",
  "version_constraint": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`azure_client_id`	The azure client id for this configuration, required when Destination is `azure_blob_storage`	String	N/A
`azure_container_name`	The azure container name for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`azure_storage_account`	The azure storage account for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`azure_tenant_id`	The azure tenant id for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`destination`	The destination for this configuration. Default is `aws_s3`	String	`aws_s3`, `azure_blob_storage`
`enabled`	Boolean flag indicating whether to create the data forwarder as enabled	Boolean	Default: `true`
`name` REQUIRED	Defined name for the specific event or alert forwarder	String	N/A
`s3_bucket_name`	Configured unique name for s3 bucket. Required when Destination is not provided or is `aws_s3`.	String	N/A
`s3_prefix`	Defined folder structure the forwarder will write events or alerts to. Required when Destination is not provided or is `aws_s3`.	String	N/A
`type` REQUIRED	The datastream type that is to be forwarded.	Sting	`alert`, `endpoint.event`, `watchlist.hit`
`version_constraint`	The version of the data to forward Note: Only supported for types `endpoint.event` with values `1.0.0` and `1.1.0` and `alert` with values `1.0.0` and `2.0.0` otherwise ignored.	String	Default (`endpoint.event` and `alert` only): `1.0.0`

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful creation of forwarder	application/json	View example response below
400	Bad request. The JSON body was malformed, or the configuration is invalid (misconfigured bucket or configuration value)	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
409	Conflict. A duplicate config was found.	application/json	See above
500	Internal server error	application/json	See above

Examples

AWS S3 Destination

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs

Request Headers

X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"

Request Body

{
  "enabled": true,
  "name": "Alert Forwarder v1.0.0 - the original and deprecated",
  "s3_bucket_name": "demo-bucket",
  "s3_prefix": "demo-alert",
  "type": "alert",
  "version_constraint": "1.0.0",
  "destination": "aws_s3",
  "current_version": "1.0.0"
}

Response

{
  "id": "6d34c7d6-2272-11ee-a854-429d08efd8d3",
  "org_key": "ABCD1234",
  "name": "Alert Forwarder v1.0.0 - the original and deprecated",
  "enabled": true,
  "s3_bucket_name": "demo-bucket",
  "s3_prefix": "demo-alert",
  "type": "alert",
  "version_constraint": "1.0.0",
  "current_version": "1.0.0",
  "create_time": "2023-07-14T18:15:34Z",
  "update_time": "2023-07-14T18:17:34Z",
  "destination": "aws_s3"
}

To download or review the Carbon Black Cloud Postman collection, click here.

Azure Blob Storage Destination

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs

Request Headers

X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"

Request Body

{
  "org_key": "ABCD1234",
  "name": "Demo Create Azure Alert",
  "enabled": false,
  "type": "alert",
  "version_constraint": "2.0.0",
  "destination": "azure_blob_storage",
  "azure_storage_account": "azuredemo",
  "azure_container_name": "azure-event-demo",
  "azure_tenant_id": "a12345bc-1abcd-1a2b-a1b2-ab12c3de45f6",
  "azure_client_id": "X98766yz-z987-z9x8-z9x8-zx98y7vw65u4"
}

Response

{
  "id": "dba5f821-9db9-11ee-a7d0-268d0c3c098b",
  "org_key": "ABCD1234",
  "name": "Azure Alert Demo",
  "enabled": false,
  "type": "alert",
  "version_constraint": "2.0.0",
  "current_version": "2.0.0",
  "create_time": "2023-12-18T15:26:47Z",
  "update_time": "2023-12-18T15:26:47Z",
  "destination": "azure_blob_storage",
  "azure_storage_account": "azuredemo",
  "azure_container_name": "azure-event-demo",
  "azure_tenant_id": "a12345bc-1abcd-1a2b-a1b2-ab12c3de45f6",
  "azure_client_id": "X98766yz-z987-z9x8-z9x8-zx98y7vw65u4"
  }

To download or review the Carbon Black Cloud Postman collection, click here.

Invalid Request

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs

Request Headers

X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"

Response for invalid configuration

{
  "error_code": "REQUEST_PRESENT_FIELD_CONDITIONAL",
  "message": "azure_client_id cannot be specified when forwarding data to aws_s3",
  "args": [
    "azure_client_id",
    "aws_s3"
  ]
}

Corrective Actions:
1. If you receive an error indicating your configuration is invalid, such as `NoSuchBucket` or `AccessDenied`, see the [Troubleshooting Errors](#troubleshooting-errors) section below.
2. Other errors may occur and will have an error message to assist in troubleshooting. This example shows the response when the destination is `aws_s3` and configuration for Azure Blob Storage was provided.
To download or review the Carbon Black Cloud Postman collection, click here.

Forwarder Healthcheck

This call can be used to run a healthcheck on a Forwarder to determine if the forwarder is able to write to the specified S3 Bucket or Azure Container using the existing configuration. The healthcheck can indicate if the bucket is misconfigured (i.e. incorrect permissions, principle arn, etc.), if the configuration is incorrect (i.e. bucket prefix doesn’t match path specified in policy), or if the forwarder is working as expected.

If successful, the healthcheck will attempt to write a test message called healthcheck.json to your S3 bucket under a subfolder called healthcheck, or your Azure Container, and respond with a 200, regardless of whether the API was able to write to the bucket.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}/health_check

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Healthcheck completed successfully	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET
https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/health_check

Successful Response

Response for a successful healthcheck that was able to write to the S3 bucket using the specified configuration:

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "enabled": true,
  "update_time": "2019-10-22T16:59:41Z",
  "status": "Valid Bucket Configuration for Bucket: DevRelTestBucket with Prefix: test",
  "error": ""
}

Successful Response with Error Status

Example response for successful healthcheck that was unable to write to the S3 bucket using the specified configuration:

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "enabled": true,
  "update_time": "2019-10-22T16:59:41Z",
  "status": "Invalid Bucket Configuration for Bucket: IncorrectBucket with Prefix: test",
  "error": "AccessDenied"
}

If you received a NoSuchBucket error or AccessDenied error, see the Troubleshooting Errors section below for suggested fixes.

Get Available Data Versions

Get all available data versions

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/versions

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful request for all available data versions	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/versions

Response

{
  "available_versions": [
    {
      "type": "alert",
      "versions": [
        "1.0.0",
        "2.0.0"
      ]
    }
  ]
}

Get Configured Forwarders

Get all configured forwarders and their information

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful request for all configured forwarders	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs

Response

[
  {
    "id": "011b9d03-b12d-11ec-af42-ae26c44461dc",
    "org_key": "ABCD1234",
    "name": "Event Demo",
    "enabled": true,
    "s3_bucket_name": "event-forwarder-demo-bucket",
    "s3_prefix": "events",
    "type": "endpoint.event",
    "version_constraint": "1.*.*",
    "current_version": "1.1.0",
    "create_time": "2022-03-31T19:58:59Z",
    "update_time": "2023-11-16T16:57:27Z",
    "destination": "aws_s3"
  },
  {
    "id": "dba5f821-9db9-11ee-a7d0-268d0c3c098b",
    "org_key": "ABCD1234",
    "name": "Azure Endpoint.Event Demo",
    "enabled": false,
    "type": "endpoint.event",
    "version_constraint": "1.0.*",
    "current_version": "1.0.0",
    "create_time": "2023-12-18T15:26:47Z",
    "update_time": "2023-12-18T15:26:47Z",
    "destination": "azure_blob_storage",
    "azure_storage_account": "azuredemo",
    "azure_container_name": "azure-event-dmo",
    "azure_tenant_id": "a12345bc-1abcd-1a2b-a1b2-ab12c3de45f6",
    "azure_client_id": "X98766yz-z987-z9x8-z9x8-zx98y7vw65u4"
  },
  {
    "id": "31f827d3-152b-11ee-8d0d-3a23c69b3825",
    "org_key": "ABCD1234",
    "name": "alert-aws-demo",
    "enabled": true,
    "s3_bucket_name": "forwarder-demo",
    "s3_prefix": "alert",
    "type": "alert",
    "version_constraint": "1.0.0",
    "current_version": "1.0.0",
    "create_time": "2023-06-27T20:42:56Z",
    "update_time": "2023-06-28T16:12:45Z",
    "destination": "aws_s3"
  },
  {
    "id": "6a93a655-175e-11ee-8fb0-02f20f8bfd92",
    "org_key": "ABCD1234",
    "name": "Watchlist Hit Demo",
    "enabled": true,
    "s3_bucket_name": "demo-bucket",
    "s3_prefix": "watchlisthits",
    "type": "watchlist.hit",
    "create_time": "2023-06-30T15:54:37Z",
    "update_time": "2023-06-30T15:54:37Z",
    "destination": "aws_s3"
  }
]

Get Specific Forwarder

Get a specific forwarder’s configuration by id

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successfully returned forwarder	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2

Response

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "org_key": "ABCD1234",
  "name": "Azure Endpoint.Event Demo",
  "enabled": false,
  "type": "endpoint.event",
  "version_constraint": "1.0.*",
  "current_version": "1.0.0",
  "create_time": "2023-12-18T15:26:47Z",
  "update_time": "2023-12-18T15:26:47Z",
  "destination": "azure_blob_storage",
  "azure_storage_account": "azuredemo",
  "azure_container_name": "azure-event-dmo",
  "azure_tenant_id": "a12345bc-1abcd-1a2b-a1b2-ab12c3de45f6",
  "azure_client_id": "X98766yz-z987-z9x8-z9x8-zx98y7vw65u4"
}

Edit Forwarder

This call is used to edit an existing forwarder. The Type (e.g. Alert, Endpoint Event, Watchlist Hit) and Destination (also called Provider, aws_s3 or azure_blob_storage) cannot be changed; all other configuration values can be modified.

When editing an existing forwarder, the API will make additional calls to check whether the Carbon Black Cloud forwarder can write to the specified destination using the configuration supplied. It will attempt to write a test message called healthcheck.json to the specified bucket under a subfolder called healthcheck, or Azure Container. If the bucket is misconfigured (e.g. incorrect permissions, principle arn, etc.) or the configuration is incorrect (e.g. bucket prefix doesn’t match path specified in policy or bucket does not exist), the Data Forwarder Configuration API will respond with a 400 and message including information regarding what was incorrect, providing the customer with feedback that enables them to fix issues as needed.

If you want to remove filters that are applied to your configuration then use the Delete Filter endpoint

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

PUT {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}

Request Body

{
  "enabled": <boolean>,
  "name": "<string>",
  "type": "<string>",
  "version_constraint": "<string>",
  "destination": "<string>",
  "s3_bucket_name": "<string>",
  "s3_prefix": "<string>",
  "azure_storage_account": "<string>",
  "azure_container_name": "<string>",
  "azure_tenant_id": "<string>",
  "azure_client_id": "<string>",
  }
}

Body Schema

Note: The type and destination (provider) cannot be modified after a Forwarder has been created.

Field	Definition	Data Type	Values
`azure_client_id`	The azure client id for this configuration, required when Destination is `azure_blob_storage`	String	N/A
`azure_container_name`	The azure container name for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`azure_storage_account`	The azure storage account for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`azure_tenant_id`	The azure tenant id for this configuration. Required when Destination is `azure_blob_storage`	String	N/A
`destination`	The destination for this configuration. Default is `aws_s3`	String	`aws_s3`, `azure_blob_storage`
`enabled`	Boolean flag indicating whether to create the data forwarder as enabled	Boolean	Default: `true`
`name` REQUIRED	Defined name for the specific event or alert forwarder	String	N/A
`s3_bucket_name`	Configured unique name for s3 bucket. Required when Destination is not provided or is `aws_s3`.	String	N/A
`s3_prefix`	Defined folder structure the forwarder will write events or alerts to. Required when Destination is not provided or is `aws_s3`.	String	N/A
`type` REQUIRED	The datastream type that is to be forwarded.	Sting	`alert`, `endpoint.event`, `watchlist.hit`
`version_constraint`	The version of the data to forward Note: Only supported for types `endpoint.event` with values `1.0.0` and `1.1.0` and `alert` with values `1.0.0` and `2.0.0` otherwise ignored.	String	Default (`endpoint.event` and `alert` only): `1.0.0`

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful editing of forwarder	application/json	View example response below
400	Bad request. The JSON body was malformed, or some part of the JSON body included an invalid value	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
409	Conflict. A duplicate config was found.	application/json	See above
500	Internal server error	application/json	See above

Example

Request

PUT https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2

Request Body

{
  "name": "DevRelTest",
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "enabled": false
  "version_constraint": "1.0.0",
  "destination": "aws_s3",
  "current_version": "1.0.0"
}

Response for valid configuration

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "org_key": "ABCD1234",
  "name": "DevRelTest",
  "enabled": false,
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "create_time": "2019-10-22T16:23:55Z",
  "update_time": "2019-10-22T16:26:01Z"
  "version_constraint": "1.0.0",
  "current_version": "1.0.0",
  "destination": "aws_s3"
}

Response for invalid configuration

If you receive a response for invalid configuration, see the Troubleshooting Errors section below for suggested fixes.

Delete Forwarder

Use this call to delete a forwarder.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

DELETE {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
203	Successful deletion of forwarder	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

DELETE https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/58aa259f-f42c-11e9-bd5d-2eca45f7dc1c

Response

No Content

Filter

The Filter API calls can be used only for “endpoint.event” forwarder type.

Validate Filter

Validate whether the filter uses compatible query syntax, field names and values

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/validate_filter

Request Body

{
  "action": "<string>",
  "enabled": <boolean>,
  "name": "<string>",
  "query": "<string>",
  "version_constraint": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`action` REQUIRED	Whether the filter should include or exclude data from being forwarded	String	`INCLUDE`, `EXCLUDE`
`name` REQUIRED	Defined name for the filter	String	N/A
`query` REQUIRED	The query to match against incoming data	String	N/A
`enabled`	Boolean flag indicating whether the Data Forwarder will apply the filter to incoming data	Boolean	Default: `true`
`version_constraint`	The version of the schema against which to validate the filter. If not included in the request, the API will validate against the lowest supported schema version; as at February 2024 this is v1.0.0 for the Endpoint Event Schema	String	Default: lowest supported version. e.g. `v1.1.0`

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Filter is valid	application/json	View example response below
400	Bad request. The JSON body was malformed, or the filter is invalid	application/json	View example response below
404	Resource not found	application/json	View example response below
500	Internal server error	application/json	See above

Example

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/validate_filter

Request Body Valid Filter

{
  "action": "INCLUDE",
  "enabled": true,
  "name": "Example Filter",
  "query": "device_os:WINDOWS AND event_origin:NGAV",
  "version_constraint": "1.1.0"
}

Response

{
    "id": "",
    "name": "Example Filter",
    "query": "device_os:WINDOWS AND event_origin:NGAV",
    "action": "INCLUDE",
    "create_time": "",
    "update_time": "",
    "enabled": true
}

Request Body Invalid Filter

{
  "action": "INCLUDE",
  "name": "type netconn and has protocol",
  "query": "type:endpoint.event.netconn AND netconn_application_protocol:TLS OR netconn_application_protocol:HTT",
  "version_constraint": "1.0.0"
}

Response

{
  "error_code": "QUERY_INVALID_FIELD",
  "message": "field netconn_application_protocol is not valid for version 1.0.0",
  "args": [
    "netconn_application_protocol",
    "1.0.0"
  ]
}

Filterable Event Schema

JSON schema document describing filterable fields, their types, and available enum values

Request

GET {cbc-hostname}/data_forwarder/v2/schemas/events?filterable=true&version_constraint={version-constraint}

Body Schema

Field	Definition	Values
`filterable` REQUIRED	Required to be set to `true` to get the fields in the schema that are able to be filtered	`true`
`version_constraint`	When specified, the API will return all filterable fields available for that schema version; if not specified, the API will return all filterable fields for the lowest supported schema version.	e.g. “1.1.0”

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Filterable Event Schema	application/json	View example response below
400	Bad request. Missing required query parameter	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/schemas/events?filterable=true&version_constraint=1.0.0

Response

{
    "$id": "https://carbonblack.com/forwarder/events/filterable.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Filterable Event Schema",
    "description": "CBC Data Forwarder Filterable Fields and Enums for Events",
    "type": "object",
    "properties": {
        "alert_id": {
            "type": "string"
        },
        "childproc_hash": {
            "type": "string"
        },
        "childproc_name": {
            "type": "string"
        },
        "childproc_pid": {
            "type": "number"
        },
        "childproc_publisher_state": {
            "type": "string",
            "enum": [
                "FILE_SIGNATURE_STATE_INVALID",
                "FILE_SIGNATURE_STATE_SIGNED",
                "FILE_SIGNATURE_STATE_VERIFIED",
                "FILE_SIGNATURE_STATE_NOT_SIGNED",
                "FILE_SIGNATURE_STATE_UNKNOWN",
                "FILE_SIGNATURE_STATE_CHAINED",
                "FILE_SIGNATURE_STATE_TRUSTED",
                "FILE_SIGNATURE_STATE_OS",
                "FILE_SIGNATURE_STATE_CATALOG_SIGNED"
            ]
        },
        ... truncated
      },
      "anyOf": [
        {
            "properties": {
                "action": {
                    "type": "string",
                    "enum": [
                        "ACTION_INVALID",
                        "ACTION_FILE_CREATE",
                        "ACTION_FILE_WRITE",
                        "ACTION_FILE_DELETE",
                        "ACTION_FILE_LAST_WRITE",
                        "ACTION_FILE_MOD_OPEN",
                        "ACTION_FILE_RENAME",
                        "ACTION_FILE_UNDELETE",
                        "ACTION_FILE_TRUNCATE",
                        "ACTION_FILE_OPEN_READ",
                        "ACTION_FILE_OPEN_WRITE",
                        "ACTION_FILE_OPEN_DELETE",
                        "ACTION_FILE_OPEN_EXECUTE",
                        "ACTION_FILE_READ",
                        "ACTION_FILE_PENDING_DELETE",
                        "ACTION_FILE_PENDING_RENAME",
                        "ACTION_FILE_SET_SECURITY",
                        "ACTION_FILE_LOCK",
                        "ACTION_FILE_DISCOVERED",
                        "ACTION_FILE_LINK",
                        "ACTION_FILE_FIND"
                    ]
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "endpoint.event.filemod"
                    ]
                }
            }
        },
        ... truncated
    ]
}

Create Filter

Create a filter for the specified configuration to include or exclude data from being forwarded. Multiple Filters for the same config id apply logical OR to support separated complex conditions. The following sample shows how two include and two exclude filters would be applied (IncludeFilter1 OR IncludeFilter2) AND NOT (ExcludeFilter1 OR ExcludeFilter2)

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters

Request Body

{
  "action": "<string>",
  "enabled": <boolean>,
  "name": "<string>",
  "query": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`action` REQUIRED	Whether the filter should include or exclude data from being forwarded	String	`INCLUDE`, `EXCLUDE`
`name` REQUIRED	Defined name for the filter	String	N/A
`query` REQUIRED	The query to match against incoming data	String	N/A
`enabled`	Boolean flag indicating whether the Data Forwarder will apply the filter to incoming data	Boolean	Default: `true`

Note: The 'enabled' property is not supported in the UI. If you plan on configuring filters in the UI then maintain the default 'true'.

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful creation of filter	application/json	View example response below
400	Bad request. The JSON body was malformed, or the filter is invalid	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
409	Conflict. A duplicate filter was found.	application/json	See above
500	Internal server error	application/json	See above

Example

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/filters

Request Body

{
  "action": "INCLUDE",
  "enabled": true,
  "name": "Example Filter",
  "query": "device_os:WINDOWS AND event_origin:NGAV"
}

Response

{
  "action": "INCLUDE",
  "create_time": "2021-07-02T16:23:55Z",
  "enabled": true,
  "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
  "name": "Example Filter",
  "query": "device_os:WINDOWS AND event_origin:NGAV",
  "update_time": "2021-07-03T16:23:55Z"
}

Bulk Filters

Create or update multiple filters for the specified configuration to include or exclude data from being forwarded. The presence of an id field is the differentiator between Create and Update.

Multiple Filters for the same config id apply logical OR to support separated complex conditions. The following sample shows how two include and two exclude filters would be applied (IncludeFilter1 OR IncludeFilter2) AND NOT (ExcludeFilter1 OR ExcludeFilter2)

Note: Due to backend limitations, bulk requests are limited to a maximum of 25 total items to ensure atomicity.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/_bulk

Request Body

[
  // New Filter Input
  {
    "action": "<string>",
    "enabled": <boolean>,
    "name": "<string>",
    "query": "<string>"
  },
  // Update Filter Input
  {
    "action": "<string>",
    "enabled": <boolean>,
    "id": "<string>",
    "name": "<string>",
    "query": "<string>"
  }
]

Body Schema

Field	Definition	Data Type	Values
List[Filters]	List of filters to be created or updated	List[Filters]	Max: 25 filters

Filter Schema

Field	Definition	Data Type	Values
`action` REQUIRED	Whether the filter should include or exclude data from being forwarded	String	`INCLUDE`, `EXCLUDE`
`name` REQUIRED	Defined name for the filter	String	N/A
`query` REQUIRED	The query to match against incoming data	String	N/A
`enabled`	Boolean flag indicating whether the Data Forwarder will apply the filter to incoming data	Boolean	Default: `true`
`id`	Id of an existing filter to be updated	String	N/A

Note: The 'enabled' property is not supported in the UI. If you plan on configuring filters in the UI then maintain the default 'true'.

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful creation of filter	application/json	View example response below
400	Bad request. The JSON body was malformed, or the filter is invalid	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
409	Conflict. A duplicate filter was found.	application/json	See above
500	Internal server error	application/json	See above

Example

Request

POST https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/filters/_bulk

Request Body

[
  {
    "action": "INCLUDE",
    "enabled": true,
    "name": "Example Filter",
    "query": "device_os:LINUX AND event_origin:EEDR",
    "id": "f13e6723-7779-4fdc-a26e-5a95e66be891"
  },
  {
    "action": "EXCLUDE",
    "enabled": true,
    "name": "Example EXCLUDE Filter",
    "query": "device_os:MAC"
  }
]

Response

{
  "results": [
    {
      "action": "INCLUDE",
      "create_time": "2021-07-02T16:23:55Z",
      "enabled": true,
      "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
      "name": "Example Filter",
      "query": "device_os:LINUX AND event_origin:EEDR",
      "update_time": "2022-01-28T17:30:52Z"
    },
    {
      "action": "EXCLUDE",
      "create_time": "2022-01-28T17:30:52Z",
      "enabled": true,
      "id": "9f7ce0be-445e-4f30-9faf-9997c1cbc552",
      "name": "Example EXCLUDE Filter",
      "query": "device_os:MAC",
      "update_time": "2022-01-28T17:30:52Z"
    }
  ]
}

Get Filters

Get all filters for the specified configuration

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful request for all configured filters	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/filters

Response

[
  {
    "action": "INCLUDE",
    "create_time": "2021-07-02T16:23:55Z",
    "enabled": true,
    "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
    "name": "Example Filter",
    "query": "device_os:WINDOWS AND event_origin:NGAV",
    "update_time": "2021-07-03T16:23:55Z"
  }
]

Get Specific Filter

Get a specific filter by id for a given configuration.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/{id}

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful request for specified filter	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

GET https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/filters/f13e6723-7779-4fdc-a26e-5a95e66be891

Response

{
  "action": "INCLUDE",
  "create_time": "2021-07-02T16:23:55Z",
  "enabled": true,
  "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
  "name": "Example Filter",
  "query": "device_os:WINDOWS AND event_origin:NGAV",
  "update_time": "2021-07-03T16:23:55Z"
}

Edit Filter

Adjust an existing a filter by modifying the query, renaming the filter, changing the action, or enabling/disabling the filter.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

PUT {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/{id}

Request Body

{
  "action": "<string>",
  "enabled": <boolean>,
  "name": "<string>",
  "query": "<string>",
  "id": "<string>",
  "create_time": "<string>",
  "update_time": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`action` REQUIRED	Whether the filter should include or exclude data from being forwarded	String	`INCLUDE`, `EXCLUDE`
`name` REQUIRED	Defined name for the filter	String	N/A
`query` REQUIRED	The query to match against incoming data	String	N/A
`enabled`	Boolean flag indicating whether the Data Forwarder will apply the filter to incoming data	Boolean	Default: `true`

Note: 'id', 'create_time', and 'update_time' are read-only and are managed by the backend. They are optional and can be excluded from the request.

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
200	Successful update of filter	application/json	View example response below
400	Bad request. The JSON body was malformed, or the filter is invalid	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
404	Resource not found	application/json	See above
409	Conflict. A duplicate filter was found.	application/json	See above
500	Internal server error	application/json	See above

Example

Request

PUT https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/57b09141-f4e8-11e9-83de-22656feed3f2/filters/f13e6723-7779-4fdc-a26e-5a95e66be891

Request Body

{
  "action": "INCLUDE",
  "create_time": "2021-07-02T16:23:55Z",
  "enabled": true,
  "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
  "name": "Example Filter - Edited",
  "query": "device_os:WINDOWS AND event_origin:NGAV AND process_reputation:KNOWN_MALWARE",
  "update_time": "2021-07-03T16:23:55Z"
}

Response

{
  "action": "INCLUDE",
  "create_time": "2021-07-02T16:23:55Z",
  "enabled": true,
  "id": "f13e6723-7779-4fdc-a26e-5a95e66be891",
  "name": "Example Filter - Edited",
  "query": "device_os:WINDOWS AND event_origin:NGAV AND process_reputation:KNOWN_MALWARE",
  "update_time": "2021-07-03T16:23:55Z"
}

Delete Filter

Use this call to delete a filter.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`event-forwarder.settings`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Data.Forwarder:event-Forwarder.Settings.delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

DELETE {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}/filters/{id}

Response

Use the following to troubleshoot errors. For more troubleshooting tips, see below.

Code	Description	Content-Type	Content
204	Successful deletion of filter	application/json	View example response below
404	Resource not found	application/json	`{ "error_code": "<string>", "message": "<string>", "args": ["<string>"] }`
500	Internal server error	application/json	See above

Example

Request

DELETE https://defense.conferdeploy.net/data_forwarder/v2/orgs/ABCD1234/configs/58aa259f-f42c-11e9-bd5d-2eca45f7dc1c/filters/f13e6723-7779-4fdc-a26e-5a95e66be891

Response

No Content

Troubleshooting Errors

Error Code	Reason For Error	Suggested Fix
`NoSuchBucket`	Configuration is invalid. The specified S3 bucket name doesn’t exist	Follow the User Guide to Creating an S3 Bucket in the AWS Console for compatibility with the CBC Data Forwarder
`AccessDenied` OR “Your request was unsuccessful” during new Data Forwarder configuration	Either: Bucket was created in the wrong region OR The policy is malformed	Ensure that your bucket is created in the same region as the where the Data Forwarder is deployed. Refer to the Configure the Bucket Policy to Allow Access document for configuration instructions
`400`	The reason varied depending on the API call	Refer to the individual API call you are making to validate the JSON body
`401`	Problem using the specified token to authenticate	Check that your X-Auth-Token matches the format secret_key/api_id and that the values are correct
`404`	This could be due to a specified resource could not be found, an incorrect org key in the path, or incorrect permissions on the API key’s access level	Verify that you specified the correct values (path, org key, forwarder id, etc.) and your forwarder configuration is using the correct Authentication information

Guides & Resources

Data Forwarders

Carbon Black Cloud Authentication Guide

Configure the Bucket Policy to Allow Access

Data Forwarder Data Guide

CBC: What URLs are used to access the APIs?

FAQ

Where do I go to get help?

Use the CB Developer Network community forum to discuss issues and get answers from other API developers in the CB Developer Network
Report bugs and product issues to Broadcom Support

Do I need a Carbon Black employee to enable Data Forwarder for me?

No, the Carbon Black Cloud Data Forwarder is completely self-service. You first need to create a valid configuration to enable the CBC Data Forwarder. See the Quick Setup in Postman & S3 Bucket Configuration guide for help.

Is there a way that I can scope down the Data Forwarder’s access to my S3 resources?

Yes, you may configure your S3 policy in a variety of ways to ensure that the Data Forwarder only has permissions to certain resources. Please see the Configure the Bucket Policy to Allow Access topic for details.

Is there a way to choose what types of files the Data Forwarder forwards?

No, only gzipped JSONL (.jsonl.gz) files are supported.

Is there a way to choose what specific types of events or alerts are forwarded?

Yes, see the Data Filtering section on this page.

Are there other types supported besides “alert”, “endpoint.event”, or “watchlist.hit”?

No, only alert, event, and watchlist hit forwarders are currently supported.

What does this field in my data mean?

See the Carbon Black Cloud Data Forwarder Data Mapping document for more information about data schema and sample data.

I am migrating from EDR to the Carbon Black Cloud Data Forwarder. How do the data sent differ between the two?

Refer to the Migration Guide for information on how EDR event data map to Carbon Black Cloud Data Forwarder event data. Some fields from the Migration Guide may be outdated, use the Data Forwarder Data Guide for the most up to date information.

Why am I getting an error?

See the Troubleshooting Errors section above.

When will a new copy of the alert will be sent?

When something changes on the backend.

Why don’t Events show up in the Forwarder at the same time as related Alerts?

The Events stream is not annotated until after the Carbon Black Cloud backend has issued an Alert, so it takes time for the Events service to process the data that identifies Events associated with Alerts.

Last modified on February 26, 2024

Carbon Black Cloud

Page Contents

Data Forwarder API

Overview

Available Forwarder Types

Requirements

Guides and Resources

Authentication

Setup for new Data Forwarder

Data Format

S3 Data Storage and Azure Blob Storage Format

Data Mapping

Data Filtering

Filter Schema

Query Fields

Event Atomicity

Wildcards

Tokenization

Examples

API Calls

Config

Create Forwarder

Forwarder Healthcheck

Get Available Data Versions

Get Configured Forwarders

Get Specific Forwarder

Edit Forwarder

Delete Forwarder

Filter

Validate Filter

Filterable Event Schema

Create Filter

Bulk Filters

Get Filters

Get Specific Filter

Edit Filter

Delete Filter

Troubleshooting Errors

Guides & Resources

FAQ