CVEAlerts

CVEAlerts is a Python-based CVE reporting and alerting project.

The project has two planned engines:

1. CVE PDF Engine - generates a concise PDF brief for one CVE.
2. CVE Tracking Engine - scans NVD for newly published or recently modified critical CVEs for a default vendor list, tracks what has already been processed, and passes new qualifying CVEs into the PDF Engine.

A self-contained GUI is planned for a later development phase.

---

Current Naming Standard

Use underscores for Python module filenames.

The current working PDF script is:

EVA-CVE.py

For this project, it should be renamed to:

eva_cve_pdf.py

The planned tracking module should be named:

eva_cve_tracking.py

Recommended repository layout:

CVEAlerts/
├── README.md
├── docs/
│   ├── cve_pdf_engine.md
│   └── cve_tracking_engine.md
└── src/
    └── cvealerts/
        ├── __init__.py
        ├── eva_cve_pdf.py
        └── eva_cve_tracking.py

During current local Windows testing, the default output directory remains:

C:\devops\data

---

Project Status

Working Now

The current working code is the PDF engine originally developed as EVA-CVE.py.

It currently supports:

• Generating a PDF brief for a specific CVE.
• Querying the NVD CVE API 2.0.
• Accepting CVE input in either full or shortened format.
• Auto-detecting supported vendors from NVD data.
• Grouping vendor advisory/reference links in the PDF.
• Adding an engineer note directing users to vendor workaround/fix guidance.

Planned Next

The tracking engine is planned as a separate module named:

eva_cve_tracking.py

It will:

• Query NVD for critical CVEs from the last 24 hours by default.
• Scan both newly published and recently modified CVEs.
• Filter results to the default supported vendor list.
• Track previously processed CVEs.
• Automatically generate PDFs for new qualifying CVEs by calling eva_cve_pdf.py.
• Provide a future --GUI flag that launches a self-contained GUI and starts tracking once GUI support exists.

---

CVE PDF Engine

Module

src/cvealerts/eva_cve_pdf.py

Source Baseline

The working code baseline is currently named:

EVA-CVE.py

This code should be renamed to:

eva_cve_pdf.py

The existing behaviour should be preserved unless a specific change request says otherwise.

Purpose

The CVE PDF Engine generates a concise PDF briefing for a single CVE.

It queries the NVD CVE API 2.0, extracts vulnerability details, performs best-effort vendor auto-detection using NVD data, groups reference links by vendor where possible, and renders a PDF report using ReportLab.

Basic Usage

Generate a CVE brief using full CVE format:

python src/cvealerts/eva_cve_pdf.py CVE-2025-2520

Generate a CVE brief using numeric CVE format:

python src/cvealerts/eva_cve_pdf.py 2025-2520

Specify an output directory:

python src/cvealerts/eva_cve_pdf.py 2025-2520 --outdir C:\devops\data

Accepted CVE Input Formats

The PDF engine accepts:

CVE-YYYY-NNNN...
YYYY-NNNN...

Examples:

CVE-2025-2520
2025-2520

Invalid examples:

2520
CVE2520
test
2025

If the numeric form is supplied, the engine prepends CVE- internally.

Example:

2025-2520 -> CVE-2025-2520

PDF Output

The generated PDF filename follows this pattern:

EVA-CVE-Brief-CVE-YYYY-NNNN.pdf

Example:

EVA-CVE-Brief-CVE-2025-2520.pdf

Default output directory:

C:\devops\data

PDF Report Sections

The generated PDF contains:

EVA Team - Estate Management - Vulnerability Management - Automation

CVE Briefing: CVE-YYYY-NNNN
Published: <timestamp> | Last Modified: <timestamp>
Vendor focus / Vendors referenced: <vendor>

1) Problem Description
2) Severity / Scoring
3) What's Affected (Configurations / CPE)
4) NVD Workarounds / Mitigations
5) Vendor Specific References / Work Arounds

Engineer Note: Review Section 5 for vendor guidance, workarounds, and fixed releases.

Engineer Note

The PDF includes this engineer-facing note:

Engineer Note: Review Section 5 for vendor guidance, workarounds, and fixed releases.

This note is intended to direct engineers to vendor advisory links, workaround guidance, mitigation information, and fixed release details.

Vendor Auto-Detection

The PDF engine attempts to detect the vendor automatically when no explicit vendor is supplied.

Detection can use:

• CPE vendor fields.
• CPE product names.
• Reference URLs.
• Reference source values.
• PSIRT email domains.
• Description text.
• Known vendor keyword patterns.

Supported/tested vendor families include:

Cisco
Fortinet
Juniper
HP-Aruba
Honeywell

The tracking engine default vendor list is intentionally narrower and is defined separately below.

PDF Engine Flags

--vendor

Optional manual vendor keyword.

Example:

python src/cvealerts/eva_cve_pdf.py 2025-20362 --vendor Cisco

Rules:

• Manual vendor input takes priority over auto-detection.
• --vendor does not change the NVD API query.
• The NVD query is always based on the CVE ID.
• The old hardcoded default of Cisco must not be restored.

--vendors

Optional comma-separated list of vendor buckets used for Section 5 reference grouping.

Example:

python src/cvealerts/eva_cve_pdf.py 2025-2520 --vendors "Cisco,Fortinet,Juniper,HP-Aruba,Honeywell"

--outdir

Output directory for generated PDFs.

Default:

C:\devops\data

--sleep

Optional delay before the NVD API request.

Example:

