adamhjouj/blackbox

Blackbox 作为一个被动记录器运行在 agent 旁边。它将 hook 可见的动作转化为经过脱敏处理的、哈希链式的事件记录；结合 Git 交叉验证文件更改；评估确定性风险规则；并以一种从容的调查工作流而非满屏日志的形式呈现结果。

_{Real interface · fully synthetic demo data · no captured user sessions}

## 为什么选择 Blackbox？ | 普通的 agent 日志 | Blackbox | | --- | --- | | 为重放对话而优化 | 为调查事件而优化 | | 文件可变且完整性不明确 | 采用仅追加的 SHA-256 链并带有签名检查点 | | 缺乏因果上下文的命令 | Prompt → 推理 → 工具 → 文件 → 发现 | | 原始输出可能包含敏感信息 | 捕获时即进行脱敏；默认省略输出主体 | | “某些东西发生了变化” | 经 Git 交叉验证的幽灵、幻影和内容不匹配发现 | | 风险掩埋在成千上万的事件中 | 确定性发现、爆炸半径和遏制操作 | | 信任本地数据库 | 在本地验证并在机外见证签名的 head | ### 旨在提供答案，而不是更多的遥测数据 - **agent 做了什么？** 可读的逐 Prompt 活动时间线。 - **影响到了什么？** 更改的文件、敏感路径、Git artifact 以及观察到的出站目标。 - **为什么存在风险？** 带有证据关联、通俗易懂解释的版本化规则。 - **我能信任这条记录吗？** 哈希链验证、Ed25519 检查点、删除水印和外部回执。 - **我接下来该怎么做？** 按严重性排序的遏制指南和可共享的取证报告。 ## 快速开始 ### 前置条件 ### 1. 从源码安装 ``` git clone https://github.com/adamhjouj/blackbox.git cd blackbox npm ci npm run build npm link ``` `npm link` 将 `blackbox` 命令设置为全局可用，同时方便从源码更新此 beta 版本。 ### 2. 从你要记录的项目中初始化 Blackbox ``` cd ~/code/your-project blackbox init ``` 这一条命令将： 1. 精确展示 Blackbox 捕获的内容以及哪些数据可能会离开本机； 2. 将异步的 Blackbox handler 添加到 `~/.claude/settings.json` 中，且不会替换你现有的 hook； 3. 创建本地签名密钥和经过认证的 Git-collector token； 4. 使用当前仓库的 remote，在 `refs/blackbox/anchors` 上配置已签名的 head 回执； 5. 在 `127.0.0.1:7842` 上启动仅限 loopback 的记录器。 如果仓库没有 remote，Blackbox 将拒绝静默降级监管链 custody。对于刻意设计的纯本地设置： ``` blackbox init --local-only-anchor ``` 该模式完全可用，但如果某个进程拥有对 `~/.blackbox` 的完全写入权限，它可能会同时重写数据库、密钥、水印和本地回执。 ### 3. 像往常一样使用 Claude Code ``` claude ``` 当相应 source 暴露数据时，Prompt、agent 声明的推理、工具调用、MCP 活动、文件变更、Git 事实、持续时间、model 和 token 使用情况都会被自动记录。 ### 4. 打开调查 UI ``` blackbox ui ``` ### 5. 确认安装 ``` blackbox doctor blackbox verify --anchors ``` `doctor` 会检查 runtime、Claude Code、hook、daemon、状态目录、collector 身份验证、custody 状态、event store 和链完整性。 ## 无需记录真实会话即可体验 ``` npm run demo ``` ## 工作原理

