用Allowlist门禁拦截AI Agent补丁：Fail-Closed实践指南

AI编程助手能在几秒内生成一个完整补丁，但生成成本越低，错误文件的清理成本就越高。一个看起来措辞谨慎、报告完整的 Agent 补丁，本质上仍是一个不可信的 diff。本文解析一则案例研究：如何用一个极小的 Python 门禁（gate），在补丁触碰你的代码树之前就将其拦截——除非预先写好的白名单（allowlist）和指定的测试命令同时通过验证。

需要明确的是，这个门禁是一个审查工具，而不是在声称任何模型或托管环境是安全的。

Allowlist Gate 案例研究

你在保护什么

案例设定的保护对象是一个仅有三个文件的健康检查服务，而非生产平台，也不是存有密钥的仓库。服务已经暴露了 /health 路由，目标是新增一个 /ready 路由并配一个聚焦的测试。

Agent 可以快速起草这个改动，但它同样可能顺手编辑部署文件、锁文件（lockfile），或某个隐藏的环境变量样本。门禁的核心职责，就是把最终应用的 diff 约束在你在会话开始前就写好的"卡片"（card）范围内。

这里有个关键的认知前提：Agent 的草稿即便周围的文字描述听起来已经完备且谨慎，它依然是一个不可信补丁。你需要的是一条本地规则，这条规则不依赖于聊天窗口里报告显得有多自信。

三条同时成立的硬性条件

目标是构建一个 fail-closed（失败即关闭） 的检查器，只有在三个条件同时成立时才以 0 退出码返回：

diff 只能触碰白名单上的路径；
diff 绝不能触碰任何禁止路径（forbidden path）；
Agent 报告中必须包含你预先写在卡片上的那条精确测试命令。

设计上最重要的一点是：把缺失字段视为失败。因为一个静默的默认值，正是未经审查的文件最终混入代码树的典型路径。allow-all 的默认行为，恰恰是你要消除的 bug。

会话卡片（Session Card）

卡片要在发出 prompt 之前写好，并存放在你控制的仓库里，而不是 Agent 的临时空间（scratch space）中。这样做的理由很直接：后续对 prompt 的任意修改，都无法悄悄放宽白名单。


**Fail-closed** 是安全系统设计中的一个基本原则：当系统遇到错误、缺失信息或不确定状态时，默认拒绝而非放行。与之相对的是 fail-open（失败即开放），即在异常情况下默认允许通过。门禁、防火墙、访问控制等安全组件通常优先选择 fail-closed，因为一次误拒（false negative）的代价远低于一次误放（false positive）——前者顶多让你多检查一遍，后者可能让未经审查的文件永久混入代码库。在本文场景中，这意味着：卡片字段缺失、diff 解析报错、参数数量不对，统统判定为失败，而不是"跳过这条检查继续运行"。
# session_card.yaml - proposal, not a production policy
goal: Add GET /ready that returns 200 and a ready status
allowed_paths:
  - app.py
  - test_app.py
forbidden_paths:
  - .env
  - .env.example
  - credentials.json
  - deploy/
  - .git/
required_test_command: python -m unittest test_app.py
max_diff_bytes: 12000

卡片中的字节上限（max_diff_bytes）是你自己设定的礼节性限制，而非任何托管方宣传的配额。

检查器实现

这个检查器仅使用 Python 标准库，不为审查一个补丁而额外引入依赖。它读取卡片、diff 和报告三份输入，完成检查后打印一行 JSON。任何解析错误或参数数量错误，都应在补丁被应用之前被当作审查失败处理。

核心逻辑分为三部分：

路径提取 只依赖 diff 中的 +++ b/ 文件头来识别被修改的路径。随后逐一比对：若命中 forbidden 列表（支持前缀匹配，如 deploy/），记为违规；若不在 allowlist 中，同样记为"超出白名单"。

命令校验 会把报告按行拆分并去除空白，要求必须有一行与卡片中的 required_test_command 完全一致。模糊地提到"已运行测试"是无法通过这道关卡的。

结构校验 包括字节上限检查，以及检测 diff 中是否存在 +++ 文件头——没有文件头的空 diff 会被直接拒绝。

最终输出形如 {"ok": false, "reasons": [...], "command": "..."} 的 JSON，并据此返回 0（通过）或 1（拒绝）退出码。

diff 文件遵循 Unified Diff 格式（由 diff -u 或 git diff 生成），每个被修改的文件在 diff 中以一对 --- a/路径 和 +++ b/路径 头部行标识，随后跟着以 @@ 开头的 hunk（变更块），+ 开头的行表示新增，- 开头的行表示删除。检查器只解析 +++ b/ 这一行来提取文件路径，是因为它明确代表"变更后的目标文件"，实现最简单且足以覆盖常规补丁场景。但这也正是已知局限中提到的：rename 操作、null header 的删除 hunk 等特殊情况可能不被正确识别，真正的生产场景需要完整的 diff 解析库（如 Python 的 whatthepatch 或 unidiff）来处理这些边界情况。

可复现的运行流程

整个验证过程不调用任何网络或模型，这正是它作为可复现产物的价值所在。你需要准备两组本地 fixture：一组干净，一组脏。

