fjwood69/gated

# gated  **一个评判你的代码“做了什么”而不是“说了什么”的晋升门控。** [PBGF 一致性规范](https://moriapp.dev/pbgf-cs)的参考实现 —— 一项针对机器生成代码的晋升裁决标准。 `gated` 在一个密封的 OCI sandbox 中执行 pull-request 代码，在网络边界处观察其行为，并发布一个必需的 GitHub Check。违反已接受 runtime invariant 的代码无法合并。 典型的例子：一个看起来像是在重试失败请求的 helper，却悄悄地吞掉了失败。阅读 diff 的审查者看到的是重试。linter 看到的是有效的代码。编写它的 agent 会流利地解释为什么它是正确的。`gated` 运行它，监视 socket，计算 egress 尝试次数，并看到了真相。 ## 为什么是 runtime，而不是静态的 静态分析推理的是程序的*文本*。任何阅读代码的检查都可以被那些表面阅读是一回事、实际运行是另一回事的代码所击败 —— 而在 agentic workflows 中，编写代码的生产者通常也编写了测试。`gated` 不阅读代码，也不信任生产者的测试：它在观察下运行 artifact，并对**观察到的边界行为**进行断言。通过意味着行为实际发生了，而不是源码看起来像会发生。 ## 工作原理 ``` GitHub webhook │ ▼ durable queue ──▶ policy admission ──▶ hermetic execution │ ▼ boundary observation │ ▼ PASS / FAIL / ERROR │ ▼ durable publication outbox │ ▼ required GitHub Check + audit ledger ``` 裁决仅取决于主机端的观察和受信任的策略输入。 **pull request 不能提供自己的策略、fixtures、detector 或裁决。** ## 核心特性 - **Runtime 证据：** 断言评估的是观察到的行为，而不是源码文本。 - **密封执行：** 生产路径使用具有封闭网络的 Podman；唯一的 egress 是被观察的 proxy。 - **Fail closed：** `ERROR` —— 门控无法干净地观察 —— 映射为 GitHub `action_required` 并**阻止**合并。这是 PBGF-CS 的 UNATTESTABLE 裁决的 Check-Run 表面：没有证据绝不等于通过。一个 fail open 的门控只是虚设；`gated` 拒绝这样做。 - **多次试验一致性：** N 次独立试验（每次试验使用全新的 sandbox 和网络）。任何 `FAIL` 都会导致裁决失败 —— 不稳定的违规仍然是违规，因此 `FAIL` 路径会短路。`PASS` 需要一致同意。 - **执行前校准：** 一个 detector 只有在经过双向校准后才能拥有阻止权限 —— 它必须捕获每一个已知的不良 fixture，*并且*通过每一个已知的良好 fixture。 - **权限分离：** 测量不能将自己提升为执行；启用是一个独立的、受治理的决策。 - **运行后准入：** 只有在准入时策略、oracle 和 subject 身份仍保持最新的情况下，结果才会被准入。 - **持久发布：** Check Run 更新通过事务性、可重试的 outbox 进行；GitHub 的宕机不会静默丢弃最终结果。 ## 覆盖账本 分支保护允许管理员在必需的检查失败时强制合并。`gated` 会记录这一点：如果合并没有理会非 `PASS` 的裁决，就会写入一条**只能追加的、hash-chained** 的记录 —— *“门控的裁决是 FAIL；但该 PR 仍然被合并了。”* 它只记录门控本身可以证明的内容，仅此而已。每一次合并要么是被门控批准的，要么是被有意识地覆盖的，并留有记录。 ## 仓库布局 - `core/` — 共享 contracts 和值类型 - `sandbox/` — subprocess 和 OCI 执行后端 - `observe/` — 主机端边界观察 - `engine/` — 试验、聚合和 runtime 断言 - `gate/` — 校准、治理、准入、GitHub App 和持久化存储 - `cli/` — 命令行包 - `tests/` — 单元、对抗性和真实的 Podman 测试 请参阅 [ARCHITECTURE.md](ARCHITECTURE.md) 了解信任边界、invariants 和已知的部署限制，以及 [COMPLETENESS.md](COMPLETENESS.md) 了解每个增量在发布前必须通过的完整性门控。 ## 开发 需要 Python 3.9 或更高版本。 ``` git clone https://github.com//gated.git cd gated python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e . ``` 运行测试套件： ``` python -W error -m unittest discover -s tests ``` 运行静态门控： ``` mypy --strict core sandbox engine observe gate cli ruff check . python scripts/check-overclaim.py python scripts/check-sterility.py ``` 需要 OCI runtime 的测试在 Podman 或配置的测试镜像不可用时会自动跳过；只要存在其中之一，边界机制就会得到完整的测试。 ## 部署 实时的 adapter 位于 `gate/live_app.py` 中。部署需要： - 一个具有 webhook 和 Checks 权限的 GitHub App； - 需要配置的 Check 名称的分支保护； - Podman 和一个不可变的 detector 镜像； - 独立接受的 detector-profile 和策略身份； - 独立的队列、策略、校准和审计存储； - 受保护的签名和 webhook 密钥。 这种设置特意没有以一键式生产安装的形式提供。 在操作实时路径之前，请阅读 [ARCHITECTURE.md](ARCHITECTURE.md)。 ## 安全边界 `gated` 证明了这里实现的机制；它并不证明主机。 内核、OCI runtime、observer、Python 进程和本地密钥保管仍然是受信任的。生产环境的加固需要诸如隔离的 detector 进程、外部签名的内容寻址 artifacts、KMS/HSM 支持的密钥以及独立管理的治理权限等控制措施。 特别是： - 准备好合并并不意味着安全完整性达标； - 安全完整性达标并不意味着在实践中得到证明 (live-proven)； - 身份绑定不能证明主机未被入侵； - 校准的盲目性假设了这是一个受信任的 detector。 精确的声明和残留风险记录在[ARCHITECTURE.md](ARCHITECTURE.md)中。 ## 与 PBGF-CS 的关系 本仓库实现了 [PBGF-CS](https://moriapp.dev/pbgf-cs) 的四项一致性要求 —— 机械化的分层分配、阻止权限的双向校准、受限和预注册的裁决，以及在缺乏证据时 fail-closed —— 这些都是通过本仓库运行的路径实现的。 按照发布的方式在你自己的证据上运行时，它支持 **Level 1 (self-attested)** 的一致性姿态。Levels 2–3（强制分离、独立证明）需要上述描述的部署加固。 ## 许可证 Apache-2.0 — 见 [LICENSE](LICENSE)。本仓库中的所有内容都是免费的，包括用于商业生产用途；[COMMERCIAL.md](COMMERCIAL.md) 描述了什么是和不是免费的（剧透：这个仓库完全是免费的）。

标签：SOC Prime, 代码审查, 开发工具, 行为验证, 逆向工具