Migrating Existing Workflows to Alert Enrichment V2.1

Migrating to the Enrichment V2.1 API opens up new functionality and more robust endpoints.

The Alert Enrichments V2.1 API allows you to programmatically create custom tags and enrichment items that add contextual information to alerts. It supports the mapping enrichment technique, which creates alert custom tags by looking up values in a data mapping table.

Use the Alert Enrichment V2.1 API to define alert tags and enrichment maps to add vital context to ongoing alerts.

Read more about how alerts are contextualized and the potential correlation and automation possibilities of alert enrichment in the Alert Intelligence documentation.

With the Alert Enrichments V2.1 API you’ll have more options for leveraging the API to enrich and contextualize alerts.

API Improvements

  • Improved composition and extraction enrichment item functionality and features
  • Alert tags can now be duplicated, marked inactive, and have a description
  • Mapping tables now automatically enrich existing alert tags
  • Mapping enrichment items can be reordered on a per-tag basis
  • Enabling future audit-log functionality
  • Bulk operations now available for enrichment items

In order to leverage these improved capabilities, your organization will need to migrate your analytics into the new tool and data set.

🚧

All customers will need to move to the V2.1 API. The Enrichment V1 and V2.0 API will be deprecated during 2023

Relevant Permissions

Roles with the following permissions can access the Alert Enrichment API:

PermissionDescription
Enrichments_Read
Enrichments_jobs_Read
Read only - make GET calls using the Enrichments API.
Enrichments_Full_Access
Enrichments_jobs_Full_Access
Full access - use the Enrichments API to view and define mapping enrichments.

To learn more about how BigPanda's permissions work, see the RBAC - Role Based Access Control guide.

Preparing for Migration

Migrating to the Alert Enrichment V2.1 API is a simple, seamless process. During the initial migration phase, you will have access to the V2.0 API as well as the new V2.1.

Before beginning migration, review all manual and automated processes that leverage the existing Alert Enrichment APIs. This includes any mapping enrichment APIs leveraging the V1.0 and V2.0 Enrichment API.

Simple Migration

If you are only using the Alert Enrichment V1 API to manage mapping enrichments, the migration process will require only a few steps:

  1. Change the endpoint name attached to Mapping Enrichment calls to the new /v2.1/mapping-enrichment/ endpoint
  2. Validate payload format matches the new requirements
  3. Test an enrichment map to ensure it is uploading correctly
  4. (Optional) If choosing to implement API management of composition and extraction tags, use the new V2.1 endpoints and JSON payload formats.

Complex Migration

If you are using the Enrichment V2.0 API to manage composition and extraction enrichments, the migration process will require a few additional updates:

  1. Change the endpoint name attached to all enrichment calls to the new endpoints:

/v2.0/alert-enrichments (mapping type) --> /v2.1/mapping-enrichment
/v2.0/alert-enrichments (non-mapping type) --> /v2.1/enrichments-config/tags/<TAG_NAME>/enrichments

  1. Validate payload format matches the new requirements

The object payload for Tag Rules or Enrichment Items is changing from a single object to an array of objects. Composition and extraction enrichments will be nested within the enrichment array.

{
     "name": "tag_name", 
     "active": true,
     "description": "", 
     "enrichments": [    
      {
        "type": "extraction",
        "active": true,
        "when": {},
        "config": {
            "source": "host",
            "destination": "tag_name",
            "regex": "(.*)",
            "template": null 
        },
        "note": null
    },
    {
        "type": "composition", 
        "active": true,
        "when": {},
        "config": {
            "destination": "tag_name",
            "value": "val-${host6666}"
        },
        "note": "wiki.com"
    }
  ]
}
  1. Test each enrichment and call type to ensure it is functioning correctly

Available Endpoints

The Alert Enrichment API allows you to manage alert tags and alert enrichment items.

Alert Tags

ActionDescription
Alert Tag ObjectDefines the schema for an alert tag.
Create Alert TagCreates a new tag
Retrieve Alert TagRetrieves a specific alert tag.
Retrieve All Alert TagsLists all alert tags configured in BigPanda.
Update Alert Tag DataUpdates tag fields for name, active state, or description.
Delete Alert TagDeletes an alert tag.

Enrichment Item Routes (Composition and Extraction Only)

ActionDescription
Composition or Extraction Enrichment ItemDefines the schema for a composition or extraction enrichment item
Create Alert Enrichment ItemCreates a new composition or extraction enrichment item for the tag.
Update Alert Enrichment ItemUpdates a composition or extraction enrichment item for the tag.
Delete Alert Enrichment ItemDeletes a composition or extraction enrichment item for the tag.
If all enrichment items for a tag are deleted, the tag will also be removed from the system

Mapping Enrichment Routes

Read more in the Best Practices for Mapping Enrichment documentation.

ActionDescription
Mapping Enrichment SchemaDefines the schema for a mapping enrichment item.
Create Mapping Enrichment SchemaCreates a mapping enrichment schema
Retrieve Mapping Enrichment SchemaRetrieves a specific mapping enrichment schema.
Retrieve All Mapping Enrichment SchemaLists all mapping enrichment schemas in BigPanda.
Update Mapping Enrichment SchemaUpdates a mapping enrichment schema.
Delete Mapping Enrichment SchemaDeletes a mapping enrichment schema.

Mapping Enrichment Table Routes

Read more in the Best Practices for Mapping Enrichment documentation.

ActionDescription
Mapping Enrichment Table ObjectUploaded enrichment map files.
Create Mapping Enrichment Table using CSVUploads a mapping enrichment table.
Retrieve Mapping Enrichment TableRetrieve a specific enrichment map.
Create Mapping Enrichment RowUpdates an enrichment map to add a new row.
Update Mapping Enrichment RowUpdates an enrichment map to update a specific map row.
Delete Mapping Enrichment RowUpdates an enrichment map to delete a specific map row.

Job Routes

ActionDescription
Job Status ObjectThe schema for the return on a job status call
Retrieve Mapping Table Job StatusRetrieves the status of a previous enrichment change.

Ordering Routes (Alert Tags, and Alert Tag Enrichment Items)

ActionDescription
Update Alert Tag OrderUpdates tag run order.
Update Enrichment Item Order for an Alert TagUpdates enrichment item order.