sujalmanpara/glassbox

# Glassbox **将任何黑盒系统转化为可重构的规格说明。** Glassbox 是一种用于逆向工程的智能体技能。不是那种“反编译二进制文件”的逆向工程——而是现代意义上的逆向工程，即你观察一个正在运行的系统，并恢复出产生该系统的*决策*，其精确程度足以让编码智能体对其进行重构。 ## 为什么会有这个项目 让一个智能体去“弄清楚这个系统是如何工作的”，它会自信地交给你一个它自己虚构出来的架构。它看到一个登录页面，就会写下“*使用 JWT 和 refresh token 轮换*”，而实际上什么也没有观察到。 Glassbox 用一个机制解决了这个问题：**每一项声明都必须附带证据标签。** | 标签 | 含义 | 要求 | |-----|-------|----------| | `[C]` | Confirmed（已确认） | 你可以指出的已存储 artifact | | `[I]` | Inferred（推断得出） | 从行为推导得出，且推理过程有记录 | | `[A]` | Assumed（假设得出） | 根据惯例填补——被标记为风险 | 以及一条硬性规则：**一份超过 30% 都是 `[A]` 的规格说明根本不是规格说明，它是同人小说。** ## 它真的有效吗？ 是的——在两个截然不同的目标上进行了两次测量。 ### 1. 对照 A/B 测试（合成目标，封存的真实基准） 见 [`experiments/`](experiments/)。一个 7 节点的 agentic 系统，带有一个封存的真实基准文件。两个智能体，相同的任务说明，相同的时间预算，并行运行——一个使用 Glassbox，另一个不使用。根据 15 个加权的架构事实进行评分。 | 分支 | 分数 | | |---|---|---| | 不使用 Glassbox | 5 / 31 | **16%** | | 使用 Glassbox | 15.5 / 31 | **50%** | 输出长度几乎完全相同（224 行对 222 行）——这是准确率的提升，而不是冗余度的增加。 **被该技能捕捉到但被对照组遗漏的：** response cache；真实的 critic 分支条件（对照组断言“总是运行两次，硬编码的”——实际上它受 input 长度控制）；以及一个伪 timeout，被正确识别为“*穿着 timeout 外衣的硬性长度限制*”，因为当一次真实运行耗时 4.4 秒时，它在 1.0 秒就被触发了。 ### 2. 实地测试（在线第三方生产 API） 见 [`field-test-nominatim/`](field-test-nominatim/)。对于合成目标最明显的反对意见是，它是为了被解决而构建的。因此，该方法被用于运行针对 **Nominatim**（即 OpenStreetMap 的 geocoder）的测试——它是真实的、复杂的且开源的，这意味着存在客观的真实基准。 **结果：针对官方文档，15 / 15 项可验证的声明均正确。** 置信度分布：34 `[C]` / 12 `[I]` / 3 `[A]`。 重点： - `limit=40` 和 `limit=41` 都返回了 **33** 个结果——这证明 `limit` 是对候选池的最终截断，而不是查询边界。文档后来逐字证实了这一点。 - 一个格式错误的请求在它的错误中泄露了**完整的结构化参数集**。 - 这三个 `[A]` 声明既正确*又*恰当地有所保留（留有余地）——这体现了校准，而不仅仅是正确性。 ## 诚实的局限性 - 每个实验 n=1 个目标，每个分支 n=1 次运行。方向性很强，但在统计学上并不严谨。 - 评分由作者进行，尽管真实基准是提前封存的。 - A/B 测试 50% 的分数是一个真实的上限——依然有一半的架构被遗漏了。v1.1 版本正是针对这一差距。 - 实地测试是针对*文档*进行验证的，而文档描述的是意图；一些内部行为从外部仍然无法验证。 ## 安装 **Hermes Agent** ``` git clone https://github.com/sujalmanpara/glassbox cp -r glassbox/skill ~/.hermes/skills/software-development/reverse-engineering ``` **Claude Code / 其他智能体** — 让你的智能体指向 [`skill/SKILL.md`](skill/SKILL.md)，或者将其粘贴到你的 system prompt 中。它是纯 Markdown 格式，没有 runtime 依赖。 ## 方法论 ``` Artifact → Evidence → Spec → Thin Rebuild → Diff → (loop) → Report ``` **两条铁律** 1. **在规格说明之前不要重构。** 先写代码总是会产生“看起来相似，行为却不同”的结果。 2. **你调试的是规格说明，而不是克隆体。** 手动修补克隆体会掩盖差距；下一次重新生成又会将其引入。 **六个阶段** | 阶段 | 内容 | |---|---| | 0 | **Scope gate** — 目标、深度、边界、合法性 | | 1 | **证据收集** — 首先发现 input-surface，然后进行行为探测 | | 2 | **接缝映射** — 找到组件交接的关节点 | | 3 | **规格合成** — 实际的交付物 | | 4 | **轻量级垂直重构** — 能够产生一个正确输出的最小化事物 | | 5 | **Diff 循环** — 80% 的保真度来源于此 | **输出：三个标准 artifact** - `SYSTEM-SPEC.md` — 可重构的规格说明 - `FIDELITY-LOG.md` — 每次 diff 迭代 + 规格补丁记录 - `EVIDENCE.md` — 为每个 `[C]` 提供支持的已索引证据 ## 工具 [`tools/probe_surface.py`](tools/probe_surface.py) 实现了阶段 1a 的自动化——这是两个测试分支都失败的步骤。 ``` python3 tools/probe_surface.py \ --url http://localhost:8080/api/run \ --base '{"transcript":"..."}' \ --domain meeting,agent,user ``` 它会探测大约 40 个候选字段名，并报告哪些字段改变了 **latency、节点数量、输出键值或错误文本** ——任何改变都意味着该字段是活跃的，并且可能控制着一个子系统。 它还会**自动进行 cache-bust（缓存清除）**，这事实证明是必不可少的：在测试中，一次未清除缓存的运行报告了误报，*并且*遗漏了真正的子系统门控字段，因为服务器的 cache 对每次探测都进行了短路处理。 ## 仓库布局 ``` skill/ the skill itself (SKILL.md + references + templates) tools/ probe_surface.py — automated input-surface discovery experiments/ the A/B protocol, sealed ground truth, both outputs, scoring ``` ## 范围与道德规范 Glassbox 旨在用于互操作性、学习、安全研究，以及重构你自己观察到的*行为*版本。 该技能的 scope gate 会拒绝：规避 DRM 或授权许可、提取机密或凭证、绕过付费墙或速率限制，以及明显违反服务条款（ToS）的抓取行为。 它还明确指导分析师从行为中重构 prompt *约束*，而不是试图对他们不拥有的系统进行 prompt-injection 提取——这不仅更合法，而且更稳健。 ## 许可证 MIT

标签：云资产清单, 代码生成, 渗透测试工具, 系统规格推导, 自动化分析, 跨站脚本, 逆向工具, 逆向工程, 防御加固