kestrel

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

Pfad	Inhalt
/app	SvelteKit-App — Event-Schema, Ingest, SSE-Hub, Dashboard-Ansichten. Gebaut & lauffähig.
/agent	Go-Userspace-Agent + eBPF-C-Probes (execve/exit/openat/connect) + /proc-Snapshot. Gebaut; läuft nur in der VM.
/infra	Nix-Dev-VM (gebaut) + nixosTest, Terraform/libvirt-Provisionierung (Phase 4).
SPEC.md	Maßgebliche Produkt- & Architekturspezifikation.

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

Ansicht	Die Frage, die sie beantwortet	Status
Live-Aktivitätsfeed (8.1)	Was passiert gerade?	✅ gebaut
Prozessbaum (8.2)	Was hat was gestartet?	✅ gebaut
Host-Übersicht (8.6)	Status auf einen Blick?	✅ gebaut
Netzwerk-Karte (8.3)	Mit wem spricht dieser Host?	✅ gebaut
Monitor für sensible Dateien (8.4)	Hat irgendetwas die wichtigen Dateien berührt?	◻️ geplant
Alarme & Regeln (8.5)	Sag mir Bescheid, wenn etwas verdächtig aussieht.	◻️ geplant

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