test fixes and new product advisories work

2026-01-28 02:30:48 +02:00
parent 82caceba56
commit 644887997c
288 changed files with 69101 additions and 375 deletions
--- a/docs/reachability/README.md
+++ b/docs/reachability/README.md
@@ -0,0 +1,128 @@
+# 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)