干净的 ready_ok.diff 只触碰 app.py 和 test_app.py，新增 ready() 函数及对应的 ReadyTest 测试用例；配套的 ready_ok.md 则是精确的单行测试命令。

脏的 ready_bad.diff 则是一个 forbidden-path 示例，比如往 .env 里写入占位 token（注意：这只是占位符，不是可复用的凭据）。

python3 session_gate.py session_card.yaml fixtures/ready_ok.diff fixtures/ready_ok.md
python3 session_gate.py session_card.yaml fixtures/ready_bad.diff fixtures/ready_bad.md

只在门禁通过后再应用

门禁判定为 "ok": true 且你亲自读过 diff 之后，才进入应用环节：

patch -p1 --dry-run < fixtures/ready_ok.diff
patch -p1 < fixtures/ready_ok.diff
python -m unittest test_app.py

先用 --dry-run 确保畸形的 hunk 不会在你检查 reject 列表之前就改写文件；只有在真正 apply 之后、同一工作区内才运行 unittest。一旦 dry-run、apply 或 unittest 任一环节失败，立即停止，绝不让 Agent 原地编辑。

预期结果与决策表

需要强调，这部分描述的是示例的规格说明，而非实测的生产结果或基准测试。

Fixture	改动内容	报告	预期
clean	`app.py`、`test_app.py`	精确命令行	退出 0
forbidden	新增 `.env`	精确命令行	退出 1
silent report	仅允许文件	省略命令	退出 1
broken card	任意 diff	任意报告	判定前中止

一个因卡片残缺而中止的运行仍然是失败——即便那个 diff 本身小而无害。你应把 JSON 结果记录在 fixture 旁边，这样后续运行无需依赖记忆即可比对。

还有几个值得额外测试的边界：空 diff 会因找不到文件头而被拒绝；而使用 null header 的删除 hunk 可能绕过这套扫描——如果这个 null-header 用例竟然通过了，就说明路径解析器需要先修复，再放任何 Agent 草稿靠近代码树。

免费模型接入的位置

（披露：本文作为 MonkeyCode 的产品外联内容准备。）

MonkeyCode 在此的角色，仅仅是你"可能"用来起草补丁并运行门禁的地方——如果你选择用它的话。相关说明提到存在免费模型接入和免费服务器选项，但本文不点名具体模型、配额、硬件、时长或持久性，因为这些细节未经一手来源核实。你应当假设一个免费工作区随时可能消失或重置。

一个实用的拆分方式是：用免费模型接入去起草 app.py 和 test_app.py（把卡片作为约束粘进 prompt）；用免费服务器作为一次性工作区去运行 session_gate.py 和 unittest，远离你笔记本上的密钥。但你仍要手动把 diff 拷回，仍要在 JSON 显示 ok 为 false 时拒绝补丁。当然，你完全可以彻底忽略这个产品，照样保留卡片、检查器和 fail-closed 规则。

已知局限

这是一个教学用检查器，隐藏着若干锋利的边角，复用前务必了解：

微型卡片解析器不是 YAML 库，嵌套值或带引号的冒号会让它崩溃；
路径检查只看 +++ b/ 头，巧妙或畸形的 diff 可以藏匿 rename；
报告里出现匹配的测试命令，不等于测试真的通过、甚至不等于它存在于磁盘上；
门禁看不到 Agent 在服务器端、在你下载 diff 之前就已执行的副作用；
forbidden 前缀是字面字符串，无法覆盖经过混淆的路径；
patch 命令是本地 Unix 假设，Windows 环境需要你信任的等价工具。

谁不该用这套方法：不要把它当作对抗恶意模型、恶意样本或密钥仓库的安全边界；不要把免费服务器指向生产凭据或无法吊销的远端；需要签名审查、policy-as-code 或真正 diff 解析器的团队，应当使用那些专门系统，而非这个教学脚本。

Policy-as-code 是指将安全策略、合规规则或访问控制以可版本化、可审查的代码形式表达，而非依赖手工检查或口头约定。常见工具包括 Open Policy Agent（OPA）、HashiCorp Sentinel、以及 GitHub 的 CODEOWNERS 配合 branch protection rules。这类系统能够处理更复杂的逻辑：路径通配符、角色权限矩阵、跨文件依赖检查，以及与 CI/CD 流水线的原生集成。本文的教学脚本与这类系统之间的核心差距，不只是功能丰富度，而是可审计性——专业 policy-as-code 工具会生成结构化的决策日志，支持事后溯源；而一个本地 Python 脚本的执行痕迹，只存在于你选择保留的终端输出里。

五条可带走的经验

先写白名单再发 prompt——Agent 无法在事后诚实地臆造出你的风险边界；
要求测试命令作为精确行——一句含糊的"关于测试"的话不能单独通过门禁；
卡片字段缺失即 fail closed——allow-all 的默认值正是你要移除的 bug；
结果行里不掺厂商声明——只记录你自己命令打印的退出码与 JSON；
把免费工作区当作一次性——即便只是短暂的教学演示，也绝不在那里存放长期密钥。

这则案例最终留给你的，是一张卡片、一个检查器、两条 fixture 命令，以及一条能在一分钟内向审查者讲清楚的规则：没有白名单匹配、没有具名测试，就不应用补丁。这个习惯即便日后你把脚本换成更严格的 diff 工具，依然成立。