kestrel

Die Sichtbarkeit auf Kernel-Ebene von Falco, mit der Live-Oberfläche, die kernel-native Werkzeuge nicht mitbringen.

Schnellstart · Spezifikation · Ansichten · Roadmap

Kestrel verfolgt Kernel-Ereignisse (Prozess-Exec, Dateizugriff, Netzwerkverbindungen) mit einem eBPF-Agenten und streamt sie an eine SvelteKit-Web-App, die einen Live-Aktivitätsfeed, Prozessbaum, Host-Übersicht und eine regelbasierte Alarm-Engine rendert. Siehe SPEC.md für das vollständige Produkt-/Architekturdokument und AGENTS.md für die Betriebsanleitung.

Warum es das gibt

Das eBPF-Ökosystem ist auf Backend/CLI/Kubernetes-Operator ausgelegt. Falco — der von der CNCF graduierte Standard — bringt bekanntermaßen keine eigene UI mit. Die Lücke zwischen „der Kernel liefert reichhaltige Daten" und „ein Mensch kann sie tatsächlich lesen" ist der Full-Stack-Sweet-Spot, in dem dieses Projekt lebt. Bewusst Single-Host (nicht Kubernetes) und nur beobachtend (kein Enforcement) in v1.

Architektur

flowchart TB
    subgraph host["Linux host · VM in dev, VPS in prod · kernel ≥ 5.8"]
        direction TB
        probes["eBPF probes (C)<br/>execve · openat · connect"]
        agent["Go agent — cilium/ebpf<br/>decode · enrich · batch"]
        ingest["/api/ingest<br/>Zod-validated at the boundary"]
        rules["rule engine"]
        hub["live hub"]
        db[("Postgres<br/>events · rules · alerts")]
        dash["SvelteKit dashboard<br/>live feed · tree · overview"]

        probes -- "ring buffer" --> agent
        agent -- "HTTP POST · JSON (Zod contract)" --> ingest
        ingest --> db
        ingest --> rules
        ingest --> hub
        hub -- "SSE" --> dash
    end

Die zentrale Deployment-Einschränkung: Der Agent benötigt einen echten Kernel, daher kann er nicht auf Cloudflare Workers laufen (V8-Isolate, kein Kernel). v1 betreibt Agent + App + Postgres auf einem einzigen Host. Siehe SPEC.md §2.

Repository-Struktur

Status

Phase 3 — in Arbeit. Die Must-haves aus Phase 2 (Live-Feed, Prozessbaum, Host- Übersicht) sind vollständig und live in der VM verifiziert: Der eBPF-Agent (execve + exit, cilium/ebpf) verfolgt einen echten Kernel und streamt Ereignisse an die App, wobei er den Baum beim Start mit einem /proc-Snapshot befüllt. Bisher in Phase 3: Der Agent hat Probes für Dateiöffnen (openat) und ausgehende Verbindungen (security_socket_connect) erhalten (kompilierverifiziert; Lasttest in der VM ausstehend), und die Netzwerk-Karte (8.3) ist gebaut — ein D3-Kraftdiagramm (force-directed) als Prozess↔Ziel-Graph. Als Nächstes: der Monitor für sensible Dateien (8.4) und die Regel-Engine mit Alarmen (8.5). Die Arbeit an den Probes bleibt in der Dev-VM, niemals auf dem Host.

Dashboard-Ansichten

Tiefe bei wenigen Ansichten schlägt oberflächliche Breite — sechs klare Ansichten, in Prioritätsreihenfolge gebaut (Must-haves zuerst).

Roadmap

• Phase 1 (App): Event-Schema · Ingest · SSE-Hub · Live-Feed · Tests
• Phase 1 (Agent): execve-Probe → Ringbuffer → cilium/ebpf → /api/ingest (in der VM)
• Phase 2: exit-Probe + /proc-Snapshot · Prozessbaum · Host-Übersicht
• [~] Phase 3: ✅ Datei- + Verbindungs-Probes · ✅ Netzwerk-Karte · ◻️ Datei-Monitor · ◻️ Regel-Engine + Alarme · ◻️ serverseitiger Prozessbaum-Cache · ◻️ Property- und Event-Delivery-Tests
• Phase 4: Nix-Dev-VM · nixosTest-Kernel-Integrationstest · GitHub-Actions-CI
• Phase 5: VPS-Deployment (Terraform), Agent + App + Postgres auf einem Host
• Phase 6 (Stretch-Ziel): Timeline/Verlauf · LLM „diesen Alarm erklären" · Enforcement · Multi-Host · k8s-DaemonSet

