Skip to content

README.md

Latest commit

 

History

History
157 lines (107 loc) · 3.53 KB

README.md

File metadata and controls

157 lines (107 loc) · 3.53 KB
Raw

Patchrank

Patchrank is a small security CLI that turns vulnerability scanner output into a patch priority report. It accepts Trivy JSON, Grype JSON, generic CVE JSON, or a plain text list of CVEs, then ranks findings with CVSS, severity, CISA KEV, FIRST EPSS, fix availability, internet exposure, and asset criticality signals.

It is built for security teams and maintainers who need a practical answer to:

What should we patch first?

Features

  • Parse Trivy JSON, Grype JSON, generic JSON, and plain CVE lists.
  • Load CISA Known Exploited Vulnerabilities data from a local JSON file.
  • Load FIRST EPSS data from a local JSON/CSV-style export.
  • Optionally fetch current CISA KEV and FIRST EPSS data.
  • Score findings with explainable reason strings.
  • Output table, Markdown, or JSON.
  • Run with only the Python standard library.

Install

From a clone:

python -m pip install .

For development without installing:

python -m patchrank --help

When running directly from the repository, set PYTHONPATH=src if your shell does not automatically see the package:

PYTHONPATH=src python -m patchrank --help

PowerShell:

$env:PYTHONPATH = "src"
python -m patchrank --help

Quick Start

Rank a Trivy report with local KEV and EPSS fixtures:

patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json --format markdown

Rank a plain CVE list and mark the asset as internet-facing:

patchrank rank examples/cves.txt --internet-facing --asset-criticality 8

Fetch live KEV and EPSS data:

patchrank rank examples/cves.txt --fetch-kev --fetch-epss --format json

Scoring Model

Patchrank uses a transparent additive score capped at 100:

  • CISA KEV match: high weight because exploitation is known.
  • EPSS probability: higher probability raises priority.
  • CVSS/severity: impact and vendor severity still matter.
  • Fix availability: patched packages are easier to act on.
  • Internet-facing asset: exposure raises priority.
  • Asset criticality: user-supplied business context.

Priority bands:

Score Priority
80-100 patch-now
60-79 urgent
40-59 soon
0-39 monitor

This is an operational heuristic, not a replacement for human risk analysis.

Supported Inputs

Trivy

trivy image --format json --output trivy.json nginx:latest
patchrank rank trivy.json

Grype

grype dir:. -o json > grype.json
patchrank rank grype.json

Plain Text

Any line containing a CVE ID is accepted:

CVE-2024-3094
CVE-2023-34362

Data Sources

Patchrank can run fully offline when you provide local KEV and EPSS files.

Development

Run tests:

python -m unittest discover -s tests

Run a smoke check from a clone:

PYTHONPATH=src python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json --format markdown

PowerShell:

$env:PYTHONPATH = "src"
python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json --format markdown

Security

Patchrank reads local reports and optionally fetches public vulnerability intelligence. It does not need credentials. Do not upload private scanner reports to third-party systems unless you understand their contents.

See SECURITY.md.

License

MIT. See LICENSE.