PrufGate

代码检查器会检查代码能否编译。PrufGate 则会查找那些能够编译、乍看之下也能通过审查，实际却无法完成任务的代码。这类代码常见于 AI 编码 Agent（或赶时间的人）为了让任务看起来已经完成而编写的内容：

• 返回硬编码成功对象的 catch 块；
• 什么也不做的点击处理程序；
• 断言 true，或模拟被测函数本身的测试；
• 悄悄混入差异中的 .skip、@ts-ignore 或降低后的覆盖率阈值；
• 导入了某个包，但没有在任何地方声明该包；
• 按 ID 加载记录，却不检查记录归属者的 API 路由。

PrufGate 具有确定性：使用纯 Python，不发起网络调用，也不使用大模型，除非你主动要求。它可在几秒内运行于拉取请求上，并生成用于代码扫描的 SARIF 和供人阅读的 Markdown。它旨在与代码检查器和 SAST 工具配合使用，而非取而代之。

六大引擎

#	引擎	检测内容
1	反伪造（prufgate/anti_fabrication）	错误路径上返回预设成功结果、模拟返回值、生产代码中的 MOCK_*/SAMPLE_* 数据、空操作 UI 处理程序、伪造的“最新”时间戳、未实现的存根、要求 LLM 在未提供任何证据的情况下给出判定的提示词，以及生产代码中的文档地址。
2	测试完整性（prufgate/anti_reward_hacking）	没有断言的测试、无法失败的断言、模拟被测单元的测试、被吞掉的异常、差异中被删除或弱化的断言、差异中被删除的测试文件或测试用例，以及针对测试字面输入特殊处理的生产代码。
3	差异防护（prufgate/diff_guard）	未提供问题引用而新增的跳过和聚焦标记（.skip、.only、xit、pytest.mark.skip、t.Skip()、#[ignore]、@Disabled）、新增到测试或测试设置中的伪退出（sys.exit(0)、process.exit(0)、模块级 SkipTest）、裸抑制项（@ts-ignore、# noqa、// nolint、#[allow]）、as unknown as T 类型转换、被弱化的 linter/CI/覆盖率设置，以及 PrufGate 自身配置中新增的豁免项。
4	契约防护（prufgate/contract_guard）	未在 package.json、pyproject.toml/requirements*.txt、go.mod 或 Cargo.toml 中声明的导入；读取时没有默认值且未在 .env.example 中列出的环境变量；前端对不存在的 API 路由的调用。
5	BOLA / IDOR（prufgate/bola）	在 Express、Next.js、NestJS、FastAPI、Flask、Django、Go（net/http、Gin、Echo、Chi）、Spring、Rails 和 Laravel 中，未设置身份验证防护或租户/所有者范围限制，却通过客户端提供的 ID 查找记录的路由处理程序。还可选择对你拥有的运行中服务进行实时双令牌探测。
6	差异审查器（prufgate/review）	针对变更行的高精度规则（由字符串拼接构建的 SQL、Shell 注入、禁用 TLS 验证、硬编码凭据、未清理的 HTML、被忽略的 Go 错误、凭据日志记录）、GitHub 建议代码块，以及可选择委派给你指定的 AI CLI 或 API。

各引擎的详细信息、规则 ID、支持的语言和已知限制：docs/ENGINES.md。

PrufGate 使用模式和结构启发式方法，而不是为每种语言使用完整解析器。它会漏检，也有时会误报正确的代码。每项发现都会注明其规则；行内 prufgate-ignore: rule -- reason 注释、豁免项和基线可用于记录原因。

快速开始

PrufGate 需要 Python 3.9 或更高版本以及 Git。

pipx install prufgate     # or: pip install prufgate  (the `prufgate` and `prufgate-mcp` commands)
prufgate --self-check     # every engine against its built-in fixtures
uvx prufgate --version    # or run it without installing, with uv

或者从最新版本（1.0.0 之后的版本）下载单个文件 prufgate.pyz。它是一个内含 PyYAML（纯 Python 实现）的 zipapp，因此只需要 Python 3.9 或更高版本：

curl -LO https://github.com/GuardianVigil-Labs/Prufgate/releases/latest/download/prufgate.pyz
curl -LO https://github.com/GuardianVigil-Labs/Prufgate/releases/latest/download/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify prufgate.pyz --repo GuardianVigil-Labs/Prufgate
python3 prufgate.pyz --self-check
python3 prufgate.pyz check .

