cve-converter

cve-converter is a Python command-line tool that takes a CVE ID, fetches public vulnerability data, enriches it with threat intelligence, and converts it into a clear, SOC-friendly security summary.

The project pulls core vulnerability details from the NVD API, then adds:

• CISA KEV status to show whether the vulnerability is known to be exploited
• FIRST EPSS score and percentile to help estimate likelihood of exploitation

The result is a report that is easier to read than raw vulnerability data and more useful for prioritization, remediation, and analyst workflows.

Why This Project Exists

Official CVE records are valuable, but they are often technical, inconsistent, and time-consuming to interpret quickly. This project turns that raw information into a practical analyst report that includes:

• severity and CVSS context
• plain-English explanation
• likely impact
• affected systems
• remediation guidance
• SOC detection suggestions
• threat-intelligence enrichment

It is designed to be simple enough for a junior SOC analyst portfolio while still showing clean code, modular design, error handling, and realistic security use cases.

SOC Workflow Context

In a real Security Operations Centre (SOC), analysts need to quickly:

• assess whether a vulnerability is actively exploited
• estimate likelihood of exploitation
• prioritise remediation
• decide what to monitor or hunt for

This tool simulates that workflow by combining:

• NVD (what the vulnerability is)
• CISA KEV (whether it is actively exploited)
• EPSS (how likely it is to be exploited)

into a single, actionable report.

Features

• Validates CVE input using a regex before making API calls
• Fetches vulnerability data from the NVD API v2.0
• Extracts key fields such as description, CVSS, severity, CWE, affected products, and references
• Enriches the report with CISA KEV status and FIRST EPSS score data
• Rewrites technical vulnerability details into plain English
• Generates remediation guidance from vendor references or rule-based best practices
• Adds SOC-focused detection and monitoring suggestions
• Includes a dedicated Threat Intelligence section with CISA KEV and EPSS details
• Supports terminal text, Markdown, and structured JSON output
• Builds one canonical report structure and renders it consistently as terminal text, Markdown, or JSON
• Saves reports to disk with --output
• Handles missing CVSS, missing CWE, missing references, and enrichment lookup failures gracefully
• Computes vulnerability type once and reuses it across summary and remediation generation
• Reuses a shared HTTP session in the threat-intelligence layer for cleaner network handling
• Includes focused unit tests for validation, parsing, formatting, and threat-intelligence enrichment

Data Sources

This project uses free public sources only:

• NVD API for core CVE information
• CISA KEV feed for known exploited vulnerability status
• FIRST EPSS API for exploit probability scoring

If KEV or EPSS data cannot be fetched, the application still completes report generation and shows the enrichment as unavailable instead of crashing.

Example Output

========================================================================================
CVE Security Summary: CVE-2021-44228
========================================================================================

Severity
--------
- Critical - CVSS 3.1 base score 10.0 indicates severe risk that may require emergency
  action.
- CVSS 3.1 | Score: 10.0 | Vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

Weakness Type
-------------
- CWE-502 Deserialization of Untrusted Data

Threat Intelligence
-------------------
- CISA KEV status: Listed
- EPSS score: 0.9721
- EPSS percentile: 99.82%
- KEV date added: 2021-12-10
- Known ransomware campaign use: Known

Plain English Summary
---------------------
- This vulnerability may let an attacker run their own code on a target system, which
  can lead to full system compromise.

Risk / Impact
-------------
- The main risk is unauthorized code execution with a CVSS base score of 10.0. An
  attacker could install malware, move laterally, or take control of the affected host.
  CISA includes this CVE in the Known Exploited Vulnerabilities catalog, which raises
  confidence that it has been exploited in real-world attacks.

Affected Systems
----------------
- Affected products identified by NVD include: apache log4j 2.0-beta9, and others.

Recommended Remediation Actions
-------------------------------
- Review and apply the vendor guidance in https://logging.apache.org/log4j/2.x/security.html.
- Patch or upgrade affected systems to a fixed version as soon as operationally possible.
- Limit exposure of vulnerable services to trusted networks until remediation is complete.

Detection / SOC Monitoring Suggestions
--------------------------------------
- Search asset inventories and vulnerability scanners for the affected product versions.
- Monitor endpoint telemetry for suspicious child processes, script interpreters, or
  unexpected service creation.
- Prioritize threat hunting and detection review because CISA KEV listing indicates
  exploitation in the wild.

References
----------
- https://nvd.nist.gov/vuln/detail/CVE-2021-44228

Project Structure

cve-converter/
|-- app.py
|-- cve_fetcher.py
|-- parser.py
|-- summariser.py
|-- remediation.py
|-- formatter.py
|-- threat_intel.py
|-- utils.py
|-- explain.txt
|-- requirements.txt
|-- .env.example
|-- .gitignore
|-- LICENSE
|-- tests/
|   |-- test_formatter.py
|   |-- test_parser.py
|   |-- test_threat_intel.py
|   `-- test_utils.py
`-- README.md

Setup

1. Install Python 3.10 or newer.
2. Create and activate a virtual environment.
3. Install dependencies:

pip install -r requirements.txt

4. Optionally copy .env.example to .env and override configuration values.

Supported environment variables:

