AI Vulnerability Intelligence Agent Converts CVEs to Actionable Security Reports

Notifications You must be signed in to change notification settings

Fork 0

Star 0

Copy path

More file actions

More file actions

Latest commit

History

History

History

369 lines (278 loc) · 20.3 KB

Raw

Copy raw file

Download raw file

Outline

CVE AI Agent 🛡️

An autonomous vulnerability intelligence engine. Continuously ingests, enriches, and triages CVE data — then delivers findings to your platform of choice via 3rd party tools like n8n, Jira, Slack, Splunk, and/or local file exports.

🎯 What This Is

The CVE AI Agent is an autonomous cybersecurity data pipeline designed for SOC-grade, auditable vulnerability intelligence.

It runs continuously in the background, fetching fresh vulnerability data from authoritative sources (NVD, CISA KEV, EPSS), evaluating each CVE against your configured risk thresholds, and dispatching AI-generated threat assessments to your workflow of choice.

⚡ Token-Efficient Architecture

Unlike traditional AI agents that "dump" raw data into LLMs, the CVE AI Agent uses a Deterministic Minimization Logic to filter out noise:

1K Token Average: Prompts are strictly pruned to stay around 1,000 tokens (approx. 4,000 characters).

Resource Savings: Minimal API usage saves money and compute resources while reducing latency.

Precision Context: Only sends relevant metadata, references, and CVE-specific context, eliminating "context window noise" that causes hallucinations.

The CVE AI Agent is LLM agnostic. Additional LLM providers can be added by extending the provider definitions in config.json.

The agent follows a strict Two-Pass architecture:

Pass 1 (Deterministic): All measurable data — CVSS, EPSS, KEV status, CWE, MITRE ATT&CK mapping, CAPEC — is extracted from APIs and curated datasets. No LLM is involved. Product names are derived using hardened regex heuristics.

Pass 2 (LLM Enrichment): The LLM fills only the explicitly marked qualitative sections (Executive Summary, Impact, Detection, Remediation, Escalation, CWE Analysis) using the deterministic context as grounding. If the LLM is unavailable, the agent generates a high-visibility failure notification and a "pure static" report for audit transparency.

📖 New user? Start with the Installation Guide.

❓ Having trouble? Check the FAQ & Troubleshooting.

🏗️ Architecture deep-dive? See ARCHITECTURE.md.

🔄 How It Works

┌─────────────────────────────────────────────────────────────┐ │ PASS 1: DETERMINISTIC ENGINE (Layer 1 & 2) │ │ layer1_fetcher.py ──► Fetches NVD, EPSS, KEV, CWE, MITRE │ │ layer2_engine.py ──► Generates 'static_json' │ └──────────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ │ PASS 2: LLM ENRICHMENT (Layer 3) │ │ layer3_enricher.py ──► Processes 'static_json' target keys │ │ (Gemini / OpenAI / Claude / Groq / Ollama) │ │ Outputs: 'enriched_json' │ └──────────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ │ OUTPUT (Layer 4) │ │ layer4_report_generator.py → PDF report │ │ agent_core.py → Slack / Jira / n8n / Splunk dispatch │ │ app_gemini.py → Web Dashboard at http://localhost:8080 │ └─────────────────────────────────────────────────────────────┘

📊 Output Examples

Here are examples of the output generated by the CVE AI Agent pipeline:

📄 AI-Enriched Threat Report (PDF)

💾 Structured CVE Intelligence (JSON)

🚀 Quickstart

Windows (Recommended)

Script What it does

