IntegrationServices Notification v3 API Migration

The integrationServices/v3/notification API will be deactivated on October 31, 2024.

Overview

This is to assist in migrating integrations from integrationServices/v3/Notification API to Alerts v7 API or Data Forwarder - Alerts Schema v2.

In this document, you will find

Recommendations for when to use the Alerts v7 API vs. the Carbon Black Cloud Data Forwarder
A mapping of deprecated v3 Notifications API endpoint to related Alerts v7 endpoint
Examples for recreating notification configurations from the Carbon Black Cloud console in the Alerts v7 API

Note: Although the same configuration screen is used in the Carbon Black Cloud console to set up email notifications, email notifications are not affected. Please continue to use this screen to configure your email notifications.

Guides and Resources

Alerts v7 API Documentation
Alerts Search Fields
Integrate using the Carbon Black Cloud Data Forwarder
Syslog Connector 2.0
After migrating, learn how to increase security by removing unused API keys.

If you did not update prior to October 31st 2024

Review the Recommendations below to determine whether the Alerts v7 API, the Data Forwarder - Alerts Schema v2, or the Syslog Connector is the better solution for your use case.
Update your systems with the selected solution.
If there is a period of Alerts that are missing and are required, use the Alert V7 API. Set the Time Range Filter of the search criteria to get Alerts using the v7 API. Use the lastUpdatedTime of the last Notification record ingested as the start time for the Time Range Filter. lastUpdatedTime in the Notification API is equivalent to thebackend_timestamp on the Alert v7 API.

Key Differences

In Notifications, the criteria that defines when a notification is sent is defined in the Carbon Black Cloud console. When using the Alerts v7 API, the criteria is part of the API request
The Notifications endpoint is a read-once queue whereas the Alerts v7 is a search request. When calling the Alerts v7 API, the caller (your script) must manage state, keeping track of the timestamp of the last Alert retrieved and using that for the start timestamp on the next request. See the Alert Bulk Export guide for details on the polling algorithm.

Observed Alerts

As part of the Alerts v7 API release and Alert Forwarder Schema v2, Observed Alerts were removed.

SIEM Notification rules that previously included Observed Alerts will no longer emit Observed Alerts.
New SIEM Notification rules only include true alerts. It is not possible to configure inclusion of Observed Alerts for new Notification rules.
Observed Alerts will continue to be returned in Alerts v6 API responses and Data Forwarder Alert Schema v1.
An Observed Alert can only be enriched by
- Searching Enriched Events by alert_id
- Searching Observations by event_id using created_by_event_id from the Observed Alert
An Observed Alert is identified by category = MONITORED in the API response and WARNING in the Alert Forwarder output.
Observed Alerts are not returned in Alerts v7 API responses or in the Data Forwarder Alert Schema v2.
See Announcing the Alerts V7 API and “Observed Alerts” Become “Observations” for more information.

Recommendations

The Data Forwarder - Alerts Schema 2.0.0 is recommended for customers

With high volume
With Access to an AWS S3 bucket or Azure BLOB storage Container. See the Announcement of the Azure Destination
Who want notifications on all alerts

The Alerts v7 API is recommended for customers

With lower volume
Who want to filter to a subset of alerts

The Syslog Connector is available to enable easy integration with other systems that support Syslog connections.

API Endpoints

Operation	Legacy v3 Notification Endpoint	New v7 Alerts API Endpoint
Get Notifications	GET /integrationServices/v3/notification	POST /api/alerts/v7/orgs/{org_key}/alerts/_search

Using the Alerts v7 API to retrieve notifications allows for more flexibility and scaling by moving the logic from the Carbon Black Cloud console to the API search request. The Alerts v7 API can be used to configure a subset of alerts to flow into your integrations, allowing for more customized and targeted notifications. The Alerts v7 API has fields that provide equivalent filtering to the options available in the notifications configuration, and many more. See the example below to get a head start on using the APIs to retrieve notifications.

Schema Changes

The following tables contains the fields to be substituted when migrating to the Alerts v7 API.

The AlertService/v7 APIs return the entire Alert object as a response. This contains significantly more metadata about the Alert than a Notification record.

To get the most benefit from the Alerts v7 API or Data Forwarder with Alert Schema v2, check out the fields available in the Alert v7 API Search Fields or Data Forwarder Alert Schema v2.0. Field names are aligned across API and Forwarder.

Fields that are marked DEPRECATED do not have an equivalent in the Alert v7 API or Alert Forwarder Schema v2.

Common fields

The following fields occur in all alert types.

Alert types other than CB Analytics and Watchlist did not have type-specific fields in a Notification.