App ausführen (dev)

cd app
pnpm install
pnpm dev            # http://localhost:5173

Die App läuft auf dem Host; der Agent läuft in der Dev-VM und liefert Ereignisse an sie. Um ohne den Agenten einen gefüllten Feed zu sehen, kann man den synthetischen Generator aktivieren: KESTREL_SYNTHETIC=1 pnpm dev.

pnpm check          # svelte-check (Typen)
pnpm test           # vitest — Schema- und Ingest-Unit-Tests
pnpm build          # Produktions-Build (adapter-node)

Die Dev-/Test-Datenbank ist PGlite (Postgres, zu WASM kompiliert): kein nativer Build, kein separater Server, derselbe SQL-Dialekt wie der Produktions-Postgres. Sie persistiert nach app/kestrel-pgdata/ (gitignored); Tests verwenden eine ephemere In-Memory-Datenbank.

Die Pipeline von Hand ausprobieren

# Ereignisse streamen (in einem Terminal laufen lassen)
curl -N http://localhost:5173/api/stream

# Ein Ereignis posten (in einem anderen) — erscheint live im Stream und im Browser
curl -X POST http://localhost:5173/api/ingest -H 'content-type: application/json' \
  -d '[{"host":"demo","type":"exec","pid":42,"comm":"bash","cmdline":"bash -i"}]'

Tests & Verifikation

Drei Ebenen, passend dazu, wo jede Klasse von Fehlern lebt (Details in SPEC.md §6–§7):

• eBPF-Verifier — kostenlos. Der Kernel beweist für jede Probe, dass sie speichersicher, beschränkt und terminierend ist, bevor er sie lädt — der riskanteste Code im System, zur Ladezeit ohne Aufwand verifiziert.
• Property-basierte Tests (Phase 3). fast-check treibt den Zod-Event-Vertrag mit adversarischen/fehlerhaften Ereignissen und stellt Regel-Engine-Invarianten sicher: keine Fehlmatches, deterministische Ergebnisse, fehlerhafte Eingaben werden an der Grenze abgewiesen.
• Korrektheit der Ereigniszustellung (Phase 3). Sequenznummern pro Ereignis + ein Client- Lücken-/Duplikaterkennung + ein Ingest-Flut-Test stellen sicher, dass jedes Ereignis Ingest → SSE genau einmal durchläuft. (Ein formales TLA+-Modell wurde erwogen und bewusst zurückgestellt — bei Single-Host-Volumen nicht gerechtfertigt.)

Aktuell: Vitest-Units (Schema, Ingest, Übersicht, Prozessbaum, Netzwerk-Graph) + der procscan-Parser des Agenten und die Event-decode-Helfer. Führe pnpm test in /app und go test ./... in /agent aus.

Design-Kompromisse

• Single-Host vs. Cluster — bewusste Scope-Entscheidung; Multi-Host ist weit entfernt (SPEC.md §8.11).
• Nur beobachten vs. Enforcement — v1 beendet niemals Prozesse; die Risikohürde für Inline-Blocking ist viel höher (SPEC.md §8.10).
• cilium/ebpf vs. libbpfgo — reines Go, CGO_ENABLED=0, bpf2go-Workflow.
• PGlite/Postgres vs. SQLite vs. ClickHouse — überall Postgres-Dialekt; bis ~1 Mio. Ereignisse gut, darüber hinaus ClickHouse erneut prüfen (SPEC.md §10).
• Verifikation kostenlos — der eBPF-Verifier beweist statisch, dass jede Probe speichersicher, beschränkt und terminierend ist, bevor der Kernel sie lädt. Der riskanteste Code im System wird zur Ladezeit kostenlos verifiziert (SPEC.md §6).