Building from the source

Note

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

1. Building dependencies

   1. kernel readers if no CO-RE is needed
   2. clang (12, 13 or 14)
   3. golang (1.19)
   4. libelf and libelf-dev
      (or elfutils-libelf and elfutils-libelf-devel)
   5. zlib1g and zlib1g-dev
      (or zlib and zlib-devel)

2. 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.
   

3. 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 & rules
       $ 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 rules                    # build ./dist/rules
   
   # 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-rules              # wipe ./dist/rules
   
   # test
   
       $ make test-types               # run unit tests for types module
       $ make test-unit                # run unit tests
       $ make test-integration         # run integration tests
       $ make test-rules               # 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
   

4. 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/rules
   GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS= CGO_LDFLAGS= go build \
       --buildmode=plugin \
       -o dist/rules/builtin.so \
       signatures/golang/export.go signatures/golang/kubernetes_api_connection.go signatures/golang/stdio_over_socket.go
   

5. 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
   ...
   

6. 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/rules/builtin.so:
   plugin.Open("/tracee/dist/rules/builtin.so"): Dynamic loading not supported
   

7. 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