kestrel

拥有 Falco 的内核级可见性，同时提供内核原生工具所不附带的实时界面。

快速开始 · 规范 · 视图 · 路线图

Kestrel 通过 eBPF 代理跟踪内核事件（进程执行、文件访问、网络连接），并将其流式传输到 SvelteKit Web 应用——该应用渲染实时活动流、进程树、主机概览，并提供基于规则的告警引擎。完整的产品/架构文档参见 SPEC.md，运维指南参见 AGENTS.md。

为什么存在

eBPF 生态系统以后端、CLI、Kubernetes Operator 为主要形态。Falco——CNCF 已毕业的业界标准——众所周知地不自带任何 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 共置于同一台主机。参见 SPEC.md §2。

仓库布局

状态

阶段 3——进行中。阶段 2 的必需项（实时活动流、进程树、主机概览）已完成，并在虚拟机中进行了实时验证：eBPF 代理（execve + exit，cilium/ebpf）跟踪真实内核并将事件流式传输到应用，启动时以 /proc 快照为进程树建立初始数据。阶段 3 目前进展：代理新增了文件打开（openat）与出站连接（security_socket_connect）探针（编译已验证；负载测试待虚拟机中进行），网络拓扑图（8.3） 已完成——一个 D3 力导向的进程↔目标图。接下来：敏感文件监控（8.4）以及规则引擎与告警（8.5）。探针相关工作始终在开发虚拟机中进行，绝不在宿主机上进行。

仪表盘视图

在少数几个视图上做深，胜过浅尝辄止的广度——六个精炼视图，按优先级顺序构建（必需项优先）。

路线图

• **阶段 1（应用）：**事件 schema · 采集 · SSE 中心 · 实时活动流 · 测试
• 阶段 1（代理）：execve 探针 → 环形缓冲区 → cilium/ebpf → /api/ingest （在虚拟机中）
• 阶段 2：exit 探针 + /proc 快照 · 进程树 · 主机概览
• [~] 阶段 3：✅ 文件与连接探针 · ✅ 网络拓扑图 · ◻️ 文件监控 · ◻️ 规则引擎与告警 · ◻️ 服务端进程树缓存 · ◻️ 属性与事件投递测试
• **阶段 4：**Nix 开发虚拟机 · nixosTest 内核集成测试 · GitHub Actions CI
• **阶段 5：**VPS 部署（Terraform），代理 + 应用 + Postgres 同机部署
• **阶段 6（拓展）：**时间线/历史 · LLM「解释此告警」· 强制执行 · 多主机 · k8s DaemonSet

运行应用（开发模式）

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

应用运行在宿主机上；代理则运行在开发虚拟机中，将事件发送给应用。若想在无代理的情况下看到有数据的实时流，可开启合成数据生成器：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）：无需原生编译、无需独立服务器，与生产 Postgres 使用相同的 SQL 方言。数据持久化到 app/kestrel-pgdata/（已被 git 忽略）；测试则使用临时的内存数据库。

手动尝试整条流水线

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

测试与验证

三个层级，分别对应每类 bug 所在之处（完整细节见 SPEC.md §6–§7）：

• **eBPF 验证器——零成本。**内核在加载每个探针之前即证明其内存安全、有界且可终止——这是系统中风险最高的代码，却在加载时免费完成验证。
• 基于属性的测试（阶段 3）。fast-check 用对抗性/畸形事件驱动 Zod 事件契约，并断言规则引擎的不变式：无误匹配、判定结果确定、畸形输入在边界即被拒绝。
• **事件投递正确性（阶段 3）。**每个事件带序列号 + 客户端缺口/重复检测器 + 采集洪泛测试，断言每个事件在 ingest → SSE 路径上恰好投递一次。（曾考虑过正式的 TLA+ 模型，但有意推迟——在单主机规模下并不值得。）

目前的测试覆盖：Vitest 单元测试（schema、ingest、overview、process tree、network graph）+ 代理的 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）。