Incremental scanning with --diff

Scan only the files that changed and the code connected to them, instead of the whole repository. On a large codebase this turns a multi-minute CI check into a few seconds, without missing cross-file vulnerabilities.

Why use it

A full gadriel code scan re-analyzes every file every time — its cost scales with repo size, not change size. A one-line pull request pays the same wall-clock as a from-scratch audit, and it repeats on every push.

--diff scopes the work to the changed files and their dependency closure (the files they import and the files that import them), so cross-file taint is still caught, and merges the result into your existing .security/findings.json.

Quick start

bashCOPY
# Scan only what changed since the base branch (auto-detected)
gadriel code scan --diff

# Diff against a specific ref
gadriel code scan --diff origin/main
gadriel code scan --diff HEAD~1

The first scan of a repo is always full — --diff is an update, not a bootstrap. After that, incremental scans merge into the baseline.

How it decides what to scan

Given the changed files, --diff builds a scan set:

scan set  =  changed files
           ∪ files they import        (forward closure)
           ∪ files that import them   (reverse closure)

The closure is why --diff stays sound: if you change a request handler and the vulnerable sink lives in an unchanged helper it calls, that helper is pulled into the scan set and the finding still fires. Findings on files outside the scan set are carried over unchanged from your last full scan.

Per scanner:

Choosing the diff base

Bare --diff resolves the base automatically, most-specific first:

1. An explicit ref you pass: --diff <ref> or --diff-base <ref>
2. CI pull-request target — GITHUB_BASE_REF (GitHub), CI_MERGE_REQUEST_TARGET_BRANCH_NAME (GitLab) → merge-base with HEAD
3. CI push event — the previous SHA (GITHUB_EVENT_BEFORE / CI_COMMIT_BEFORE_SHA)
4. Local — merge-base with your upstream branch, else HEAD~1

Every scan logs the base it chose, so you can always see what was compared.

Flags

When --diff falls back to a full scan

--diff never silently under-scans. When it can't compute a sound incremental scope it runs a full scan and records a coverage advisory in the report. It falls back when:

Language coverage

The report tells you it was incremental

A --diff scan tags .security/findings.json so no downstream consumer mistakes it for a full audit:

jsonCOPY
{
  "scan_scope":    "diff",
  "diff_base":     "9be40051…",
  "files_scanned": 4
}

A full scan (including a --diff that fell back) carries "scan_scope": "full".

CI recipe

Run --diff on pull requests (fast, per-push) and a full scan on merges to main (authoritative — it refreshes the baseline the incremental scans merge into).

yamlCOPY
# .github/workflows/gadriel.yml
on: [pull_request, push]

jobs:
  gadriel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # REQUIRED — --diff needs the base commit

      - name: Install gadriel
        run: npm install -g gadriel@latest

      # Pull requests: fast incremental scan
      - name: Incremental scan
        if: github.event_name == 'pull_request'
        run: gadriel code scan --diff --fail-on high

      # Merge to main: full scan refreshes the baseline
      - name: Full scan
        if: github.ref == 'refs/heads/main'
        run: gadriel code scan --fail-on high

Trust it: --diff-verify

To prove that incremental scans aren't hiding anything, run the canary on a schedule (e.g. nightly):

bashCOPY
gadriel code scan --diff origin/main --diff-verify

It scans diff-scoped and full, then compares. It exits non-zero if any finding the full scan produced on the scanned files is missing from the diff scan. Green means your incremental scans are sound on your codebase.

Troubleshooting

See also

• gadriel code scan --help — the full flag reference
• ADR-184 — the incremental-diff design and soundness contract