Getting Started

What PullGuard scans

46 analyzers grouped into six capability categories. Every category produces findings with severity, file:line location, remediation guidance, and (where relevant) a dollar-cost estimate. Free tier runs 14 of the 46; paid tiers unlock the rest.

Install

Three paths — same scanner image, same workflow file, different license tier.

name: PullGuard

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # Required for git-history analyzers

      - uses: pullguard-dev/pullguard-action@v1

      - uses: pullguard-dev/pullguard-action@v1
        with:
          license-key: ${{ secrets.PULLGUARD_LICENSE_KEY }}

pullguard db status          # which database this scan will open, and how old it is
pullguard db update          # CLI installs: download or refresh your own copy

      - uses: pullguard-dev/pullguard-action@v1
        with:
          license-key: ${{ secrets.PULLGUARD_LICENSE_KEY }}
          report-to-app: true

Your first scan

On the next pull request after install, four customer-visible surfaces light up:

Customising the scan

Two configuration surfaces. Both are optional — PullGuard works out of the box.

• Workflow inputs — pass values via the with: block on pullguard-action@v1. Set the failure threshold, your developer hourly rate, the path to scan, point at a custom .driftrc.yml, etc.
• .driftrc.yml — a per-repository configuration file. Override per-language complexity thresholds, enable / disable individual analyzers, define enterprise custom rules, configure the dependency-vulnerability database location, set per-PR baseline files for delta-only scanning.
• .pullguardignore — a suppression file for false positives. File-glob patterns and rule:<rule-id> entries. Security-category analyzers cannot be suppressed.

Full reference at Configuration →.

What the output actually looks like

Before you install anything: open the live scan on our public playground repo → — a real pull request, scanned by the released Action, with the PullGuard comment and Check Run on it. Every vulnerability in that repo was planted deliberately, so every finding on the PR is a true positive.

Below is a real PR comment, abridged — it is the output of the shipped formatter on a two-file service with one SQL injection and one command injection. Nothing here is mocked up.

## 🔴 PullGuard Report

❌ **Gate: FAIL — 2 blocking critical findings (policy: fail the build on any
critical-severity finding)**

**Score: 79/100** (Grade 🔴 F) · 5 findings across 3 files

<details>
<summary><strong>Severity Breakdown</strong></summary>

| Severity    | Count |
|-------------|-------|
| 🔴 critical | 2     |
| 🟠 major    | 1     |
| 🔵 minor    | 2     |

</details>

<details>
<summary><strong>📋 SOC 2 Security Evidence</strong></summary>

**Security Posture:** 6/8 controls in good standing (1 monitoring-only),
0 concerns, 2 failures.

| Control                          | Status         | Findings |
|----------------------------------|----------------|----------|
| CC3.1 Risk Assessment            | ❌ FAIL        | 2        |
| CC6.1 Logical Access Controls    | ❌ FAIL        | 2        |
| CC6.2 Authentication / User IDs  | ✅ PASS        | 0        |
| CC6.7 Cryptographic Controls     | ✅ PASS        | 0        |

</details>

<details>
<summary><strong>🔒 Security Findings (2)</strong></summary>

| Severity    | Rule                        | File:Line       | Description                                                                | Effort |
|-------------|-----------------------------|-----------------|----------------------------------------------------------------------------|--------|
| 🔴 critical | `builtin/security-patterns` | `src/db.js:2`     | Potential SQL injection in src/db.js: user input concatenated into SQL query | medium |
| 🔴 critical | `builtin/security-patterns` | `src/refund.js:3` | Potential command injection in src/refund.js: user input passed to shell command | low |

</details>

### Top Findings

| Severity    | Rule                        | File:Line         | Description                                                | Effort  |
|-------------|-----------------------------|-------------------|------------------------------------------------------------|---------|
| 🔴 critical | `builtin/security-patterns` | `src/db.js:2`     | Potential SQL injection …                                    | medium  |
| 🔴 critical | `builtin/security-patterns` | `src/refund.js:3` | Potential command injection …                                | low     |
| 🟠 major    | `builtin/repo-hygiene`      | `<repo-root>`     | Missing CI workflows (.github/workflows/).                   | low     |
| 🔵 minor    | `builtin/dead-code`         | `src/db.js:1`     | Orphaned file: src/db.js is not imported by any other file.  | trivial |

<details>
<summary>🧰 Triage — fingerprints for <code>/pullguard ignore</code> (5)</summary>

Comment `/pullguard ignore <fingerprint> for:30d <reason>` on this PR (repo
collaborators only) to add a reviewed, TIME-BOXED `.pullguardignore` entry — it
reverts automatically and the finding comes back.

| Finding                     | File              | Triage                                            |
|-----------------------------|-------------------|---------------------------------------------------|
| `builtin/security-patterns` | `src/db.js`       | `1egz27g_126` — always-surfaced; acknowledge or a  |
|                             |                   | reasoned `false_positive` override (stays visible) |
| `builtin/repo-hygiene`      | `<repo-root>`     | `/pullguard ignore emzfz0_153 for:30d <reason>`     |

</details>

The full comment also carries the cost estimate, the health dashboard, quick wins, and — if you use them — the compliance strip and the suppression state. Security findings are always surfaced: they appear on the PR comment, the Step Summary, the JSON report, the SARIF output and the gate, and no suppression can silently remove them.

View your results

• In the PR — a summary comment plus the run's Summary tab on every scan, with a link to the graphics. (see one live →)
• Browsable graphics — a self-contained HTML report and an over-time dashboard, uploaded as the pullguard-report artifact (offline, no server). See Reports & Dashboard →.
• In your IDE — open the SARIF output in a free SARIF viewer (VS Code, Visual Studio, JetBrains, Eclipse) to click a finding straight to source, or push it to GitHub's Security tab so findings annotate the PR. See Open findings in your IDE →.

Your first 30 days

Most of what a team gets from PullGuard comes from a few switches beyond the first scan. pullguard doctor . lists which of them your repository already uses and links the rest.

1. Week 1 — commit a baseline on your base branch (pullguard scan --update-baseline), so pull requests report only what they introduce. Baselines →
2. Week 1 — upload SARIF so findings appear in the code-scanning tab and in your IDE. SARIF →
3. Week 2 — triage with reviewed suppressions in .pullguardignore: time-boxed, reason required, and security findings stay visible. Suppressions →
4. Week 3 — set SLA budgets and ownership so aged findings are flagged and the list routes itself to the people who own the code. SLA → · Ownership →
5. Week 4 — turn on what your auditors ask for: the compliance frameworks you report against, and test coverage with a minimum for new code. Compliance → · Coverage →