RunReveal
Log ManagementLog Processing

Enrichments

Enrichments allow you to augment your log events with supplemental data based on pattern matching.

How it works

An enrichment in Runreveal consists primarily of two parts:

  1. An enrichment configuration, which contains metadata about your enrichment like Name and Description, which log sources to enrich, as well as information about which log event field you wish to match with.

  2. A set of enrichment Rules, which describe the data you wish to add to your log events, and the conditions when you would like that data added.

Manage enrichment rules

Add rules in the UI

On the create or edit enrichment page, use the Rules section to add rules manually with:

  • Match type (exact, regex, or cidr)
  • Pattern
  • Data object (string keys and string values)

Load rules from CSV

For large rule sets, use the Load from file button in the Rules section.

Your CSV must have:

  • Exactly 3 columns
  • Comma-delimited rows
  • Double-quoted values (escape inner quotes with "")

Each row must follow:

match_type,pattern,data

Where:

  • match_type is one of exact, regex, or cidr
  • pattern is the value to match
  • data is a JSON object with string keys and values (no nested objects)

Example rows:

"exact","[email protected]","{""user_id"":""12345""}"
"regex","\.org^","{""email_tld"":""org""}"
"cidr","10.0.0.0/16","{""location"":""san francisco""}"

Edit existing rules

Clicking a row in the rules table does not open an inline rule editor.

To update an existing rule:

  1. Delete the existing rule from the rules table
  2. Add a new rule with the updated values
  3. Click Update Enrichment to save

If you add a rule with the same pattern as an existing rule, the UI adds another entry instead of replacing the original one automatically. To avoid ambiguity, delete the old rule first.

If you prefer, you can also use the Chat Agent tool EnrichmentUpdate to directly edit the enrichment for you.

Manage enrichments with the API

You can also create and update enrichments programmatically with:

  • POST /enrichments/create
  • POST /enrichments/update
  • POST /enrichments/appendrules
  • GET /enrichments/get
  • GET /enrichments/list
  • DELETE /enrichments/delete

All enrichment endpoints require workspaceid as a query parameter and Authorization: Basic <TOKEN>.

Example

Let's say you are wanting to enrich log events from your cloudflare audit log source, to map user emails to user id's from some other external system you have.

First, let us take a look at an example log event from that source, a log in event from [email protected]:

{
  "action": {
    "result": true,
    "type": "login"
  },
  "actor": {
    "email": "[email protected]",
    "id": "c38246172e13e3e341f7ef3319d2c913",
    "ip": "24.225.52.121",
    "type": "user"
  },
  "id": "a683351a-5e63-7272-72b6-6bf7f712fdf2",
  "interface": "",
  "metadata": {},
  "newValue": "",
  "oldValue": "",
  "owner": {
    "id": "c38246172e13e3e341f7ef3319d2c913"
  },
  "resource": {
    "id": "c38246172e13e3e341f7ef3319d2c913",
    "type": "account"
  },
  "when": "2024-08-20T23:47:18Z",
  "newValueJson": {},
  "oldValueJson": {}
}

To create our enrichment configuration, we need to determine which log event field we want to match with to look up our supplemental data. We tell the enrichment configuration how to find this field using gjson path notation. In this case, we could create an enrichment configuration with path actor.email configured to enrich the cloudflare audit log source.

Next, we will want to define a set of rules which will map cloudflare user email adresses to user id's. If [email protected] here had user id 12345, then we could make a rule:

exact, [email protected], {"user_id": "12345"}

This would tell Runreveal to match any log event where the value of actor.email is exactly [email protected]. If the event does match, then {"user_id": "12345"} will be added to the enrichments field of the log event before it is written to its destination.

Now, we can save and enable our enrichment by clicking the Create Enrichment button:

To verify that our enrichment is working, we can search for our newly enriched events on the Explore page:

From the results, we can see our resulting log event ends up in the logs table as:

{
  ...
  "enrichments": [
    {
      "data": {
        "user_id": "12345"
      },
      "name": "actor.email",
      "provider": "cloudflare-email-to-external-id",
      "type": "custom",
      "value": "[email protected]"
    }
  ],
  "rawLog": {
    "action": {
      "result": true,
      "type": "login"
    },
    "actor": {
      "email": "[email protected]",
      "id": "c38246172e13e3e341f7ef3319d2c913",
      "ip": "24.225.52.121",
      "type": "user"
    },
    "id": "a683351a-5e63-7272-72b6-6bf7f712fdf2",
    "interface": "",
    "metadata": {},
    "newValue": "",
    "oldValue": "",
    "owner": {
      "id": "c38246172e13e3e341f7ef3319d2c913"
    },
    "resource": {
      "id": "c38246172e13e3e341f7ef3319d2c913",
      "type": "account"
    },
    "when": "2024-08-20T23:47:18Z",
    "newValueJson": {},
    "oldValueJson": {}
  },
  ...
}

Use Cases

Enrichments are powerful tools for tagging events with metadata that can be used for filtering, detection tuning, and compliance. Below are common patterns for using enrichments to manage log processing.

Exclude Known-Good Activity from Detections

Use enrichments to tag events from trusted service accounts, automation systems, or known-good IP ranges. Your detections can then check for these enrichment flags to reduce false positives.

Tag Service Accounts for Detection Exclusion

Create an enrichment to tag events from known service accounts. Detections can check for this flag to skip expected automation activity.

Step 1: Create the Enrichment

Navigate to Enrichments → Click Create Enrichment → Name it service-account-exclusions → Set Match Field to actor.email

Step 2: Add Service Account Rules

Add rules for each service account you want to exclude from detections

Rule 1 (Exact Match):
  Pattern: [email protected]
  Data: {"exclude_from_detections": true, "reason": "Scheduled backup service"}

Rule 2 (Exact Match):
  Pattern: [email protected]
  Data: {"exclude_from_detections": true, "reason": "Infrastructure monitoring"}

Rule 3 (Regex):
  Pattern: ^automation-.*@company\.com$
  Data: {"exclude_from_detections": true, "reason": "Approved automation platform"}

The enrichment handles all pattern matching logic. Your detections only need to check for the exclude_from_detections flag, making them simpler and more maintainable.

Tag Trusted IP Ranges

Tag events from corporate VPN, office networks, or trusted cloud infrastructure to reduce noise in network-based detections.

Enrichment: trusted-networks
Match Field: src.ip

Rule 1 (CIDR Match):
  Pattern: 10.0.0.0/8
  Data: {"trusted_network": true, "network_zone": "corporate"}

Rule 2 (CIDR Match):
  Pattern: 192.168.100.0/24
  Data: {"trusted_network": true, "network_zone": "vpn"}

Rule 3 (CIDR Match):
  Pattern: 52.94.76.0/22
  Data: {"trusted_network": true, "network_zone": "aws-services"}
  • Log Processing Getting Started - Understand where enrichments fit in the full log processing pipeline.
  • Transforms - Parse, normalize, and reshape fields before matching enrichment rules.
  • Filtering - Route or scope logs before they are enriched.
  • Dropping - Drop events based on enrichment flags such as should_drop.
  • Writing Detections - Use enrichment metadata in detection logic to tune fidelity.
  • Queries - Validate enrichment outcomes and investigate enriched events with SQL.

Previous

Filtering

Next

Sampling Logs

On this page