Browsable, shareable scan output with no server and no network. Everything renders to a single self-contained HTML file — it works fully offline, so air-gapped teams get a dashboard feel without standing up a service.
Every PullGuard surface leads with a grade and a drift score. The score runs 0–100 and lower is better — it is a severity-weighted measure of finding density, so a big healthy codebase is not punished for its size.
| Grade | Score | What it means |
|---|---|---|
| A | 0–15 | Excellent — minimal drift, well-maintained. |
| B | 16–35 | Good — some issues, nothing urgent. |
| C | 36–55 | Needs attention — tech debt accumulating. |
| D | 56–75 | Significant problems — active remediation needed. |
| F | 76+ | Critical — security or architecture issues demanding immediate action. |
Not every category counts the same. Security carries double weight, because a vulnerability is not the same kind of problem as an inconsistent name:
security ×2, operations ×1.5, architecture/complexity ×1.2,
dependencies/history/quality ×1, documentation/imports/patterns/structure ×0.8, naming ×0.6
The same legend is printed on the HTML report, the CI step summary and the PR comment, and it is generated from the scoring code itself — so what you read can never drift from what produced the grade. Informational findings contribute nothing to the score.
pullguard scan . --format html > pullguard-report.html
One .html with grade/score/findings/cost cards, a severity bar, the trend
strip, and a findings table you can filter by severity. Each finding shows two date columns:
git blame), with commit + author. Present with --blame..pullguardignore entry (and the /pullguard ignore command where it applies), so a reviewer who decides "not a real issue" can record that decision without leaving the report. Security findings that always surface get the reviewed, reason-required path instead, and stay visible.taint-flow / interprocedural (a dataflow from an attacker-controlled source to a sink was traced, within a file or across functions and files), content-shape (a structured agent/MCP config was parsed and its shape is the evidence), or pattern (a calibrated pattern rule matched — no proven flow is claimed). Triage the proven flows first. The tier is display metadata only: it never changes a severity, a grade, or whether a finding blocks.| Date | What it is | How |
|---|---|---|
| First discovered by PullGuard | Finding age & "new since" — when a fingerprint first appeared. | Persisted in .drift-history.json; always on. Commit it so dates survive CI. |
| Introduced | When/by-whom the code was written. | Local git blame via --blame (opt-in). Fully local, air-gap-safe. |
Both dates are also present in --format json output.
pullguard scan . --format ai-bom > pullguard-ai-bom.json
Enterprise. A standard
CycloneDX 1.6 machine-learning
bill of materials, derived from the same AI Usage inventory that powers the report's
AI Usage panel — one machine-learning-model component per distinct
model your code calls, plus an application component per provider, each
carrying call-site counts and a pullguard:dataEgress flag (set when a
secret or PII was observed flowing into that call). Consumable by BOM tooling and
useful as procurement / EU AI Act / NIST AI RMF evidence of which AI components a
codebase actually depends on. Model names are sourced from scanned (untrusted) code,
so they're allowlist-sanitized before inclusion. An empty components: []
array is a valid, honest result on a repo with no detected AI-provider calls.
pullguard dashboard . -o pullguard-dashboard.html
A self-contained dashboard built from your local history. Click any chart point (or history row) to drill down to that scan's findings and their file:line — no server required.
.pullguardignore entry (or /pullguard ignore command) uses, so triage decisions can be made from the dashboard.Build history by scanning over time (e.g. on every push to main or on a schedule)
and committing .drift-trend.json + .drift-scan-details.json
(see State files to commit).
dashboard.retainScans in .driftrc.yml controls how many recent scans keep
finding-level detail (default 50; 0 = keep all).
A CI run starts from a fresh checkout, so anything PullGuard compares against a previous scan must be committed to the repository. A file that is missing is treated as “no previous scan”: nothing is reported as changed, and the features below stay silent rather than guessing.
| File | Written | What needs it |
|---|---|---|
.drift-baseline.json | By --update-baseline (Action: update-baseline: true) | Baseline mode — pull requests report only what they introduce. See Configuration. |
.drift-history.json | Every scan | First-seen dates: finding age, “new since”, and aging budgets. |
.drift-trend.json | Every scan | The over-time dashboard’s trend. |
.drift-scan-details.json | Every scan | The dashboard drill-down (dashboard.retainScans scans kept). |
.drift-agent-config.json | Every scan of a repository with an MCP configuration | agent_config_drift — an MCP tool definition that changed after approval. Without it every CI run is a first scan and the rule cannot fire. Stores hashes only, never the definitions. |
.drift-signatures.json | By --update-baseline | Optional. breaking_change compares against the git merge base; this file is used only when a scan has no git history to compare with. |
.pullguardignore | By you, or pullguard ignore | Triage decisions. See Configuration. |
.drift-cache.json is a local scan cache and does not need to be committed.
PullGuard never writes a state file through a symbolic link the repository commits under one of these names.
pullguard dashboard --org ./all-repos -o portfolio.html
A 10,000-ft view across every repository PullGuard runs on — one self-contained page for leadership and platform teams. Point it at a directory where each repo's history lives (each repo commits its own history file, or a CI job collects them into one folder):
Same air-gapped, single-file design — nothing hosted, nothing leaves your boundary.
The GitHub Action renders both files on every run and uploads them as the
pullguard-report artifact — no extra steps:
pullguard-report.html — the per-scan report.pullguard-dashboard.html — the over-time dashboard.workflow_dispatch: to your workflow's on: block to get a "Run workflow" button on the Actions tab — regenerate the report + dashboard from the web UI, no commit needed.How to view the graphics: open the run → Artifacts → download pullguard-report, unzip, and open either .html in any browser.
GitHub doesn't render interactive HTML inline (it strips scripts/SVG from comments & summaries), so the rich report/dashboard are download-and-open. To view at a URL instead, publish the artifact to GitHub Pages — but that makes it web-hosted, so keep it off for air-gapped/confidential repos.
Any scanner can report zero findings. Few can show that the scan actually looked. Every run writes
pullguard-scan-attestation.predicate.json (and an unsigned in-toto statement,
pullguard-scan-attestation.intoto.json) next to pullguard-report.json. It records what the scan
read, which analyzers ran or did not finish, where the zero-day rules came from, how old the vulnerability data was, and
the SHA-256 of the exact report. It also records the commit scanned, whether the scan was a pull-request delta, and
which paths your configuration excluded. It then gives a strict completeness verdict
with its reasons: a truncated read, a failed file read, a code file too large to read (over 500 KB), an analyzer that did not finish or that your licence tier allows
but that did not run, a tier that does not run the security analyzers, a degraded engine, zero-day rules that did not
run, missing, stale or undated vulnerability data, a scanned commit that was not recorded, a checked-out tree that is
not the recorded commit, a scan of only a subdirectory, a pull-request scan whose own .driftrc.yml could
not be checked against the base branch, or any of these facts not being recorded at all. To gate a workflow on it, run
pullguard attest check --require-complete (below).
What "complete" is relative to. Complete means every file inside
the configured scope was read and every analyzer your tier allows ran. The scope is your base branch's configuration:
the paths it excludes are recorded in the predicate (config.userExcludes) so a reviewer can see them, but
they are not a reason on their own. A scan served from the local cache (--cache) cannot attest complete,
because the cached report does not carry the facts the verdict needs.
It proves completeness, not cleanliness. A complete scan can still have findings, and a clean scan is not proof of no vulnerabilities. It does not prove the scanner binary is genuine; pin and verify the image digest for that.
Signing uses your workflow's identity, never ours. A key shipped in the scanner image could be copied and used to forge a "complete" verdict, so PullGuard does not sign. Add GitHub's artifact attestation step after the scan (check GitHub's documentation for which plans support attestations on private repositories):
permissions:
contents: read
id-token: write
attestations: write
artifact-metadata: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the base branch must be present, or a pull request's own config cannot be checked
- uses: pullguard-dev/pullguard-action@v1
with:
license-key: ${{ secrets.PULLGUARD_LICENSE_KEY }}
- uses: actions/attest@v4
with:
subject-path: pullguard-report.json
predicate-type: https://pullguard.dev/attestations/scan-completeness/v1
predicate-path: pullguard-scan-attestation.predicate.json
To verify, pin who signed it and what it is about. A valid signature only says that some workflow in your repository produced the file. Check that it was the scanning workflow you expect, running on your protected branch, at the commit you care about, then check that the predicate still matches the report and re-derive the verdict:
gh attestation verify pullguard-report.json --repo your-org/your-repo \
--predicate-type https://pullguard.dev/attestations/scan-completeness/v1 \
--signer-workflow your-org/your-repo/.github/workflows/pullguard.yml \
--source-ref refs/heads/main \
--source-digest <commit-sha> \
--deny-self-hosted-runners
pullguard attest check --report pullguard-report.json \
--attestation pullguard-scan-attestation.predicate.json \
--expect-commit <commit-sha> --require-complete
Use attestations from protected-branch runs as audit evidence, not
pull-request runs. A pull request can edit the workflow that signs its own run, so a signature from a
pull-request run proves little about how the scan was configured. --signer-workflow and
--source-ref reject those. On a pull-request run the scanned commit is GitHub's merge commit, not the head
of the branch. Run the attest step only when the scan step succeeded (not with if: always() or after
continue-on-error), so a failed run never signs anything.
pullguard attest check exits 0 when the attestation matches the report,
1 when it does not (the report or the predicate was changed — this is never a soft warning),
2 when an input cannot be read, and 3 with --require-complete when the scan was not
complete. --expect-commit fails (exit 1) unless the report scanned exactly that full commit
hash, and --expect-image-ref does the same for the scanner image reference recorded in the predicate.
The GitHub Action does not record the image reference yet, so use --expect-image-ref only for scans where
you set PULLGUARD_IMAGE_REF (or attest build --image-ref) yourself; on an Action run it fails.
A checker of a different PullGuard version than the scanner reports that it cannot re-derive the analyzer set rather
than an edit; check with the scanner's version.
--predicate-type is required on gh attestation verify: without it, the command looks
for SLSA provenance instead. pullguard attest build writes the same two files from any saved report, for
scans run outside the Action.
For a Java taint finding, PullGuard names the concrete request that delivers the input to the flow: the
HTTP method, the route (a Spring class-level prefix composed with the method mapping, a JAX-RS class
@Path composed with the method's @Path under the application's @ApplicationPath, or a servlet's @WebServlet or
WEB-INF/web.xml pattern, with a wildcard filled as /api/x), the parameter (by its HTTP name, not its Java name) and an inert marker such as
PGW-1a2b3c4d. For example: GET /api/users/search?q=PGW-1a2b3c4d. Send it to a test
environment and look for the marker at the reported sink.
For JavaScript and TypeScript (Express-style app.get('/path', …) / router.post(…)
routes with an inline or same-file handler) and Python (Flask-style @app.route(…) / @bp.post(…)), the
same request is derived from the route and the request read on the source line: a query or path parameter, a header,
a cookie, a form field or a JSON/form body field (for example DELETE /files/PGW-1a2b3c4d). A route counts only
when its handler's own request argument is the one the source reads, so an HTTP-client call of the same shape is never
taken for a route. Authentication middleware or decorators seen on the route are reported beside the request; their
absence is reported as unknown, never as unguarded.
The witness appears in the PR comment's taint-flow list, in SARIF result properties
(witness, witnessStatus, witnessAuth, witnessReason) and in the HTML
report. It proves that the request delivers attacker-controlled input to the flow.
It does not claim the flow is exploitable, and no payload is generated. It never changes a finding's severity, the
gate or the finding's identity.
When no request can be derived, the finding says why (for example no-route-in-file for a
helper class, source-via-helper when the value comes through a wrapper method, or
route-index-bounded when a very large controller file exceeded the per-file bound on this display work). No witness is not "not reachable": the flow is still reported. A witness is derived from the
source text, so it names the route and binding lines it was read from for a reviewer to check. Coming next:
request-body fields for Java.
Developers can jump from a finding straight to the offending line inside their editor — no PullGuard-specific plugin to install. PullGuard emits SARIF (the industry-standard static-analysis format), and every major IDE has a free SARIF viewer that turns each result into a click-to-source jump, resolved against your open checkout.
1. Get the SARIF file. The GitHub Action uploads
pullguard.sarif inside the pullguard-report artifact automatically (v1.3.2+) — just
download it. To generate it directly (locally, or in the container/CLI form):
pullguard scan . --format sarif > pullguard.sarif
You can also send it straight to GitHub's Security tab, so findings annotate the PR and appear in code scanning:
- run: pullguard scan . --format sarif > pullguard.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: pullguard.sarif # needs: permissions → security-events: write
Copy-paste workflow: docs/sarif-security-tab.example.yml (runs the image, uploads to the Security tab, and keeps the SARIF as an artifact for IDE viewers).
2. Open it in your IDE with the repository as the open folder/project — PullGuard's SARIF paths are repo-root-relative, so the viewer maps each finding to your local file:
| IDE | Free viewer | How |
|---|---|---|
| VS Code | Microsoft SARIF Viewer (open-source) | Install from the Marketplace → "SARIF: Open" → pick pullguard.sarif → click any result. |
| Visual Studio | Microsoft SARIF Viewer | Open the .sarif file; results dock into the Error List with go-to-source. |
| JetBrains (IntelliJ, PyCharm, GoLand, …) | Qodana plugin / SARIF import | Import the .sarif; findings appear in the Problems view, click to navigate. |
| Eclipse | SARIF viewer plugin | Open the .sarif file; results link to source. |
| GitHub (zero install) | Security tab (code scanning) | The upload-sarif step above renders findings inline on the PR + in the Security tab. |
Tip: open the SARIF with the repo at its root so relative paths resolve. The HTML report's clickable links (above) go to your git host in a browser; the SARIF route opens the file in your editor — use whichever fits the moment.
For VS Code there is also a dedicated PullGuard extension (v1.3.3+). It reads
the pullguard-report.json your CI or CLI already produces and shows findings inline:
No scanner runs in the editor — the extension just renders the report — so it's tiny and needs
no license key. When the report was produced with --blame, it also shows each
finding's introduced date and owner.
The extension is rolling out to the VS Code Marketplace — contact us for early access. The SARIF viewers above remain the primary, available-today IDE path (and cover every other editor).
Run the portfolio aggregator in a dedicated platform repo (on a schedule or via the
"Run workflow" button). It collects each repo's committed history and renders one
portfolio.html artifact — see docs/portfolio-workflow.example.yml.
All three outputs are single files with zero external references — no CDN, fonts, analytics, or network calls. Generate them on an isolated runner, copy them anywhere, open them in any browser. The data lives entirely in your repo; nothing is hosted and nothing leaves your boundary.