# aquasecurity/tracee architecture

> Architecture diagram of the GitHub repository aquasecurity/tracee, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aquasecurity/tracee
- Repository: https://github.com/aquasecurity/tracee

## Overview

##### Main Components
- Kernel eBPF Layer: Represent the eBPF probes that live in the kernel and collect the raw system events. This includes the C files in pkg/ebpf (such as tracee.bpf.c) and supporting header files.
- Loader/Initialization Module: Show the user-space component (in pkg/cmd/initialize and cmd/tracee-ebpf) that loads the eBPF programs into the kernel and sets up callbacks.
- Signature/Rule Engine: Outline the modules in pkg/signatures and pkg/policy (including the tracee-rules command in cmd/tracee-rules) that analyze events against pre-defined security signatures and rules.
- API Layer & External Interfaces: Include the gRPC server (pkg/server/grpc) and the HTTP server (pkg/server/http) as methods to expose processed events and telemetry information. Also note the CLI entrypoints (cmd/tracee variants) for direct tool interaction.
- Container & Kubernetes Integration: Acknowledge the modules under pkg/containers as well as the Kubernetes CRD and helm charts under deploy/helm and deploy/kubernetes. Also include integration points for container runtimes (docker, containerd, crio).
- Observability & Metrics: Indicate support for metrics collection (pkg/metrics) as well as the Prometheus/Grafana dashboard configurations (performance/dashboard) for performance and monitoring.
- Auxiliary Libraries: Recognize supporting modules such as logging (pkg/logger), error formatting (pkg/errfmt), and utility functions (pkg/utils).

##### Relationships and Data Flow
- Flow of raw event data from the eBPF layer to the Event Processing Engine.
- From the event processing block, send the data to both the Signature/Rule Engine (for security analysis) and to the Output/API modules.
- Separate flows from the API/CLI components to external consumers (e.g., CLI dashboard, gRPC clients, HTTP clients).

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the clear separation between the kernel-level (eBPF probes) and the user-level processing components.
- Loose Coupling: Note the independent modules in the policy/signature engine, event processing, CLI/API, and container integration.
- Extensibility: Identify the “rules” and “signatures” components (tracee-rules and pkg/signatures) that are designed to be extended with minimal impact on the core pipeline.
- Integration with External Tools: Show how the tool is packaged (via Docker, Helm charts), thus reinforcing the “cloud-native” design for container and Kubernetes environments.

##### Relevant Technologies, Frameworks, or Libraries
- Go (Golang) as the main programming language.
- eBPF via Linux for kernel-level event collection.
- gRPC and HTTP for API servers.
- Helm charts and Kubernetes manifests for deployment.
- Docker for containerized execution.
- Prometheus and Grafana for observability and performance dashboards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Tracee Architecture"
        Kernel["Kernel eBPF Probes (pkg/ebpf)"]:::kernel
        Loader["Loader/Initialization (pkg/cmd/initialize, cmd/tracee-ebpf)"]:::user
        EventEngine["Event Collection & Processing (pkg/events, pkg/bufferdecoder, pkg/ebpf/events_pipeline, pkg/filters)"]:::user
        SigEngine["Signature/Rule Engine (pkg/signatures, pkg/policy, cmd/tracee-rules)"]:::user
        API["API & CLI (pkg/server/grpc, pkg/server/http, cmd/tracee)"]:::api
        Integration["Container & Kubernetes Integration (pkg/containers, deploy/helm, deploy/kubernetes)"]:::integration
        Observability["Observability & Metrics (pkg/metrics, performance/dashboard)"]:::integration
        Aux["Auxiliary Libraries (pkg/logger, pkg/errfmt, pkg/utils)"]:::aux
    end

    Kernel -->|"loads_probes"| Loader
    Loader -->|"initiates_event_capture"| EventEngine
    EventEngine -->|"sends_events"| SigEngine
    EventEngine -->|"outputs_data"| API
    SigEngine -->|"alerts_analysis"| API
    API -->|"serves_clients"| Integration
    API -->|"streams_metrics"| Observability

    Integration ---|"integrates_with_Docker_K8s"| ExternalSystems[External Systems]
    Observability ---|"dashboards"| ExternalMonitoring[External Monitoring]

    Aux -.->|"supports"| EventEngine
    Aux -.->|"supports"| SigEngine

    click Kernel "https://github.com/aquasecurity/tracee/tree/main/pkg/ebpf"
    click Loader "https://github.com/aquasecurity/tracee/tree/main/pkg/cmd/initialize"
    click Loader "https://github.com/aquasecurity/tracee/blob/main/cmd/tracee-ebpf/main.go"
    click EventEngine "https://github.com/aquasecurity/tracee/tree/main/pkg/events"
    click EventEngine "https://github.com/aquasecurity/tracee/tree/main/pkg/bufferdecoder"
    click EventEngine "https://github.com/aquasecurity/tracee/blob/main/pkg/ebpf/events_pipeline.go"
    click EventEngine "https://github.com/aquasecurity/tracee/tree/main/pkg/filters"
    click SigEngine "https://github.com/aquasecurity/tracee/tree/main/pkg/signatures"
    click SigEngine "https://github.com/aquasecurity/tracee/tree/main/pkg/policy"
    click SigEngine "https://github.com/aquasecurity/tracee/blob/main/cmd/tracee-rules/main.go"
    click API "https://github.com/aquasecurity/tracee/tree/main/pkg/server/grpc"
    click API "https://github.com/aquasecurity/tracee/tree/main/pkg/server/http"
    click API "https://github.com/aquasecurity/tracee/blob/main/cmd/tracee/main.go"
    click Integration "https://github.com/aquasecurity/tracee/tree/main/pkg/containers"
    click Integration "https://github.com/aquasecurity/tracee/tree/main/deploy/helm"
    click Integration "https://github.com/aquasecurity/tracee/tree/main/deploy/kubernetes"
    click Observability "https://github.com/aquasecurity/tracee/tree/main/pkg/metrics"
    click Observability "https://github.com/aquasecurity/tracee/blob/main/performance/dashboard/docker-compose.yml"
    click Aux "https://github.com/aquasecurity/tracee/tree/main/pkg/logger"
    click Aux "https://github.com/aquasecurity/tracee/tree/main/pkg/errfmt"
    click Aux "https://github.com/aquasecurity/tracee/tree/main/pkg/utils"

    classDef kernel fill:#2d2d2d,stroke:#000,stroke-width:2px,color:#fff,shape:hexagon;
    classDef user fill:#1f77b4,stroke:#333,stroke-width:2px,color:#fff;
    classDef api fill:#ff7f0e,stroke:#333,stroke-width:2px,color:#fff;
    classDef integration fill:#2ca02c,stroke:#333,stroke-width:2px,color:#fff;
    classDef aux fill:#9467bd,stroke:#333,stroke-width:2px,color:#fff;
```
