Metadata-Version: 2.4
Name: cve-risk-analyzer
Version: 0.1.1
Summary: Filter your company's products and rank real-world CVE risk (CVSS + EPSS + CISA KEV + public exploits), with AI-written exploitability analysis.
Project-URL: Homepage, https://github.com/yourname/cve-risk-analyzer
Project-URL: Issues, https://github.com/yourname/cve-risk-analyzer/issues
Author: zzzzsecurityzzzz
License-Expression: MIT
License-File: LICENSE
Keywords: cli,cve,cvss,epss,kev,risk,security,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: platformdirs>=4.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.32
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# CVE Risk Analyzer

A terminal tool that watches the products your company uses, pulls fresh CVEs,
and ranks them by **real-world exploit risk** — not just raw CVSS. It blends
severity, exploit probability (EPSS), active-exploitation status (CISA KEV), and
public exploit-code availability, then uses Claude to explain *how easily each
one can actually be exploited*: preconditions, limitations, and a verdict.

## Data sources (all keyless except Claude)

| Source | Purpose | Key |
|---|---|---|
| Shodan CVEDB | primary discovery: CVE data + CVSS + EPSS + KEV in one call | none |
| FIRST.org EPSS | exploit-probability backfill for any CVE missing it | none |
| GitHub Search | public exploit / PoC detection | optional `GITHUB_TOKEN` |
| **NVD (NIST)** | authoritative CVSS + structured CPE version ranges | optional `NVD_API_KEY` |
| **OpenCVE** | structured CPE version ranges + CVSS/KEV/CWE | optional `OPENCVE_API_TOKEN` |
| Anthropic Claude | exploitability narrative & verdict | `ANTHROPIC_API_KEY` |

Without an Anthropic key the tool still runs in **rule-based mode** (scores and
signals only, no narrative).

**NVD and OpenCVE are optional and auto-activate when their credentials are set.**
CVEDB handles discovery; NVD and/or OpenCVE then overlay authoritative CVSS scores
and **structured CPE version ranges** onto the top-ranked CVEs (enrichment by
CVE-ID, so they always hit the CVEs you actually see). The run header shows which
sources are active (e.g. `sources: CVEDB + EPSS + OpenCVE`).

- **NVD** — free key at <https://nvd.nist.gov/developers/request-an-api-key>
- **OpenCVE** — free account at <https://app.opencve.io>; create an Organization
  API token (Bearer) and set `OPENCVE_API_TOKEN`. Basic Auth
  (`OPENCVE_USERNAME` + `OPENCVE_PASSWORD`) is also supported (legacy).

When either source supplies structured version ranges, `--version` becomes a
**precise range match** (`versionStartIncluding ≤ you ≤ versionEndIncluding`)
instead of a text heuristic. Everything works fully without these keys.

## Install

