HackDev-CVEWatch

CVE feed monitor with keyword/vendor/severity filtering, EPSS exploitation-probability scoring, CISA KEV cross-referencing, and new-CVE alerting, built on the NVD REST API v2. Part of the HackDev open-source cybersecurity toolkit.

Features

• Queries the NVD REST API v2, no API key required for casual use (--api-key/NVD_API_KEY for higher rate limits)
• EPSS scoring: enriches every CVE with its FIRST.org EPSS exploitation-probability score (batched API calls, free, no key), filterable with --min-epss
• CISA KEV cross-reference: flags any CVE on the CISA Known Exploited Vulnerabilities catalog as actively exploited — the strongest priority signal in a report. The feed is cached locally with a 24h TTL (--kev-ttl) so repeated runs don't re-download it every time.
• Filters: --keyword, --vendor/--product, --min-cvss, --min-epss, --since
• Local JSON state tracking so repeated (e.g. scheduled/cron) runs only alert on newly observed CVEs
• Automatic exponential backoff on NVD rate limiting (HTTP 403/429)
• Priority-sorted reports: CISA KEV first, then descending EPSS score, then descending CVSS
• Three output formats: text, json, and a self-contained html report (inline CSS, no external assets)
• Optional --webhook-url to POST new findings as JSON, without crashing the run on delivery failure

Installation

git clone https://github.com/raghubirrajmahato15/HackDev-CVEWatch.git
cd HackDev-CVEWatch
pip install -r requirements.txt

Requires Python 3.10+ and requests.

Usage

Basic run, reporting any CVEs not seen before, with EPSS + KEV enrichment (on by default):

python cvewatch.py

Only CVEs that are both high-CVSS and have a meaningful exploitation probability:

python cvewatch.py --min-cvss 7.0 --min-epss 0.1

Generate a self-contained HTML report:

python cvewatch.py --keyword apache --format html -o report.html

Skip the EPSS/KEV enrichment calls for a faster, fully-NVD-only run:

python cvewatch.py --keyword nginx --no-epss --no-kev

Use an NVD API key, forward new findings to a webhook:

export NVD_API_KEY=your-nvd-api-key
python cvewatch.py --keyword "remote code execution" --webhook-url https://hooks.example.com/alert

Running on a schedule

CVEWatch's state file is designed to be idempotent — each run only reports and marks-seen new CVEs, so it's safe to run unattended. A cron entry:

# Check for new high-severity CVEs every 6 hours
0 */6 * * * cd /opt/hackdev-cvewatch && /usr/bin/python3 cvewatch.py --min-cvss 8.0 --webhook-url "$WEBHOOK_URL" >> /var/log/cvewatch.log 2>&1

Or a systemd timer (cvewatch.timer + cvewatch.service):

# /etc/systemd/system/cvewatch.service
[Service]
Type=oneshot
WorkingDirectory=/opt/hackdev-cvewatch
ExecStart=/usr/bin/python3 cvewatch.py --min-cvss 8.0 --webhook-url %E{CVEWATCH_WEBHOOK_URL}

# /etc/systemd/system/cvewatch.timer
[Timer]
OnCalendar=*-*-* 00,06,12,18:00:00
Persistent=true

[Install]
WantedBy=timers.target

CLI flag reference

Flag	Description
-o, --output	Write output to this file instead of stdout
--format {text,json,html}	Output format (default: text)
-v, --verbose	Enable verbose (DEBUG-level) logging
--keyword TEXT	Filter by description keyword
--vendor TEXT / --product TEXT	Filter by vendor/product (best-effort match)
--min-cvss FLOAT	Minimum CVSS v3 base score
--min-epss FLOAT	Minimum EPSS exploitation-probability score (0.0-1.0)
--since YYYY-MM-DD	Filter by publish date; drives the NVD pubStartDate parameter
--results-per-page INT	Results per page (default 50, capped at 2000)
--state-file PATH	Seen-CVE state file (default ~/.hackdev/cvewatch_seen.json)
--show-all	Report all matching CVEs, not just new ones
--api-key KEY	NVD API key (or NVD_API_KEY env var)
--webhook-url URL	POST new findings as JSON to this URL
--no-epss / --no-kev	Skip EPSS enrichment / CISA KEV cross-reference
--kev-cache PATH / --kev-ttl SECONDS	KEV cache location and TTL (default 24h)
--version	Show version and exit

Project layout

cvewatch.py                 Thin CLI entrypoint
hackdev_cvewatch/
  nvd.py                       NVD API client, CVE parsing, filtering
  epss.py                        FIRST.org EPSS batch lookup
  kev.py                           CISA KEV catalog, TTL-cached
  state.py                          Seen-CVE JSON state tracking
  report.py                          Priority sorting, text/JSON/HTML rendering
  cli.py                              argparse wiring, orchestration
tests/                       pytest suite

Testing

pip install -r requirements-dev.txt
pytest -q

Covers CVE parsing/filtering against realistic NVD fixture JSON, EPSS batch lookup (success, HTTP failure, network exception, malformed entries, batching), KEV cache TTL behavior (fresh cache reused with zero network calls; stale cache triggers a refresh; network failure falls back to the stale cache), state-file dedup across simulated runs, and priority sorting / all three report formats.

Legal

HackDev-CVEWatch queries only publicly available data (NVD, FIRST.org EPSS, CISA KEV) and is intended for defensive use: vulnerability monitoring, security research, and internal alerting. It performs no offensive actions against any system. Users are responsible for complying with each data source's terms of use and rate limits.