numbat 记录输出与数据投递完全指南:NDJSON 记录、HTTP Sink 与 ship 转发实战教程
numbat 记录输出与数据投递完全指南:NDJSON 记录、HTTP Sink 与 ship 转发实战教程
numbat 是一款面向终端的 AI agent 行为可见性与本地检测工具,支持对 Claude Code、Codex、Cursor 等智能体的动作进行事件化采集、CEL 规则检测与取证重建。它的检测结果统一输出为带版本的 NDJSON 记录流,可写入 stdout、本地文件或通过 HTTP sink 直接投递,还可以用内置的 ship 转发器把本地记录文件持久化推送到远端。本文带你从零理清这三种数据出口与转发链路。
📄 先认识 numbat 的 NDJSON 记录流
numbat 的所有输出都是同一套"记录流"契约:每行一个 JSON 对象,携带 record_type、run_id 和 schema_version(当前为 0.3.0),并附带 endpoint 对象(hostname、os、arch、username、uid)。你可以用官方 JSON Schema 对任意一行做校验,详见 record-stream.schema.json 与 schema/v0.3.0 说明。
| record_type | 含义 | 产生场景 |
|---|---|---|
event |
归一化后的类型化事件(命令执行、文件读写、网络动作等) | scan / collect / hook |
finding |
规则命中结果,含 rule_id、severity、引用的事件 id | scan / collect / hook |
enforcement |
拦截决策(deny / no_override) | 仅 hook 的 enforce 模式 |
indicator |
去重后的指标投影:域名、IP、URL、邮箱、哈希,带计数与首末次出现时间 | scan / collect |
scan_summary |
一次 scan 的收尾汇总,status 为 complete / partial / error | 仅 scan |
一条典型的事件记录长这样(可参考测试夹具 benign_fixture.ndjson):
{"schema_version":"0.3.0","event_id":"b4","source_agent":"claude-code","event_type":"command.exec","command":"env","confidence":"high","evidence":{"artifact_type":"claude_jsonl","line":4}}
两个实用细节:
- 设置环境变量
NUMBAT_DEVICE_ID可在endpoint中追加稳定的device_id,方便做跨主机的 fleet 关联; - 值字段(凭证查询参数、Authorization 值、URL 内密码等)在输出前会自动脱敏,findings 中的
redacted:true表示至少有一个字段被掩码。
📡 三个输出目的地:stdout、file、http
scan、collect、hook 命令共用同一组输出参数:--output SINK(可重复)、--output-file PATH,完整定义见 CLI 参考。
| Sink | 行为 | 适用场景 |
|---|---|---|
stdout |
直接打印记录流,不可与其他 sink 组合 | 调试、管道处理 |
file |
追加写入本地 NDJSON 文件(hook install 的默认方式) | 持久化留存,后续用 ship 或日志系统转发 |
http |
批量 POST 到指定 URL,内容类型为 application/x-ndjson |
实时投递到自建采集端 |
常用示例:
# 本地扫描 Codex 历史,只写 findings 到文件
numbat scan --agent codex --output file --output-file records.ndjson
# 同时写文件 + 直投 HTTP(双路)
numbat hook install --agent claude --emit all \
--output file --output http \
--output-file ~/.numbat/live.ndjson \
--http-url https://ingest.example/numbat
关键认知:直投 HTTP 不是磁盘队列。 直投模式的缓冲在内存中(上限 16 MiB,超大单条记录会被拒绝),投递失败不会落盘补发;生产环境建议始终保留 file 输出,由日志转发器负责搬运。这一点在 deployment.md 中被明确推荐。
🔐 HTTP Sink 实战:认证、签名与压缩
HTTP sink 的实现在 internal/output/httpsink.go 中,核心参数如下:
| 参数 | 说明 |
|---|---|
--http-url URL |
采集端地址(必填) |
--http-auth none|bearer|hmac-sha256 |
认证模式,默认 none |
--http-batch-size N |
每批目标条数,默认 500,可提前刷出 |
--http-gzip |
gzip 压缩 POST 体(HMAC 对压缩后的字节签名) |
--http-timeout DURATION |
请求超时,默认 30s |
--http-allow-insecure |
允许向非环回地址使用明文 http |
两个安全设计值得注意:
- 密钥只走环境变量,绝不接受命令行参数:bearer 模式读
NUMBAT_HTTP_TOKEN,hmac-sha256 模式读NUMBAT_HTTP_HMAC_KEY; - HMAC 签名默认写入
X-Numbat-Signature头(sha256=<小写hex>),并配合X-Numbat-Timestamp头携带 Unix 秒级时间戳,被签名的字节是<unix秒>.<请求体>。接收端应校验时间戳新鲜度并用恒定时间比较签名。
# HMAC 签名的实时投递示例
NUMBAT_HTTP_HMAC_KEY=*** numbat scan \
--output http --http-url https://ingest.example/numbat \
--http-auth hmac-sha256 --http-gzip
🚚 ship 转发:带检查点的持久化投递
当主机上没有现成日志转发器时,numbat ship 是官方内置的"兜底"方案:它以长驻进程方式 tail 一个本地 NDJSON 记录文件,按批推送到 HTTP 端点。完整说明见 CLI 参考 ship 章节,核心逻辑在 cmd/numbat/ship.go。
# 第 1 步:hook 只写文件(不要同时开直投,否则会双路重复发送)
numbat hook install --agent codex --emit all \
--output file --output-file ~/.numbat/records.ndjson
# 第 2 步:ship 持续转发
NUMBAT_HTTP_TOKEN=*** numbat ship \
--input-file ~/.numbat/records.ndjson \
--http-url https://ingest.example/numbat \
--http-auth bearer
ship 的可靠性设计:
- 持久检查点:只有收到
2xx才推进偏移量,状态默认保存在<input-file>.ship-state(可用--state-file覆盖),并校验文件身份指纹,轮转文件会按序排空; - 至少一次投递:端点宕机或进程重启后,只要输入文件与轮转分段还在,未发记录会被重放——所以接收端必须容忍重复(用稳定记录 id 去重);
- 413 自适应拆分:端点返回 413 时,ship 只在 NDJSON 记录边界处二分重试;若单条记录始终被拒,则记录日志、推进检查点并跳过,后续记录继续发送;
- 超大记录保护:超过 8 MiB 的完整记录会留在输入文件但从 HTTP 投递中跳过,避免卡死整条队列;
- 优雅停机:SIGINT/SIGTERM 时,进行中的成功请求会先落检查点再退出,退出码为 0。
✅ 实战组合推荐
按 deployment.md 的部署模式表,推荐这样搭配:
| 场景 | 推荐组合 |
|---|---|
| 单机取证排查 | numbat scan + --output file,本地查看即可 |
| 有成熟日志平台(SIEM/EDR) | hook 只写 file,交给现有日志转发器 |
| 无日志平台、无外部 shipper | hook 只写 file + 常驻 numbat ship |
| 需要实时告警、可容忍丢失 | --output file --output http 双路,文件兜底 |
最后提醒两个高频"坑":
- ship 与直投 HTTP 不要叠加:官方明确要求文件 hook 配 ship 时,hook 端不要同时选 http sink,否则同一条记录会走两条链路;
- scan 的退出码即投递健康度:
0表示至少解析了一个工件且投递成功;1覆盖初始化失败、零工件或输出投递失败——排障时先看退出码和 stderr 诊断流。
更多命令细节可查阅 docs/cli.md,事件归一化模型见 docs/event-model.md。