PatchSense

PatchSense reads your lockfiles, looks up every pinned package in OSV, and ranks each advisory from 0 to 100 using CISA KEV (known exploited), FIRST EPSS (exploit probability), CVSS, whether the package is a direct dependency, and whether a fix exists. Instead of a flat list of CVEs you get three tiers, Critical, Review, and Defer, so you know what to patch first. It runs locally, caches data in SQLite, works offline from that cache, writes table, JSON, SARIF, Markdown, and GitLab reports, can post a pull-request or merge-request comment, and ships an MCP server for coding agents.

Install

cargo install patchsense --locked

Requires Rust 1.99 or newer. Other install methods are listed in the GitHub repository.

Quick start

patchsense scan .                         # scan every lockfile under the current directory
patchsense scan . --fail-on review        # exit 1 if any finding is Review or Critical
patchsense scan . -f json -o report.json  # save a JSON report
patchsense init                           # write an example patchsense.toml
patchsense scan . --offline               # rescan from the local cache, no network

Example output:

┌───────┬──────────┬─────────────────────────────────────┬─────────┬──────────────────────────────────────┬─────┬────────────────────────────┬──────┬────────┐
│ Score ┆ Tier     ┆ Package                             ┆ Version ┆ Advisory/CVE                         ┆ KEV ┆ EPSS                       ┆ CVSS ┆ Fix    │
╞═══════╪══════════╪═════════════════════════════════════╪═════════╪══════════════════════════════════════╪═════╪════════════════════════════╪══════╪════════╡
│ 100   ┆ Critical ┆ org.apache.logging.log4j:log4j-core ┆ 2.14.1  ┆ GHSA-jfh8-c2jp-5v3q (CVE-2021-44228) ┆ yes ┆ 1.0000 (percentile 1.0000) ┆ 10   ┆ 2.15.0 │
│ 62    ┆ Review   ┆ org.apache.logging.log4j:log4j-core ┆ 2.14.1  ┆ GHSA-p6xc-xr62-6r2g (CVE-2021-45105) ┆ no  ┆ 1.0000 (percentile 0.9999) ┆ 8.6  ┆ 2.17.0 │
│ 34    ┆ Defer    ┆ org.apache.logging.log4j:log4j-core ┆ 2.14.1  ┆ GHSA-6hg6-v5c8-fphq (CVE-2026-34477) ┆ no  ┆ 0.0056 (percentile 0.4647) ┆ 6.3  ┆ 2.25.4 │
└───────┴──────────┴─────────────────────────────────────┴─────────┴──────────────────────────────────────┴─────┴────────────────────────────┴──────┴────────┘
Critical: 2  Review: 2  Defer: 4

Command reference

patchsense <COMMAND>

  scan     Scan lockfiles and print matching advisories
  cache    Inspect or delete the local SQLite cache
  init     Write an example config, agent instructions, or MCP snippets
  comment  Create or update a pull-request comment from a JSON report
  mcp      Run the MCP server on stdio
  help     Print help for a subcommand

  -h, --help     Print help
  -V, --version  Print version

patchsense scan [OPTIONS] [PATH]

PATH is a directory or a single lockfile. Default: the current directory.

Writing several reports in one run:

patchsense scan . --no-color \
  --format json     --output patchsense-report.json \
  --format sarif    --output patchsense.sarif \
  --format markdown --output patchsense-report.md

Rules for pairing: the n-th --format goes to the n-th --output. At most one format may be left without an --output (it goes to stdout). More --output values than --format values is an error.

patchsense cache [--cache-dir <DIR>] <info|clear>

--cache-dir works before or after the subcommand (cache info --cache-dir DIR or cache --cache-dir DIR info).

patchsense init [OPTIONS]

patchsense comment --report <FILE> [OPTIONS]

Posts the Markdown summary of a JSON report as a pull-request comment (GitHub) or merge-request note (GitLab). A hidden <!-- patchsense-report --> marker means later runs edit the same comment instead of adding a new one.

