Skip to content
This repository was archived by the owner on Oct 5, 2026. It is now read-only.
xgfurbPublic archive

About

Archived — retired daily CVE monitoring agent for Microsoft and Linux

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

CVE Monitoring Agent

Checks Daily CVE Scan

Readable vulnerability briefs for Microsoft Windows, Office, and Linux server products. Reports prioritize confirmed exploitation, show what changed, and link back to the evidence.

Python 3.12+ · Linux/macOS · No third-party runtime dependencies · Optional email and AI

Quick start · GitHub deployment · Configuration · Reading reports · Troubleshooting · Development

What you receive

  • An email digest with the ten highest-priority findings and a complete HTML report attached (inside a ZIP file when larger than 2 MiB).
  • A readable HTML report, Markdown, and JSON for every scan, including scans with no new findings.
  • A “Start here” list, followed by exploited, critical, high, and other updates. Recently added CISA entries come first within the exploited section.
  • Attack requirements from CVSS, including local/network access and required privileges.
  • Clear change labels such as newly confirmed exploitation, severity changed, and patch evidence changed.
  • Source health and freshness, so a failed download cannot look like an all-clear.

Counts cover the complete report and are exclusive: an exploited critical CVE counts in the exploited section once. Existing unchanged findings are not emailed repeatedly. No-change scans still write a report and a GitHub job summary. Previously reported findings may still require remediation.

Quick start

Use Python 3.12 or newer on Linux or macOS. No package installation is needed to run the agent.

git clone https://github.com/xgfurb/cve-agent.git
cd cve-agent
python main.py --demo

Open the HTML path printed in the terminal. The demo uses clearly labeled synthetic examples: no network requests, email, AI calls, or changes to reporting history.

Preview live vulnerability data

cp .env.example .env
python main.py --check-config --delivery local
python main.py --preview --delivery local --verbose

The live preview fetches data and writes reports, but sends no email, makes no AI calls, and changes no state. A free NVD API key speeds up collection. Add it to .env before the preview if available.

Start your own reporting history

This repository includes legacy reporting history. For a new local installation that should have its own baseline, reset that copied history once, then scan:

python main.py --reset --delivery local
python main.py --delivery local --verbose

Reset creates a backup and exits without scanning. Do not reset an existing deployment just to upgrade it; see state migration and retention.

The first scan backfills 90 days of modified records, plus relevant older CISA entries. This can produce a large initial report and take many minutes, especially without an NVD key. A backfilled finding is not necessarily a newly published vulnerability. Subsequent scans collect changes since the last successful scan with a two-day overlap and suppress unchanged findings already reported to the same destination.

Configuration

Start with .env.example. Settings load automatically from .env; exported environment variables override the file, and explicit CLI options take precedence. Values are literal: shell commands and variable expansion are never executed. Keep credentials in .env or GitHub secrets, never in committed files.

Setting Default Purpose
NVD_API_KEY Empty Faster NVD collection; optional.
DELIVERY_MODE auto local writes files; email requires SMTP settings; auto chooses based on credentials.
LOOKBACK_DAYS 90 Initial NVD modified-record backfill.
STATE_RETENTION_DAYS 180 Retention for inactive cache and history.
STATE_FILE reported_cves.json Local history and delivery outbox.
OUTPUT_DIR reports HTML, Markdown, and JSON output directory.
HTTP_TIMEOUT 30 Request timeout in seconds.
AI_ENABLED auto Enable explanations when an Anthropic key exists; false disables them.
AI_MAX_BATCHES 3 Maximum explanation batches per report, with up to eight findings each.
CLAUDE_MODEL See .env.example Model used for optional explanations.

Product aliases, initial search queries, and the minimum score belong in a JSON configuration file; see coverage and relevance. SMTP and Anthropic credentials are described below.

These environment settings apply locally. In GitHub Actions, only settings explicitly passed by the workflow are available to the process; creating an arbitrary repository variable does not automatically configure the agent.

Email

Set these values in .env:

SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@example.com
SMTP_PASS=your-smtp-app-password
EMAIL_TO=security@example.com

EMAIL_TO accepts comma-separated addresses. DELIVERY_MODE=auto selects email when credentials are present and files otherwise. Incomplete email configuration fails before a scan starts. Use --delivery local to explicitly select files only.

SMTP uses verified STARTTLS and a timeout. Use a STARTTLS endpoint, typically port 587; implicit TLS on port 465 is not supported. Certificate verification cannot be disabled.

A report is saved before email is attempted. Connection/login failures remain queued. An interrupted submission becomes uncertain, because the server might already have accepted it. Stable message IDs identify retries, but SMTP cannot guarantee exactly-once inbox delivery.

# Retry reports that clearly failed before submission; does not rescan or call AI.
python main.py --deliver-pending

# Only after verifying the report was NOT received:
python main.py --deliver-pending --retry-uncertain

# If you verified an uncertain report DID arrive:
python main.py --acknowledge-delivery REPORT_ID

