# cilium/tetragon architecture

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

- Interactive diagram: https://gitdiagram.com/cilium/tetragon
- Repository: https://github.com/cilium/tetragon

## Overview

##### Core Components (Top Level)

a. Tetragon Agent (Central Component):
- As the main controller component
- To both kernel space and user space components
- Observer and sensor management subsystems

b. eBPF Programs Layer:
- Various sensors (process, network, syscall)
- Connection to kernel hooks
- BPF maps for data sharing

c. User Space Components:
- API server (gRPC)
- Policy engine
- Event processing pipeline
- Metrics exporters

a. Kernel Events Flow:
- eBPF programs → BPF maps
- BPF maps → Tetragon Agent
- Agent → Event Processing
- Event Processing → Exporters/API

b. Control Flow:
- Policy Updates → Policy Engine
- Policy Engine → Sensor Management
- Sensor Management → eBPF Program Loading

##### Integration Points (External Connections)

a. Kubernetes Integration:
- Connection to Kubernetes API
- Pod/Namespace awareness
- Policy CRDs

b. Monitoring Systems:
- Metrics endpoints
- Prometheus integration
- Health checking

a. Sensor Management:
- Process execution tracking
- System call monitoring
- Network activity observation
- File access tracking

b. Policy Enforcement:
- TracingPolicy handling
- Runtime enforcement rules
- Filter management

##### Component Details

Labels for key features:
- Process lifecycle monitoring
- Security event detection
- Runtime enforcement
- Kubernetes awareness
- eBPF program management

##### Operational Flows

Main operational paths:
- Event generation and processing
- Policy application and enforcement
- Monitoring and alerting
- Configuration management

##### eBPF Integration
- Clear separation between kernel and user space
- BPF program attachment points
- Map usage for data sharing

##### Kubernetes Integration
- CRD handling
- Pod awareness
- Namespace filtering

##### Security Context
- Privilege boundaries
- Enforcement points
- Security policy flow

##### Scalability Aspects
- Parallel processing paths
- Buffering mechanisms
- Load distribution

- Real-time security observability
- eBPF-based implementation
- Kubernetes integration
- Policy-based enforcement
- Rich event metadata

This will provide a clear understanding of how Tetragon operates as a security observability and enforcement system while maintaining accuracy to its actual implementation.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Kernel
        ebpf[eBPF Programs]:::kernel
        bpfmaps[BPF Maps]:::kernel
        khooks[Kernel Hooks]:::kernel
    end

    subgraph Agent
        tetragon[Tetragon Agent]:::agent
        observer[Observer]:::agent
        sensorMgr[Sensor Manager]:::agent
    end

    subgraph EventProcessing
        eventHandler[Event Handler]:::processing
        eventExporter[Event Exporter]:::processing
        metrics[Metrics Exporter]:::processing
    end

    subgraph PolicyManagement
        policyEngine[Policy Engine]:::policy
        tracingPolicy[Tracing Policy]:::policy
        filters[Filters]:::policy
    end

    subgraph Sensors
        processSensor[Process Sensor]:::sensor
        networkSensor[Network Sensor]:::sensor
        securitySensor[Security Sensor]:::sensor
    end

    subgraph Kubernetes
        k8sAPI[Kubernetes API]:::k8s
        policycrds[Policy CRDs]:::k8s
    end

    subgraph Monitoring
        prometheus[Prometheus]:::monitoring
        healthCheck[Health Check]:::monitoring
    end

    %% Core Connections
    khooks --> ebpf
    ebpf --> bpfmaps
    bpfmaps --> observer
    observer --> tetragon
    tetragon --> eventHandler
    eventHandler --> eventExporter
    eventHandler --> metrics

    %% Policy Flow
    policyEngine --> sensorMgr
    tracingPolicy --> policyEngine
    filters --> policyEngine
    sensorMgr --> ebpf

    %% Sensor Management
    sensorMgr --> processSensor
    sensorMgr --> networkSensor
    sensorMgr --> securitySensor

    %% Kubernetes Integration
    k8sAPI --> policycrds
    policycrds --> tracingPolicy

    %% Monitoring
    metrics --> prometheus
    tetragon --> healthCheck

    %% Styles
    classDef kernel fill:#000033,color:white
    classDef agent fill:#0066cc,color:white
    classDef processing fill:#ff9933,color:white
    classDef policy fill:#00cc66,color:white
    classDef sensor fill:#cc6699,color:white
    classDef k8s fill:#3399ff,color:white
    classDef monitoring fill:#999999,color:white

    %% Click Events
    click tetragon "https://github.com/cilium/tetragon/blob/main/cmd/tetragon/main.go"
    click observer "https://github.com/cilium/tetragon/blob/main/pkg/observer/observer.go"
    click sensorMgr "https://github.com/cilium/tetragon/blob/main/pkg/sensors/manager.go"
    click eventHandler "https://github.com/cilium/tetragon/blob/main/pkg/eventhandler/eventhandler.go"
    click eventExporter "https://github.com/cilium/tetragon/blob/main/pkg/exporter/exporter.go"
    click policyEngine "https://github.com/cilium/tetragon/blob/main/pkg/policyfilter/policyfilter.go"
    click tracingPolicy "https://github.com/cilium/tetragon/blob/main/pkg/tracingpolicy/tracingpolicy.go"
    click filters "https://github.com/cilium/tetragon/blob/main/pkg/filters/filters.go"
    click processSensor "https://github.com/cilium/tetragon/blob/main/pkg/process/process.go"
    click networkSensor "https://github.com/cilium/tetragon/blob/main/pkg/reader/network/network.go"
    click securitySensor "https://github.com/cilium/tetragon/blob/main/pkg/sensors/tracing/enforcer.go"
    click metrics "https://github.com/cilium/tetragon/tree/main/pkg/metrics"
    click healthCheck "https://github.com/cilium/tetragon/blob/main/pkg/health/health.go"
    click ebpf "https://github.com/cilium/tetragon/blob/main/bpf/process/bpf_process_event.h"
    click k8sAPI "https://github.com/cilium/tetragon/tree/main/pkg/k8s/client/clientset/versioned"
    click policycrds "https://github.com/cilium/tetragon/blob/main/pkg/k8s/apis/cilium.io/v1alpha1/tracing_policy_types.go"
```
