129 lines
7.5 KiB
Markdown
129 lines
7.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
# 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](ebpf-architecture.md) | System design and data flow |
|
|
| [evidence-schema.md](evidence-schema.md) | NDJSON schema reference |
|
|
| [probe-reference.md](probe-reference.md) | Tracepoint and uprobe details |
|
|
| [deployment-guide.md](deployment-guide.md) | Kernel requirements and installation |
|
|
| [operator-runbook.md](operator-runbook.md) | Operations and troubleshooting |
|
|
| [security-model.md](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 │ │
|
|
│ └──────────────┘ └────────────────┘ └──────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Signals Module Architecture](../modules/signals/architecture.md)
|
|
- [Evidence Schema Conventions](../11_DATA_SCHEMAS.md)
|
|
- [Zastava Container Tracking](../modules/zastava/architecture.md)
|