start.bat Launches the full app (agent + web dashboard at http://localhost:8080)

start_agent.bat Launches the agent only (headless background pipeline)

test.bat Runs the 3-CVE smoke test using mock data to verify pipeline integrity

Both launchers will:

Create a Python virtual environment (.venv) if one doesn't exist

Install all required dependencies from requirements.txt

Prompt you to choose your LLM provider

Warn if a required API key is missing

Start the application

Docker (1-Command Deployment)

Windows: .\docker-start.bat

Linux / macOS: chmod +x docker-start.sh && ./docker-start.sh

Dashboard available at http://localhost:8080.

Linux / macOS / Manual

git clone https://github.com/gtamir02-png/cve-ai-agent.git && cd cve-ai-agent python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt export GEMINI_API_KEY="your_key_here" python app_gemini.py

🧠 Analysis Pipeline — File Map

File Layer Role

pipeline_v2.py Orchestrator Primary execution pipeline. Runs Layers 1 through 4 sequentially. CLI: python pipeline_v2.py --cve CVE-2026-0300

layer1_fetcher.py Layer 1 Fetches raw API data (NVD, EPSS, KEV, CWE CSV, MITRE dataset) and handles fallback values.

layer2_engine.py Layer 2 Deterministic logic engine. Derives scores, applies risk formulas, constructs static_json with [LLM NEEDED] placeholders.

layer3_enricher.py Layer 3 Identifies [LLM NEEDED] tags, builds minimal prompts, and fills qualitative sections in enriched_json.

layer4_report_generator.py Layer 4 Generates the PDF report using ReportLab, styling components based on the enriched_json schema. Includes a failure alert boxes if LLM enrichment fails.

layer3_attack_enricher.py Supporting (Decommissioned) Formerly Layer 3b AI-derived ATT&CK mapping. Removed to prioritize deterministic integrity.

| mitre_attack_mapper.py | Supporting | Three-tier CWE→ATT&CK mapper (Seed Dataset → CAPEC Bridge → LLM fallback). | | llm_core.py | Supporting | Provider-agnostic LLM dispatcher. | | agent_core.py | Agent | The autonomous loop. Polls CVEs, triggers the pipeline, and sends webhooks. | | app_gemini.py | Web UI | Flask/Waitress web dashboard and REST API. |

📊 MITRE ATT&CK Mapping — Tier Priority

The MitreAttackMapper resolves CWE IDs to ATT&CK techniques in strict priority order:

Tier Source Confidence Shown in Report

0 (highest) CWE_and_ATTACK.json — curated dataset with real per-technique scores Actual value, e.g. 82%

1 CAPEC bridge built from MITRE STIX (data/attack_capec_cache.json) Fixed 60%

2 (lowest) LLM synthesis (fallback only when CWE not found above) Fixed 40%

The report's MITRE ATT&CK Mapping section shows a color-coded Confidence column: 🟢 ≥70% · 🟡 40–69% · 🔴 0.10, else 0) )

🤖 LLM Providers

Provider Recommended Models Key Env Variable

Google Gemini (default) gemini-3-flash-preview, gemini-2.5-flash, gemini-2.5-pro GEMINI_API_KEY

OpenAI gpt-4o, gpt-4o-mini OPENAI_API_KEY

Anthropic Claude claude-opus-4-5, claude-sonnet-4-5, claude-haiku-3-5 ANTHROPIC_API_KEY

Groq llama-3.3-70b-versatile, llama-3.1-70b-versatile, llama-3.1-8b-instant GROQ_API_KEY

Ollama (offline) gemma2, llama3.2, mistral (none)

The agent attempts each model in the configured list in order, falling back to the next on failure. If all fail, it falls back to a rule-based report (no LLM sections).

Note: While environment variables are recommended for API keys, you can also configure your key directly in config.json by placing it in the "custom_key": "" field under the respective provider.

📤 Integration Outputs

Integration Config Key Notes

Slack slack_enabled Sends alert message and uploads PDF/JSON files (requires Bot Token) or text-only (Webhook)

Jira jira_enabled Creates ticket with PDF attachment

n8n n8n_enabled Sends full JSON payload to webhook

Splunk splunk_enabled Posts structured event to Splunk HEC

PDF Export agent_auto_export Auto-saves to Exported_CVE_Reports/

💬 Slack Integration (File Uploads vs Text Alerts)

The CVE Agent supports two modes for Slack notifications:

1. File Upload Mode (Recommended)

Uploads the PDF Report and the Enriched JSON file directly into the Slack channel as threaded replies to the main alert.

Requirements: You must use the official Slack API. Create a Slack App at api.slack.com/apps.

Scopes Needed: Go to "OAuth & Permissions" and add chat:write and files:write to your Bot Token Scopes. Install the app to your workspace.

Config: Set slack_bot_token (e.g. xoxb-...) and slack_channel_id (e.g. C0123456789) in config.json. Leave slack_webhook_url empty. Invite the bot to your channel (/invite @BotName).

1. Webhook Mode (Text Only)

Sends a simple text alert with the CVE summary. Does not support file attachments.

Requirements: A standard Slack Incoming Webhook URL.

Config: Set slack_webhook_url in config.json. Leave slack_bot_token and slack_channel_id empty.

🔁 Recheck Feature

The agent includes an automated recheck workflow that periodically re-evaluates previously-processed CVEs when authoritative signals change (NVD, EPSS, CISA KEV, or patch status). The recheck manager performs a cheap Layer‑1-only fetch, diffs against the last stored snapshot, and then either:

writes a new snapshot and reschedules the CVE,

logs the change (no report) if below thresholds, or

triggers the existing pipeline in delta mode when the change meets configured thresholds (e.g. KEV newly listed or CVSS/EPSS moves above filters).

Note: recheck.recheck_cvss_threshold controls eligibility for monitoring existing CVEs. It is independent of agent_cvss_value, which controls the main report/action threshold for new findings. This allows the agent to monitor emerging threats below the reporting threshold.

Configuration (in config.json under recheck):

recheck.enabled (bool, default: true)

recheck.max_age_days (int, default: 90)

recheck.recheck_cvss_threshold (float, default: 8.0) — controls which previously-processed CVEs are monitored for recheck, independent of the main report threshold.

recheck.epss_delta_threshold (float, default: 0.05)

recheck.kev_always_triggers (bool, default: true)

recheck.schedule — controls how often CVEs are rechecked by risk category.

Implementation:

recheck_manager.py — standalone recheck logic called from agent_core.py each polling cycle. It writes snapshots to cve_snapshots, updates cve_recheck_queue, and logs events to agent_events.

On first run with an empty queue, the manager performs a CVSS-filtered scan of the cves table and queues matching CVEs for recheck.

The queue is then processed on subsequent cycles, with due items fetched by next_recheck and rescheduled based on observed changes.

🔒 Authentication

The web dashboard requires a password. Set it before first launch:

$env:DASHBOARD_PASS="YourSecurePass123" # Windows export DASHBOARD_PASS="YourSecurePass123" # Linux/macOS

Or set dashboard_password in config.json.

📋 Changelog (Recent)

v2.3 — Pipeline Hardening & High-Fidelity Extraction (NEW): Added high-visibility red failure alerts in PDF reports with detailed LLM provider error reason (e.g. 429 Rate Limit). Hardened product extraction regex for WordPress/Perl/Frameworks. Decommissioned Layer 3b AI-derived ATT&CK mapping to ensure 100% deterministic integrity for the MITRE section.

v2.4 — Automated Recheck Workflow (NEW): Added a configurable recheck manager to periodically re-evaluate previously-processed CVEs when authoritative signals change (NVD/EPSS/KEV/patch status). See the Recheck Feature section below for details.

v2.2 — Report Type Configuration: Added report_type config parameter (full | short) to control PDF report structure. Short reports compress 5 key LLM sections to AI-only content, reducing page count by ~30–40%.

v2.1 — Stability & Hardening: Fixed NoneType errors in Layer 1 fetcher for null CWE IDs; resolved PDF LayoutError for long descriptions; fixed NameError in manual analysis loop.

Report: "Relevance" column replaced with color-coded Confidence % in MITRE ATT&CK section

EPSS: Fixed score vs. percentile separation; SOC Triage now shows 3 rows (Score, Percentile, Assessment)

Timeline: KEV Remediation Due Date is now a dedicated red-dot timeline entry

Risk Breakdown: Simplified formula display; correct × notation for multipliers

LLM Config: Updated to latest stable Gemini models; removed decommissioned Mixtral from Groq list

📖 See INSTALL.md for full setup instructions.

🏗️ See ARCHITECTURE.md for the technical deep-dive.

📄

[truncated for AI cost control]