Why

Human review catches design issues; it misses the boring, dangerous stuff — a secret pasted into a config, a query built with string concatenation, a missing auth check. Vigil reads only the diff on every PR and reports security-relevant defects before they merge, with a severity, a confidence level, and a concrete fix. Two layers:

• Deterministic secret scan — fast regex pass over added lines (AWS/GCP/Stripe/GitHub keys, private keys, JWTs, generic secret = "..."), with placeholder filtering.
• AI review — Claude analyzes each changed file's diff for the OWASP-style weakness classes and returns structured findings.

Quick start

Add .github/workflows/security-review.yml to your repo:

name: Security review
on: pull_request

permissions:
  contents: read
  pull-requests: write   # so Vigil can post its report

jobs:
  vigil:
    runs-on: ubuntu-latest
    steps:
      - uses: nadirzhon/vigil@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Add your key once at Settings → Secrets and variables → Actions → ANTHROPIC_API_KEY. That's it — open a PR and Vigil comments with its findings.

What a report looks like

🛡️ Vigil — security review

Found 2 issue(s): 🟥 1 critical · 🟧 1 high

❌ Blocking: at least one issue is high or higher.

🟥 Possible GitHub token committed — CRITICAL

🔑 config/settings.py:14 · hardcoded-secret · confidence: high A value matching a GitHub token pattern was added to config/settings.py. Fix: Remove the secret, rotate it immediately, and load it from an environment variable.

🟧 SQL injection via string formatting — HIGH

🤖 api/users.py:42 · injection · confidence: high The query interpolates user_id directly into SQL, allowing injection. Fix: Use a parameterized query instead of f-string interpolation.

Inputs

Output: findings_count — total number of findings.

Make it advisory (don't block merges)

      - uses: nadirzhon/vigil@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail_on_severity: none

How it works

1. Reads the pull_request event and fetches changed files (with patches) via the GitHub API.
2. Skips binaries, removed files, huge diffs, and non-code paths (and your exclude globs).
3. Runs the deterministic secret scan, then an AI review per file (structured JSON output, Claude's safety refusals handled gracefully).
4. Posts a single report comment (updated in place on new pushes) and writes the job summary.
5. Exits non-zero when a finding meets fail_on_severity.

Vigil never sends your whole repo anywhere — only the diffs of changed files are sent to the Claude API for analysis.

Development

uv pip install -e ".[dev]"
pytest          # 16 tests: secret scan, gating, report rendering, review parsing (mocked)
ruff check .

Part of an AI × Security toolkit

• offsec-mcp — MCP server giving AI agents offensive-security tools (recon, CVE, JS analysis)
• specter — autonomous AI recon agent that drives those tools end-to-end
• vigil — AI security review for every pull request · (this repo)
• mcpscan — security scanner for MCP servers (tool poisoning, injection surfaces)
• State of MCP Security — research: 87% of scanned MCP servers expose a medium+ hardening issue

License

MIT — see LICENSE. Findings are AI-assisted and may be imperfect; treat Vigil as a fast first pass, not a replacement for human review.