Blackbox 将完整记录保留在你的机器上。在会话边界，它还可以向 Git、文件或 HTTPS 写入微小的签名回执。该回执包含版本、序列、head 哈希、签名、公钥指纹和时间戳——**绝不**包含 Prompt、源代码、路径、命令、工具输出或机密信息。 ## 调查模型 ### Dashboard 在一个地方搜索会话、项目、Prompt 和证据。最近会话卡片显示项目、时间、事件计数、严重性和标记的操作，且无需永久侧边栏。路由可恢复，且浏览器的“后退/前进”功能均可用。 ### 概览 确定性摘要可以在首屏直观解答发生了什么变化、主要发现、完整性状态、受影响的文件/主机以及下一步的遏制行动。Blackbox 绝不捏造 AI 生成的 incident 声明。 ### Activity 每一轮（turn）都会保留其 Prompt 标识，并显示持续时间、model、token 使用量、工具、嵌套步骤、结果，以及可用时 agent **声明的推理**。选择一个步骤即可打开证据，同时不会丢失滚动位置或展开状态。 ### Evidence 检查爆炸半径、脱敏情况、在命令/工具输入中观察到的出站目标、已更改的文件、核对、链验证、原始脱敏档案以及变更历史。存储的主体内容可以老化掉，而它们的加密承诺将被保留。 ### Graph 该图是确定性的 Sugiyama 风格 DAG，而非 AI 可视化。围绕某个发现、Prompt 或证据项重新设定根节点，以查看最小且有用的因果邻域；仅在需要时展开目录和深度。 ## Blackbox 记录的内容 | 信号 | 示例 | 存储行为 | | --- | --- | --- | | 会话生命周期 | start, stop, end, compaction, notifications | 哈希链事件 | | 用户意图 | prompt 文本和 prompt 标识符 | 脱敏、有界、哈希链式 | | agent 声明的意图 | 可用的推理摘要、model、token 使用情况 | 脱敏并附加到其对应的轮次 | | 工具活动 | shell、文件、web fetch、任务、MCP 调用 | 输入在脱敏后保留；输出默认进行哈希处理 | | 文件变更 | 脱敏的补丁/主体、哈希、diffstat | 内容寻址且可独立修剪 | | Git ground truth | refs、commits、worktree 基线/最终状态 | 用于核对 | | 环境 | toolchain 版本、MCP 名称、manifest 哈希 | 排除参数和环境机密 | | 风险解释 | 标记、组合、证据链接 | 可在版本化规则集下重新推导 | Blackbox 仅知道其已配置 source 暴露的内容。“出站主机”是指在 hook 可见的命令或工具输入中观察到的目标——而非来自内核网络传感器的证明。 ## 风险与核对 当前的 `r4` 规则集可检测并组合以下各项的证据： 风险是一个解释层，绝不是不可变链的一部分。你可以在不更改已记录证据的情况下重新计算它： ``` blackbox rescore --ruleset r4 blackbox rescore --ruleset r4 --check ``` 在会话结束时，核对过程会将 hook 报告的变更与 Git 观察到的 worktree 进行比较： - **幽灵变更 (Ghost mutation)** — Git 看到了更改，但没有匹配的文件 hook。 - **幻影变更 (Phantom mutation)** — hook 报告了更改，但最终状态中不存在。 - **内容不匹配 (Content mismatch)** — 存储的写入主体与磁盘上的 digest 不一致。 这些是差异事实，而不是对 agent 行为的自动指控。 ## 日常命令 | 命令 | 用途 | | --- | --- | | `blackbox status` | 记录器状态、事件计数、身份验证和 anchor 状态 | | `blackbox doctor` | 诊断完整安装并验证链 | | `blackbox ui` | 打开本地调查界面 | | `blackbox sessions` | 列出已记录的会话 | | `blackbox search "query"` | 搜索 Prompt 和已脱敏的证据 | | `blackbox blast --session ` | 总结受影响的文件、目标、Git artifact 和遏制措施 | | `blackbox file --session ` | 检查变更历史和存储的证据 | | `blackbox verify --anchors` | 验证哈希、签名、水印和已配置的回执 | | `blackbox audit --session ` | 显示哪些内容被脱敏，而不泄露机密 | | `blackbox report --session ` | 导出确定性的 Markdown 审查报告 | | `blackbox report --session --forensic` | 导出 custody、验证、发现和自清单 | | `blackbox help --all` | 显示所有命令和选项 | ## 安全模型 ### Blackbox 旨在保护的内容 - **静止状态下的机密暴露：** 已知的机密格式会在第一次写入事件前被脱敏。如果脱敏过程抛出异常，内容将被降级为哈希。 - **静默的行编辑：** 每个事件都会对所有规范化列和前一个事件哈希进行哈希处理。 - **尾部删除：** 原子更新的 head 记录会保留预期的序列和计数。 - **一致的本地重写：** Ed25519 检查点将根据受信任的本地公钥进行验证。 - **签名删除：** 数据库之外的高水位线要求保留最新的预期检查点。 - **完整的本地状态重写：** 外部的签名 head 回执允许独立的目标证明旧链曾经存在。 - **恶意的记录内容：** UI 采用纯文本 DOM 构造、严格的 CSP、同源读取和仅限 loopback 的服务器。 ### 诚实的局限性 - 控制了数据库、签名密钥、水印、配置、hook **以及所有外部回执**的进程可以击败 custody。 - 脱敏是深度防御，而不是对识别出所有未来机密格式的数学保证。 - Hook 捕获可能不完整；Blackbox 会记录 daemon 停机时间，并核对记录覆盖率，以便让缺失部分清晰可见。 - Git 仅能佐证文件状态，无法佐证进程或网络活动。 - 记录器是观察性的。它不阻止执行、不强制实施策略、不隔离 agent，也不恢复文件。 - Agent “推理”是 agent 提供的、可用于记录的解释——而不是私有的隐藏思维链 (chain-of-thought)。 在依赖 Blackbox 进行 incident-response 流程之前，请阅读 [SECURITY.md](SECURITY.md)、[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 和 [docs/FORENSIC-COLLECTORS.md](docs/FORENSIC-COLLECTORS.md)。 ## 隐私与数据生命周期 默认情况下，本地状态位于 `~/.blackbox`： ``` ~/.blackbox/ ├── blackbox.db # events, derived layers, and mutation evidence ├── config.json # port, collector token, and anchor configuration ├── signing.key # Ed25519 private key, mode 0600 ├── signing.pub # trusted public key ├── signing.head # checkpoint high-watermark ├── daemon.pid └── daemon.log ``` 使用 `BLACKBOX_HOME`、`BLACKBOX_DB` 或 `--db` 覆盖测试或隔离的位置。 在 dashboard 中打开 **Edit name → Recorder & privacy**（或访问 `#/settings`），以获得关于记录器 endpoint、数据库位置和大小、保留行为、输出主体存储、custody 目标和移除命令的可读本地视图。状态 endpoint 是同源的，并且从不暴露 collector token。 ### 保留事实，淘汰存储内容 ``` blackbox prune --older-than 30d ``` 修剪会移除旧的已脱敏变更主体，同时保留事件事实、哈希、大小、diffstat、墓碑记录和链验证。由于各会话共享一条仅追加的 custody 链，Blackbox 不会假装删除一个会话是一个无害的操作。 ### 删除所有本地 Blackbox 数据 ``` blackbox erase --all --yes ``` 这将停止 daemon，并永久删除 event store、签名密钥、日志和本地回执。Claude hook 保持已安装状态。 ### 完全卸载（包括数据） ``` blackbox uninit --erase-data --yes ``` 这只会从 Claude 设置中移除 Blackbox handler，保留不相关的 hook，停止 daemon，禁用其 macOS LaunchAgent，并删除 `~/.blackbox`。已经推送到 Git remote 或写入其他目标的回执，必须根据该目标的保留策略进行删除。 ## 仓库导航 ``` src/ ├── daemon.ts loopback receiver, read API, and UI serving ├── store.ts · hash.ts append-only SQLite chain ├── normalize.ts · redact.ts tolerant normalization and fail-closed redaction ├── risk-engine.ts · rules*.ts versioned deterministic interpretation ├── mutation.ts · filestate.ts content-addressed evidence and reconstruction ├── git-collector.ts ref-change facts ├── worktree.ts · reconcile.ts Git ground-truth comparison ├── transcript.ts prompt and agent-stated reasoning recovery ├── provenance.ts · graph.ts story and deterministic causal DAG ├── sign.ts · anchor.ts checkpoints, watermark, external receipts ├── search.ts · blast.ts corpus search and containment projection ├── report.ts review and forensic case-file exports ├── doctor.ts installation and health diagnostics └── ui/ dependency-free dashboard and investigation views test/ security, invariants, integration, and UI tests examples/demo-events.jsonl fully synthetic demo capture docs/ architecture, collectors, and phase decisions experiments/ reproducible hook/collector research ``` runtime 继续使用 TypeScript 和原生浏览器 JavaScript。所服务的 UI 是自包含的，没有前端框架或 runtime 依赖。 ## 开发 ``` git clone https://github.com/adamhjouj/blackbox.git cd blackbox npm ci npm test npm run demo ``` CI 会在 macOS 和 Linux 上构建并测试 Node 18、20 和 22。打标签的 release 会运行相同的测试套件，构建与 npm 兼容的 `.tgz`，生成 `SHA256SUMS.txt`，并将两者都附加到 GitHub release 中。 ## 常见问题

