kestrel

Видимость уровня ядра, как у Falco, но с живым интерфейсом, которого нативные инструменты ядра не имеют.

Быстрый старт · Спецификация · Представления · Дорожная карта

Kestrel отслеживает события ядра (запуск процессов, доступ к файлам, сетевые подключения) с помощью eBPF-агента и передаёт их в SvelteKit-приложение, которое отображает живой поток активности, дерево процессов, обзор хоста и механизм алертов на основе правил. Полный документ по продукту и архитектуре см. в SPEC.md, операционное руководство — в AGENTS.md.

Зачем это нужно

Экосистема eBPF по форме — это бэкенд/CLI/Kubernetes-оператор. Falco — стандарт, вышедший из CNCF, — как известно, не имеет собственного UI. Разрыв между «ядро отдаёт богатые данные» и «человек может их реально прочитать» — это та самая full-stack ниша, в которой живёт проект. Сознательно однохостовой (не Kubernetes) и только для наблюдения (без активного вмешательства) в v1.

Архитектура

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

Ключевое ограничение развёртывания: агенту нужно настоящее ядро, поэтому он не может работать на Cloudflare Workers (изоляты V8, нет ядра). В v1 агент + приложение + Postgres размещаются на одном хосте. См. SPEC.md §2.

Структура репозитория

Статус

Фаза 3 — в процессе. Обязательные пункты Фазы 2 (живой поток, дерево процессов, обзор хоста) завершены и проверены вживую в VM: eBPF-агент (execve + exit, cilium/ebpf) трассирует реальное ядро и передаёт события в приложение, при старте наполняя дерево снимком /proc. Пока что в Фазе 3: агент обзавёлся пробами открытия файлов (openat) и исходящих подключений (security_socket_connect) (проверено компиляцией; нагрузочный тест в VM — предстоит), и сетевая карта (8.3) готова — D3-граф связей процесс↔адресат с силовой раскладкой. Дальше: монитор чувствительных файлов (8.4) и механизм правил + алерты (8.5). Работа с пробами выполняется в dev VM, но никогда на хосте.

Представления дашборда

Глубина нескольких представлений лучше, чем широта без глубины, — шесть чётких представлений, созданных в порядке приоритета (сначала обязательные).

Дорожная карта

• Фаза 1 (приложение): схема событий · ingest · SSE-хаб · живой поток · тесты
• Фаза 1 (агент): проба execve → ring buffer → cilium/ebpf → /api/ingest (в VM)
• Фаза 2: проба exit + снимок /proc · дерево процессов · обзор хоста
• [~] Фаза 3: ✅ пробы файлов и подключений · ✅ сетевая карта · ◻️ монитор файлов · ◻️ механизм правил + алерты · ◻️ серверный кэш дерева процессов · ◻️ тесты на основе свойств + тесты доставки событий
• Фаза 4: Nix dev VM · интеграционный тест ядра nixosTest · GitHub Actions CI
• Фаза 5: развёртывание на VPS (Terraform), агент + приложение + Postgres на одном хосте
• Фаза 6 (сверх плана): таймлайн/история · LLM «объясни этот алерт» · активное вмешательство · несколько хостов · k8s DaemonSet

Запуск приложения (dev)

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

Приложение работает на хосте; агент работает в dev VM и отправляет события в него. Чтобы увидеть наполненный поток без агента, включите синтетический генератор: KESTREL_SYNTHETIC=1 pnpm dev.

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

База для разработки/тестов — PGlite (Postgres, скомпилированный в WASM): без нативной сборки, без отдельного сервера, тот же диалект SQL, что и у продакшен-Postgres. Она сохраняется в app/kestrel-pgdata/ (gitignored); тесты используют эфемерную БД в памяти.

Попробуйте конвейер вручную

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

Тестирование и проверка

Три уровня, привязанных к тому, где живёт каждый класс багов (полные подробности в SPEC.md §6–§7):

• Верификатор eBPF — бесплатно. Ядро доказывает, что каждая проба безопасна по памяти, ограничена и завершаема, прежде чем позволить ей загрузиться, — самый рискованный код в системе проверяется при загрузке без каких-либо затрат.
• Тесты на основе свойств (Фаза 3). fast-check прогоняет Zod-контракт событий через враждебные/искажённые события и проверяет инварианты механизма правил: никаких ложных совпадений, детерминированные вердикты, искажённый ввод отклоняется на границе.
• Корректность доставки событий (Фаза 3). Последовательные номера на событие + клиентский детектор пропусков/дубликатов + флуд-тест ingest гарантируют, что каждое событие проходит ingest → SSE ровно один раз. (Формальная модель TLA+ рассматривалась и намеренно отложена — не оправдана при объёме одного хоста.)

На сегодня: Vitest-юниты (схема, ingest, обзор, дерево процессов, сетевой граф) + парсер procscan агента и хелперы decode событий. Запустите pnpm test в /app, go test ./... в /agent.

Компромиссы в дизайне

• Один хост против кластера — осознанный выбор границ проекта; мультихостовость — далёкая перспектива (SPEC.md §8.11).
• Только наблюдение против активного вмешательства — v1 никогда не убивает процессы; планка риска для инлайн-блокирования гораздо выше (SPEC.md §8.10).
• cilium/ebpf против libbpfgo — чистый Go, CGO_ENABLED=0, workflow bpf2go.
• PGlite/Postgres против SQLite против ClickHouse — диалект Postgres везде; хорошо при объёме до ~1 млн событий, при превышении — пересмотреть ClickHouse (SPEC.md §10).
• Бесплатная проверка — верификатор eBPF статически доказывает, что каждая проба безопасна по памяти, ограничена и завершаема до того, как ядро её загрузит. Самый рискованный код в системе проверяется при загрузке без каких-либо затрат (SPEC.md §6).