kestrel

La visibilità a livello di kernel di Falco, con la UI live che gli strumenti nativi del kernel non includono.

Avvio rapido · Specifica · Viste · Roadmap

Kestrel traccia gli eventi del kernel (esecuzione di processi, accesso ai file, connessioni di rete) con un agente eBPF e li trasmette a un'app web SvelteKit che visualizza un feed di attività in tempo reale, l'albero dei processi, la panoramica dell'host e un motore di alert basato su regole. Vedi SPEC.md per il documento completo di prodotto/architettura e AGENTS.md per la guida operativa.

Perché esiste

L'ecosistema eBPF è modellato su backend/CLI/operator Kubernetes. Falco — lo standard diplomato CNCF — è notoriamente privo di una UI propria. Il divario tra «il kernel emette dati ricchi» e «un essere umano può effettivamente leggerli» è il punto dolce full-stack in cui vive questo progetto. Deliberatamente single-host (non Kubernetes) e solo osservazione (nessuna enforcement) nella v1.

Architettura

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

Il vincolo di distribuzione chiave: l'agente necessita di un kernel reale, quindi non può girare su Cloudflare Workers (isolati V8, nessun kernel). La v1 colloca agente + app + Postgres sullo stesso host. Vedi SPEC.md §2.

Struttura del repository

Stato

Fase 3 — in corso. I must-have della Fase 2 (feed live, albero dei processi, panoramica host) sono completi e verificati live nella VM: l'agente eBPF (execve + exit, cilium/ebpf) traccia un kernel reale e trasmette gli eventi all'app, popolando l'albero con uno snapshot /proc all'avvio. Fase 3 finora: l'agente ha acquisito le sonde di apertura file (openat) e di connessione in uscita (security_socket_connect) (verificate in compilazione; load test in sospeso nella VM), e la mappa di rete (8.3) è stata costruita — un grafo a forze processi↔destinazioni. Prossimo passo: il monitor dei file sensibili (8.4) e il motore di regole + alert (8.5). Il lavoro sulle sonde resta nella VM di sviluppo, mai sull'host.

Viste della dashboard

La profondità su poche viste batte un'ampiezza superficiale: sei viste precise, costruite in ordine di priorità (prima i must-have).

Roadmap

• Fase 1 (app): schema eventi · ingest · hub SSE · feed live · test
• Fase 1 (agente): sonda execve → ring buffer → cilium/ebpf → /api/ingest (nella VM)
• Fase 2: sonda exit + snapshot /proc · albero dei processi · panoramica host
• [~] Fase 3: ✅ sonde file + connect · ✅ mappa di rete · ◻️ monitor file · ◻️ motore di regole + alert · ◻️ cache lato server dell'albero dei processi · ◻️ test di proprietà e consegna eventi
• Fase 4: VM di sviluppo Nix · test di integrazione kernel nixosTest · CI GitHub Actions
• Fase 5: deploy VPS (Terraform), agente + app + Postgres co-ubicati
• Fase 6 (estensione): timeline/storico · LLM «spiega questo alert» · enforcement · multi-host · DaemonSet k8s

Esecuzione dell'app (dev)

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

L'app gira sull'host; l'agente gira nella VM di sviluppo e le invia gli eventi. Per vedere un feed popolato senza l'agente, attiva il generatore sintetico: KESTREL_SYNTHETIC=1 pnpm dev.

pnpm check          # svelte-check (types)
pnpm test           # vitest — schema + ingest unit tests
pnpm build          # production build (adapter-node)

Il database di sviluppo/test è PGlite (Postgres compilato in WASM): nessuna build nativa, nessun server separato, stesso dialetto SQL del Postgres di produzione. Persiste in app/kestrel-pgdata/ (gitignored); i test usano un DB in-memory effimero.

Prova la pipeline manualmente

# stream events (leave running in one terminal)
curl -N http://localhost:5173/api/stream

# post an event (in another) — appears live in the stream and the 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"}]'

Testing e verifica

Tre livelli, abbinati al punto in cui vive ogni classe di bug (dettagli completi in SPEC.md §6–§7):

• Verificatore eBPF — gratuito. Il kernel dimostra che ogni sonda è memory-safe, limitata e terminante prima di caricarla: il codice più rischioso del sistema, verificato al momento del caricamento senza alcun costo.
• Test basati su proprietà (Fase 3). fast-check guida il contratto eventi Zod con eventi avversari/malformati e verifica gli invarianti del motore di regole: nessun falso match, verdetti deterministici, input malformati respinti al confine.
• Correttezza della consegna eventi (Fase 3). Numeri di sequenza per evento + un rilevatore lato client di buchi/duplicati + un test di ingest flood verificano che ogni evento attraversi ingest → SSE esattamente una volta. (Un modello formale TLA+ è stato preso in considerazione e deliberatamente rimandato — non giustificato a volumi single-host.)

Oggi: unit test Vitest (schema, ingest, panoramica, albero dei processi, grafo di rete) + il parser procscan dell'agente e gli helper decode degli eventi. Esegui pnpm test in /app, go test ./... in /agent.

Compromessi progettuali

• Single-host vs cluster — scelta di scope deliberata; multi-host è un obiettivo molto lontano (SPEC.md §8.11).
• Solo osservazione vs enforcement — la v1 non uccide mai i processi; l'asticella del rischio per il blocco inline è molto più alta (SPEC.md §8.10).
• cilium/ebpf vs libbpfgo — Go puro, CGO_ENABLED=0, workflow bpf2go.
• PGlite/Postgres vs SQLite vs ClickHouse — dialetto Postgres ovunque; ok fino a ~1M di eventi, rivalutare ClickHouse oltre (SPEC.md §10).
• Verifica gratuita — il verificatore eBPF dimostra staticamente che ogni sonda è memory-safe, limitata e terminante prima che il kernel la carichi. Il codice più rischioso del sistema è verificato al caricamento a costo zero (SPEC.md §6).