• NVD_API_BASE_URL: Override the default NVD base URL
• NVD_API_KEY: Optional free NVD API key for improved rate limits
• NVD_TIMEOUT_SECONDS: API timeout in seconds

Usage

Run the standard terminal report:

python app.py CVE-2024-3094

Run with debug logging:

python app.py CVE-2024-3094 --log-level DEBUG

Print a Markdown report:

python app.py CVE-2024-3094 --format markdown

Save a Markdown report to a file:

python app.py CVE-2024-3094 --format markdown --output reports/cve-2024-3094.md

Print a structured JSON report:

python app.py CVE-2024-3094 --format json

Save a report to a file:

python app.py CVE-2024-3094 --format json --output reports/cve-2024-3094.json

Example Inputs

You can try the tool with CVEs such as:

CVE-2024-3094
CVE-2023-4863
CVE-2021-44228
CVE-2014-0160
CVE-2017-5753

Example commands:

python app.py CVE-2024-3094
python app.py CVE-2024-3094 --format markdown
python app.py CVE-2023-4863 --format json
python app.py CVE-2021-44228 --format json --output log4shell-report.json

What The Report Includes

• CVE ID
• Severity and CVSS explanation
• Weakness type
• Threat-intelligence context from KEV and EPSS
• CISA KEV listing status, dates, and ransomware-use note when available
• EPSS score and percentile
• Plain-English summary
• Risk and likely impact
• Affected systems
• Recommended remediation actions
• Detection and SOC monitoring suggestions
• References

JSON Output

When --format json is used, the tool returns the same underlying report structure that also drives the text and Markdown output.

Top-level JSON sections include:

• cve_id
• severity
• weakness_type
• threat_intelligence
• plain_english_summary
• risk_impact
• affected_systems
• recommended_remediation_actions
• remediation_priority
• detection_soc_monitoring_suggestions
• references
• metadata

This makes the project more usable in scripts, pipelines, or future web or API interfaces.

Example JSON shape:

{
  "cve_id": "CVE-2021-44228",
  "severity": {
    "level": "Critical",
    "explanation": "CVSS 3.1 base score 10.0 indicates severe risk that may require emergency action.",
    "cvss": {
      "version": "3.1",
      "base_score": 10.0
    }
  },
  "weakness_type": "CWE-502 Deserialization of Untrusted Data",
  "threat_intelligence": {
    "cisa_kev": {
      "listed": true
    },
    "epss": {
      "score": 0.9721,
      "percentile": 0.9982
    }
  }
}

Markdown Output

When --format markdown is used, the tool creates a report that is easy to paste into:

• GitHub issues
• analyst notes
• documentation
• ticketing systems

This makes the tool more practical for reporting workflows without changing the underlying analysis logic.

Example Markdown output:

# CVE Security Summary: CVE-2021-44228

## Severity
- Critical - CVSS 3.1 base score 10.0 indicates severe risk that may require emergency action.
- CVSS 3.1 | Score: 10.0 | Vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

## Weakness Type
- CWE-502 Deserialization of Untrusted Data

## Threat Intelligence
- CISA KEV status: Listed
- EPSS score: 0.9721
- EPSS percentile: 99.82%
- KEV date added: 2021-12-10
- Known ransomware campaign use: Known

## Plain English Summary
- This vulnerability may let an attacker run their own code on a target system, which can lead to full system compromise.

## Recommended Remediation Actions
- Review and apply the vendor guidance in https://logging.apache.org/log4j/2.x/security.html.
- Patch or upgrade affected systems to a fixed version as soon as operationally possible.
- Limit exposure of vulnerable services to trusted networks until remediation is complete.

Module Overview

• app.py is the CLI entry point and orchestrates the full workflow
• cve_fetcher.py handles requests to the NVD API
• parser.py extracts useful fields from the raw NVD response
• threat_intel.py enriches the report with KEV and EPSS data through a small client that reuses a shared HTTP session and timeout settings
• summariser.py converts technical content into simpler language and adds light threat-priority context
• remediation.py generates remediation advice
• formatter.py builds one canonical report payload and renders it as terminal text, Markdown, or JSON
• utils.py contains shared helpers, settings, validation, and data models

The parser now determines the vulnerability type once and the rest of the application reuses that result, which keeps the internal workflow simpler and avoids duplicate logic. The formatter also uses one shared report payload so the human-readable and JSON outputs stay aligned as the project evolves.

Testing

Run the unit tests from the project folder:

python -m unittest discover -s tests

The test suite currently covers:

• CVE format validation
• parsing of complete and sparse NVD records
• graceful handling of missing CVSS, missing CWE, and empty references
• text, Markdown, and JSON report formatting
• threat-intelligence enrichment success and failure paths

Portfolio Value

This project demonstrates:

• Python API integration
• defensive coding and graceful error handling
• modular design and separation of concerns
• security-focused parsing and reporting
• practical analyst workflow thinking
• unit testing of core behavior

Future Improvements

• Add mocked end-to-end API tests and broader edge-case coverage
• Export reports to HTML for richer reporting and ticketing workflows
• Add more enrichment sources such as CISA alerts, exploit reference tagging, or prioritization metadata
• Add a small Flask or FastAPI web interface for a more application-like user experience
• Improve affected product and version parsing for more precise reporting
• Package the project as an installable CLI tool with a pyproject.toml