kestrel

Kestrel rastrea eventos del kernel (ejecución de procesos, acceso a archivos, conexiones de red) con un agente eBPF y los transmite a una aplicación web SvelteKit que renderiza un feed de actividad en vivo, un árbol de procesos, una vista general del host y un motor de alertas basado en reglas. Consulta SPEC.md para el documento completo de producto/arquitectura y AGENTS.md para la guía operativa.

Por qué existe

El ecosistema eBPF está orientado a backend/CLI/operadores de Kubernetes. Falco — el estándar graduado de la CNCF — es famoso por no incluir ninguna interfaz propia. La brecha entre «el kernel emite datos ricos» y «un humano realmente puede leerlos» es el punto dulce full-stack en el que vive este proyecto. Deliberadamente de un solo host (no Kubernetes) y solo observación (sin aplicación de políticas) en v1.

Arquitectura

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 restricción clave de despliegue: el agente necesita un kernel real, por lo que no puede ejecutarse en Cloudflare Workers (aislamientos V8, sin kernel). v1 coloca el agente + la app + Postgres en un mismo host. Consulta SPEC.md §2.

Estructura del repositorio

Ruta	Qué
/app	App SvelteKit — esquema de eventos, ingest, hub SSE, vistas del panel. Construida y ejecutable.
/agent	Agente de espacio de usuario en Go + sondas eBPF en C (execve/exit/openat/connect) + instantánea de /proc. Construido; se ejecuta solo en la VM.
/infra	VM de desarrollo Nix (construida) + nixosTest, aprovisionamiento con Terraform/libvirt (Fase 4).
SPEC.md	Especificación autoritativa de producto y arquitectura.

Estado

Fase 3 — en curso. Los imprescindibles de la Fase 2 (feed en vivo, árbol de procesos, vista general del host) están completos y verificados en vivo en la VM: el agente eBPF (execve + exit, cilium/ebpf) rastrea un kernel real y transmite eventos a la app, sembrando el árbol con una instantánea de /proc al arrancar. Hasta ahora en la Fase 3: el agente incorporó sondas de apertura de archivos (openat) y de conexiones salientes (security_socket_connect) (verificado en compilación; prueba de carga pendiente en la VM), y el mapa de red (8.3) está construido — un grafo dirigido D3 de procesos↔destinos. Lo siguiente: el monitor de archivos sensibles (8.4) y el motor de reglas + alertas (8.5). El trabajo de sondas se queda en la VM de desarrollo, nunca en el host.

Vistas del panel

La profundidad en pocas vistas vence a la amplitud hecha superficialmente: seis vistas nítidas, construidas en orden de prioridad (primero lo imprescindible).

Vista	La pregunta que responde	Estado
Feed de actividad en vivo (8.1)	¿Qué está pasando ahora mismo?	✅ construido
Árbol de procesos (8.2)	¿Qué generó qué?	✅ construido
Vista general del host (8.6)	¿Estado en una sola pantalla?	✅ construido
Mapa de red (8.3)	¿Con qué está hablando este host?	✅ construido
Monitor de archivos sensibles (8.4)	¿Algo tocó los archivos que importan?	◻️ planificado
Alertas y reglas (8.5)	Avísame cuando algo parezca sospechoso.	◻️ planificado

Hoja de ruta

• Fase 1 (app): esquema de eventos · ingest · hub SSE · feed en vivo · pruebas
• Fase 1 (agente): sonda execve → ring buffer → cilium/ebpf → /api/ingest (en la VM)
• Fase 2: sonda exit + instantánea de /proc · árbol de procesos · vista general del host
• [~] Fase 3: ✅ sondas de archivos y conexiones · ✅ mapa de red · ◻️ monitor de archivos · ◻️ motor de reglas + alertas · ◻️ caché del árbol de procesos en servidor · ◻️ pruebas de propiedades y de entrega de eventos
• Fase 4: VM de desarrollo Nix · prueba de integración de kernel nixosTest · CI de GitHub Actions
• Fase 5: despliegue en VPS (Terraform), agente + app + Postgres en el mismo host
• Fase 6 (ampliación): línea de tiempo/historial · LLM «explícame esta alerta» · aplicación de políticas · multi-host · DaemonSet de k8s

Ejecutar la app (dev)

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

La app se ejecuta en el host; el agente se ejecuta en la VM de desarrollo y le envía eventos. Para ver un feed poblado sin el agente, activa el generador sintético: 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 datos de desarrollo/pruebas es PGlite (Postgres compilado a WASM): sin compilación nativa, sin servidor separado, el mismo dialecto SQL que el Postgres de producción. Persiste en app/kestrel-pgdata/ (ignorado por git); las pruebas usan una DB efímera en memoria.

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

Pruebas y verificación

Tres niveles, alineados con dónde vive cada clase de bug (detalle completo en SPEC.md §6–§7):