prufgate init --hooks 写入的钩子会在 PATH 上调用 prufgate，因此请将该文件安装为命令：install -m 755 prufgate.pyz ~/.local/bin/prufgate。除 mcp 外，zipapp 可以运行 pip 安装版支持的所有命令（如需 MCP 服务，请使用 pipx install prufgate）。与 pip 安装版一样，它不包含 shell 工具套件（./prufgate.sh fast / full，需使用 ast-grep、gitleaks 和 zizmor）；prufgate.pyz fast 和 full 仅运行 Python 引擎。如需完整工具套件，请使用容器镜像或检出代码仓库。没有适用于各操作系统的原生二进制文件：每次发布都需要在三个操作系统上构建，而 zipapp 已能满足相同需求。python3 scripts/build_pyz.py 可从检出的代码仓库构建相同文件；它会从 PyPI 下载哈希锁定的 PyYAML sdist，并拒绝与 requirements.txt 不匹配的文件。

或者运行已签名的容器镜像，其中包含完整的检查流程以及 ast-grep、gitleaks 和 zizmor：

docker run --rm -v "$PWD:/workspace" ghcr.io/guardianvigil-labs/prufgate:1.1.0          # the fast gate on this repository
docker run --rm -v "$PWD:/workspace" ghcr.io/guardianvigil-labs/prufgate:1.1.0 prufgate check .

或者将 GitHub Action 添加到拉取请求工作流中，并固定为 v1.1.0 标签的提交 SHA（完整示例）：

- uses: actions/checkout@<commit-sha>
  with: { fetch-depth: 0, persist-credentials: false }
- run: python3 -m pip install "PyYAML>=6.0"
- uses: GuardianVigil-Labs/Prufgate@<commit-sha-of-v1.1.0>

每个版本都经过签名，并附带构建来源证明和 SBOM：验证版本。

或者将其添加到你的 pre-commit 配置文件 .pre-commit-config.yaml 中（详情）：

repos:
  - repo: https://github.com/GuardianVigil-Labs/Prufgate
    rev: v1.1.0
    hooks:
      - id: prufgate          # changed files, on every commit
      - id: prufgate-full     # whole repository, before a push (pre-commit install --hook-type pre-push)

然后，在你的项目中：

prufgate check .                          # engines 1-5 on the whole repository
prufgate check --changed --base origin/main   # only what this branch changed
prufgate init --hooks                     # starter config + coding-agent hooks

所有场景下的退出代码都相同：0 表示检查通过，1 表示发现阻断问题（P0/P1），2 表示 PrufGate 无法运行（配置错误、基准引用无效、文件无法读取、引擎崩溃）。发生崩溃绝不会被视为通过。

运行方式

需求	使用方式
编码时快速检查	prufgate check --changed
在 VS Code 中内联查看发现项	VS Code 扩展（源代码）：保存时运行 prufgate check --changed，仅限受信任的工作区（目前请从 .vsix 安装）
单个引擎	prufgate test-audit、prufgate bola、prufgate review
生成 SARIF 和 Markdown 报告的完整门禁	从检出目录运行 ./prufgate.sh fast（已更改的文件）或 ./prufgate.sh full。报告输出到 reports/prufgate.sarif、reports/prufgate-review.md、reports/gl-code-quality-report.json（GitLab Code Quality）和 reports/prufgate-junit.xml。
GitHub 拉取请求门禁	本仓库中的组合操作：docs/CI_INTEGRATION.md
让编码 Agent 在停止前修复其发现的问题	prufgate init --hooks（Claude Code Stop 钩子，会询问一次；Cursor 规则；pre-commit 钩子和 CI 门禁会强制执行）
阻止编码 Agent 跳过钩子、强制推送或删除测试和 CI 配置	prufgate init --hooks（Claude Code、Cursor）或 --agent copilot|codex|gemini：失败时默认拒绝的钩子会运行 prufgate hook <agent> <event>（支持情况表）
针对头部分支代码运行基分支测试（执行仓库测试：仅限沙盒或 CI，选择启用）	prufgate verify --differential --allow-run-tests
在已安装 mutmut、Stryker、PIT、gremlins、go-mutesting 或 cargo-mutants 时，对已更改行运行变异冒烟测试（执行仓库测试：选择启用）	prufgate verify --mutation --allow-run-tests
将 PrufGate 用作 Claude Code 插件（钩子加上 /prufgate:prufgate-check 技能）	pipx install prufgate，然后在 Claude Code 中运行 /plugin marketplace add GuardianVigil-Labs/Prufgate 和 /plugin install prufgate@prufgate（详情）
告知其他 Agent 和 AI 审查工具（Cursor Bugbot、Copilot review）使用 PrufGate 的发现结果	prufgate init --agents-md（AGENTS.md）和 --bugbot（.cursor/BUGBOT.md）：添加标记区段，重新运行时在原处更新（详情）
仅针对 PrufGate 自身低置信度发现结果获取 AI 第二意见（选择启用，会向你选择的提供方发送几行代码）	在配置中设置 ai_adjudicate: true：参见 AI 仲裁
供 Agent 通过 MCP 使用的工具	prufgate mcp：九个只读工具
通过 webhook 扫描的服务	prufgate api：使用 bearer token，默认仅监听环回地址

