eBPF Reachability Evidence System
This documentation covers the eBPF-based runtime reachability evidence collection system in StellaOps.
Overview
The eBPF reachability system provides kernel-level syscall tracing to prove which code paths, files, and network connections were (or weren't) executed in production. This evidence complements static analysis by providing runtime proof of actual behavior.
Key Capabilities
- Syscall Tracing: Capture file access (
openat), process execution (exec), and network connections (inet_sock_set_state) - User-Space Probes: Monitor libc network functions and OpenSSL TLS operations
- Container Awareness: Automatic correlation of events to container IDs and image digests
- Signed Evidence Chains: DSSE-signed chunks with Rekor transparency log integration
- Deterministic Output: Canonical NDJSON format for reproducible evidence
Quick Start
Prerequisites
- Linux kernel 5.x+ with BTF support (4.14+ with external BTF)
- Container runtime (containerd, Docker, or CRI-O)
- StellaOps CLI installed
Enable Runtime Evidence Collection
# Start the runtime signal collector
stella signals start --target /var/lib/stellaops/evidence
# Verify collection is active
stella signals status
# View recent signals
stella signals inspect sha256:abc123...
# Verify evidence chain integrity
stella signals verify-chain /var/lib/stellaops/evidence
Configuration
# stellaops.yaml
signals:
enabled: true
output_directory: /var/lib/stellaops/evidence
rotation:
max_size_mb: 100
max_age_hours: 1
signing:
enabled: true
key_id: fulcio # or KMS key reference
submit_to_rekor: true
filters:
target_containers: [] # Empty = all containers
path_allowlist:
- /etc/**
- /var/lib/**
path_denylist:
- /proc/**
- /sys/**
Documentation Index
| Document | Description |
|---|---|
| ebpf-architecture.md | System design and data flow |
| evidence-schema.md | NDJSON schema reference |
| probe-reference.md | Tracepoint and uprobe details |
| deployment-guide.md | Kernel requirements and installation |
| operator-runbook.md | Operations and troubleshooting |
| security-model.md | Threat model and mitigations |
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ User Space │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ Zastava │ │ Scanner │ │ RuntimeSignalCollector │ │
│ │ Container │ │ Reachability │ │ │ │
│ │ Tracker │ │ Merger │ │ ┌─────────────────┐ │ │
│ └──────┬──────┘ └──────┬───────┘ │ │ EventParser │ │ │
│ │ │ │ └────────┬────────┘ │ │
│ │ │ │ │ │ │
│ └────────┬───────┘ │ ┌────────▼────────┐ │ │
│ │ │ │ CgroupResolver │ │ │
│ ┌────────▼────────┐ │ └────────┬────────┘ │ │
│ │ RuntimeEvent │ │ │ │ │
│ │ Enricher │◄────────┤ ┌────────▼────────┐ │ │
│ └────────┬────────┘ │ │SymbolResolver │ │ │
│ │ │ └────────┬────────┘ │ │
│ ┌────────▼────────┐ │ │ │ │
│ │ NDJSON Writer │◄────────┼───────────┘ │ │
│ └────────┬────────┘ │ │ │
│ │ └─────────────────────────┘ │
│ ┌────────▼────────┐ │
│ │ ChunkFinalizer │──────► Signer ──────► Rekor │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
──────────┼──────────
│
┌─────────────────────────────┼───────────────────────────────────┐
│ Kernel │Space │
│ │ │
│ ┌──────────────────────────▼───────────────────────────────┐ │
│ │ Ring Buffer │ │
│ └──────────────────────────▲───────────────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌────────┴───────┐ ┌──────────────────┐ │
│ │ Tracepoints │ │ Uprobes │ │ BPF Maps │ │
│ │ │ │ │ │ │ │
│ │ sys_openat │ │ libc:connect │ │ cgroup_filter │ │
│ │ sched_exec │ │ libc:accept │ │ symbol_cache │ │
│ │ inet_sock │ │ SSL_read/write │ │ pid_namespace │ │
│ └──────────────┘ └────────────────┘ └──────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