Event Forwarder Configuration API

Introduction

The Carbon Black Cloud Forwarder now provides the ability to configure forwarders via an API to provide you with a self-service capability and full control of the configuration. This is the first step in future plans to provide this configuration within the UI.

Current Available Forwarder(s)

  • endpoint.event

Create Forwarder

Creating a Forwarder

RBAC Permissions Required

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

Request

POST https://defense-<environment>.conferdeploy.net/event_forwarder_config/v1/orgs/{org_key}/configs

Request Body

Required fields:
Name, s3_bucket_name, s3_prefix, type

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

Body Schema

Field Description Default Required
name Defined name for the specific event forwarder N/A Yes
s3_bucket_name Configured unique name for s3 bucket N/A Yes
s3_prefix Defined folder structure the forwarder will write events to N/A Yes
type The datastream type that is to be forwarded. Supported datastream types: ‘endpoint.event’, ‘alert’ N/A Yes

Response

Code Description Content-Type Content
200 Successful creation of forwarder application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/event_forwarder_config/v1/orgs/ABC123/configs

Request Body

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

Response

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

Delete Forwarder

Deleting a Forwarder

RBAC Permissions Required

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

Request

DELETE https://defense-<environment>.conferdeploy.net/event_forwarder_config/v1/orgs/{org_key}/configs/<id>

Response

Code Description Content-Type Content
200 Successful deletion of forwarder application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/event_forwarder_config/v1/orgs/WNEXFKQ7/configs/58aa259f-f42c-11e9-bd5d-2eca45f7dc1c

Response

{}

Get Configured Forwarders

Get all configured forwarders and their information

RBAC Permissions Required

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

Request

GET https://defense-<environment>.conferdeploy.net/event_forwarder_config/v1/orgs/{org_key}/configs

Response

Code Description Content-Type Content
200 Successful acquiring of all configured forwarders application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/event_forwarder_config/v1/orgs/ABC123/configs

Response

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "org_key": "ABC123",
  "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:59:41Z"
}

Edit Forwarder

Edit an existing forwarder. Current functionalities for editing a forwarder: Enabling/Disabling and changing s3 bucket name

RBAC Permissions Required

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

Request

PUT https://defense-<environment>.conferdeploy.net/event_forwarder_config/v1/orgs/{org_key}/configs/<id>

Request Body

Required fields:
Name, s3_bucket_name, s3_prefix, type

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

Body Schema

Field Description Default Required
name Defined name for the specific event forwarder N/A Yes
s3_bucket_name Configured unique name for s3 bucket N/A Yes
s3_prefix Defined folder structure the forwarder will write events to N/A Yes
type The datastream type that is to be forwarded. Supported datastream types: ‘endpoint.event’, ‘alert’ N/A Yes

Response

Code Description Content-Type Content
200 Successful editing of forwarder application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/event_forwarder_config/v1/orgs/ABC123/configs/57b09141-f4e8-11e9-83de-22656feed3f2

Request Body

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

Response

{
  "id": "57b09141-f4e8-11e9-83de-22656feed3f2",
  "org_key": "ABC123",
  "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"
}

Last modified on March 2, 2020