kestrel

O Kestrel rastreia eventos do kernel (execução de processos, acesso a arquivos, conexões de rede) com um agente eBPF e os transmite para um aplicativo web SvelteKit que renderiza um feed de atividade ao vivo, árvore de processos, visão geral do host e um mecanismo de alerta baseado em regras. Consulte SPEC.md para o documento completo de produto/arquitetura e AGENTS.md para o guia operacional.

Por que existe

O ecossistema eBPF tem formato de backend/CLI/operador Kubernetes. O Falco — o padrão graduado pela CNCF — notoriamente não acompanha nenhuma UI própria. A lacuna entre "o kernel emite dados ricos" e "um humano consegue realmente lê-los" é o ponto ideal full-stack em que este projeto vive. Deliberadamente host único (não Kubernetes) e somente observação (sem aplicação de políticas) na v1.

Arquitetura

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

A restrição-chave de implantação: o agente precisa de um kernel real, então ele não pode rodar no Cloudflare Workers (isolados V8, sem kernel). A v1 coloca agente + aplicativo + Postgres no mesmo host. Consulte SPEC.md §2.

Estrutura do repositório

Caminho	Descrição
/app	Aplicativo SvelteKit — schema de eventos, ingestão, hub SSE, visualizações do dashboard. Compilado e executável.
/agent	Agente Go em userspace + sondas eBPF em C (execve/exit/openat/connect) + snapshot /proc. Compilado; roda somente na VM.
/infra	VM de desenvolvimento Nix (compilada) + nixosTest, provisionamento Terraform/libvirt (Fase 4).
SPEC.md	Especificação definitiva de produto e arquitetura.

Status

Fase 3 — em andamento. Os itens obrigatórios da Fase 2 (feed ao vivo, árvore de processos, visão geral do host) estão completos e verificados ao vivo na VM: o agente eBPF (execve + exit, cilium/ebpf) rastreia um kernel real e transmite eventos para o aplicativo, populando a árvore com um snapshot /proc na inicialização. Até agora na Fase 3: o agente ganhou sondas de abertura de arquivo (openat) e de conexão de saída (security_socket_connect) (verificação de compilação; teste de carga pendente na VM), e o mapa de rede (8.3) está pronto — um grafo D3 force-directed de processo↔destino. A seguir: o monitor de arquivos sensíveis (8.4) e o mecanismo de regras + alertas (8.5). O trabalho das sondas permanece na VM de desenvolvimento, nunca no host.

Visualizações do dashboard

Profundidade em poucas visualizações supera amplitude superficial — seis visualizações nítidas, construídas em ordem de prioridade (itens obrigatórios primeiro).

Visualização	A pergunta que ela responde	Status
Feed de atividade ao vivo (8.1)	O que está acontecendo agora?	✅ pronto
Árvore de processos (8.2)	O que gerou o quê?	✅ pronto
Visão geral do host (8.6)	Status em uma única tela?	✅ pronto
Mapa de rede (8.3)	Com o que este host está se comunicando?	✅ pronto
Monitor de arquivos sensíveis (8.4)	Algo tocou nos arquivos importantes?	◻️ planejado
Alertas e regras (8.5)	Avise-me quando algo parecer suspeito.	◻️ planejado

Roteiro

• Fase 1 (aplicativo): schema de eventos · ingestão · hub SSE · feed ao vivo · testes
• Fase 1 (agente): sonda execve → ring buffer → cilium/ebpf → /api/ingest (na VM)
• Fase 2: sonda exit + snapshot /proc · árvore de processos · visão geral do host
• [~] Fase 3: ✅ sondas de arquivo + conexão · ✅ mapa de rede · ◻️ monitor de arquivos · ◻️ mecanismo de regras + alertas · ◻️ cache da árvore de processos no servidor · ◻️ testes de propriedade + entrega de eventos
• Fase 4: VM de desenvolvimento Nix · teste de integração de kernel nixosTest · GitHub Actions CI
• Fase 5: deploy em VPS (Terraform), agente + aplicativo + Postgres no mesmo host
• Fase 6 (estendida): linha do tempo/histórico · LLM "explique este alerta" · aplicação de políticas · multi-host · DaemonSet k8s

Executando o aplicativo (dev)

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

O aplicativo roda no host; o agente roda na VM de desenvolvimento e envia eventos para ele. Para ver um feed populado sem o agente, ative o gerador 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)

O banco de dados de desenvolvimento/teste é o PGlite (Postgres compilado para WASM): sem build nativo, sem servidor separado, mesmo dialeto SQL do Postgres de produção. Ele persiste em app/kestrel-pgdata/ (ignorado pelo git); os testes usam um banco em memória efêmero.

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

Testes e verificação

Três camadas, alinhadas a onde cada classe de bug vive (detalhes completos em SPEC.md §6–§7):