Environment it reads:

• GitHub: GITHUB_TOKEN with pull-requests: write, GITHUB_REPOSITORY, GITHUB_EVENT_PATH, optional GITHUB_API_URL. The comment is a pull-request conversation comment: GET and POST /repos/{owner}/{repo}/issues/{pull_number}/comments, and PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}. On a pull request, pull-requests: write authorizes those calls. issues: write is not required.
• GitLab: GITLAB_TOKEN (project access token with api scope; CI_JOB_TOKEN cannot write notes), CI_API_V4_URL, CI_PROJECT_ID, CI_MERGE_REQUEST_IID.

patchsense mcp

Runs a Model Context Protocol server on stdio. Tools:

patchsense init --print-mcp-config prints ready-to-paste snippets, for example Cursor's .cursor/mcp.json:

{
  "mcpServers": {
    "patchsense": { "command": "patchsense", "args": ["mcp"] }
  }
}

Claude Code: claude mcp add --transport stdio patchsense -- patchsense mcp

How the score works

Each finding gets 0–100 points:

Tiers: Critical ≥ 70, Review ≥ 40, otherwise Defer. Weights that do not sum to 100 are scaled to 100, with a warning. All of this is configurable.

Configuration

PatchSense looks for patchsense.toml starting at the scan directory and walking up to the git root. --config or PATCHSENSE_CONFIG points at a specific file. Precedence: flag > environment variable > file > built-in default. Unknown keys are rejected. Every key is optional; this is the full file with defaults:

schema_version = 1                      # only 1 is accepted

[scan]
ecosystems = ["npm", "pypi", "packagist", "go", "maven", "cargo"]  # default: all
exclude = []                            # extra glob patterns to skip
include_dev = true                      # false = same as --no-dev
fail_on = "critical"                    # critical | review | any | never | 0-100

[scan.go_imports]                       # Go import check, see below
skip_vendor = true                      # skip directories named vendor
skip_testdata = true                    # skip directories named testdata
skip_tests = true                       # skip *_test.go

[score.weights]
kev = 35
epss = 25
cvss = 20
direct = 10
fix_available = 10

[score.epss]
mode = "probability"                    # probability | percentile
saturation = 0.10                       # probability that earns the full EPSS weight

[score.thresholds]
critical = 70
review = 40

[score.unknown_direct]
weight_fraction = 1.0                   # share of the direct weight when the parser cannot tell

[cache]
ttl_hours_osv = 24                      # whole hours
ttl_hours_epss = 24
ttl_hours_kev = 24
strict_cache = false                    # true = --strict-cache

[output]
top = 20                                # rows in the Markdown report

[explain]
agent = "auto"                          # auto | codex | claude | cursor
top = 10                                # findings sent to the agent
timeout_secs = 120

# Suppress an advisory. Repeat the table for more rules.
[[ignore]]
id = "GHSA-xxxx-xxxx-xxxx"              # OSV, GHSA, or CVE id (aliases match too)
reason = "Used only in a build script"  # required
expires = "2027-01-31"                  # optional, inclusive YYYY-MM-DD

Ignored findings are listed under ignored in the JSON report. An expired rule is dropped with a warning. [explain] lang from older configs is accepted but ignored (output is English only).

Environment variables

Output formats

Warnings (stale cache, parse failures, unsupported lockfiles) go to stderr and are also stored in the JSON and Markdown reports.

Exit codes

--fail-on never always exits 0 when the scan runs. --min-score never changes the exit code.

Offline mode and cache

Data is cached in cache.db:

Online scans reuse rows younger than their TTL and refetch older ones. With --offline:

• OSV results must be in the cache and within ttl_hours_osv. A missing or expired row exits 2 and the error says which package and how old. No partial report is printed.
• EPSS / KEV: a missing row is a warning and that signal counts as absent. An expired row is still used, with a warning naming its age, so scores do not drop just because the cache aged.
• --strict-cache (or [cache] strict_cache = true) turns missing or expired EPSS/KEV into exit 2.