python src/cvealerts/eva_cve_pdf.py 2025-2520 --sleep 1.5

NVD API Key

The PDF engine uses this environment variable when present:

NVD_API_KEY

PowerShell session example:

$env:NVD_API_KEY="your_api_key_here"

Persistent Windows user environment example:

setx NVD_API_KEY "your_api_key_here"

After using setx, open a new terminal session.

---

CVE Tracking Engine

Module

src/cvealerts/eva_cve_tracking.py

Purpose

The CVE Tracking Engine is a planned discovery, tracking, and orchestration module.

It will query the NVD CVE API for critical CVEs, filter them to the default supported vendor list, track what has already been processed, and pass new qualifying CVEs into eva_cve_pdf.py for automatic PDF generation.

The tracking engine must not duplicate PDF rendering logic.

Default Operation

Default command:

python src/cvealerts/eva_cve_tracking.py --scan-critical

Default behaviour:

Query NVD for all critical CVEs within the last 24 hours from the time of execution.
Filter to the default vendor list.
Generate PDFs for new qualifying CVEs.
Track processed CVEs in local state.

Default scan window:

scan_start = execution_time_utc - 24 hours
scan_end   = execution_time_utc

Default Tracking Vendor List

The default vendor list for the tracking engine is:

Cisco
Fortinet
Juniper
HP-Aruba

The tracker should use this default list unless --vendors is supplied.

Example explicit vendor list:

python src/cvealerts/eva_cve_tracking.py --scan-critical --vendors "Cisco,Fortinet,Juniper,HP-Aruba"

Critical CVE Definition

For this project:

Critical CVE = CVSS base score between 9.0 and 10.0 inclusive

Numerical rule:

9.0 <= baseScore <= 10.0

The tracker may use NVD severity filters, but it must still validate the numeric score locally.

Preferred scoring order:

1. CVSS v4.0 if present.
2. CVSS v3.1 if present.
3. CVSS v3.0 if present.
4. CVSS v2 only as a legacy fallback if explicitly enabled later.

Tracking Discovery Strategy

The tracker should run two scan types by default:

1. Published scan.
2. Modified scan.

Both scans use the selected date window. By default, that is the last 24 hours from execution time.

Tracking State

The tracker should maintain a local JSON state file.

Recommended default path:

C:\devops\data\cve_tracking_state.json

The state file should prevent duplicate PDF generation and record run history.

Tracking Engine Flags

Planned flags:

--scan-critical
--days
--since
--until
--include-modified
--published-only
--modified-only
--vendors
--outdir
--state
--dry-run
--no-pdf
--force-regenerate
--regenerate-updated
--results-per-page
--max-pages
--sleep
--summary
--GUI

--GUI

Future-use flag.

Planned behaviour:

Launch the self-contained GUI and start tracking.

Current status:

Not implemented yet.

The flag should be reserved in the specification so future development remains consistent.

Tracking Console Output

The tracker should display readable console summaries instead of dumping raw NVD JSON.

Example default scan output style:

EVA CVE Tracking Engine
------------------------------------------------------------
Scan type        : Critical CVE discovery
Severity filter  : CVSS 9.0 - 10.0
Date window      : <execution_time_utc - 24h> to <execution_time_utc>
Published scan   : enabled
Modified scan    : enabled
Supported vendors: Cisco, Fortinet, Juniper, HP-Aruba
State file       : C:\devops\data\cve_tracking_state.json
Output directory : C:\devops\data

Querying NVD API...
Published scan   : Complete
Modified scan    : Complete

CVE Tracking Engine Summary
------------------------------------------------------------
Candidates returned by NVD       : <count>
Critical after local validation  : <count>
Supported vendor matches         : <count>
New CVEs                         : <count>
PDFs generated                   : <count>
Skipped already seen             : <count>
Failed                           : <count>

---

Planned Self-Contained GUI

A self-contained GUI is planned for a later development phase.

The GUI should call the same underlying engines:

GUI
    -> eva_cve_pdf.py
    -> eva_cve_tracking.py

The GUI should not duplicate PDF generation or tracking logic.

Planned GUI capabilities:

• Generate a single CVE PDF brief.
• Run the tracking engine using the default last-24-hours mode.
• Select scan ranges.
• View scan results.
• Open generated PDFs.
• Configure output directory.
• Configure supported vendors.
• Display NVD API key guidance.

The future --GUI flag in eva_cve_tracking.py should launch this GUI and start tracking once implemented.

---

Requirements

Initial dependencies:

reportlab

The project currently uses Python standard library HTTP handling.

If future development switches to requests, it should be added explicitly to requirements.txt.

---

Development Principles

• Preserve the working PDF engine baseline.
• Do not remove existing PDF functionality unless explicitly required.
• Do not duplicate PDF rendering logic in the tracking engine.
• Keep single-CVE PDF generation separate from batch tracking/discovery logic.
• Keep vendor detection consistent across both engines.
• Keep console output readable for engineers.
• Preserve Windows compatibility.
• Use underscores for Python module filenames.
• Keep generated PDFs and state files out of Git.

---

Summary

CVEAlerts provides two complementary capabilities:

CVE PDF Engine
    eva_cve_pdf.py
    Generate one high-quality PDF brief for one CVE.

CVE Tracking Engine
    eva_cve_tracking.py
    Discover recent critical CVEs for Cisco, Fortinet, Juniper, and HP-Aruba, then pass new matches into the PDF engine.

The planned GUI will sit above both engines and provide a self-contained interface for everyday engineer use.