tracee-ebpf

README

Tracee-eBPF: Linux Tracing and Forensics using eBPF

In some cases, you might want to leverage Tracee's eBPF event collection capabilities directly, without involving the detection engine. This might be useful for debugging/troubleshooting/analysis/research/education. In this case you can use Tracee's eBPF collector component, which will start dumping raw data directly into standard output.

Watch a quick video demo of Tracee's eBPF tracing capabilities

Documentation

The full documentation of Tracee's eBPF tracing is available at https://aquasecurity.github.io/tracee/dev/tracee-ebpf/. You can use the version selector on top to view documentation for a specific version of Tracee.

Quickstart

Before you proceed, make sure you follow the minimum requirements for running Tracee.

docker run --name tracee --rm --pid=host --cgroupns=host --privileged -v /tmp/tracee:/tmp/tracee -it aquasec/tracee:latest trace

Here we are running the same aquasec/tracee container, but with the trace sub-command, which will start just a raw trace (Tracee-eBPF), without the detection engine (Tracee-Rules). Here's a sample output of running with no additional arguments:

TIME(s)        UID    COMM             PID     TID     RET             EVENT                ARGS
176751.746515  1000   zsh              14726   14726   0               execve               pathname: /usr/bin/ls, argv: [ls]
176751.746772  1000   zsh              14726   14726   0               security_bprm_check  pathname: /usr/bin/ls, dev: 8388610, inode: 777
176751.747044  1000   ls               14726   14726  -2               access               pathname: /etc/ld.so.preload, mode: R_OK
176751.747077  1000   ls               14726   14726   0               security_file_open   pathname: /etc/ld.so.cache, flags: O_RDONLY|O_LARGEFILE, dev: 8388610, inode: 533737
...

Each line is a single event collected by Tracee-eBPF, with the following information:

1. TIME - shows the event time relative to system boot time in seconds
2. UID - real user id (in host user namespace) of the calling process
3. COMM - name of the calling process
4. PID - pid of the calling process
5. TID - tid of the calling thread
6. RET - value returned by the function
7. EVENT - identifies the event (e.g. syscall name)
8. ARGS - list of arguments given to the function

Use the --help flag to see a full description of available options. Some flags has specific help sections that can be accessed by passing help to the flag, for example --output help. This section covers some of the more common options.

Getting Tracee-eBPF

You can obtain Tracee-eBPF in any of the following ways:

1. Download from the GitHub Releases (tracee.tar.gz).
2. Use the docker image from Docker Hub: aquasec/tracee with the trace sub-command.
3. Build the executable from source using make build. For that you will need additional development tooling.
4. Build the executable from source in a Docker container which includes all development tooling, using make build DOCKER=1.

All of the other setup options and considerations listed under Tracee's Installation section applies to Tracee-eBPF as well.