完整的命令和选项参考见 docs/GETTING_STARTED.md，所有配置项见 docs/CONFIGURATION.md。

配置一览

PrufGate 无需配置即可运行。如需调整，请添加 .prufgate/config.yaml：

version: 1
packs: [core, web-ui, ai-safety]      # cti is an opt-in domain pack
exclude: ["dist/**", "vendor/**"]
auth_guards: [requireUser, get_current_user]
tenant_keys: [organization_id, account_id]
exempt:
  src/legacy/adapter.ts:
    route-canned-fallback: "#104: legacy fallback until the payments API migration"
known_debt:
  stub-click-handler: 0                # a ceiling that can only go down

在拉取请求中（任何带有基准分支引用的运行），PrufGate 会读取该文件在基分支上的版本，因此配置更改会在合并后生效：更改不能豁免自身产生的发现问题。

AI 裁定

PrufGate 默认采用确定性方式运行，不会向任何地方发送数据。两种可选模式会使用你选择的 AI 提供商（claude CLI、OPENAI_API_KEY、ANTHROPIC_API_KEY 或 OLLAMA_HOST；--ai-provider 可指定其他提供商）：

• prufgate review --ai 会要求模型审查整个差异。
• 在配置中设置 ai_adjudicate: true（在拉取请求中，由 prufgate check 和 prufgate.sh 门禁在基础引用处读取；单独使用 --ai-adjudicate 不起作用）后，会针对每个低置信度发现提出一个是非问题（如有配置，也包括 medium）：这是真的吗？提示词包含规则、发现说明及周围几行经过脱敏的代码，不会包含完整文件。

裁定结果只能用于过滤噪声。被判定为不真实的发现不再阻止流程，并会移至“AI-dismissed”列表，附上模型给出的原因：该列表会显示在 prufgate check 输出和 Markdown 报告的一个部分中，也会作为类型为 external 的 SARIF suppressions 条目（AI-dismissed: <reason>）出现。高置信度发现绝不会发送；绝不会添加或提高任何发现。提供商出错、超时、回复不完全符合 {"real": true|false, "reason": "..."} 格式、运行超出预算，或代码中包含针对裁判的内容（评论中提及 AI、LLM、裁判、审查者或 PrufGate），都会使该发现保留其在未启用 AI 时的状态。裁定结果会缓存在仓库之外。设置说明：docs/CONFIGURATION.md。

文档

• 入门指南：安装、命令、报告、退出代码
• 配置参考：所有配置项、抑制规则、环境变量
• 引擎：规则、语言和限制
• CI 和 Agent 集成：GitHub Action、其他 CI、Agent 钩子、MCP、REST API
• 自定义规则：你自己的 ast-grep 规则和钩子
• 架构
• 基准测试：在已标注语料库上测得的精确率和召回率，以及如何添加案例
• 更新日志

贡献与安全

欢迎贡献：请参阅 CONTRIBUTING.md 和维护者指南 AGENTS.md。请按照 SECURITY.md 中的说明，私下报告安全漏洞。

PrufGate 由 GuardianVigil 根据 Apache License 2.0 发布。名称和徽标均为商标：请参阅 TRADEMARKS.md。