# 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)