Configuring Tracee¶

Tracee has many different options and settings that control how Tracee operates.

To learn about how to apply configuration to Tracee, please refer to the CLI or Kubernetes specific guides, depending on how you deploy Tracee.

A complete config file with all available options can be found here. Most of the options are documented in different sections in the documentation.

NOTE: The YAML examples can be translated to JSON as well

Common configurations¶

Output¶

--output (-o): Controls how and where the output is printed.

NOTE: You can view more in the output section.

YAML:

output:
  - json

Server¶

--server: Sets options for the HTTP and/or gRPC servers.

CLI Examples:

# Address configuration
tracee --server http-address=:3366
tracee --server grpc-address=unix:/var/run/tracee.sock

# HTTP features (boolean flags)
tracee --server metrics --server healthz --server pprof

YAML:

server:
  http-address: ":3366"
  grpc-address: "unix:/var/run/tracee.sock"
  metrics: true
  healthz: true
  pprof: true
  pyroscope: true

Stores (Process Tree and DNS Cache)¶

--stores: Controls process tree and DNS cache options.

NOTE: You can view more in the Process Tree section and DNS Cache section.

YAML:

stores:
  process:
    enabled: true
    source: both
  dns:
    enabled: true

Runtime¶

--runtime (-r): Controls runtime configurations for Tracee.

CLI Examples:

# Set working directory
tracee --runtime workdir=/opt/tracee

YAML:

runtime:
  - workdir=/opt/tracee

NOTE: The workdir is the path where Tracee will install or lookup its resources. The default is /tmp/tracee. This option is useful when running Tracee in environments where /tmp is not suitable or secure.

Log¶

--logging (-l): Controls Tracee logging options, like verbosity, filters, destination file and others.

NOTE: You can view more in the Tracee Logs section.

YAML:

log:
  - level: debug

Containers¶

To enable container enrichment, include the flag: --enrichment container. To disable it, simply omit the flag. Note: Setting any container sub-option (e.g., container.docker.socket=/path) automatically enables container, so --enrichment container is not needed.

YAML:

enrichment:
  container:
    enabled: true

NOTE: You can view more in the enrichment section.

--enrichment: Configures enrichment options including container enrichment and runtime sockets. For example, to configure runtime sockets:

YAML:

enrichment:
  container:
    enabled: true
    cgroupfs:
      path: /host/sys/fs/cgroup
      force: false
    docker-socket: /var/run/docker.sock
    containerd-socket: /var/run/containerd/containerd.sock
    crio-socket: /var/run/crio/crio.sock
    podman-socket: /var/run/podman/podman.sock
  resolve-fd: true
  exec-hash:
    enabled: true
    mode: sha256
  user-stack-trace: true

Capabilities¶

--capabilities (-C): Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs.

NOTE: You can view more in the Tracee Capabilities section

YAML:

capabilities:
  - add: 
      - CAP_SYS_ADMIN
  - drop: 
      - CAP_NET_RAW

NOTE: Capabilities are Linux-specific permissions that control which privileged operations a program can perform.

Buffer and Cache¶

--buffers: Configures the buffer sizes for kernel and user buffers.

Buffer sizes for perf ring buffers (kernel.events, kernel.artifacts, kernel.control-plane) are specified in pages. The pipeline buffer size is specified in event objects. The default size for perf ring buffers is 1024 pages. The default size for the pipeline buffer is 1000 event objects.

YAML:

buffers:
    kernel:
        events: 2048
        artifacts: 1024
        control-plane: 512
    pipeline: 20000

CLI:

--buffers kernel.events=2048 --buffers kernel.artifacts=1024 --buffers kernel.control-plane=512 --buffers pipeline=20000

NOTE: You can view more in the buffers section.