🛡️ CVE Exploit Mapper

Transform vulnerability scanner noise into actionable, risk-prioritized remediation reports.

---

CVE Exploit Mapper ingests Nessus and Qualys scan exports, enriches each CVE with real-world threat intelligence, and produces risk-prioritized remediation reports ranked by actual exploitability — not just raw CVSS.

🎯 The Problem

Vulnerability scanners produce thousands of findings ranked by CVSS severity alone. Security teams waste time patching CVEs that look severe on paper but have zero known exploits, while truly dangerous, actively exploited vulnerabilities languish in the backlog.

💡 The Solution

CVE Exploit Mapper layers four threat intelligence sources on top of scanner data to answer the question: "Which vulnerabilities should I actually patch first?"

Intelligence Source	What It Tells You
EPSS (FIRST.org)	Probability of exploitation in the next 30 days
CISA KEV	Confirmed active exploitation by threat actors
ExploitDB	Public exploit code availability
NVD	Authoritative CVSS scores, vectors, CWE data

✨ Features

• Multi-scanner support — Nessus CSV/XML/XLSX, Qualys CSV, or any generic CSV with a CVE column
• Deduplication Engine — Consolidate thousands of repeating version-based vulnerabilities by application and remediation action (e.g., 900+ Thunderbird patches -> 1 finding).
• Composite risk scoring — Weighted formula combining CVSS, EPSS, KEV, and exploit data (methodology)
• Priority tiers — CRITICAL / HIGH / MEDIUM / LOW with SLA recommendations
• Multiple output formats — CSV, JSON, HTML, and Excel (multi-sheet workbook with charts)
• Smart caching — SQLite-backed cache with configurable TTL to minimize API calls
• Single CVE lookup — Quick threat intel lookup for any CVE
• Beautiful terminal output — Rich tables and progress bars

📦 Installation

# Clone the repository
git clone https://github.com/SolidCode321/cve-exploit-mapper.git
cd cve-exploit-mapper

# Install the package
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

🚀 Quick Start

1. Deduplication / Consolidation

Scanners like Nessus output thousands of repetitive, localized findings (e.g., triggering a finding for every single missing patch of an application on a host). The consolidate command collapses these findings into grouped remediation tasks using exact application metadata.

# Analyze a Nessus XLSX or CSV file (auto-detects format)
cve-exploit-mapper consolidate nessus_export.xlsx

# Include non-version findings in the final report
cve-exploit-mapper consolidate nessus.csv --include-non-version

2. Deep Threat Intel Scan (CVSS Re-ranking)

# Analyze a Nessus CSV export (auto-detects format)
cve-exploit-mapper scan nessus_export.csv

# Generate only an HTML report
cve-exploit-mapper scan qualys_report.csv -f html -o report.html

# Generate all formats with NVD API key for faster lookups
cve-exploit-mapper scan scan.csv -f all --nvd-api-key YOUR_KEY

# Skip NVD lookups (faster, uses scanner CVSS only)
cve-exploit-mapper scan scan.csv --skip-nvd

Quick CVE Lookup

# Look up threat intelligence for a single CVE
cve-exploit-mapper enrich CVE-2024-3094
cve-exploit-mapper enrich CVE-2021-44228

Manage Databases

# Force refresh all cached intelligence data
cve-exploit-mapper update-db

# View current configuration and cache status
cve-exploit-mapper config

📊 Risk Scoring

The composite risk score (0–100) combines multiple signals:

Factor	Weight	Source
CVSS Base Score	25%	NVD / Scanner
EPSS Score	30%	FIRST.org
CISA KEV Status	20%	CISA
Public Exploit Available	15%	ExploitDB
Exploit Maturity	10%	ExploitDB

Priority Tiers:

Tier	Score	Action
🔴 CRITICAL	80-100	Patch immediately
🟠 HIGH	60-79	Patch within 7 days
🟡 MEDIUM	40-59	Patch within 30 days
🟢 LOW	0-39	Next maintenance window

See docs/scoring.md for the full methodology.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     CLI (click + rich)                       │
├──────────┬──────────┬──────────┬──────────┬────────────────┤
│  Parser  │ Consoli- │ Enricher │ Enricher │   Risk Scorer  │
│  Module  │  dator   │  (EPSS)  │ (Exploit │   & Ranker     │
│ Nessus/  │          │          │    DB)   │                │
│ Qualys/  │          │          │          │                │
│ Generic  │          │          │          │                │
├──────────┴──────────┴──────────┴──────────┴────────────────┤
│              Pydantic Data Models + SQLite Cache            │
├─────────────────────────────────────────────────────────────┤
│              Report Generator (CSV/JSON/HTML/Excel)         │
└─────────────────────────────────────────────────────────────┘

⚠️ Limits & Best Practices

1. Large Excel Files (.xlsx): The tool uses openpyxl in read_only mode. Memory usage is optimized natively, but extreme files (500k+ findings) should preferably be sent as raw CSVs.
2. NVD API Limits: If you run cve-exploit-mapper scan across thousands of unique CVEs without an API Key, the NVD API limits fetches heavily (taking multiple hours). Always query massive files using --skip-nvd, or configure standard limits safely with --nvd-api-key.
3. ICMP / SMB Filtering: The consolidate function inherently purges repetitive noise such as "ICMP Timestamp Request" and "SMB Signing not required".
4. Hosts are kept separate: Consolidation resolves vulnerabilities per application, per host. Mozilla Thunderbird missing 90 patches on exactly 5 hosts will output exactly 5 single, consolidated rows to assist in real-world deployment scoping.

📁 Project Structure

src/cve_exploit_mapper/
├── cli.py                  # CLI entry point
├── models.py               # Pydantic data models
├── parsers/                # Scanner export parsers
│   ├── nessus_parser.py    # Nessus CSV + XML
│   ├── qualys_parser.py    # Qualys CSV
│   └── generic_parser.py   # Generic CSV fallback
├── enrichers/              # Threat intelligence enrichers
│   ├── epss_enricher.py    # FIRST.org EPSS API
│   ├── kev_enricher.py     # CISA KEV catalog
│   ├── exploitdb_enricher.py # ExploitDB index
│   ├── nvd_enricher.py     # NVD CVE API 2.0
│   └── cache.py            # SQLite cache layer
├── scoring/
│   └── risk_scorer.py      # Composite risk scoring engine
└── reports/                # Report generators
    ├── csv_report.py
    ├── json_report.py
    ├── html_report.py       # Standalone HTML with embedded CSS
    └── excel_report.py      # Multi-sheet workbook with charts

⚙️ Configuration

NVD API Key (Optional but Recommended)

Without a key: ~5 requests/minute. With a free key: ~50 requests/minute.

# Set via environment variable
export NVD_API_KEY=your-api-key-here

# Or pass via CLI flag
cve-exploit-mapper scan scan.csv --nvd-api-key YOUR_KEY

Get a free key at: https://nvd.nist.gov/developers/request-an-api-key

Cache

All enrichment data is cached in ~/.cache/cve-exploit-mapper/enrichment_cache.db with configurable TTLs:

Source	Default TTL
EPSS	7 days
CISA KEV	24 hours
ExploitDB	7 days
NVD	30 days

# Clear cache
cve-exploit-mapper scan scan.csv --clear-cache

# Disable cache for a single run
cve-exploit-mapper scan scan.csv --no-cache

🧪 Development

# Install dev dependencies
make dev

# Run tests
make test

# Lint
make lint

# Format code
make fmt

# Type check
make typecheck

📄 License

MIT License — see LICENSE for details.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.