Blackbox 会把我的代码或 Prompt 发送到其他地方吗？

不会。事件、Prompt、路径、代码和证据都将保留在本地数据库中。如果启用了外部锚定，只有微小的签名链 head 回执会离开本机。

它会拖慢 Claude Code 吗

Blackbox 安装的是异步 HTTP hook，因此记录过程不会进入 agent 的关键路径。但在极其繁忙的系统上，仍然可能出现资源争用；覆盖率诊断能让捕获缺失变得清晰可见，而不是将其隐藏。

Blackbox 是 EDR、沙箱还是策略引擎？

不是。它是一个记录器和调查工具。它不提供内核遥测、执行预防、隔离、回滚或策略强制执行。

为什么默认需要外部 anchor？

与签名密钥存储在一起的哈希链可以证明意外损坏和有限的篡改，但拥有完全写入权限的攻击者可以同时重写两者。而在其他地方见证的签名 head 可以让这种重写变得可证伪。纯本地模式作为明确的权衡方案依然可用。

我可以将它用于 Claude Code 以外的 agent 吗？

规范化的存储和读取 API 是与 agent 无关的，但目前完整的捕获 adapter 优先针对 Claude Code hook。新的 collector 必须保留相同的脱敏和溯源不变量。

## License Blackbox 采用 [MIT License](LICENSE) 发布。

**本地记录。清晰调查。独立验证。** 如果 Blackbox 帮助你了解了一起 agent incident，请考虑为该仓库加星，并分享一个合成的复现用例，让下一次调查变得更简单。

标签：MITM代理, 网络安全研究, 自动化攻击