Enriched Events API Migration

The Enriched Event API will be deactivated on September 5, 2024.

Overview

This guide is to assist Endpoint Standard customers in migrating from the Enriched Events Search API to the Observations API.

In this document, you will find

  • A mapping of deprecated Enriched Events Search API endpoints to new Observations API endpoints
  • A mapping of deprecated Enriched Events Search API schema to new Observations API schema
  • Carbon Black Cloud Python SDK migration information

Why Observations?

  • Richer search, easy aggregation, and faster filtering to isolate type and distribution of classes of detections, such as Intrusion Detection System
  • Deeper unpacking of network traffic to catch malicious activity masquerading as “benign” protocols
  • MITRE ATT&CK tactics and techniques - aligning to industry-standard security framework for ease of learning and evaluation
  • For developers, the Observations API adds aggregation tooling to quickly evaluate the blast radius of suspicious activity without having to first ingest all Observations into your own data lake or SIEM

Guides and Resources

API Endpoints

The new Observations API uses the same URL structure as the existing Enriched Events Search API, simply replacing enriched_events with observations. Additionally, the new endpoints are all v2, and they utilize the same response codes as Enriched Events.

API Endpoint Equivalencies

Operation Legacy Enriched Events Search Endpoint New Observations Endpoint
Create Search POST /v2/orgs/{org_id}/enriched_events/search_jobs POST /v2/orgs/{org_id}/observations/search_jobs
Get Search Results GET /v2/orgs/{org_id}/enriched_events/search_jobs/{job_id}/results GET /v2/orgs/{org_id}/observations/search_jobs/{job_id}/results
Create Facets POST /v2/orgs/{org_id}/enriched_events/facet_jobs POST /v2/orgs/{org_id}/observations/facet_jobs
Get Facet Results GET /v2/orgs/{org_id}/enriched_events/facet_jobs/{job_id}/results GET /v2/orgs/{org_id}/observations/facet_jobs/{job_id}/results
Create Details Job POST /v2/orgs/{org_id}/enriched_events/detail_jobs POST /v2/orgs/{org_id}/observations/detail_jobs
Get Details Results GET /v2/orgs/{org_id}/enriched_events/detail_jobs/{job_id}/results GET /v2/orgs/{org_id}/observations/detail_jobs/{job_id}/results
Get Details Status GET /v2/orgs/{org_id}/enriched_events/detail_jobs/{job_id} N/A - It can be found by comparing contacted with completed numbers from the Get Details Results API
Search Suggestion GET /v2/orgs/{org_id}/enriched_events/search_suggestions GET /v2/orgs/{org_id}/observations/search_suggestions
Search Validation GET /v2/orgs/{org_id}/enriched_events/search_validation GET /v2/orgs/{org_id}/observations/search_validation
Create Aggregation POST /v1/orgs/{org_id}/enriched_events/aggregation_jobs/{aggregation_field} POST /v2/orgs/{org_id}/observations/search_jobs
Get Aggregation Results GET /v1/orgs/{org_key}/enriched_events/aggregation_jobs/{job_id}/results POST /v2/orgs/{org_id}/observations/search_jobs/{job_id}/group_results

Schema Changes

The following table contains the new fields available when migrating to the Observations API. The fields or sub-fields not captured here remain the same for their respective API endpoints.

New Fields

Operation New Fields
Create Search observation_id, observation_type, observation_description, attack_tactic, attack_technique
Get Search Results observation_id, observation_type, observation_description, attack_tactic, attack_technique
Create Facets observation_type, attack_tactic, attack_technique
Get Facet Results observation_type, attack_tactic, attack_technique
Create Details Job observation_id, observation_type, observation_description, attack_tactic, attack_technique Note: Observation_ids should be provided instead of event_ids.
Create Aggregation observation_id, observation_type, observation_description, attack_tactic, attack_technique
Get Aggregation Results observation_id, observation_type, observation_description, attack_tactic, attack_technique

Substituted Fields

Enriched Events Field Observations Field
event_network_inbound netconn_inbound
event_network_local_ipv4 netconn_local_ipv4
event_network_local_ipv6 netconn_local_ipv6
event_network_location netconn_location
event_network_protocol netconn_protocol
event_network_remote_port netconn_port

How to find Enriched Events in the Observations API

Enriched Events have been re-classified under the following Observation Types:

  • CB_ANALYTICS - Enriched Event associated with an Alert that was created using Carbon Black Cloud Analytics
  • CONTEXTUAL_ACTIVITY - Enriched Event NOT associated with an Alert that was captured by the sensor, but did not match any Carbon Black detections
  • TAMPER - Enriched Event that captures evidence of processes that are tampering with the Operating System or the Carbon Black Cloud Sensor and may be associated to an alert
  • INDICATOR_OF_ATTACK - Enriched Event that arise from endpoint behavior that matches known indicators of attack and are almost always tied to a known MITRE ATT&CK Technique. Indicators of attack are not always malicious in nature, but should be reviewed.

For more information on all the observation types see the user guide

Note: As part of the Alerts v7 API release and Alert Forwarder Schema v2, Observed Alerts were removed.
  • 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.

Carbon Black Cloud Python SDK Migration

Version 1.4.2 of the Carbon Black Cloud Python SDK supports the new Observations API.

All legacy methods remain to provide backwards compatibility. They will be removed from the SDK in the same timeframe as the APIs being deactivated, not earlier than mid-2024.

Customers should update to the new cbc_sdk.platform observations module to take advantage of new features at their convenience, so new features can be used in the future.

See details in the 1.4.2 release notes for the Carbon Black Cloud Python SDK.

Documentation on the new Observations module in the SDK is in the SDK Read The Docs.

Deactivation Timeline

The Enriched Events Search API will not be deactivated earlier than 12 months after deprecation. The earliest deactivation date is mid 2024.


Last modified on October 10, 2023