gtamir02-png/cve-ai-agent
GitHub: gtamir02-png/cve-ai-agent
CVE AI Agent 是一个自动化漏洞情报管道，利用AI生成可审计的威胁报告，提升安全运营效率。
Stars: 4 | Forks: 0
# CVE AI 代理 🛡️
[](LICENSE)
[](https://python.org)
[](#-llm-providers)
## 🎯 这是什么
**CVE AI Agent** 是一个自主的网络安全数据管道，专为 **SOC 级别、可审计的漏洞情报** 而设计。
它持续在后台运行，从权威来源（NVD、CISA KEV、EPSS）获取最新的漏洞数据，根据您配置的风险阈值评估每个 CVE，并将 AI 生成的威胁评估分派到您选择的工作流中。
### ⚡ 高效的 Token 架构
与传统 AI 代理将原始数据"倾倒"给 LLM 不同，CVE AI Agent 使用 **确定性最小化逻辑** 来过滤噪声：
* **平均 1K Token**：提示经过严格修剪，保持在大约 1,000 个 token（约 4,000 个字符）。
* **节省资源**：最小化 API 使用量，在降低延迟的同时节省资金和计算资源。
* **精确上下文**：仅发送相关的元数据、引用和 CVE 特定上下文，消除导致幻觉的"上下文窗口噪声"。
CVE AI Agent **与 LLM 无关**。可以通过扩展 `config.json` 中的提供者定义来添加额外的 LLM 提供者。
该代理遵循严格的 **双遍架构**：
- **第一遍（确定性）**：所有可测量的数据——CVSS、EPSS、KEV 状态、CWE、MITRE ATT&CK 映射、CAPEC——从 API 和策划的数据集中提取。不涉及 LLM。产品名称使用健壮的正则表达式启发法推导。
- **第二遍（LLM 增强）**：LLM 仅填充明确标记的定性部分（执行摘要、影响、检测、修复、升级、CWE 分析），使用确定性上下文作为基础。如果 LLM 不可用，代理会生成一个高可见性的失败通知和一个"纯静态"报告，以确保审计透明度。
## 🔄 工作原理
```
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────┘
```
## 📊 输出示例
以下是 CVE AI Agent 管道生成的输出示例：
### 📄 AI 增强的威胁报告 (PDF)
### 💾 结构化 CVE 情报 (JSON)
## 🚀 快速开始
### Windows (推荐)
| 脚本 | 功能 |
|---|---|
| `start.bat` | 启动 **完整应用**（代理 + 位于 `http://localhost:8080` 的 Web 仪表盘） |
| `start_agent.bat` | **仅启动代理**（无头后台管道） |
| `test.bat` | 使用模拟数据运行 **3 个 CVE 的冒烟测试** 以验证管道完整性 |
这两个启动器都会：
1. 如果不存在，则创建一个 Python 虚拟环境 (`.venv`)
2. 从 `requirements.txt` 安装所有必需的依赖项
3. 提示您选择 LLM 提供者
4. 如果缺少必需的 API 密钥，则发出警告
5. 启动应用程序
### Docker（一键部署）
**Windows**：`.\docker-start.bat`
**Linux / macOS**：`chmod +x docker-start.sh && ./docker-start.sh`
仪表盘位于 `http://localhost:8080`。
### Linux / macOS / 手动安装
```
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
```
## 🧠 分析管道 — 文件映射
| 文件 | 层级 | 作用 |
|---|---|---|
| `pipeline_v2.py` | 协调器 | **主要执行管道。** 按顺序运行第 1 到第 4 层。CLI：`python pipeline_v2.py --cve CVE-2026-0300` |
| `layer1_fetcher.py` | 第 1 层 | 获取原始 API 数据（NVD、EPSS、KEV、CWE CSV、MITRE 数据集）并处理回退值。 |
| `layer2_engine.py` | 第 2 层 | 确定性逻辑引擎。推导分数，应用风险公式，构建带有 `[LLM NEEDED]` 占位符的 `static_json`。 |
| `layer3_enricher.py` | 第 3 层 | 识别 `[LLM NEEDED]` 标签，构建最小提示，并在 `enriched_json` 中填充定性部分。 |
| `layer4_report_generator.py` | 第 4 层 | 使用 ReportLab 生成 PDF 报告，根据 `enriched_json` 模式设置组件样式。如果 LLM 增强失败，包含故障警报框。 |
| `layer3_attack_enricher.py` | 支持 | （已停用）原第 3b 层 AI 推导的 ATT&CK 映射。已移除以优先确保确定性完整性。 |
| `mitre_attack_mapper.py` | 支持 | 三级 CWE→ATT&CK 映射器（种子数据集 → CAPEC 桥接 → LLM 回退）。 |
| `llm_core.py` | 支持 | 与提供者无关的 LLM 调度器。 |
| `agent_core.py` | 代理 | 自主循环。轮询 CVE，触发管道，并发送 webhook。 |
| `app_gemini.py` | Web UI | Flask/Waitress Web 仪表盘和 REST API。 |
## 📊 MITRE ATT&CK 映射 — 层级优先级
`MitreAttackMapper` 严格按优先级顺序将 CWE ID 解析为 ATT&CK 技术：
| 层级 | 来源 | 报告中显示的置信度 |
|---|---|---|
| **0** (最高) | `CWE_and_ATTACK.json` — 包含真实按技术评分的策划数据集 | 实际值，例如 `82%` |
| **1** | 基于 MITRE STIX 构建的 CAPEC 桥接 (`data/attack_capec_cache.json`) | 固定 `60%` |
| **2** (最低) | LLM 综合（仅在上述未找到 CWE 时作为回退） | 固定 `40%` |
报告的 **MITRE ATT&CK 映射** 部分显示一个带颜色编码的 **置信度** 列：🟢 ≥70% · 🟡 40–69% · 🔴 <40%。
## 📄 PDF 报告结构（12 个部分）
CVE 代理生成专业的 PDF 报告，并具有 **可配置的报告类型**（v2.2+）。可选择：
- **`full`** — 包含静态数据和 AI 生成分析部分的完整报告（默认）
- **`short`** — 仅包含关键部分的 AI 生成洞察的精简报告（针对快速决策优化）
### 完整报告模式 (`"report_type": "full"`)
| # | 部分 | 静态数据 | AI 分析 | 来源 |
|---|---|---|---|---|
| 0 | 记分板（风险评分 · CVSS · EPSS 评分 · KEV · 行动） | ✓ | — | 确定性 |
| 1 | 元数据（产品 · 触发 · 攻击面 · CWE · 补丁状态） | ✓ | — | 确定性 |
| 2 | 执行摘要 | ✓ NVD 描述 | ✓ AI 分析 | LLM |
| 3 | 业务与技术影响 | ✓ CVSS 指标 | ✓ AI 分析 | LLM |
| 4 | SOC 分诊与可利用性 | ✓ | — | 确定性 |
| 5 | 漏洞时间线 | ✓ | — | 确定性 |
| 6 | 影响范围（基于 CVSS + CPE） | ✓ | — | 确定性 |
| 7 | 检测指导 | ✓ 日志源 | ✓ AI 分析 | LLM |
| 8 | 修复 | ✓ 补丁状态 | ✓ AI 分析 | LLM |
| 9 | 升级程序 | ✓ 触发器 | ✓ AI 分析 | LLM |
| 10 | MITRE ATT&CK 映射 | ✓ | — | 确定性 |
| 11 | 风险分解公式 | ✓ | — | 确定性 |
| 12 | 附录（CVSS 定义） | ✓ | — | 确定性 |
### 精简报告模式 (`"report_type": "short"`)
针对速度和 SOC 快速分诊优化。移除冗余的静态部分，并用 AI 生成的洞察填充关键区域：
| # | 部分 | 内容 | 来源 |
|---|---|---|---|
| 0 | 记分板 | ✓ 所有指标 | 确定性 |
| 1 | 元数据 | ✓ 所有字段 | 确定性 |
| 2 | 执行摘要 | **仅 AI 分析**（替代 NVD 描述） | LLM |
| 3 | 业务与技术影响 | **仅 AI 分析**（替代 CVSS 指标） | LLM |
| 4 | SOC 分诊与可利用性 | ✓ 所有指标 | 确定性 |
| 5 | 漏洞时间线 | ✓ 所有事件 | 确定性 |
| 6 | 影响范围 | ✓ 所有数据 | 确定性 |
| 7 | 检测指导 | **仅 AI 分析**（替代日志源） | LLM |
| 8 | 修复 | **仅 AI 分析**（替代补丁状态） | LLM |
| 9 | 升级程序 | **仅 AI 分析**（替代触发器） | LLM |
| 10 | MITRE ATT&CK 映射 | ✓ 完整映射 | 确定性 |
| 11 | 风险分解公式 | ✓ 完整公式 | 确定性 |
| 12 | 附录 | ✓ CVSS 定义 | 确定性 |
**主要区别：**
- 精简报告在保留所有 LLM 洞察的同时，将页面数量减少约 30–40%
- 静态确定性数据被压缩到记分板/元数据/SOC/时间线/范围部分
- 所有 5 个 LLM 部分（2、3、7、8、9）完全由 AI 生成的叙述填充
- 非常适合以 AI 建议为主要决策依据的自动化分诊工作流
## 📁 数据文件与配置
| 文件 | 格式 | 用途 |
|---|---|---|
| `config.json` | JSON | 运行时配置：LLM 提供者、模型、阈值、集成、输出控制 |
| `CWE_and_ATTACK.json` | JSON | **主要的 MITRE 映射和 CWE 来源。** 综合的 CWE 参考和策划的 ATT&CK 映射。 |
| `CVSS_v4.0.json` | JSON | 用于报告 CVSS 附录表的 CVSS v4.0 指标缩写定义。 |
| `assets.json` | JSON | 资产/产品过滤列表。当 `use_assets_filtering: true` 时，只有匹配这些资产的 CVE 才会触发分析。 |
| `data/attack_capec_cache.json` | JSON | 自动生成的 MITRE ATT&CK ↔ CAPEC 桥接（首次运行时从 STIX 下载，缓存 30 天）。 |
| `schema.sql` | SQL | SQLite 数据库模式定义。 |
| `cves.db` | SQLite | 实时漏洞数据库（已添加到 .gitignore）。 |
## ⚙️ 配置参考 (`config.json`)
```
{
"llm_provider": "gemini", // Active provider: gemini | openai | groq | claude | ollama | none
"llm_models": { ... }, // Per-provider model lists and API key env vars
"agent_cvss_value": 10, // Minimum CVSS score to trigger analysis
"agent_min_severity": "Critical", // Severity filter
"agent_cvss_operator": ">=", // Comparison operator for CVSS threshold
"preferred_cvss_version": "4.0", // Prefer v4.0, fallback to v3.1/v3.0
"agent_auto_export": true, // Auto-export PDF to Exported_CVE_Reports/
"export_format": "pdf", // pdf
"report_type": "short", // full | short
"use_assets_filtering": false, // Filter by assets.json product list
"agent_sleep_seconds": 3600, // Polling interval in seconds
"dashboard_password": "change-me", // Dashboard login password (admin user)
"slack_enabled": false, // Enable Slack notifications
"slack_bot_token": "xoxb-...", // (Optional) Bot Token for file uploads
"slack_channel_id": "C0...", // (Optional) Channel ID for file uploads
"jira_enabled": false, // Enable Jira ticket creation
"n8n_enabled": false, // Enable n8n webhook dispatch
"splunk_enabled": false, // Enable Splunk HEC ingestion
"splunk_hec_url": "", // Splunk HEC endpoint
"splunk_hec_token": "", // Splunk HEC token
"output_files": { // Per-run output artifact toggles
"static_json": true,
"enriched_json": true
},
"risk_score_weights": { // Deterministic scoring weights
"cvss_multiplier": 7,
"epss_multiplier": 10,
"kev_bonus": 15,
"exploit_bonus": 5
}
}
```
### `report_type` 配置 (v2.2+)
| 值 | 行为 | 使用场景 |
|---|---|---|
| `"full"` | **默认。** 在 LLM 区域中分别显示静态数据和 AI 分析部分。为存档/合规提供最大细节。 | 详细分诊、SOC 文档、审计跟踪 |
| `"short"` | 在第 2、3、7、8、9 部分中，AI 分析替代静态数据。精简布局以加快决策。减少约 30–40% 的页面。 | 快速分诊、执行摘要、实时仪表盘 |
## 🔧 风险评分公式
```
risk_score = min(100,
cvss_base (CVSS × 7)
+ epss_bonus (EPSS_raw × 10)
+ kev_bonus (15 if KEV listed, else 0)
+ exploit_bonus (5 if EPSS_raw > 0.10, else 0)
)
```
## 🤖 LLM 提供者
| 提供者 | 推荐模型 | 关键环境变量 |
|---|---|---|
| **Google Gemini** *(默认)* | `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** *(离线)* | `gemma2`, `llama3.2`, `mistral` | *(无)* |
代理会按配置列表中的顺序尝试每个模型，如果失败则回退到下一个。如果全部失败，则回退到基于规则的报告（无 LLM 部分）。
*注意：虽然推荐使用环境变量存储 API 密钥，但您也可以通过将密钥放在相应提供者下的 `"custom_key": ""` 字段中，直接在 `config.json` 中进行配置。*
## 📤 集成输出
| 集成 | 配置键 | 说明 |
|---|---|---|
| **Slack** | `slack_enabled` | 发送警报消息并上传 PDF/JSON 文件（需要 Bot Token）或纯文本（Webhook） |
| **Jira** | `jira_enabled` | 创建带有 PDF 附件的票据 |
| **n8n** | `n8n_enabled` | 向 webhook 发送完整的 JSON 载荷 |
| **Splunk** | `splunk_enabled` | 向 Splunk HEC 发布结构化事件 |
| **PDF 导出** | `agent_auto_export` | 自动保存到 `Exported_CVE_Reports/` |
## 🔁 重检功能
该代理包含一个自动化的重检工作流，当权威信号（NVD、EPSS、CISA KEV 或补丁状态）发生变化时，会定期重新评估先前处理过的 CVE。重检管理器执行廉价的仅第一层获取，与上次存储的快照进行差异比较，然后：
- 写入新快照并重新安排 CVE 调度，
- 如果低于阈值，则记录更改（不生成报告），或
- 当更改满足配置的阈值（例如，KEV 新增列表或 CVSS/EPSS 超过滤波器）时，以增量模式触发现有管道。
配置（在 `config.json` 的 `recheck` 下）：
- `recheck.enabled`（布尔值，默认值：`true`）
- `recheck.max_age_days`（整数，默认值：`90`）
- `recheck.recheck_cvss_threshold`（浮点数，默认值：`8.0`）— 控制哪些先前处理过的 CVE 被监控以进行重检，独立于主报告阈值。
- `recheck.epss_delta_threshold`（浮点数，默认值：`0.05`）
- `recheck.kev_always_triggers`（布尔值，默认值：`true`）
- `recheck.schedule` — 控制按风险类别重检 CVE 的频率。
实现：
- `recheck_manager.py` — 独立的重检逻辑，在 `agent_core.py` 的每个轮询周期调用。它将快照写入 `cve_snapshots`，更新 `cve_recheck_queue`，并将事件记录到 `agent_events`。
- 首次在队列为空时运行，管理器会对 `cves` 表执行 CVSS 过滤扫描，并将匹配的 CVE 排队等待重检。
- 然后，队列在后续周期中处理，待处理项通过 `next_recheck` 获取，并根据观察到的变化重新安排。
## 🔒 认证
Web 仪表盘需要密码。在首次启动前设置：
```
$env:DASHBOARD_PASS="YourSecurePass123" # Windows
export DASHBOARD_PASS="YourSecurePass123" # Linux/macOS
```
或在 `config.json` 中设置 `dashboard_password`。
## 📋 更新日志（近期）
- **v2.3 — 管道加固与高保真提取**（新功能）：在 PDF 报告中添加了高可见性的红色故障警报，并包含详细的 LLM 提供者错误原因（例如 429 速率限制）。加固了用于 WordPress/Perl/Frameworks 的产品提取正则表达式。停用了第 3b 层 AI 推导的 ATT&CK 映射，以确保 MITRE 部分 100% 的确定性完整性。
- **v2.4 — 自动化重检工作流**（新功能）：添加了可配置的重检管理器，当权威信号（NVD/EPSS/KEV/补丁状态）发生变化时，定期重新评估先前处理过的 CVE。详情请参阅下方的 **重检功能** 部分。
- **v2.2 — 报告类型配置**：添加了 `report_type` 配置参数（`full` | `short`）以控制 PDF 报告结构。精简报告将 5 个关键 LLM 部分压缩为仅 AI 内容，减少约 30–40% 的页面。
- **v2.1 — 稳定性与加固**：修复了第 1 层获取器中 CWE ID 为 null 时的 `NoneType` 错误；解决了长描述导致的 PDF `LayoutError`；修复了手动分析循环中的 NameError。
- **报告**：MITRE ATT&CK 部分中的"相关性"列被替换为带颜色编码的 **置信度 %**
- **EPSS**：修复了分数与百分位数的分离问题；SOC 分诊现在显示 3 行（分数、百分位数、评估）
- **时间线**：KEV 修复截止日期现在是一个专用的红点时间线条目
- **风险分解**：简化了公式显示；乘法器使用正确的 `×` 符号
- **LLM 配置**：更新到最新的稳定 Gemini 模型；从 Groq 列表中移除了已停用的 Mixtral
标签：AI代理, API集成, C2, CVE处理, GPT, LLM集成, Python编程, SOC级, Token优化, 两阶段架构, 可审计, 可观测性, 威胁情报, 威胁评估, 安全运营中心, 开发者工具, 数据管道, 漏洞数据, 漏洞管理, 网络安全, 网络映射, 网络调试, 自动化, 请求拦截, 软件工程, 逆向工具, 隐私保护