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:
| Name | Type | Description |
|---|---|---|
| id | string | Autogenerated ID, returned from read endpoints |
| name | string | Name for the enrichment |
| workspaceID | string | Your workspace ID |
| description | string | Small description of the enrichment |
| sources | list<string> | List of Sources that the enrichment should apply to |
| path | string | A gjson-compatible path specifying which log field your enrichment rules should match against. |
| isActive | bool | Whether the enrichment is currently active |
| rules | list<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:
| Name | Type | Description |
|---|---|---|
| id | string | Autogenerated ID, returned from read endpoints |
| type | string | Matching type for rule, must be one of "exact", "cidr", or "regex" |
| pattern | string | Pattern to match against |
| data | map<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:
| Name | Description | Required |
|---|---|---|
| workspaceid | Your workspace ID | Yes |
Body: Enrichment
Required fields:
nameworkspaceIDdescriptionsourcespathisActiverules
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:
| Name | Description | Required |
|---|---|---|
| workspaceid | Your workspace ID | Yes |
Body: Enrichment
Required fields:
idnameworkspaceIDdescriptionsourcespathisActiverules
Note: id is required for updates
GET /enrichments/get
Query Parameters:
| Name | Description | Required |
|---|---|---|
| workspaceid | Your workspace ID | Yes |
| id | The enrichment id to get | Yes |
GET /enrichments/list
Query Parameters:
| Name | Description | Required |
|---|---|---|
| workspaceid | Your workspace ID | Yes |
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:
| Name | Description | Required |
|---|---|---|
| workspaceid | Your workspace ID | Yes |
| id | The id of the enrichment to delete | Yes |