Building from the source¶

Note

Consider also visiting the following instructions:
1. docker container as building environment
2. building tracee container images

Building dependencies
1. clang && llvm (12, 13 or 14)
2. golang (1.19)
3. libelf and libelf-dev
  (or elfutils-libelf and elfutils-libelf-devel)
4. zlib1g and zlib1g-dev
  (or zlib and zlib-devel)
5. clang-format-12 (specific version) for fix-fmt
6. kernel readers if no CO-RE is needed
You might take a look at the following files to understand how to have a building environment:
Those are very good examples for you to replicate a working environment.

Clone tracee repository

$ git clone git@github.com:aquasecurity/tracee
Cloning into 'tracee'...
remote: Enumerating objects: 13251, done.
remote: Counting objects: 100% (555/555), done.
remote: Compressing objects: 100% (240/240), done.
remote: Total 13251 (delta 343), reused 369 (delta 280), pack-reused 12696
Receiving objects: 100% (13251/13251), 11.75 MiB | 8.62 MiB/s, done.
Resolving deltas: 100% (8105/8105), done.

All makefiles have a help target to give you needed instrutions

$ make help

# environment

    $ make env                      # show makefile environment/variables

# build

    $ make all                                  # build tracee-ebpf, tracee-rules & signatures
    $ make bpf-core                             # build ./dist/tracee.bpf.core.o
    $ make bpf-nocore                           # build ./dist/tracee.bpf.XXX.o
    $ make tracee-ebpf                          # build ./dist/tracee-ebpf
    $ make tracee-rules                         # build ./dist/tracee-rules
    $ make tracee-bench                         # build ./dist/tracee-bench
    $ make signatures                           # build ./dist/signatures
    $ make e2e-net-signatures                   # build ./dist/e2e-net-signatures
    $ make e2e-instrumentation-signatures       # build ./dist/e2e-instrumentation-signatures
    $ make tracee                               # build ./dist/tracee

# install

    $ make install-bpf-nocore       # install BPF no CO-RE obj into /tmp/tracee
    $ make uninstall-bpf-nocore     # uninstall BPF no CO-RE obj from /tmp/tracee

# clean

    $ make clean                    # wipe ./dist/
    $ make clean-bpf-core           # wipe ./dist/tracee.bpf.core.o
    $ make clean-bpf-nocore         # wipe ./dist/tracee.bpf.XXX.o
    $ make clean-tracee-ebpf        # wipe ./dist/tracee-ebpf
    $ make clean-tracee-rules       # wipe ./dist/tracee-rules
    $ make clean-tracee-bench       # wipe ./dist/tracee-bench
    $ make clean-signatures         # wipe ./dist/signatures
    $ make clean-tracee             # wipe ./dist/tracee

# test

    $ make test-unit                # run unit tests
    $ make test-types               # run unit tests for types module
    $ make test-integration         # run integration tests
    $ make test-signatures          # opa test (tracee-rules)

# flags

    $ STATIC=1 make ...             # build static binaries
    $ BTFHUB=1 STATIC=1 make ...    # build static binaries, embed BTF
    $ DEBUG=1 make ...              # build binaries with debug symbols

Build all targets at once (but bpf-nocore)

$ make all
Submodule 'libbpf' (https://github.com/libbpf/libbpf.git) registered for path '3rdparty/libbpf'
Cloning into '/home/rafaeldtinoco/tracee/3rdparty/libbpf'...
mkdir -p dist/signatures
GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS= CGO_LDFLAGS= go build \
    --buildmode=plugin \
    -o dist/signatures/builtin.so \
    signatures/golang/export.go signatures/golang/kubernetes_api_connection.go signatures/golang/stdio_over_socket.go

Build a static binary by setting STATIC=1

$ STATIC=1 make all
CC="clang" \
    CFLAGS=""-fPIC"" \
    LD_FLAGS="" \
    make \
    -C ./3rdparty/libbpf/src \
    BUILD_STATIC_ONLY=1 \
    DESTDIR=/home/rafaeldtinoco/tracee/dist/libbpf \
    OBJDIR=/home/rafaeldtinoco/tracee/dist/libbpf/obj \
    INCLUDEDIR= LIBDIR= UAPIDIR= prefix= libdir= \
    install install_uapi_headers
...

Build a static binary with BTFHUB Support

$ BTFHUB=1 STATIC=1 make all
Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub'...
remote: Enumerating objects: 205, done.
remote: Counting objects: 100% (16/16), done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 205 (delta 4), reused 10 (delta 3), pack-reused 189
Receiving objects: 100% (205/205), 10.59 MiB | 7.56 MiB/s, done.
Resolving deltas: 100% (73/73), done.
Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub-archive'...
remote: Enumerating objects: 1993, done.
remote: Counting objects: 100% (28/28), done.
remote: Compressing objects: 100% (23/23), done.
Receiving objects:  15% (301/1993), 154.97 MiB | 15.72 MiB/s

Note

BTFHUB support will embed several very small files (BTF files) into your final binary. Those files will allow tracee-ebpf binary to be executed in kernels that doesn't have embedded BTF information (the ones described at the BTFHUB repository)

Attention

compiling tracee-rules with STATIC=1 won't allow you to use golang based signatures as plugins, only as built-ins:

2021/12/13 13:27:21 error opening plugin /tracee/dist/signatures/builtin.so:
plugin.Open("/tracee/dist/signatures/builtin.so"): Dynamic loading not supported

Build a debuggable binary with DWARF generation by setting DEBUG=1

$ DEBUG=1 make
...
GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS="-I/home/gg/code/tracee/dist/libbpf" CGO_LDFLAGS="-lelf  -lz  /home/gg/code/tracee/dist/libbpf/libbpf.a" go build \
    -tags core,ebpf \
    -ldflags=" \
         -extldflags \"\" \
         -X main.version=\"v0.8.0-107-g121efeb\" \
        " \
    -v -o dist/tracee-ebpf \
   ./cmd/tracee-ebpf