Building from the source

Note

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

1. Supported Architectures

   1. x86_64 (amd64)
   2. aarch64 (arm64)

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

   You might take a look at the following files to understand how to have a building environment:

   1. .github/actions/build-dependencies/action.yaml
   2. packaging/Dockerfile.ubuntu-packaging
   3. packaging/Dockerfile.fedora-packaging

   Those are very good examples for you to replicate a working environment.

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

4. All makefiles have a help target to give you needed instructions

   make help
   

   # environment
   
       $ make env                      # show makefile environment/variables
   
   # build
   
       $ make all                      # build tracee-ebpf, tracee-rules & signatures
       $ make bpf                      # build ./dist/tracee.bpf.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-inst-signatures      # build ./dist/e2e-inst-signatures
       $ make tracee                   # build ./dist/tracee
   
   # clean
   
       $ make clean                    # wipe ./dist/
       $ make clean-bpf                # wipe ./dist/tracee.bpf.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
   

5. Build all targets at once

   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
   

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

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

8. Build a debugable 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 \
      ./cmd/tracee