Tracing Event Filtering¶

$ sudo ./dist/tracee-ebpf --trace help
$ sudo ./dist/tracee-ebpf --trace xxx

Tracing output might become too hard to consume when tracing all the events from a system. Luckily, Tracee has a powerful mechanism to accurately trace just the information that is relevant to the user, the --trace flag.

With --trace command line flag you define expressions that tells tracee-ebpf what you are interested in based on event metadata filtering capabilities. Only events that match given criteria will be traced.

Tip

You can filter events by most of the visible fields from Tracee events.

Initial Example¶

All the examples bellow this item can be executed with the following tracee-ebpf prefix command:

$ sudo ./dist/tracee-ebpf \
    --output json \
    --trace comm=bash \
    --trace follow
    --output option:parse-arguments \
    <rest of filters>

This will allow you to test the filtering rules by executing a new process in any running shell and might serve as a good indicative if your filter works as expected.

Filters and Operators¶

Event (Operators: =, != and "follow". Prefix/Suffix: *)
```
1) --trace event=openat
2) --trace event=execve,open
3) --trace event=open*
4) --trace event!=open*,dup*
5) --trace follow
```
Note

The "follow" operator will make tracee to follow all newly created processes, that are being filtered for, childs.

Event Arguments (Operators: =, !=. Prefix/Suffix: *)

1) --trace event=openat --trace openat.pathname=/etc/shadow
2) --trace event=openat --trace openat.pathname=/tmp*
3) --trace event=openat --trace openat.pathname!=/tmp/1,/bin/ls

Note

Multiple values are ORed if used with = operator
But ANDed if used with any other operator.

Event Return Code (Operators: =, !=, <, >)

1) --trace event=openat --trace openat.pathname=/etc/shadow --trace "openat.retval>0"
2) --trace event=openat --trace openat.pathname=/etc/shadow --trace "openat.retval<0"

Tip

Try cat /etc/shadow as a regular use and filter for retval<0.

Event Sets (Operators: =, !=)
```
1) --trace set=fs
2) --trace set=lsm_hooks,network_events
```
Note

Selects a set of events to tracee according to pre-defined sets which can be listed by using --list command line argument.

Container (Operators: =, != and "new". Boolean)

1) --trace container # all container events
2) --trace '!container' # events from the host only
3) --trace container=new # containers created after tracee-ebf execution
4) --trace container=3f93da58be3c --trace event=openat
5) --trace container=new --trace event=openat --trace openat.pathname="/etc/shadow"

Note

The new flag allows to trace newly created containers only.

Command (Operators: =, !=)
```
1) --trace comm=cat,vim,ping
2) --trace comm!=ping
```
Note

Do not use given command prefix for these examples as they're filtering by command name as well.

PID (Operators: =, !=, <, > and "new")

1) --trace pid=new # newly created events (after tracee-ebpf execution)
2) --trace pid=510,1709 # # pids 510 and 1709
3) --trace 'pid>0' --trace pid 'pid<1000'
4) --trace pid=2578238 --trace event=openat --trace openat.pathname=/etc/shadow --trace follow

Process Tree

1) --trace tree=476165 # events descending from process 476165
2) --trace tree!=5023 # events that do not descend from process 5023

UID (Operators: =, !=, <, >)

1) --trace uid=0
2) --trace 'uid>0'
3) --trace 'uid>0' --trace uid!=1000 # do not trace root and uid=1000

Network Interface

1) -trace comm=nc,ping -trace event=net_packet -trace net=docker0
2) -trace event=dns_request,dns_response -trace net=docker0

Attention

Do not forget to provide the interface to be traced with "net=name"

UTS Namespace (hostnames) (Operators: =, !=)
```
1) --trace uts!=ab356bc4dd554 
```
PID Namespace (Operators: =, !=, <, >)
```
1) --trace pidns!=4026531836
```
MOUNT Namespace (Operators: =, !=, <, >)
```
1) --trace mntns=4026531840
```