Skip to content

Getting Started with Detecting

Tracee is a runtime security detection engine, more than an introspection tool (tracee-ebpf) only. tracee-rules is a rules 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.


You may sometimes read rules or signatures. Both mean the same thing for tracee: a set of expressions that will define whether there was a security event detection or not.

There are 3 basic concepts for tracee-rules:

  1. Inputs - Event sources to be processed.

    1. tracee-ebpf only current supported ource
  2. Rules (a.k.a Signatures) - behavioral pattern to detect from the input source. Signatures can be authored in:

    1. Golang (high performance, more error prone)
    2. Rego (OPA) (high level declarative language)
    3. Go-Cel (tech-preview) (good performance, simple)
  3. Outputs - How to communicate detections:

    1. Print to stdout
    2. Post to a webhook
    3. Integrate with external systems

Getting Started

tracee-rules doesn't have any requirement, but in order to run with tracee-ebpf, make sure you follow the tracee-ebpf prerequisites.


You can't customize (yet) tracee-rules execution when executing official tracee container. The official container is configured with a pre-set of signatures already enabled by default. In order to customize it you have to follow building/ instructions and change the default entrypoint and signatures.

Check getting tracee in order to understand how to obtain tracee-rules.

Running tracee-rules

  1. Running tracee-rules with trace-ebpf in the simplest possible way:

    sudo ./dist/tracee-ebpf \
        -o format:gob \
        | tracee-rules \
        --input-tracee file:stdin \
        --input-tracee format:gob

    This will:

    1. Start tracee-ebpf with the default tracing mode (default events).
    2. Configure tracee-ebpf to output events into stdout as gob format.
    3. Start tracee-rules with all built-in signatures enabled.
  2. A more realistic example


Let's put together all that we learned from the tracing section, together with what we're learning at this section and see how we can trace events and pipe them to tracee-rules so detections occur:

$ sudo ./dist/tracee-ebpf \
    --output json \
    --trace comm=bash \
    --trace follow \
    --output option:detect-syscall \
    --output option:parse-arguments \
    --trace event=$(./dist/tracee-rules --list-events) \
    | ./dist/tracee-rules \
    --input-tracee format:json \
    --input-tracee file:stdin

Loaded 14 signature(s): [TRC-1 TRC-13 TRC-2 TRC-14 TRC-3 TRC-11 TRC-9 TRC-4 TRC-5 TRC-12 TRC-6 TRC-10 TRC-7 TRC-15]

We are:

  1. tracing all executed commands from all existing and new bash processes,
  2. detecting syscalls that generated each event (if they're not syscalls),
  3. parsing captured event arguments into a human readable format,
  4. filtering for ALL events needed by all existing signatures,
  5. detecting behaviors described in all existing and loaded tracee-rules signatures.

Selecting Signatures

When executing tracee-rules, you're able to select which signatures you would like it to load. Also, in order to make tracee-ebpf only trace for meaningful events (for the loaded signature(s)) you may request from tracee-rules which events are needed for the selected signatures.

  1. List default (all) signatures

    $ ./dist/tracee-rules --list
    Loaded 14 signature(s): [TRC-1 TRC-13 TRC-2 TRC-14 TRC-3 TRC-11 TRC-9 TRC-4 TRC-5 TRC-12 TRC-6 TRC-10 TRC-7 TRC-15]
    ID         NAME                                VERSION DESCRIPTION
    TRC-1      Standard Input/Output Over Socket   0.1.0   Redirection of process's standard input/output to socket
    TRC-13     Kubernetes API server connection detected 0.1.0   A connection to the kubernetes API server was detected. The K8S API server is the brain of your K8S cluster, adversaries may try and communicate with the K8S API server to gather information/credentials, or even run more containers and laterally expand their grip on your systems.
    TRC-2      Anti-Debugging                      0.1.0   Process uses anti-debugging technique to block debugger
    TRC-14     CGroups Release Agent File Modification 0.1.0   An Attempt to modify CGroups release agent file was detected. CGroups are a Linux kernel feature which can change a process's resource limitations. Adversaries may use this feature for container escaping.
    TRC-3      Code injection                      0.1.0   Possible code injection into another process
    TRC-11     Container Device Mount Detected     0.1.0   Container device filesystem mount detected. A mount of a host device filesystem can be exploited by adversaries to perform container escape.
    TRC-9      New Executable Was Dropped During Runtime 0.1.0   An Executable file was dropped in your system during runtime. Usually container images are built with all binaries needed inside, a dropped binary may indicate an adversary infiltrated into your container.
    TRC-4      Dynamic Code Loading                0.1.0   Writing to executable allocated memory region
    TRC-5      Fileless Execution                  0.1.0   Executing a process from memory, without a file in the disk
    TRC-12     Illegitimate Shell                  0.1.0   A program on your server spawned a shell program. Shell is the linux command-line program, server programs usually don't run shell programs, so this alert might indicate an adversary is exploiting a server program to spawn a shell on your server.
    TRC-6      kernel module loading               0.1.0   Attempt to load a kernel module detection
    TRC-10     K8S TLS Certificate Theft Detected  0.1.0   Kubernetes TLS certificate theft was detected. TLS certificates are used to establish trust between systems, the kubernetes certificate is used to to enable secured communication between kubernetes components, like the kubelet, scheduler, controller and API server. An adversary may steal a kubernetes certificate on a compromised system to impersonate kuberentes components within the cluster.
    TRC-7      LD_PRELOAD                          0.1.0   Usage of LD_PRELOAD to allow hooks on process
    TRC-15     Hooking system calls by overriding the system call table entries 0.1.0   Usage of kernel modules to hook system calls
  2. List events needed by default (all) signatures

    $ ./dist/tracee-rules --list-events
  3. List events needed for given signatures only


    If we chose to load a single signature, we can ask tracee-rules to give us the events needed by that signature. This will allow tracee-ebpf to just listen to those events.

    $ ./dist/tracee-rules --rules TRC-3 --list-events

Tracing with Selected Signatures


Let's pretend we would like to pick TRC-2 signature only and monitor all new processes happening as childs of all running bash processes.

$ sudo ./dist/tracee-ebpf --output json --trace comm=bash --trace follow --output option:detect-syscall --output option:parse-arguments --output option:exec-env --trace event=$(./dist/tracee-rules --rules TRC-2 --list-events) | ./dist/tracee-rules --input-tracee format:json --input-tracee file:stdin --rules TRC-2
Loaded 1 signature(s): [TRC-2]

*** Detection ***
Time: 2022-07-09T21:42:45Z
Signature ID: TRC-2
Signature: Anti-Debugging
Data: map[]
Command: strace
Hostname: fujitsu