Changing the email destination does not discard reports queued for the previous destination. Restore the original destination to reconcile them. A local report receipt does not suppress email alerts after switching to email.

GitHub Actions deployment

The deployed workflow runs daily at 12:17 UTC. Open Daily CVE Scan to check recent runs or select Run workflow. GitHub schedules can start later than the configured time.

To deploy your own fork, push the code to its default branch and configure Settings → Secrets and variables → Actions:

  • NVD_API_KEY — recommended for speed.
  • SMTP_SERVER, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_TO — optional email delivery.
  • ANTHROPIC_API_KEY — optional; enables bounded explanations by default. Set repository variable AI_ENABLED=false to disable them.

For a new fork, reset the copied legacy history once before the first production run if you want an independent baseline. Commit the reset state to your fork before the state branch is created. Trigger Daily CVE Scan manually and verify all four stages succeed.

The workflow has four stages:

  1. Scan: restore history, fetch data, create reports and a pending outbox. Read-only repository permission.
  2. Checkpoint: persist the outbox on the dedicated codex/cve-agent-state branch and claim delivery. Repository write permission, with no SMTP or AI secrets.
  3. Deliver: send the saved report. Read-only repository permission.
  4. Persist receipts: update delivery status on the state branch. Repository write permission, with no SMTP or AI secrets.

The default code branch is never changed by the bot. Runs sharing state are serialized. State updates use a compare-and-swap check plus a non-force branch update. Repository rules must allow the Actions token to create/update codex/cve-agent-state; rules blocking it fail the checkpoint before mail is sent.

Reports, migration backups, and recovery snapshots are retained as run artifacts for 30 days. Each artifact name includes the run ID and attempt number. A partial scan remains a failing workflow, while its usable report can still be saved and delivered. Open a run to read its summary. Under Artifacts, download prepared-RUN_ID-ATTEMPT, extract it, and open the .html file inside reports/. The same directory contains Markdown and JSON versions. Large emailed reports are attached as ZIP files; extract the HTML and open it in a browser.

A successful delivery means the SMTP server accepted the message. The final stage must also succeed to save that receipt durably. It does not prove inbox placement; check spam or mail filtering if needed.

The state branch includes public vulnerability evidence, generated commentary, and delivery status. It does not store API keys, SMTP passwords, or recipient addresses (a hash identifies the destination). Its visibility follows the repository's visibility. Do not add private fleet inventory or sensitive notes to this state without revisiting storage.

State snapshots on the dedicated data branch use lossless state.json.gz compression (split into numbered 4 MiB parts for large snapshots) to support large initial backfills. Existing uncompressed snapshots remain readable.

The cache retains the evidence fields used by reports (English description, vulnerable CPE criteria, scores, references, dates, and status). Redundant upstream metadata and translations are omitted; report facts and product matching remain unchanged.

Recover an interrupted workflow

Prefer Re-run all jobs over re-running only a failed delivery job. Attempt-specific artifacts deliberately prevent an old delivery claim from being replayed on a new attempt.

If email was accepted but receipt persistence failed, the next scan marks the old claim uncertain. Check the inbox and the receipts artifact before retrying. To reconcile locally with a narrowly scoped GitHub token:

export GITHUB_REPOSITORY=owner/repository
export GH_TOKEN=your-token
python scripts/state_branch.py restore --state recovery.json --meta recovery-meta.json
# Configure the same SMTP destination in .env, then choose ONE:
python main.py --state recovery.json --acknowledge-delivery REPORT_ID
# OR, if the email was not received:
python main.py --state recovery.json --deliver-pending --retry-uncertain
python scripts/state_branch.py checkpoint --state recovery.json --meta recovery-meta.json

Do not reconcile while another run is active. A changed state-branch head causes the checkpoint to refuse an overwrite; preserve your local receipts and reconcile against the latest snapshot. Do not force-push recovery state.

Coverage and relevance

Default product groups: Windows; Microsoft Office/365; Ubuntu; RHEL; Debian; Rocky Linux; AlmaLinux; SUSE Linux Enterprise; Oracle Linux; Amazon Linux; and the Linux kernel.

The first scan uses broad NVD description queries and classifies results using available vulnerable CPE entries, CISA product names, and description aliases. After a successful baseline, collection reads all modified NVD records and filters locally. This catches product-description changes, rejected CVEs, and CPE-only updates. All pages and date windows are fetched; severity selection happens after score normalization, including CVSS 4.0-only records.

Relevant CISA KEV entries are reconciled across the whole catalog, including older CVEs and those without a CVSS score. Missing NVD records retain CISA-only evidence and are retried. Existing KEV enrichment is refreshed at least weekly or through the normal NVD change stream.

This is product-level monitoring, not an inventory scanner. A description match is labeled “Needs applicability check.” CPE evidence also needs installed-version verification. Linux kernel coverage does not replace distribution package advisories, and the initial keyword backfill is not exhaustive. The initial exploitation report can contain old unresolved vulnerabilities newly seen by this monitor; CISA addition and publication dates make their age visible.

