PrufGate

Checks whether code, and the tests that claim it works, are real.

Linters check that code compiles. PrufGate looks for code that compiles, passes review at a glance and still does not do the job. This is the kind of code an AI coding agent (or a hurried human) writes to make a task look finished:

• a catch block that returns a hard-coded success object;
• a click handler that does nothing;
• a test that asserts true, or mocks the very function it tests;
• a .skip, @ts-ignore or lowered coverage threshold slipped into a diff;
• an import of a package that is not declared anywhere;
• an API route that loads a record by ID without checking who owns it.

PrufGate is deterministic: plain Python, no network calls and no LLM unless you ask for one. It runs in seconds on a pull request, and writes SARIF for code scanning and Markdown for humans. It is meant to sit next to your linters and SAST tools, not replace them.

The six engines

Details, rule IDs, supported languages and known limits for each engine: docs/ENGINES.md.

PrufGate uses pattern and structure heuristics, not a full parser for every language. It will miss things and it will sometimes flag correct code. Every finding names its rule, and inline prufgate-ignore: rule -- reason comments, exemptions and baselines let you record why.

Quick start

PrufGate needs Python 3.9 or newer and 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

Or download one file, prufgate.pyz, from the latest release (releases after 1.0.0). It is a zipapp with PyYAML (pure Python) inside, so it needs nothing but Python 3.9 or newer:

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 .

The hooks that prufgate init --hooks writes call prufgate on PATH, so for them install the file as a command: install -m 755 prufgate.pyz ~/.local/bin/prufgate. The zipapp runs every command a pip install has except mcp (use pipx install prufgate for the MCP server). Like a pip install, it does not include the shell batteries (./prufgate.sh fast / full with ast-grep, gitleaks and zizmor); prufgate.pyz fast and full run the Python engines only. For the full battery use the container image or a checkout. There are no native per-OS binaries: they would need a build on three operating systems for every release, and the zipapp covers the same need. python3 scripts/build_pyz.py builds the same file from a checkout; it downloads the hash-locked PyYAML sdist from PyPI and refuses one that does not match requirements.txt.

Or run the signed container image, which adds the full gate with ast-grep, gitleaks and zizmor:

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

Or add the GitHub Action to a pull-request workflow, pinned to the commit SHA of the v1.2.0 tag (full example):

- 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.2.0>

Every release is signed and carries build provenance and an SBOM: Verify a release.

Or add it to your pre-commit configuration, .pre-commit-config.yaml (details):

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

Then, in your project:

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

Exit codes are the same everywhere: 0 clean, 1 blocking findings (P0/P1), 2 PrufGate could not run (bad config, bad base ref, unreadable file, engine crash). A crash never reads as a pass.

Ways to run it

The full command and option reference is in docs/GETTING_STARTED.md, and every configuration key is in docs/CONFIGURATION.md.

Configuration in one look

PrufGate works without configuration. To tune it, add .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

In a pull request (any run with a base ref) PrufGate reads this file as it is on the base branch, so configuration changes take effect after merge: a change cannot exempt its own findings.

AI adjudication

PrufGate is deterministic by default and sends nothing anywhere. Two opt-in modes use an AI provider you choose (a claude CLI, OPENAI_API_KEY, ANTHROPIC_API_KEY or OLLAMA_HOST; --ai-provider names another):

• prufgate review --ai asks the model to review the whole diff.
• ai_adjudicate: true in the configuration (read at the base ref in a pull request, by prufgate check and the prufgate.sh gate; --ai-adjudicate alone does nothing without it) asks one yes/no question per low-confidence finding (medium too if configured): is this real? The prompt holds the rule, the finding message and a few redacted lines around it, never whole files.

An adjudication verdict can only hide noise. A finding judged not real stops blocking and moves to an "AI-dismissed" list with the model's reason: a section of prufgate check output and of the Markdown report, and a SARIF suppressions entry of kind external (AI-dismissed: <reason>). High-confidence findings are never sent; nothing is ever added or raised. A provider error, a timeout, a reply that is not exactly {"real": true|false, "reason": "..."}, a run over its budget, or code that addresses the judge (a comment naming the AI, LLM, judge, reviewer or PrufGate) keeps the finding as it would be without AI. Verdicts are cached outside the repository. Settings: docs/CONFIGURATION.md.

Documentation

• Getting started: install, commands, reports, exit codes
• Configuration reference: every key, suppressions, environment variables
• The engines: rules, languages and limits
• CI and agent integration: GitHub Action, other CI, agent hooks, MCP, REST API
• Custom rules: your own ast-grep rules and hooks
• Architecture
• Benchmark: measured precision and recall on a labelled corpus, and how to add a case
• Changelog

Contributing and security

Contributions are welcome: see CONTRIBUTING.md and the maintainer guide AGENTS.md. Please report vulnerabilities privately, as described in SECURITY.md.

PrufGate is published by GuardianVigil under the Apache License 2.0. The name and logo are trademarks: see TRADEMARKS.md.