Data Forwarder API

Introduction

The Carbon Black Cloud Forwarder lets you send data about alerts and events to an AWS S3 bucket where it can be reconfigured to port into 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.

You can now configure a forwarder in the Carbon Black Cloud console under Settings > Data Forwarders.

Available Forwarder Types

  • endpoint.event
  • alert

Requirements

  • Carbon Black Cloud Endpoint Standard or Enterprise EDR
  • API Key with appropriate permissions
  • Configured S3 bucket in the same region as the forwarder

Quick Setup with Postman & S3 bucket Configuration

Watch the video tutorial or follow the step-by-step guide for enabling the Carbon Black Cloud Data Forwarder using Postman. The guide walks you through the following:

  1. Create a bucket in your AWS Management Console
  2. Configure an AWS S3 Bucket to allow the Data Forwarder to write events
  3. Create a New Access Level in the Carbon Black Cloud Console
  4. Create a New API Key in the Carbon Black Cloud Console
  5. Configure the API in Postman
  6. Create a New Event or Alert Forwarder
  7. Monitor the Data Flow to the S3 Bucket
  8. Optional: Add a filter to adjust the Data Flow of Endpoint Events

Alternative Bucket Setup

If you already have an AWS S3 bucket or are looking for additional ways to configure your bucket for varying levels of access and other use-cases, see here.

Data Format

S3 Data Storage Format

Currently the Carbon Black Cloud Data Forwarder only supports output to AWS S3 buckets provided by customers. The Data Forwarder outputs gzip compressed single-event-per-line JSON format (sometimes known as “JSONL”) to the customer’s S3 bucket 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 and Alert schema as well as sample data in the Data Forwarder Data Guide.

Data Filtering

NEW Custom Query Support

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 Common Fields as long as the query does not exceed the complexity (“depth”) limit.


Wildcarding & Tokenization

Wildcards are used in search terms to represent one or more other characters and are supported on most 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

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


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.

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

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


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

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level for the “Data Forwarder” category
    • To use all functions of the Data Forwarder, allow the following permissions: Create, Read, Update, Delete(or see each call below for individual requirements)
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
  • API Route: data_forwarder/v2/orgs/{org_key}/configs
    • Note: when you insert your org_key, you must also remove the { } brackets.

API Calls

Config


The following API calls can be used for either “endpoint.event” or “alert” forwarder types.

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 S3 Bucket using the configuration supplied. It will attempt to write a test message called healthcheck.json to the specified bucket under a subfolder called healthcheck. If the bucket is misconfigured (i.e. incorrect permissions, principle arn, etc.) or the configuration is incorrect (i.e. 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.

If you want to forward both alert type data and endpoint.event 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. The subfolder you configure will be automatically added to the S3 bucket.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings CREATE

Request

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

Request Body

{
  "name": "<string>",
  "s3_bucket_name": "<string>",
  "s3_prefix": "<string>",
  "type": "<string>",
  "enabled": "<boolean>"
}

Body Schema

Field Definition Data Type Values
name REQUIRED Defined name for the specific event or alert forwarder String N/A
s3_bucket_name REQUIRED Configured unique name for s3 bucket String N/A
s3_prefix REQUIRED Defined folder structure the forwarder will write events or alerts to String N/A
type REQUIRED The datastream type that is to be forwarded. Sting endpoint.event, alert
enabled Boolean flag indicating whether to create the data forwarder as enabled Boolean Default: true

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

Example

Request

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

Request Body

{
  "name": "DevRelTest",
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "enabled": false
}

Response for valid configuration

{
  "id": "58aa259f-f42c-11e9-bd5d-2eca45f7dc1c",
  "org_key": "ABC123",
  "name": "DevRelTest",
  "enabled": false,
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "create_time": "2019-10-21T17:58:11Z",
  "update_time": "2019-10-21T17:58:11Z"
}

Response for invalid configuration

If you receive an error indicating your configuration is invalid, either NoSuchBucket or AccessDenied, see the Troubleshooting Errors section below.

Forwarder Healthcheck

This call can be used to run a healthcheck on an Forwarder to determine if the forwarder is able to write to the specified S3 Bucket 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 and respond with a 200, regardless of whether the API was able to write to the bucket.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings READ

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 Configured Forwarders

Get all configured forwarders and their information

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings READ

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": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "org_key": "ABCD1234",
  "name": "DevRelTest",
  "enabled": true,
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "create_time": "2019-10-22T16:23:55Z",
  "update_time": "2019-10-22T16:26:01Z"
}]

Get Specific Forwarder

Get a specific forwarder’s configuration by id

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings READ

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": "DevRelTest",
  "enabled": true,
  "s3_bucket_name": "DevRelTestBucket",
  "s3_prefix": "test",
  "type": "endpoint.event",
  "create_time": "2019-10-22T16:23:55Z",
  "update_time": "2019-10-22T16:26:01Z"
}

Edit Forwarder

This call is used to edit an existing forwarder. You can edit the Enabling/Disabling functionality or change the s3 bucket name.

When editing an existing forwarder, the API will make additional calls to check whether the Carbon Black Cloud event or alert forwarder can write to the specified S3 Bucket using the configuration supplied. It will attempt to write a test message called healthcheck.json to the specified bucket under a subfolder 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 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

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings UPDATE

Request

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

Request Body

{
  "name": "<string>",
  "s3_bucket_name": "<string>",
  "s3_prefix": "<string>",
  "type": "<string>"
}

Body Schema

Field Definition Data Type Values
name REQUIRED Defined name for the specific event or alert forwarder String N/A
s3_bucket_name REQUIRED Configured unique name for s3 bucket String N/A
s3_prefix REQUIRED Defined folder structure the forwarder will write events or alerts to String N/A
type REQUIRED The datastream type that is to be forwarded. Sting endpoint.event, alert

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
}

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"
}

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings DELETE

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings CREATE

Request

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

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

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"
}

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",
  "enabled": true,
  "name": "Example Filter",
  "query": "bad:WINDOWS"
}

Response

{
    "error_code": "QUERY_UNKNOWN_FIELD",
    "message": "field bad does not exist",
    "args": [
        "bad"
    ]
}

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

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

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)

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings CREATE

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"
}

Get Filters

Get all filters for the specified configuration

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings UPDATE

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
event-forwarder.settings DELETE

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 Quick Start Guide to create an S3 bucket for use by the CBC Data Forwarder
AccessDenied 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 Data Forwarder and S3 Policy document for policy troubleshooting and 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

Quick Setup in Postman & S3 Bucket Configuration

Carbon Black Cloud Authentication Guide

Writing a Bucket Policy for the Data Forwarder

Data Forwarder Data Guide

Deconstructing the Process GUID

CBC: What URLs are used to access the APIs?

FAQ

Where do I go to get help?

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

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 Data Forwarder and S3 Policy document 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 “endpoint.event” and “alert”?

  • No, only event and alert forwarders are currently supported.

What does this field in my data mean?

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?

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 October 28, 2021