kestrel

Kestrel trace les événements noyau (exécution de processus, accès aux fichiers, connexions réseau) avec un agent eBPF et les diffuse vers une application web SvelteKit qui affiche un flux d'activité en direct, l'arborescence des processus, une vue d'ensemble de l'hôte et un moteur d'alertes basé sur des règles. Voir SPEC.md pour le document complet produit/architecture et AGENTS.md pour le guide opérationnel.

Pourquoi ça existe

L'écosystème eBPF est orienté backend/CLI/opérateur Kubernetes. Falco — le standard diplômé de la CNCF — est célèbre pour ne fournir aucune interface propre. L'écart entre « le noyau émet des données riches » et « un humain peut réellement les lire » est le point idéal full-stack où se situe ce projet. Volontairement monohôte (pas Kubernetes) et observation seule (aucune application de politique) en v1.

Architecture

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

La contrainte de déploiement clé : l'agent a besoin d'un vrai noyau, il ne peut donc pas fonctionner sur Cloudflare Workers (isolats V8, pas de noyau). La v1 co-localise l'agent + l'application + Postgres sur un seul hôte. Voir SPEC.md §2.

Structure du dépôt

Chemin	Contenu
/app	Application SvelteKit — schéma d'événements, ingestion, hub SSE, vues du tableau de bord. Compilée et exécutable.
/agent	Agent Go en espace utilisateur + sondes eBPF en C (execve/exit/openat/connect) + instantané /proc. Compilé ; ne s'exécute que dans la VM.
/infra	VM de dev Nix (construite) + nixosTest, provisionnement Terraform/libvirt (phase 4).
SPEC.md	Spécification produit et architecture de référence.

État

Phase 3 — en cours. Les indispensables de la phase 2 (flux en direct, arborescence des processus, vue d'ensemble de l'hôte) sont terminés et vérifiés en direct dans la VM : l'agent eBPF (execve + exit, cilium/ebpf) trace un vrai noyau et diffuse les événements vers l'application, en initialisant l'arborescence avec un instantané /proc au démarrage. Phase 3 jusqu'ici : l'agent a gagné des sondes d'ouverture de fichier (openat) et de connexion sortante (security_socket_connect) (vérifiées à la compilation ; test de charge en attente dans la VM), et la carte réseau (8.3) est construite — un graphe D3 orienté force processus↔destination. Prochaines étapes : le moniteur de fichiers sensibles (8.4) et le moteur de règles + alertes (8.5). Le travail sur les sondes reste dans la VM de dev, jamais sur l'hôte.

Vues du tableau de bord

De la profondeur sur quelques vues vaut mieux qu'une largeur superficielle — six vues nettes, construites par ordre de priorité (les indispensables d'abord).

Vue	Question à laquelle elle répond	État
Flux d'activité en direct (8.1)	Que se passe-t-il en ce moment ?	✅ construite
Arborescence des processus (8.2)	Qui a engendré quoi ?	✅ construite
Vue d'ensemble de l'hôte (8.6)	Un écran pour l'état ?	✅ construite
Carte réseau (8.3)	À qui cet hôte parle-t-il ?	✅ construite
Moniteur de fichiers sensibles (8.4)	Quelque chose a-t-il touché aux fichiers importants ?	◻️ planifiée
Alertes et règles (8.5)	Préviens-moi quand quelque chose semble suspect.	◻️ planifiée

Feuille de route

• Phase 1 (application) : schéma d'événements · ingestion · hub SSE · flux en direct · tests
• Phase 1 (agent) : sonde execve → ring buffer → cilium/ebpf → /api/ingest (dans la VM)
• Phase 2 : sonde exit + instantané /proc · arborescence des processus · vue d'ensemble de l'hôte
• [~] Phase 3 : ✅ sondes fichier + connexion · ✅ carte réseau · ◻️ moniteur de fichiers · ◻️ moteur de règles + alertes · ◻️ cache serveur de l'arborescence des processus · ◻️ tests de propriétés et de livraison des événements
• Phase 4 : VM de dev Nix · test d'intégration noyau nixosTest · CI GitHub Actions
• Phase 5 : déploiement VPS (Terraform), agent + application + Postgres co-localisés
• Phase 6 (étendu) : chronologie/historique · LLM « explique-moi cette alerte » · application de politique · multi-hôtes · DaemonSet k8s

Exécuter l'application (dev)

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

L'application s'exécute sur l'hôte ; l'agent s'exécute dans la VM de dev et lui envoie les événements. Pour voir un flux peuplé sans l'agent, activez le générateur synthétique : KESTREL_SYNTHETIC=1 pnpm dev.

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

La base de données dev/test est PGlite (Postgres compilé en WASM) : pas de compilation native, pas de serveur séparé, même dialecte SQL que le Postgres de production. Elle persiste dans app/kestrel-pgdata/ (ignoré par git) ; les tests utilisent une base en mémoire éphémère.

Essayez le pipeline à la main

# 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"}]'

Tests et vérification

Trois niveaux, adaptés à l'endroit où vit chaque classe de bug (détail complet dans SPEC.md §6–§7) :