Custom Rules
The Prequel Platform supports adding custom rules for your organization.
Step 1: Obtain Prequel API Token
Go to API Tokens and create a new API token with the Rules role. Use this token in the API calls below to add your custom rule. Be sure to copy the generated token for later.
export TOKEN=<generated token>
Step 2: Create Rule in CRE Playground
Create your custom rule at https://play.prequel.dev. Refer to the Syntax Reference for more details on writing detection rules.
Step 3: Add the Custom Rule
Save the rule to a file named rule.yaml
and use the following command to add the new rule.
curl -v -XPOST -H "Authorization: Bearer $TOKEN" "https://api-beta.prequel.dev:8080/v1/api/rules" --data-binary @rule.yaml
Example output:
{"rules":[{"name":"","id":"EuEvkAKjKawJ2cbGEJ6atP","hash":"FFp4wmYUUNqdYnukEDdwsUzvr3Qaj3SfSSGCfwtjG1wA"}]}
Additional resources:
Step 4: Add the Data Source
If the custom rule uses a new data source, then you'll need to create it.
A data source definition describes how to automatically identify the service or library in your environment. Prequel will use this definition to automatically attach and execute the rule when the source is discovered.
The definition uses one or more terms in a tree with AND, OR, and NOT operators. This provides a flexible way to describe data sources using common fields like Kubernetes labels, image URLs, container names, etc.
version: 0.0.1
sources:
- name: alloy
type: cre.log.alloy
tree:
term:
# docker.io/grafana/alloy:v1.5.1
type: image
regex: ^.*aws-network-policy-agent.*
- name: AWS EKS Nodeagent
type: cre.log.aws.eks-nodeagent
tree:
term:
# <account>.dkr.ecr.us-west-2.amazonaws.com/amazon/aws-network-policy-agent:v1.1.6-eksbuild.1
type: image
regex: ^.*aws-network-policy-agent.*
The tree
field can use multiple operators and types. Types are matched using regular expressions.
version: 0.0.1
sources:
- name: nats
type: cre.log.nats
desc: Target nats pod
tree:
and:
- term:
type: image
regex: ^.*nats.*
- term:
type: namespace
regex: prequel
- not:
or:
- term:
type: hostname
regex: shrubbery
- term:
type: podName
regex: banana
The following term types are supported:
Term | Description |
---|---|
namespace | Kubernetes namespace |
containerName | the name of the container |
image | the image field within a Pod specification refers to a container image stored in a registry |
imageRef | a reference to a specific, immutable version of that image, typically identified by its content digest |
hostname | the name of the host on which the service is running |
podName | the name of the pod |
podLabel | a label on a pod |
podAnnotation | an annotation on a pod |
label | labels are metadata in the form of key-value pairs that can be attached to any Kubernetes object (not just Pods) |
annotation | annotations are used for attaching non-identifying information like build details or release IDs |
processComm | process executable name |
cmdLine | full process command line and arguments |
To add the new data source, run the following command:
curl -v -XPOST -H "Content-Type: application/yaml" -H "Authorization: Bearer $TOKEN" "https://api-beta.prequel.dev:8080/v1/api/data_sources" --data-binary @data.yaml
Example output:
{"sources":[{"name":"demo-service","type":"cre.log.demo-service"}]}
To see available data sources:
curl -v -XGET -H "Authorization: Bearer $TOKEN" "https://api-beta.prequel.dev:8080/v1/api/data_sources"
Example output:
{
"kpis": {
"version": "",
"total_data_sources": 1,
"prequel_data_sources": 0
},
"data_sources": [
{
"name": "alloy",
"type": "cre.log.demo-service",
"data": "term:\n type: image\n regex: ^.*aws-network-policy-agent.*\n",
"domain": "custom",
"org": "9a4126bd-1dbc-4b39-b4ec-5167cdb815b0"
}
]
}
Additional resources: