Back to Blogs

Announcing VMware Carbon Black Cloud Alerts v7 API

Posted on June 13, 2023

The new Alerts V7 API will improve alert management and allow for easier management, consumption, and triage of alerts in the Carbon Black Cloud. Alerts v7 API extends the capabilities with improved methods of retrieving alerts and added functionality to manage alert workflow.

Note: This blog was updated on 10th Oct 2023 with additional information.

Highlights

  • Return only the records you want; there are more fields that can be used to filter the data returned including creation time, category, type, status and more
  • New fields included in the Alert which will reduce the need for a second call to enrich the alert with additional information. Including the much asked for process_cmdline
  • Alerts can be closed based on matching search criteria and a determination such as true positive or false positive provided
  • Grouped and Ungrouped Alert Searches are separate APIs
  • Facets now support exclusions, the same as the Search (Find) endpoints
  • A new Alert History request that includes workflow state changes and notes
  • Notes can be added at both the alert level and the threat level, and the maximum length has been increased to 20,000 characters
  • Observed Alerts have been removed from the Alerts API as these events are not considered actionable threats. They can now be called from the Observations API. For more information about this, see the announcement on Carbon Black Tech Zone.
  • An updated Data Forwarder schema with the same fields. Read more here.

Alerts v6 will continue to be supported until July 31, 2024. Users can continue to use Alerts v6 and plan the update in that period.

Improved Polling

When polling alerts regularly, for example to integrate with a SIEM application when the Data Forwarder is not an option, you can reliably filter on create and update times.

The new field time_range has been added at the top level of the search request body and is a filter on the new field backend_timestamp which is when the alert was persisted in Carbon Black Cloud. Use the range field to specify a period prior to when the search is being run such as -2d for the previous two days, or start and end for arbitrary periods.

Find Alerts Request Body

See the complete API Specification for detailed usage instruction

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>"
  },
  "criteria": { "<object>"},
  "exclusions": { "<object>"},
  "start": <integer>,
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Requirements

  • Any Carbon Black Cloud product
  • Some Alert Types are only generated by specific products

Alerts v6 Notes

  • As part of the Alerts v7 release a new alert type of Intrusion Detection System (IDS) is available. The Alert v6 API search does not return these alerts. The v6 Get Alert by Id route will return the record but data will be incomplete, and the Alert Type will incorrectly show as CB_ANALYTICS. Please transition to Alerts v7 API to work with this new alert type and get the most from your integration.

Observed Alerts

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.

More Information


Coming soon

  • Carbon Black Cloud Python SDK with support for Alerts v7 API

Have questions or feedback?

  • Subscribe to the Developer Network Newsletter