Legacy Field	New Field
ruleName	Deprecated
eventTime	detection_timestamp with conversion from ISO to integer representation. This Python code snippet performs the conversion: `int(datetime.fromisoformat(alert["detection_timestamp"]).timestamp()) * 1000`
eventId	id (Alert ID) In Notifications, event referred to the Alert that generated the notification.
eventDescription	reason
url	alert_url
Device Information	Additional device information not included on the Alert can be retrieved using the Specific Device Information API
deviceInfo.deviceType	os
deviceInfo.email	DEPRECATED
deviceInfo.deviceId	device_id
deviceInfo.deviceName	device_name
deviceInfo.deviceHostName	DEPRECATED
deviceInfo.deviceVersion	device_os_version
deviceInfo.targetPriorityType	device_target_value
deviceInfo.targetPriorityCode	DEPRECATED
deviceInfo.internalIpAddress	device_internal_ip
deviceInfo.groupName	DEPRECATED. With the release of Asset Groups, the Devices v6 API will be extended with Asset Group Name.
deviceInfo.externalIpAddress	device_external_ip
type	This field exists but has different content. The type field in Alerts v7 identifies the type of alert; e.g. `CB_ANALYTICS`, `WATCHLIST`.

CB Analytics Alerts

Legacy Field	New Field
type	DEPRECATED The type field in Alerts v7 identifies the type of alert; `CB_ANALYTICS`. In Alerts v7, only records with the notification type `THREAT` are returned. Records that in Notifications had the category `MONITORED` (Observed) are now Observations See more information in Announcing the Alerts v7 API and “Observed Alerts” Become “Observations. Also see the Observations API.
threatInfo.time	detection_timestamp with conversion from ISO to integer representation. This Python code snippet performs the conversion: `int(datetime.fromisoformat(alert["detection_timestamp"]).timestamp()) * 1000`
threatInfo	ttps Alerts v7 has a list of TTPs. Each TTP maps to a threatInfo element per the following field mappings:
threatInfo.score	severity
threatInfo.incidentId	threat_id
threatInfo.summary	reason
threatInfo.indicators.indicatorName	ttp
threatInfo.indicators.sha256Hash	process_sha256
threatInfo.indicators.applicationName	app_name

Watchlist Alerts

Legacy Field	New Field
type	Notification used `THREAT_HUNTER`. Alerts use `WATCHLIST`
threatHunterInfo.time	backend_timestamp with conversion from ISO to integer representation. This Python code snippet performs the conversion: `int(datetime.fromisoformat(alert["backend_timestamp"]).timestamp()) * 1000`
threatHunterInfo.score	severity
threatHunterInfo.incidentId	threat_id
threatHunterInfo.summary	reason
indicators.indicatorName	ioc_id
indicators.sha256Hash	process_sha256
indicators.applicationName	app_name
watchlists	watchlists
iocId	ioc_id
count	DEPRECATED
dismissed	A value of `True` in Notification is equivalent to `CLOSED` in Alerts. Other values in Alerts are `OPEN` and `IN_PROGRESS`.
documentGuid	DEPRECATED
firstActivityTime	first_event_timestamp with conversion from ISO to integer representation. This Python code snippet performs the conversion: `int(datetime.fromisoformat(alert["first_event_timestamp"]).timestamp()) * 1000`
md5	process_md5
policyId	device_policy_id
processGuid	process_guid
processPath	process_name
reportName	report_name
reportId	report_id
reputation	process_reputation
responseAlarmId	threat_id
responseSeverity	severity
runState	run_state
sha256	process_sha256
status	DEPRECATED
tags	report_tags
targetPriority	device_target_value
threatId	threat_id
lastUpdatedTime	backend_timestamp In Alerts v7, the field `backend_update_timestamp` is updated when an alert is updated. However, Notifications were not resent when alerts received updates so on a Notification, lastUpdatedTime will always equal backend_timestamp
threatCause.actor	process_sha256
threatCause.actorName	app_name,
threatCause.reason	report_name
threatCause.actorType	DEPRECATED
threatCause.threatCategory	DEPRECATED
threatCause.actorProcessPPid	DEPRECATED
threatCause.causeEventId	DEPRECATED
threatCause.reputation	process_reputation
threatCause.originSourceType	DEPRECATED

Examples

Alert Crosses a Threshold

The example below shows how to use the Alerts v7 API to achieve this notification configuration from the Carbon Black Cloud console. It also shows how to retrieve historical data using the time range filter. More information on using the time range filter can be found here.

Examples

HTTP

Request

POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_search

Request Headers

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

Request Body

{
    "time_range": {
        "start": "2023-04-03T08:48:47.211Z",
        "end": "2023-09-14T09:51:20.233Z",
    },
    "criteria": {
        "minimum_severity": 2,
        "type": [
            "CB_ANALYTICS", 
            "WATCHLIST"
        ]
        "policy_name": [
            "DEVO Policy"
        ]
    },
    "exclusions": { },
    "start": "1",
    "rows": "1",
    "sort": [
        {
            "field": "severity",
            "order": "DESC"
        }
    ]
}

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

Watchlist Gets a Hit

The example below shows how to use the Alerts v7 API to achieve this notification configuration from the Carbon Black Cloud console. It also shows how to filter by the last time an alert was updated.