Documentation

Everything you need to integrate and operate Patchguard.

Quick Start

Patchguard operates via a GitHub App. You can get started in three steps.

Sign in with GitHub — Click "Start Free with GitHub" at the top of the home page → authorize the OAuth app.
Select repositories — Choose one or more repos to scan on the onboarding screen.
Wait for the first scan — SBOM generation + integrated query across 5 CVE feeds takes roughly 30 seconds.

Your dashboard will immediately show the top CVEs ranked by Defense Window Score. Click the "AI Repair" button to trigger the 5-stage pipeline automatically.

AI Repair Pipeline

The core engine of Patchguard consists of 5 stages:

Stage 1 · Context Collection

Analyzes code paths that consume the vulnerable package. The reachability_service uses tree-sitter-based precision parsing to walk the import graph across 25 languages and includes only the files that actually call the vulnerable function. Test suite detection and build command extraction also happen at this stage.

Stage 2 · AI Generation

Feeds CWE + context + up to 3 similar CVE fix examples into the Forensic Tier and requests a unified diff along with fix rationale (root_cause / fix_strategy / breaking_change_risk). Automatically retries once on JSON parse failure. Falls back to the Analyst Tier if Forensic is unavailable.

Stage 3 · Sandbox Test

Runs the generated patch inside a Docker sandbox. Absolute rules:

docker run \
  --network=none \        (default) or --network=bridge + DNS whitelist
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /work:rw,size=1024m \
  --tmpfs /tmp:rw,size=256m \
  -v ${workspace}:/source:ro \
  -w /work \
  ${image}

Dependency-upgrade-only patches (lockfile-only) skip this stage and undergo offline verification instead.

Stage 4 · Security Re-scan

Semgrep + Patchguard AI jointly re-scan the patch. If the generated diff introduces new vulnerabilities (SQLi, XSS, path traversal, etc.), it is blocked before a PR is created.

Stage 5 · Confidence + PR

confidence_service computes a weighted sum of 5 signals (max 100 points):

Test Pass (or lockfile syntax validation) — up to 50
Rescan Safe — 30
No Breaking Change — 10
CVE Similar Patch Reference — 10

If the score meets the threshold (default 40), a GitHub PR is created automatically; otherwise the job transitions to manual_guide.

10 Security Lanes

Patchguard goes beyond simple CVE scanning to cover 10 integrated security lanes. Findings from all lanes share the same Defense Window Score for prioritization and the same AI Repair pipeline.

CVE — Integrated vulnerability detection via NVD · OSV · GitHub Advisory · CISA KEV · EPSS
Container — Base image + per-layer vulnerable package scanning
IaC — Misconfiguration detection for Terraform / CloudFormation / Kubernetes manifests
Secrets — Detection of hardcoded API keys, tokens, and credentials with rotation guidance
SAST — Tree-sitter static analysis across 25 languages (SQLi, XSS, Path Traversal, etc.)
Malicious Pkg — Typosquatting and supply-chain attack package identification
LLM Guard — Prompt injection detection, model output validation, and AI safety rails
ML-BOM — Machine learning model dependency inventory + license and vulnerability tracking
MCP Audit — MCP server / tool call auditing and privilege boundary verification
Agent Supply Chain — Integrity and provenance verification of AI agent tool chains

Defense Window Score

The Defense Window Score quantifies "how urgently this CVE needs to be fixed" on a 0–100 scale.

score = min(40, cvss/10 * 40)        # CVSS contribution
       + 20 if cisa_kev                    # Actively exploited
       + 15 if has_public_poc              # Public PoC exists
       + 15 if is_reachable                # Our code actually calls it
       + 5  if not patch_available         # Mitigation needed
       + 5  if epss_spike                  # EPSS +0.2↑ in 7 days

The "Urgent CVEs" section on the dashboard displays the top 5 based on this score.

SBOM Vault

You can instantly export the following formats for every connected repository:

CycloneDX 1.6 — OWASP standard, includes VEX
SPDX 2.3 — Includes license information

Endpoint: GET /api/repos/{repo_id}/sbom?format=cyclonedx

EU CRA / NIS2

Audit logs are append-only and linked via a hash chain — modifying any row breaks integrity. Verify at any time with GET /api/audit-logs/verify

Download a CRA Article 14 compliance PDF via GET /api/reports/cra-compliance/pdf?days=90

API Reference

The full OpenAPI spec is available at /docs (Swagger UI) and /openapi.json Key endpoints:

POST /api/findings/{id}/repair — Start AI repair
GET /api/repairs/{job_id} — Repair status
GET /api/defense-window — Priority list
GET /api/dashboard — Organization summary + statistics
GET /api/dashboard/posture — Security posture score
GET /api/dashboard/compliance — Framework mapping
GET /api/dashboard/attack-surface — Graph JSON
GET /api/settings/cost — Monthly AI compute cost
GET /api/audit-logs/verify — Hash chain verification

All API errors return structured JSON responses. See the full error code list (PG-XYYY) and resolution steps at Error Code Reference

Webhook Signatures

All outgoing webhooks from Patchguard include an HMAC-SHA256 signature. Header format (same as Stripe):

X-PatchOps-Signature: t=1712345678,v1=<hex>

signed_payload = ${timestamp}.${body}
v1 = HMAC-SHA256(secret, signed_payload)

When verifying, ensure the timestamp is within ±5 minutes of the current time to prevent replay attacks.

CLI

Install the Patchguard CLI and Python SDK via pip:

pip install patchguard-ai patchops-cli

Generate a key from Settings → API Keys to call directly from your CI pipeline. The key format is pk_live_.... Send it via the Authorization header:

curl -H "Authorization: Bearer pk_live_..." \
     https://patchguard.ai/api/dashboard

Key CLI commands:

# Scan repository
patchops scan --repo .

# List top CVEs by Defense Window
patchops findings --sort defense-window --limit 10

# Trigger AI repair
patchops repair --finding <finding_id>

# Export SBOM
patchops sbom export --format cyclonedx

Python SDK

Both synchronous and asynchronous clients are supported:

Synchronous client

from patchguard import PatchopsClient

client = PatchopsClient(api_key="pk_live_...")
findings = client.findings.list(sort="defense_window", limit=10)
for f in findings:
    print(f"{f.cve_id}  score={f.defense_window_score}")

Asynchronous client

from patchguard.async_client import AsyncPatchopsClient

async with AsyncPatchopsClient(api_key="pk_live_...") as client:
    findings = await client.findings.list(sort="defense_window")
    job = await client.repairs.create(finding_id=findings[0].id)
    result = await client.repairs.poll(job.id, timeout=300)
    print(result.confidence_score, result.pr_url)

The SDK fully supports automatic retries (429/5xx), timeout configuration, and type hints. It is included in pip install patchguard-ai