← Docs

Reports & Dashboard

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.

How grading works

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.

GradeScoreWhat it means
A0–15Excellent — minimal drift, well-maintained.
B16–35Good — some issues, nothing urgent.
C36–55Needs attention — tech debt accumulating.
D56–75Significant problems — active remediation needed.
F76+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.

Per-scan HTML report

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:

Finding dates

DateWhat it isHow
First discovered by PullGuardFinding age & "new since" — when a fingerprint first appeared.Persisted in .drift-history.json; always on. Commit it so dates survive CI.
IntroducedWhen/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.

AI Bill of Materials (CycloneDX ML-BOM)

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.

Over-time dashboard

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.

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

State files to commit

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.

FileWrittenWhat needs it
.drift-baseline.jsonBy --update-baseline (Action: update-baseline: true)Baseline mode — pull requests report only what they introduce. See Configuration.
.drift-history.jsonEvery scanFirst-seen dates: finding age, “new since”, and aging budgets.
.drift-trend.jsonEvery scanThe over-time dashboard’s trend.
.drift-scan-details.jsonEvery scanThe dashboard drill-down (dashboard.retainScans scans kept).
.drift-agent-config.jsonEvery scan of a repository with an MCP configurationagent_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.jsonBy --update-baselineOptional. breaking_change compares against the git merge base; this file is used only when a scan has no git history to compare with.
.pullguardignoreBy you, or pullguard ignoreTriage 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.

Portfolio view — every project at once

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.

In CI — automatic artifacts

The GitHub Action renders both files on every run and uploads them as the pullguard-report artifact — no extra steps:

Trigger & view from GitHub

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.

Scan-completeness attestation (v1.5.18+)

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.

Exploit witnesses: the request that reaches the flow (v1.5.18+, Java, JavaScript/TypeScript, Python)

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.

Open findings in your IDE (click to source)

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:

IDEFree viewerHow
VS CodeMicrosoft SARIF Viewer (open-source)Install from the Marketplace → "SARIF: Open" → pick pullguard.sarif → click any result.
Visual StudioMicrosoft SARIF ViewerOpen the .sarif file; results dock into the Error List with go-to-source.
JetBrains (IntelliJ, PyCharm, GoLand, …)Qodana plugin / SARIF importImport the .sarif; findings appear in the Problems view, click to navigate.
EclipseSARIF viewer pluginOpen 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.

PullGuard for VS Code (extension)

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

Portfolio across many repos

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.

Air-gapped by design

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.