Customize aliases and bootstrap queries without editing Python:

python main.py --config examples/products.json

Changing product configuration triggers a new backfill. Use broad queries that can retrieve records even when version names are absent from the description; use aliases to express relevance. min_score defaults to 7.0; confirmed exploitation is included at any score. Run the same config consistently in scheduled jobs.

What the labels mean

Label Evidence
Actively exploited CVE appears in the current CISA KEV catalog, or retained cached KEV evidence when the source is unavailable (prominently disclosed).
Ransomware CISA reports known ransomware campaign use.
Patch reference available NVD includes a safe HTTPS reference tagged Patch; verify vendor/version applicability.
Patch not confirmed The data does not establish patch availability. An advisory alone is not proof of a fix.
Zero-day mention The source description uses the term; the monitor does not independently confirm it. KEV addition dates are not exploitation dates.
CISA catalog deadline Federal directive context, not a deadline assigned to your organization.

Human-readable descriptions are shortened for scanning; JSON retains the longer normalized text, and links lead to the full source. Application code controls IDs, scores, ordering, counts, evidence labels, and links.

Optional AI explanations

Set ANTHROPIC_API_KEY. AI_ENABLED=auto (the default) uses it for explanations; set AI_ENABLED=false or pass --no-ai to disable them. The model adds short, labeled explanations to at most 24 findings by default (three batches of eight). It cannot remove findings or replace factual fields. Empty, invalid, truncated, or unavailable output falls back to the complete factual report. AI text is escaped, link-free commentary and still needs verification against sources.

CLAUDE_MODEL is configurable. Token usage is saved in the JSON report. Operating cost depends on input volume and selected model; no fixed monthly cost is promised.

State migration and retention

The existing ID-to-date reported_cves.json migrates automatically to version 3. A timestamped backup is created before writing. Existing delivery history is preserved, and current facts establish the missing baseline. Previously reported CVEs now confirmed in KEV receive a one-time exploitation reconciliation alert.

For a fresh installation or fork that should not inherit the example history:

python main.py --reset

Reset preserves a backup and exits without scanning. On an already deployed repository, reset a restored state snapshot and checkpoint it using the recovery procedure; resetting the code-branch file does not replace the dedicated state branch.

Corrupt state stops with a clear error and preserves the original. Writes are atomic and protected against concurrent local runs. Inactive cache/history expires after 180 days; active KEV and pending deliveries are retained. Sent outbox records are retained for 14 days. Local HTML/JSON files are retained until you remove them.

Commands and status codes

python main.py --help
python main.py --check-config
python main.py --preview --delivery local
python main.py --demo
python main.py --no-ai
python main.py --state /path/state.json --output /path/reports
Exit code Meaning
0 Complete scan or successful requested operation.
1 Configuration, state, or local operation failure.
2 Incomplete source coverage (also used by argparse for invalid flags).
3 Pending, failed, mismatched-destination, or uncertain delivery needs attention.

Troubleshooting

What you see What to check
The first report contains thousands of findings This is the initial baseline, including older modified records and relevant CISA entries. Start with the prioritized digest; use the full attachment for review.
No email on a successful scan No new findings may need delivery, or the run may use local mode. Check the scan summary and delivery status.
Email configuration fails Run python main.py --check-config; supply all SMTP credentials and recipients, or select --delivery local.
Source coverage is partial or failed Read the source-health section and workflow logs. The report may still be useful, but it is not an all-clear.
Checkpoint fails before delivery Check repository permissions and rules for codex/cve-agent-state. Preserve the prepared artifact; email is gated on a successful checkpoint.
Delivery is uncertain, or receipt persistence failed Check the inbox and receipts artifact before retrying. Follow the recovery procedure to avoid duplicate mail.
State restoration fails Preserve the original snapshot and recovery artifacts. Do not delete or force-push state to clear the error.

For more detail, run with --verbose. Never post .env, tokens, or SMTP credentials when sharing diagnostics.

Development

python -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements-dev.txt
python -m unittest discover -s tests -v
ruff check .
ruff format --check .
pip-audit -r requirements-dev.txt --require-hashes --disable-pip

Runtime uses only the Python standard library. Development dependencies are pinned with hashes. CI runs the offline suite on Python 3.12 and 3.14, lint/format checks, dependency auditing, checksum-pinned actionlint workflow validation, and a checksum-pinned Gitleaks secret scan. Dependabot proposes dependency/action updates. Regenerate the development lock after changing requirements-dev.in:

uv pip compile requirements-dev.in --python-version 3.12 --generate-hashes -o requirements-dev.txt

Modules: config validates settings; sources collects evidence; models classifies records; state manages durable history; reporting renders reports; analysis optionally adds commentary; delivery handles SMTP; cli coordinates the run. scripts/state_branch.py handles GitHub checkpoints.

About

Archived — retired daily CVE monitoring agent for Microsoft and Linux

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages