Alert Enrichment v2.2
Advanced Enrichment mapping brings dynamic multi-value tags to automatic alert enrichment.
Key Features
Combine several event payload fields into a single enrichment rule.
Streamline enrichment configuration with multi-column rules.
Classify enrichment rules into groups to drive action-based enrichment.
Update or add individual mapping rows.
Relevant Permissions
Roles with the following permissions can access the Alert Enrichment API:
Permission | Description |
|---|---|
Alert Enrichment | View and use the Alert Enrichments UI and API. |
Mapping Enrichment (API Only) | Use the Mapping Enrichment API. |
Permission access levels can be adjusted by selecting either View or Full Access. To learn more about how BigPanda's permissions work, see the Roles Management guide.
Tag Limitations
To maintain quality of service, BigPanda limits the number of alert tags and enrichment items available. Each organization can have:
1000 alert tags
500 enrichment items per alert tag
20,000 alert enrichment items total
200 mapping enrichment result tags per map
If more alert tags or enrichment items are needed, we recommend exploring normalization options to help streamline your alert data and improve incident quality.
New Elements
Enrichment V2.2 introduces a new type of enrichment: advanced mapping. Advanced mapping configurations create dynamic map rules to better account for the variable inbound fields across your monitoring tools or teams.
Advanced mapping is structured similar to previous mapping enrichment structure, but includes a new optional groups attribute for result tags. When defining map schema, you can combine multiple column rules together using the groups attribute.
Groups Attributes
The groups object defines rules to cluster result columns together. Each group object lists the result columns and grouping rules such as order and match processing.
Attribute | Description | Type |
|---|---|---|
fields | Defines the column names to group together. Attributes include: type: the column type. tag_name: the column name. Must be exact match to the column name in the uploaded map. | Array of objects |
order | Where in the run order this group runs. The first group with matched columns will apply as the tag value. | Integer |
name | The name of the group. | String |
method | Whether the field values within the group should result in a single matched value or array of values. One of | String |
"groups": [
{
"fields": [
{
"type": "group_tag",
"tag_name": "alert_group"
},
{
"type": "group_tag",
"tag_name": "ticket_active"
}
],
"order": 1,
"name": "alert_group_ticket_active",
"method": "union"
},
{
"fields": [
{
"type": "group_tag",
"tag_name": "alert_group"
}
],
"order": 2,
"name": "alert_group",
"method": "first_match"
}
]
Ungrouped result tag
{
"type": "result_tag",
"tag_name": "email"
}
### Grouped result tag
{
"type": "result_tag",
"tag_name": "email",
"groups": [...]
}
Advanced Enrichment Available API Calls
Alert Enrichment v2.2 has full CRUD functionality.
API Endpoints |
|
Supported Methods | POST, GET, PUT, DELETE |
Rate Limitation | 5 requests per second |
Advanced Mapping Enrichment Routes
Action | Endpoint | Description |
Create Advanced Mapping Enrichment Schema | POST | Creates a mapping enrichment schema |
Retrieve Advanced Mapping Enrichment Schema | GET | Retrieves a specific mapping enrichment schema. |
Retrieve All Advanced Mapping Enrichment Schema | GET | Lists all mapping enrichment schemas in BigPanda. |
Update Advanced Mapping Enrichment Schema | PUT
| Updates a mapping enrichment schema. |
Delete Advanced Mapping Enrichment Schema | DELETE | Deletes a mapping enrichment schema. |
Upload an Enrichment Map for Advanced Mapping
Advanced enrichment uses the same map structure as previous enrichment map.
API Endpoints |
|
Supported Methods | POST, GET, PATCH, PUT, DELETE |
Rate Limitation | 5 requests per second |
To upload a map for an Advanced Mapping configuration, enter the schema id in the Advanced Map upload URL.
Action | Endpoint | Description | Body |
|---|---|---|---|
Create mapping enrichment table | POST | Creates a new table or replaces an existing table. Send the entire table as a CSV file. | The complete CSV file |
Update Mapping Enrichment Row | PATCH | Updates an existing row of an enrichment map. Best used for updates to a single row. | JSON object with map details |
Create Mapping Enrichment Row | PUT | Adds or updates map rows for an existing enrichment map. All rows must have an id. To insert a new row, generate a new UUID code for the row. | JSON List of map details. |
Retrieve map rows | GET | Retrieves a specific row, or all rows for an existing map. Max per page: 100 Multiple row ids can be included in the query, separated by commas. | N/A |
Retrieve an upload job status | GET | Retrieves the upload status of a specific map upload. | N/A |
Delete rule | DELTE | Delete a specific row from a specific map. | N/A |
Must match schema
Every map row must include a tag or group for every column in the schema.
URL encoding
When sending query lists separated by commas, your API tool may require you to format the call with URL encoding. BigPanda will automatically parse an encoded URL.
{
"id": "955056f6-c7bf-4733-a3ad-d3b23f06f173",
"created_by": null,
"created_at": "2024-11-28T15:08:03.272+00:00",
"updated_by": null,
"updated_at": "2024-11-28T15:08:03.303+00:00",
"metadata": null,
"session_id": "S129",
"location": "Chicago",
"threat_score": "90",
"vulnerability_score": "85",
"action_type": "Alert",
"escalation_level": "Critical",
"risk_level": "P1",
"remediation_action": "Block"
}
Read more about uploading enrichment maps in the Best Practices for Mapping Enrichment documentation.
Upgrading Basic Mapping to Advanced Mapping
When converting basic mapping schemas to advanced mapping, you must adjust call parameters as well as the rule structure:
Identify which mapping schemas you wish to replace, and determine downstream effects on tags.
Create a new advanced mapping schema with the groups structure.
Upload a new map to the advanced enrichment endpoint.
Validate enrichment processes before removing old mapping schemas.
{
"type":"advanced_mapping",
"execution_order": "6",
"name":"map-schema 5",
"config":{
"fields": [
{
"type": "query_tag",
"tag_name": "offset"
},
{
"type": "query_tag",
"tag_name": "agent"
},
{
"type": "result_tag",
"tag_name": "region"
},
{
"type": "result_tag",
"tag_name": "email",
"groups": [
{
"fields": [
{
"type": "group_tag",
"tag_name": "alert_group"
},
{
"type": "group_tag",
"tag_name": "ticket_active"
}
],
"order": 1,
"name": "alert_group_ticket_active",
"method": "union"
},
{
"fields": [
{
"type": "group_tag",
"tag_name": "alert_group"
}
],
"order": 2,
"name": "alert_group",
"method": "first_match"
}
]
},
{
"type": "result_tag",
"tag_name": "urgent",
"groups": [
{
"fields": [
{
"type": "group_tag",
"tag_name": "ticket_active"
}
],
"order": 1,
"name": "ticket_active_group",
"method": "first_match"
}
]
}
]
}
}