diff --git a/tracee-rules/Readme.md b/tracee-rules/Readme.md new file mode 100644 index 00000000000..4eb47fd29dd --- /dev/null +++ b/tracee-rules/Readme.md @@ -0,0 +1,60 @@ +![Tracee Logo](images/tracee.png) + +# Tracee-Rules: Runtime security detection engine + +> Note: This is a new component for Tracee that is still under development + +Tracee-Rules is a rule engine that helps you detect suspicious behavioral patterns in streams of events. It is primarily made to leverage events collected with Tracee-eBPF into a Runtime Security solution. +There are 3 basic concepts for Tracee-Rules: +1. Inputs - Event sources to be processed. Currently only Tracee-eBPF is a supported event source. +3. Rules - (a.k.a Signatures) The particular behavioral pattern to detect in the input source. Signatures can be authored in Golang, or Rego (OPA). +2. Outputs - How to communicate detections. Print to stdout, post to a webhook, or integrate with external systems. + +# Getting started + +Prerequisites: +- Follow the [Tracee-eBPF](../tracee-ebpf/Readme.md#Getting-Started) guide to make sure you can run tracee-ebpf. + +Getting Tracee-Rules: +Currently you need to build from source. `cd tracee-rules && make` will build the executable as well as all built-in signatures into the local `dist` directory. + +Running with Tracee-eBPF: + +```bash +sudo tracee-ebpf -o format:gob -o option:eot | tracee-rules --tracee-file /dev/stdin +``` + +This will: +1. Start `tracee-ebpf` with the default tracing mode (see [Tracee-eBPF](../tracee-ebpf)'s help for more filtering options). +2. Configure Tracee-eBPF to output events into stdout as [gob](https://golang.org/pkg/encoding/gob/) format, and add a terminating event to signal end of stream. +3. Start `tracee-rules` with all built-in rules enabled. + +# Integrations + +When a detection is made by any of the signatures, it will be printed to stdout. Using the `--webhook` flag you can post detections into an HTTP endpoint that can further relay the detection. + +# Rules +Rules are discovered from the local `rules` directory (unless changed by the `--rules-dir` flag). By default, all discovered rules will be loaded unless specific rules are selected using the `--rules` flag. + +## Authoring Rules +Tracee-Rules supports authoring rules in Golang or in Rego (the language of Open Policy Agent). + +### Rego Rules +Create a `.rego` file in the rules directory that has the following Rego Rules (in this context rules are Rego's language constructs): + +1. `__rego_metadoc__`: A *document* rule that defines the rule's metadata (based on [WIP Rego convention](https://hackmd.io/@ZtQnh19kS26YiNlJLqKJnw/H1gAv5nB) for describing policy metadata). +2. `tracee_selected_events`: A *set* rule that defines the event selectors. +3. `tracee_match`: A *boolean* or a *document* rule that defines the logic of the signature. If bool is "returned", a true evaluation will generate a Finding with no data if document is "returned", any non-empty evaluation will generate a Finding with the returned document as the Finding's "Data". + +See [example2.rego](/rules/rego/example2.rego) and [example1.rego](/rules/rego/example1.rego) for example Rego signatures. + +### Go rules +Tracee-Rules exports a `Signature` interface that you can implement. We use [Go Plugins](https://golang.org/pkg/plugin/) to load Go signatures. + +1. Create a new Go project with a package `main` +2. Import `github.com/aquasecurity/tracee/tracee-rules/types` and implement the `types.Signature` interface. +3. Export a package level variable called `ExportedSignatures` of type `[]types.Signature` that declares the implemented signature (or more) that your package exports. +4. Compile using goplugins `go build -buildmode=plugin -o yourplugin.so yoursource.go`. +5. Place the resulting compiled file in the rules directory and it will be automatically discovered by Tracee-Rules. + +See [example.go](/rules/golang/example.go) for example Go signatures.