Enrichments
Using the API

Using The API

You can create and edit your enrichments using the runreveal API if you need more programmatic control. This is especially useful if you have a large number of rules, or rules that change often.

Authentication and Authorization

Authentication with the API is done using API tokens which you can generate in the UI. These tokens are scoped to specficic roles which are authorized to perform different sets of actions. For working with enrichments, you will want to create a token with either the admin role (which has full read/write/delete access) or the analyst role (which has read/edit permissions).

Once you have generated a token, you can use it by setting the Authorization header:

Authorization: Basic <TOKEN>

Making Requests

Requests can be made by appending the desired endpoint to the api base url (https://api.runreveal.com) and setting the appropriate Authorization header. For POST endpoints, you should also set the appropriate Content-type header, application/json for all enrichment endpoints.

💡

Tip: All endpoints require workspace id as a query parameter, you can find your workspace id on the workspace settings page (opens in a new tab)

Examples:

  • Creating an enrichment:
$ TOKEN="<your token>"
$ WKSPCID="<your workspace id>"
$ CREATE_JSON="{
  \"name\": \"example\",
  \"workspaceID\": \"${WKSPCID}\",
  \"description\": \"example enrichment\",
  \"sources\": [\"my-source\"],
  \"path\": \"normalized.actor.email\",
  \"isActive\": true,
  \"rules\": [
    {
      \"type\": \"exact\",
      \"pattern\": \"[email protected]\",
      \"data\": {
        \"userid\": \"12345\"
      }
    }
  ]
}"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/enrichments/create?workspaceid=${WKSPCID}" --data-raw "${CREATE_JSON}"
  • Updating an Enrichment:
$ TOKEN="<your token>"
$ WKSPCID="<your workspace id>"
$ UPDATE_JSON="{
  \"id\": \"2oFro0ffPTle8mRgigX44o41f4U\",
  \"name\": \"example\",
  \"workspaceID\": \"${WKSPCID}\",
  \"description\": \"example enrichment\",
  \"sources\": [\"my-source\"],
  \"path\": \"normalized.actor.email\",
  \"isActive\": true,
  \"rules\": [
    {
      \"type\": \"exact\",
      \"pattern\": \"[email protected]\",
      \"data\": {
        \"userid\": \"12345\"
      },
    },
    {
      \"type\": \"exact\",
      \"pattern\": \"[email protected]\",
      \"data\": {
        \"userid\": \"67890\"
      }
    }
  ]
}"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/enrichments/update?workspaceid=${WKSPCID}" --data-raw "${UPDATE_JSON}"

Reference

Resources

Enrichment

Parameters:

NameTypeDescription
idstringAutogenerated ID, returned from read endpoints
namestringName for the enrichment
workspaceIDstringYour workspace ID
descriptionstringSmall description of the enrichment
sourceslist<string>List of Sources that the enrichment should apply to
pathstringA gjson-compatible path specifying which log field your enrichment rules should match against.
isActiveboolWhether the enrichment is currently active
ruleslist<enrichment_rule>List of rules to apply to each log event

Example:

{
  "id": "2oFgWhP298CnRowC3hEhD2mdRed",
  "name": "My Enrichment",
  "workspaceID": "2oFgWhJ2FOS8PRnv8dTG7XPSeIp",
  "description": "Example enrichment",
  "sources": ["mysourcename"],
  "path": "normalized.actor.email",
  "isActive": true,
  "rules": [
    {
      "id": "2oFgWjb5mWnOOcUWbVkLjxnXgRb",
      "type": "exact",
      "pattern": "[email protected]",
      "data": {
        "userid": "1234567"
      }
    }
  ]
}

Enrichment Rule

Parameters:

NameTypeDescription
idstringAutogenerated ID, returned from read endpoints
typestringMatching type for rule, must be one of "exact", "cidr", or "regex"
patternstringPattern to match against
datamap<string, string>Data to attach to matching log events

Examples:

CIDR matching

{
  "id": string,
  "type": string,
  "pattern": string,
  "data": map<string, string>,
}

Endpoints

POST /enrichments/create

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes

Body: Enrichment

Required fields:

  • name
  • workspaceID
  • description
  • sources
  • path
  • isActive
  • rules
ℹ️

Note: id is not required on creation, it will be generated server side

💡

Tip: You can get the valid source names available for use in the sources field by querying the /sources/list?workspaceid={workspaceid} endpoint

POST /enrichments/update

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes

Body: Enrichment

Required fields:

  • id
  • name
  • workspaceID
  • description
  • sources
  • path
  • isActive
  • rules
ℹ️

Note: id is required for updates

GET /enrichments/get

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes
idThe enrichment id to getYes

GET /enrichments/list

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes
ℹ️

Note: For performance reasons, the list endpoint does not return individual enrichment rules. To see those, use the get endpoint for a specific configuration.

GET /enrichments/delete

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes
idThe id of the enrichment to deleteYes

POST /enrichments/appendrules

Query Parameters:

NameDescriptionRequired
workspaceidYour workspace IDYes
idThe id of the enrichment to append toYes

Body: List<EnrichmentRule>

Required Fields:

  • type
  • pattern
  • data
ℹ️

Note: id is not required on append, ids will be generated server side

Loading Rules From CSVEmail