Recommended — install the `cve-analyzer` command with [pipx](https://pipx.pypa.io)
(isolates its dependencies from your other Python tools):

```bash
pipx install cve-risk-analyzer          # once published to PyPI
# or, from a local checkout:
pipx install .
```

Or with plain pip / for development:

```bash
pip install -e .        # editable install from a checkout
```

After installing, the command is available anywhere:

```bash
cve-analyzer guide      # how-to
cve-analyzer where      # shows where state + keys live, and which keys are set
```

### Keys & state

Run `cve-analyzer where` to see the exact paths. State (your watchlist) lives in
an OS-native per-user data dir:

- Windows: `%LOCALAPPDATA%\cve-analyzer`
- macOS: `~/Library/Application Support/cve-analyzer`
- Linux: `~/.local/share/cve-analyzer`

Put API keys in a `.env` there, in a `.env` in your current folder, or export them
as environment variables. Only `ANTHROPIC_API_KEY` is needed for AI analysis;
`NVD_API_KEY`, `OPENCVE_API_TOKEN`, and `GITHUB_TOKEN` are optional and enrich
results when present.

> The examples below use `python -m cve_analyzer` (works from a source checkout).
> Once installed, `cve-analyzer` is the equivalent shorter command.

## Usage

```bash
# Not sure where to start? Print the built-in how-to for every command:
python -m cve_analyzer guide

# Build your watchlist — product tokens are auto-resolved (e.g. "Cisco IOS XE" -> ios_xe)
python -m cve_analyzer add "Apache Tomcat"
python -m cve_analyzer add "Cisco IOS XE"
python -m cve_analyzer add "OpenSSL" --version 3.0
python -m cve_analyzer add "Some Product" --token exact_cpe_token   # manual override
python -m cve_analyzer list
python -m cve_analyzer remove "OpenSSL"

# Track a WHOLE vendor (all their products) — keyless, via NVD
python -m cve_analyzer add-vendor cisco            # e.g. 6,600+ Cisco CVEs across all products
python -m cve_analyzer remove cisco --vendor

# Report — prints the risk table to your terminal AND writes a shareable file
python -m cve_analyzer report                       # rank all + AI on top findings
python -m cve_analyzer report --no-ai               # rule-based only, no API cost
python -m cve_analyzer report --open                # also open the HTML in your browser
python -m cve_analyzer report --no-preview -f json -o findings.json
python -m cve_analyzer report --top 5 --limit 20

# Filters
python -m cve_analyzer report --since 90d           # only CVEs published in last 90 days
python -m cve_analyzer report --since 2025-01-01    # ...or since an absolute date
python -m cve_analyzer report --version 3.0         # only CVEs affecting that version

# Report on specific CVEs (skips the watchlist)
python -m cve_analyzer report CVE-2023-20198 CVE-2024-21762 -o crit.html

# Deep-dive one CVE in the terminal (use --deep for the strongest model)
python -m cve_analyzer analyze CVE-2023-20198
python -m cve_analyzer analyze CVE-2024-21762 --deep
```

`report` is the main command: it prints the ranked risk table (with a legend)
to the terminal *and* writes an HTML/JSON file. Use `--no-preview` for file-only,
or `analyze` to inspect a single CVE in the terminal.

### Filters & flags

| Flag | Commands | Meaning |
|---|---|---|
| `--since` | report | `Nd`/`Nw`/`Nm`/`Ny` or `YYYY-MM-DD`. Switches to newest-first fetching so recent CVEs surface. |
| `--version` / `-v` | report, add | On report: keep CVEs affecting the version (precise with NVD/OpenCVE, else heuristic). On `add`: store a version for the product. |
| `--limit` / `-l` | report | Max CVEs fetched per product (default 15). |
| `--top` / `-t` | report | How many top-ranked CVEs get the AI narrative (default 10). |
| `--ai` / `--no-ai` | report | Toggle the Claude narrative (`--no-ai` = zero API cost). |
| `--preview` / `--no-preview` | report | Print the table + AI cards to the terminal (default on). |
| `--legend` / `--no-legend` | report | Show/hide the how-to-read key. |
| `--open` | report | Open the generated HTML in your browser. |
| `--deep` | analyze | Use the strongest model (Opus) for a single CVE. |
| `--token` | add | Override the auto-resolved CPE product token. |

> **On `--version` precision:** with an NVD or OpenCVE key set, version filtering
> uses **structured CPE ranges** for precise matching. Without either, the keyless
> CVEDB source has no version data, so it falls back to a best-effort text match
> against the CVE description (a narrowing aid, not authoritative).

## Risk score

Transparent weighted blend (tune in `scoring.py`):

```
risk = 10 * (0.40*CVSS/10 + 0.30*EPSS + 0.20*KEV + 0.10*PoC)
```

## Project layout

```
cve_analyzer/
  cli.py          # commands
  config.py       # env + paths (UTF-8 fix for Windows)
  watchlist.py    # product watchlist storage
  models.py       # normalized Vuln record
  scoring.py      # composite risk
  filters.py      # --since date window + --version heuristic
  analysis.py     # Claude narrative
  render.py       # slick terminal output (rich)
  report.py       # HTML / JSON export
  sources/
    cvedb.py      # Shodan CVEDB client + token resolver (discovery)
    nvd.py        # NVD/NIST client — authoritative CVSS + CPE ranges (optional key)
    opencve.py    # OpenCVE client — CPE ranges + CVSS/KEV/CWE (optional token)
    epss.py       # FIRST.org EPSS backfill
    poc.py        # GitHub PoC detection
```
