Initial Patchrank CLI

Author: whatisproblem

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4

.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests
+
+      - name: Run CLI smoke test
+        run: PYTHONPATH=src python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json --format markdown --limit 5

.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+
+.env
+.env.*
+!.env.example
+
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+# Code of Conduct
+
+Be respectful, specific, and evidence-driven. Security work often involves
+disagreement about risk; keep discussions focused on data, behavior, and fixes.

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Thanks for helping improve Patchrank.
+
+## Local Checks
+
+```bash
+python -m unittest discover -s tests
+PYTHONPATH=src python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json
+```
+
+PowerShell:
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m unittest discover -s tests
+python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json
+```
+
+## Guidelines
+
+- Keep runtime dependencies minimal.
+- Add tests for each parser or scoring change.
+- Keep scoring explainable; every score boost should have a reason string.
+- Do not commit private vulnerability reports, tokens, or customer data.
+- Prefer fixtures with synthetic package names and public CVE IDs.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whatisproblem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,157 @@
+# 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:
+
+```bash
+python -m pip install .
+```
+
+For development without installing:
+
+```bash
+python -m patchrank --help
+```
+
+When running directly from the repository, set `PYTHONPATH=src` if your shell
+does not automatically see the package:
+
+```bash
+PYTHONPATH=src python -m patchrank --help
+```
+
+PowerShell:
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m patchrank --help
+```
+
+## Quick Start
+
+Rank a Trivy report with local KEV and EPSS fixtures:
+
+```bash
+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:
+
+```bash
+patchrank rank examples/cves.txt --internet-facing --asset-criticality 8
+```
+
+Fetch live KEV and EPSS data:
+
+```bash
+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
+
+```bash
+trivy image --format json --output trivy.json nginx:latest
+patchrank rank trivy.json
+```
+
+### Grype
+
+```bash
+grype dir:. -o json > grype.json
+patchrank rank grype.json
+```
+
+### Plain Text
+
+Any line containing a CVE ID is accepted:
+
+```text
+CVE-2024-3094
+CVE-2023-34362
+```
+
+## Data Sources
+
+- CISA Known Exploited Vulnerabilities catalog:
+  https://www.cisa.gov/known-exploited-vulnerabilities-catalog
+- FIRST EPSS API:
+  https://www.first.org/epss/api
+
+Patchrank can run fully offline when you provide local KEV and EPSS files.
+
+## Development
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests
+```
+
+Run a smoke check from a clone:
+
+```bash
+PYTHONPATH=src python -m patchrank rank examples/trivy.json --kev examples/kev.json --epss examples/epss.json --format markdown
+```
+
+PowerShell:
+
+```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](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Scope
+
+Security reports are welcome for:
+
+- Incorrect handling of local report files.
+- Unsafe network behavior in enrichment features.
+- Output that could leak private report content unexpectedly.
+- Supply-chain issues in CI or packaging metadata.
+
+Patchrank does not require credentials. Please do not include private scanner
+reports, tokens, or customer system details in public issues.
+
+## Reporting
+
+Use GitHub private security advisories when available. Otherwise, open an issue
+with a minimal synthetic reproduction.