kestrel

Falco のカーネルレベルの可視性に、カーネルネイティブツールには付属していないライブ UI を組み合わせました。

クイックスタート · 仕様 · ビュー · ロードマップ

Kestrel は、eBPF エージェントでカーネルイベント（プロセス実行、ファイルアクセス、ネットワーク接続）をトレースし、ライブアクティビティフィード、プロセスツリー、ホスト概要、ルールベースのアラートエンジンを描画する SvelteKit Web アプリへストリーミングします。完全な製品・アーキテクチャ文書は SPEC.md、運用ガイドは AGENTS.md を参照してください。

なぜ存在するのか

eBPF エコシステムはバックエンド / CLI / Kubernetes オペレーター型の構成です。CNCF 卒業済みの標準である Falco は、独自の UI を同梱しないことで有名です。「カーネルが豊富なデータを出力する」と「人間が実際にそれを読める」の間のギャップこそ、このプロジェクトが取り組むフルスタックのスイートスポットです。v1 では意図的にシングルホスト（Kubernetes ではない）かつ観測専用（強制なし）にしています。

アーキテクチャ

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 を 1 台のホストに同居させます。SPEC.md §2 を参照してください。

リポジトリ構成

ステータス

Phase 3 — 進行中。 Phase 2 の必須機能（ライブフィード、プロセスツリー、ホスト概要）は完了し、VM 内でライブ検証済みです。eBPF エージェント（execve + exit、cilium/ebpf）は実カーネルをトレースし、起動時に /proc スナップショットでツリーを初期化しながら、イベントをアプリへストリーミングしています。Phase 3 の現状: エージェントにファイルオープン（openat）と送信接続（security_socket_connect）プローブが追加され（コンパイル検証済み。VM での負荷テスト待ち）、ネットワークマップ（8.3） が完成しました — D3 による力指向のプロセス↔宛先グラフです。次は: 機密ファイルモニター（8.4）とルールエンジン + アラート（8.5）です。プローブの作業は開発 VM 内でのみ行い、ホスト上では決して行いません。

ダッシュボードのビュー

少数のビューで深さを追求することは、浅く広く作ることよりも優れています — 優先順位（必須項目を先に）に従って構築された、明確な 6 つのビューです。

ロードマップ

• Phase 1（アプリ）: イベントスキーマ · インジェスト · SSE ハブ · ライブフィード · テスト
• Phase 1（エージェント）: execve プローブ → リングバッファ → cilium/ebpf → /api/ingest （VM 内）
• Phase 2: exit プローブ + /proc スナップショット · プロセスツリー · ホスト概要
• [~] Phase 3: ✅ ファイル + 接続プローブ · ✅ ネットワークマップ · ◻️ ファイルモニター · ◻️ ルールエンジン + アラート · ◻️ サーバーサイドのプロセスツリーキャッシュ · ◻️ プロパティ + イベント配信テスト
• Phase 4: Nix 開発 VM · nixosTest カーネル統合テスト · GitHub Actions CI
• Phase 5: VPS デプロイ（Terraform）、エージェント + アプリ + Postgres の同居
• Phase 6（ストレッチ）: タイムライン / 履歴 · LLM による「このアラートを説明」 · 強制 · マルチホスト · k8s DaemonSet

アプリの実行（開発）

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

アプリはホスト上で実行され、エージェントは開発 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（WASM にコンパイルされた Postgres）です。ネイティブビルド不要、別サーバーも不要で、本番の Postgres と同じ SQL 方言を使用します。データは app/kestrel-pgdata/（gitignore 対象）に永続化され、テストでは一時的なインメモリ DB を使用します。

パイプラインを手動で試す

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

テストと検証

バグの種類ごとに適した 3 段階のテスト（詳細は SPEC.md §6–§7）:

• eBPF 検証器 — 無料。 カーネルは、ロードする前にすべてのプローブがメモリ安全で、有界かつ終了することを証明します — システム内で最もリスクの高いコードが、ロード時に無料で検証されます。
• プロパティベーステスト（Phase 3）。 fast-check が敵対的 / 不正なイベントで Zod イベントコントラクトを駆動し、ルールエンジンの不変条件を検証します: 誤一致なし、判定は決定的、不正な入力は境界で拒否。
• イベント配信の正確性（Phase 3）。 イベントごとのシーケンス番号 + クライアント側の欠落 / 重複検出器 + インジェストフラッドテストにより、すべてのイベントが インジェスト → SSE を正確に 1 回通過することを検証します。（正式な TLA+ モデルも検討しましたが、意図的に延期 — シングルホストのボリュームでは正当化されないため。）

現時点: Vitest ユニットテスト（スキーマ、インジェスト、概要、プロセスツリー、ネットワークグラフ）+ エージェントの procscan パーサーとイベントの decode ヘルパー。/app で pnpm test、/agent で go test ./... を実行してください。

設計上のトレードオフ

• シングルホスト vs クラスター — 意図的なスコープの選択。マルチホストはかなり先の話（SPEC.md §8.11）。
• 観測専用 vs 強制 — v1 はプロセスを強制終了しません。インライン遮断を行うためのリスク基準ははるかに高いからです（SPEC.md §8.10）。
• cilium/ebpf vs libbpfgo — 純粋な Go、CGO_ENABLED=0、bpf2go ワークフロー。
• PGlite/Postgres vs SQLite vs ClickHouse — すべて Postgres 方言。約 100 万イベントまでは問題なく、それを超えたら ClickHouse を再検討（SPEC.md §10）。
• 無料の検証 — eBPF 検証器は、カーネルがロードする前に、すべてのプローブがメモリ安全で、有界かつ終了することを静的に証明します。システム内で最もリスクの高いコードが、ロード時にゼロコストで検証されます（SPEC.md §6）。