Typical CI pattern: run one online scan to warm the cache, then --offline for later runs.

patchsense scan .             # fills the cache
patchsense scan . --offline   # reuses it
patchsense cache info         # see what is stored

CI usage

Any CI that has Rust:

cargo install patchsense --locked
patchsense scan . --no-color --fail-on critical \
  --format json  --output patchsense-report.json \
  --format sarif --output patchsense.sarif

GitHub Actions with a PR comment:

permissions:
  contents: read
  pull-requests: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install patchsense --locked
      - run: patchsense scan . --no-color --format json --output patchsense-report.json
      - if: always() && github.event_name == 'pull_request'
        run: patchsense comment --report patchsense-report.json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

pull-requests: write is the permission for that comment. patchsense comment writes a pull-request conversation comment through the issue-comment routes above, and GitHub authorizes those routes on a pull request with pull-requests: write. issues: write is not required. On GitLab, run the same scan with --format gitlab --output gl-dependency-scanning-report.json and patchsense comment --provider gitlab with a masked GITLAB_TOKEN.

Supported ecosystems and lockfiles

Details:

• Directories named node_modules, vendor, target, .git, .venv, and venv are skipped during discovery.
• requirements: discovery also picks up requirements-*.txt, requirements_*.txt, *.requirements.txt, and any .txt inside a requirements/ directory (case-insensitive). -r/--requirement and -c/--constraint includes are followed relative to the including file. A cycle or missing include is a warning; remote includes are skipped with a warning.
• Composer: platform constraints such as php: ^8.3 are skipped; a concrete version such as php: 8.3.35 is scanned.
• Go import check: when an OSV advisory lists affected import paths, PatchSense checks .go files under the scan root. If none of those packages is imported, the finding stays (same score and tier) but gets the note imported package not seen (JSON field import_note). Subpackages, aliases, dot, and blank imports count. See docs/go-import-reachability.md.
• Not supported: bun.lock / bun.lockb (a warning is printed when one is found).

--explain (optional AI summary)

patchsense scan . --explain sends the top findings to a local, read-only coding agent CLI found on PATH: codex, claude, or Cursor's agent / cursor-agent. With auto they are tried in that order. The text is labeled AI explanation, may be wrong. A missing agent, a timeout ([explain] timeout_secs), or a bad response is only a warning and never changes the exit code.

Troubleshooting / FAQ

error: no supported lockfile found in . — Run from the project root, pass the lockfile path directly, or check that the file is not under a skipped directory or --exclude / [scan] exclude.

error: offline cache is missing OSV results … — Run one scan without --offline first, using the same --cache-dir (or PATCHSENSE_CACHE_DIR). --offline together with --no-cache can never succeed.

offline cache expired … — Rerun online, or raise [cache] ttl_hours_osv.

more than one --format would be written to stdout — Give every --format except one an --output.

failed to parse fail_on — Use critical, review, any, never, or an integer 0–100.

unknown field in the config — Keys are strict; compare with the configuration reference above.

could not detect a comment provider — Outside GitHub Actions or GitLab CI, pass --provider github or --provider gitlab, or use --dry-run to preview.

A Go finding says imported package not seen. — Your code does not import the vulnerable package of that module. The finding is kept because tests, vendored code, and build tags are not fully analysed; verify before ignoring it with an [[ignore]] rule.

Is my code uploaded anywhere? — No. Only package names and versions are sent to OSV, and CVE ids to EPSS; the KEV catalog is downloaded as a whole. --offline makes no network calls.

Links

• Repository: https://github.com/Widyasa/patchsense
• Changelog: https://github.com/Widyasa/patchsense/blob/master/CHANGELOG.md
• Known limitations: https://github.com/Widyasa/patchsense/blob/master/docs/limitations.md
• Issues: https://github.com/Widyasa/patchsense/issues
• Library API docs: https://docs.rs/patchsense

License

Licensed under either of MIT or Apache-2.0, at your option.