cve-lookup

name	cve-lookup
description	Build and maintain a local vulnerability database by looking up CVE information from the web and organizing it into a structured year/CVE hierarchy. Searches NVD, MITRE, GitHub Security Advisories, Exploit-DB, CISA KEV, and more to compile structured reports with standardized templates. Maintains a searchable database index with metadata for each CVE entry. Triggered by: "CVE", "cve查询", "漏洞查询", "vulnerability lookup", "CVE编号", "查漏洞", "漏洞详情", "security advisory", "cve lookup", "漏洞缓解", "漏洞防御", "漏洞修复", "mitigation", "remediation", "概念性POC", "概念性PoC", "漏洞分析", "深度分析", "漏洞复现", "漏洞数据库", "构建漏洞库", "vulnerability database", "CVE数据库", "漏洞库查询", "数据库统计".
version	3.1.0
allowed-tools	Read Write WebSearch WebFetch Glob Bash
dependencies	python>=3.8
metadata	{"tags":"security, cve, vulnerability, exploit, database, vulnerability-database, scripts"}

CVE Lookup

Purpose

Build and maintain a structured local vulnerability database by looking up CVE information from the web. For each CVE, produces an in-depth structured report with a standardized template and organized reference data. All entries are stored in a <year>/<CVE-ID> directory hierarchy with a searchable database index. Supports database queries (search by year, CWE, severity), statistics, and maintenance operations. Prioritizes completeness and analytical depth over brevity — no arbitrary size limits on generated content.

When to Use

• 用户输入一个 CVE 编号（如 CVE-2024-3094），要求查询漏洞详情
• 用户说"查漏洞"、"查 CVE"、"看下这个漏洞"
• 用户需要了解某个已知漏洞的发现过程、原理和 PoC
• 用户需要生成结构化的漏洞分析报告用于文档或团队分享
• 安全研究或开发过程中需要评估某个漏洞的影响
• 用户需要构建和维护本地 CVE 漏洞数据库（"构建漏洞库"、"建数据库"）
• 用户希望按年份和 CVE 编号浏览已收集的漏洞数据（"按年份查看"、"浏览数据库"）
• 用户需要在本地数据库中搜索、统计或分析已有 CVE 数据（"查数据库"、"数据库统计"、"有多少CVE"）
• 用户希望为特定年份、组件或 CWE 分类生成漏洞概览报告

When NOT to Use

• 查询非 CVE 编号的安全公告（如 GHSA、MSRC 编号）—— 应使用通用搜索
• 需要实时扫描或检测系统是否存在漏洞 —— 应使用专业扫描工具
• 仅需简单描述（一句话总结）而不需要完整报告 —— 直接 WebSearch 即可

Core Principles

1. 源驱动原则（Source-Driven） — 报告中每一句事实性陈述必须可追溯到具体搜索结果。禁止推断、猜测或补全搜索结果中不存在的信息。 当搜索结果不足以支撑某个字段时，填写 暂无数据 并注明搜索范围——这是正常且预期的行为，不是失败。

2. 证据优先原则 — 写报告前先建立"信息清单"：哪些字段有明确来源、哪些搜索结果矛盾、哪些完全未找到。不得为了填充模板而编造任何内容。

3. 多源交叉验证 — 单一来源的信息标记为"待验证"，3+ 独立来源一致的信息标记为"高可信度"。来源冲突时保留所有说法并标注差异——不得自行选择"更可信"的版本。

4. 数据缺失透明化 — 当某个章节信息不足时，必须向用户说明：(a) 搜索了哪些来源，(b) 为什么信息不足（如 CVE 状态为 Reserved、漏洞刚刚发布等），(c) 提供了什么替代参考信息（如有）。

5. 数据库组织原则 — 所有获取的 CVE 数据必须按 <year>/<CVE-ID> 的层级结构存储。每条 CVE 在对应年份目录下拥有独立子目录，包含主报告和结构化参考数据。维护统一的数据库索引文件，支持按年份、CWE、严重程度等多种维度的搜索和统计。

Workflow / Steps

Step 1: 解析 CVE 编号

从 $ARGUMENTS 中提取 CVE 编号。支持以下输入格式：

输入格式	示例	标准化结果
完整编号	CVE-2024-3094	CVE-2024-3094
小写	cve-2024-3094	CVE-2024-3094
纯数字	2024-3094	CVE-2024-3094

校验规则：

• 格式必须匹配 CVE-\d{4}-\d{4,}（年份 + 至少 4 位数字 ID）
• 年份范围：1999 到当前年份
• 校验失败时向用户报告格式错误并停止执行

输出路径说明：本 Skill 的所有报告文件均输出到当前 VSCode 工作目录（workspace root）下的 CVE-Reports/ 文件夹中，而非 skill 安装目录内的 cve-lookup/ 文件夹。工作目录即 Claude Code 当前运行所在的项目根目录。

Step 2: 多源搜索漏洞信息

使用 WebSearch 和 WebFetch 从以下来源搜索，按优先级顺序尝试。每个来源失败时自动降级到下一来源，不中断整体流程。

来源列表（按优先级）：

1. NVD (National Vulnerability Database) — 官方权威漏洞数据库

   • 搜索关键词："CVE-XXXX-XXXX nvd.nist.gov"
   • 可获取：CVSS 评分、CWE 分类、受影响版本、官方参考链接

2. MITRE CVE — CVE 编号管理机构

   • 搜索关键词："CVE-XXXX-XXXX mitre.org"
   • 可获取：CVE 描述、状态（已发布/保留/拒绝）、参考列表

3. GitHub Security Advisory — 开源项目安全公告

   • 搜索关键词："CVE-XXXX-XXXX GitHub advisory"
   • 可获取：受影响的开源组件、版本范围、修复版本

4. CISA Known Exploited Vulnerabilities — 已知被利用漏洞目录

   • 搜索关键词："CVE-XXXX-XXXX CISA KEV"
   • 可获取：是否已被野外利用、利用活动时间线

5. Exploit-DB / 安全博客 — PoC 和漏洞分析文章

   • 搜索关键词："CVE-XXXX-XXXX exploit PoC" 和 "CVE-XXXX-XXXX 漏洞分析"
   • 可获取：PoC 代码、技术分析文章、攻击面分析

6. 官方安全公告与缓解建议 — 厂商官方缓解/防御/修复指南

   • 搜索关键词："CVE-XXXX-XXXX advisory mitigation" 和 "CVE-XXXX-XXXX vendor recommendation"
   • 可获取：厂商官方缓解措施、补丁链接、配置修改建议、临时规避方案

7. 中文漏洞数据库 — 中国国家漏洞库信息

   • 搜索关键词："CVE-XXXX-XXXX CNNVD" 和 "CVE-XXXX-XXXX CNVD"
   • 可获取：CNNVD/CNVD 编号、中文描述、国内影响评估、中文补丁信息

8. 深度技术分析来源 — 漏洞原理深度剖析

   • 搜索关键词："CVE-XXXX-XXXX analysis", "CVE-XXXX-XXXX root cause", "CVE-XXXX-XXXX deep dive"
   • 获取：技术博客文章（Project Zero、Qualys、Rapid7 等）、学术论文

9. 社交媒体与安全社区 — 实时漏洞讨论与情报

   • 搜索关键词："CVE-XXXX-XXXX twitter", "CVE-XXXX-XXXX reddit"
   • 可获取：安全研究员的早期分析、利用状态讨论、社区缓解方案
   • 作为补充来源，不单独依赖

重试策略：

• 每个来源最多搜索 2 次（使用不同关键词），2 次均失败则跳过
• WebFetch 获取详情页时设置超时（10 秒），超时则跳过该页面
• 至少有 2 个不同来源获取到有效信息，否则向用户报告"信息不足"
• 中文漏洞数据库和社交媒体来源作为"补充层"：即使获取失败也不中断流程，但应记录下来供用户参考

Step 3: 结构化整理搜索结果

将从各来源获取的信息按以下维度去重、合并。本步骤仅整理信息，不得新增搜索结果中不存在的内容：

信息维度	来源优先级	处理规则
漏洞描述	NVD > MITRE > GitHub	取最详细的描述，标注来源
CVSS 评分	NVD（最权威）	仅取 NVD 数据；无则填暂无数据
CWE 分类	NVD	取最具体的 CWE；无则填暂无数据
受影响版本	NVD + GitHub	合并并去重；标注各版本来源
PoC 信息	Exploit-DB > GitHub > 博客	记录链接和可用性评估
缓解措施	官方安全公告 > NVD References	合并所有来源，按类型分类
防御方案	安全厂商分析 > 官方公告	分层提取，标注来源
修复方案	GitHub Advisory > 官方公告	优先官方修复版本和补丁
技术分析	Project Zero > Unit 42 > 学术论文	提取根因、攻击链、利用细节
概念性PoC依据	技术分析 > 官方描述	提取攻击入口、利用路径、触发序列

信息可信度标记：

• 来自 3+ 独立来源且内容一致 → 高可信度
• 仅来自 1 个来源 → 待验证
• 不同来源冲突 → 保留所有说法，标注差异，不自行裁决

建立"信息清单"： 整理完成后，形成一份明确的清单：哪些字段有数据（标注来源）、哪些搜索结果矛盾、哪些完全未找到。此清单作为 Step 4 撰写报告的依据——清单中没有的内容不得写入报告。

Step 4: 生成 CVE 报告与结构化参考数据

前置操作： 使用 Read 工具读取 references/report-template.md，获取完整的标准报告模板。该模板包含所有必需字段、来源标注规范和"暂无数据"标记指引。

数据库目录结构： 报告和相关参考数据统一保存在 CVE-Reports/ 下的分级目录中：

CVE-Reports/                        # 漏洞数据库根目录
├── index.md                        # 数据库汇总索引（所有 CVE 的聚合概览）
├── lookup-table.md                 # 漏洞类型对照表（快速搜索用，含漏洞类型+受影响软件）
├── cve-index.json                  # 集中式索引 JSON（所有 CVE 元数据的聚合，单文件读取，高效搜索）
├── taxonomy.md                     # 分类层次说明（可选的分类体系文档）
├── 2024/
│   ├── CVE-2024-3094/
│   │   ├── report.md               # 主报告（标准模板生成的完整报告）
│   │   └── metadata.json           # 结构化参考数据（关键字段摘要，用于索引）
│   └── CVE-2024-21887/
│       ├── report.md
│       └── metadata.json
├── 2023/
│   └── ...
└── 2025/
    └── ...

生成流程：

1. 确保目录结构存在：CVE-Reports/<year>/<CVE-ID>/
2. 创建主报告文件 CVE-Reports/<year>/<CVE-ID>/report.md
3. 严格按模板填充，遵循以下规则：
   • 有来源的事实 → 写入内容并标注来源（URL 或来源名称）
   • 无来源的字段 → 填写 暂无数据，不得删除字段，不得编造内容
   • 来源矛盾的字段 → 保留所有说法，标注差异，不得自行选择
   • 信息不足以支撑的章节 → 标注搜索范围和不足原因（如"已搜索 NVD、MITRE、GitHub Advisory，均未找到发现过程信息"）
4. 报告 frontmatter 中的 confidence、source_count、poc_conceptual_generated 等元数据必须与实际搜索结果一致，不得使用模板中的示例值
5. 每完成一个章节，立即对照信息清单确认：该章节的所有事实性陈述是否均可在清单中找到对应来源。如发现清单中不存在的内容，立即删除。
6. 生成结构化参考数据文件 CVE-Reports/<year>/<CVE-ID>/metadata.json，包含该 CVE 的关键字段摘要，用于数据库索引和搜索。推荐使用 Python 脚本生成以避免 AI 编码错误：

   python cve-lookup/scripts/generate_metadata.py \
     --cve-id "CVE-YYYY-XXXX" \
     --year YYYY \
     --cvss X.X \
     --severity "CRITICAL|HIGH|MEDIUM|LOW|UNKNOWN" \
     --cwe "CWE-XXX" \
     --component "组件名称" \
     --summary "一句话摘要" \
     --vuln-type "类型1" "类型2" \
     --tags "标签1" "标签2" \
     --has-poc true/false \
     --has-mitigation true/false \
     --source-count N \
     --output "CVE-Reports/<year>/<CVE-ID>/metadata.json"
   

   脚本会自动校验字段格式、类型和范围，并根据 CWE 自动推断 vuln_type。也可通过 stdin 传递 JSON 数据：

   echo '{"cve_id":"CVE-YYYY-XXXX","year":YYYY,...}' | \
     python cve-lookup/scripts/generate_metadata.py \
       --output "CVE-Reports/<year>/<CVE-ID>/metadata.json"
   

   生成的 metadata.json 包含以下字段：

   {
     "cve_id": "CVE-YYYY-XXXX",
     "year": YYYY,
     "cvss_score": X.X,
     "severity": "CRITICAL|HIGH|MEDIUM|LOW|UNKNOWN",
     "cwe": ["CWE-XXX"],
     "vuln_type": ["RCE", "SQL注入", "缓冲区溢出", "XSS", "权限提升", ...],
     "affected_component": "组件名称",
     "summary": "一句话摘要",
     "collection_date": "YYYY-MM-DD",
     "source_count": N,
     "has_poc": true|false,
     "has_mitigation": true|false,
     "tags": ["标签1", "标签2"]
   }
   

   • metadata.json 仅包含搜索结果中确实存在的数据，缺失字段填写 null
   • vuln_type 字段从 CWE 分类和搜索结果中的技术描述提取漏洞类型（如 RCE、SQL注入、缓冲区溢出、XSS、权限提升、拒绝服务、信息泄露等），用于索引表快速筛选。如果无法从来源确定漏洞类型，填写 null
   • tags 字段根据 CWE 分类、漏洞类型等自动推断（如 "RCE"、"缓冲区溢出"、"SQL注入"）

Step 5: 更新数据库索引与对照表

在 CVE-Reports/index.md 中追加或更新该 CVE 的条目。index.md 是数据库的汇总索引，涵盖所有已收集的 CVE：

# 漏洞数据库索引

更新日期：YYYY-MM-DD
CVE 总数：N

## 按年份统计

| 年份 | CVE 数量 | 严重等级分布 |
|------|---------|-------------|
| 2024 | 12 | 🟥 CRITICAL: 5, 🟧 HIGH: 4, 🟨 MEDIUM: 3 |

## 所有 CVE 列表

| CVE ID | 严重程度 | CWE | 受影响组件 | 收集日期 |
|--------|---------|-----|-----------|---------|
| CVE-YYYY-XXXX | CRITICAL | CWE-XXX | <组件> | YYYY-MM-DD |

• 如果 index.md 不存在，创建并写入完整格式
• 如果已存在该 CVE 条目，更新相关信息（收集日期、CVSS 等）
• 每次写入后更新统计信息（年份汇总、总数、严重等级分布）

推荐使用 Python 脚本一次性更新所有索引文件（自动处理 cve-index.json、lookup-table.md、index.md 的追加/更新/排序/统计）：

# 从已生成的 metadata.json 追加/更新索引
python cve-lookup/scripts/append_to_index.py \
  --database CVE-Reports \
  --metadata "CVE-Reports/<year>/<CVE-ID>/metadata.json"

# 或通过 stdin 直接传递 metadata JSON
cat "CVE-Reports/<year>/<CVE-ID>/metadata.json" | \
  python cve-lookup/scripts/append_to_index.py --database CVE-Reports

如果无法使用脚本，再手动更新各索引文件。

同时生成/更新集中式索引 JSON 文件 CVE-Reports/cve-index.json：

[
  {
    "cve_id": "CVE-2024-3094",
    "year": 2024,
    "severity": "CRITICAL",
    "cwe": ["CWE-506"],
    "vuln_type": ["供应链后门", "嵌入式恶意代码"],
    "affected_component": "liblzma / xz-utils",
    "summary": "xz-utils 库中被植入后门，影响 SSH 认证安全",
    "collection_date": "2026-07-06"
  },
  {
    "cve_id": "CVE-2023-44487",
    "year": 2023,
    "severity": "HIGH",
    "cwe": ["CWE-400"],
    "vuln_type": ["资源耗尽", "拒绝服务"],
    "affected_component": "HTTP/2 协议栈（多种实现）",
    "summary": "HTTP/2 快速重置攻击导致拒绝服务",
    "collection_date": "2026-07-06"
  }
]

• cve-index.json 是当前数据库所有 CVE 的集中式索引，每个条目包含的关键字段用于快速筛选
• 读一个文件即可获取全部 CVE 的概览，无需遍历文件系统
• 新增 CVE 时追加条目到数组末尾；更新已有 CVE 时替换对应条目
• 使用标准的 JSON 格式，可被其他工具（jq、Python、JavaScript）直接读取和处理

同时生成/更新漏洞类型对照表（人类可读）CVE-Reports/lookup-table.md：

# 漏洞类型对照表

> 快速搜索用索引表，按漏洞类型分类。更新日期：YYYY-MM-DD | 总数：N

## 按漏洞类型索引

| 漏洞类型 | CVE 数量 | 相关 CVE |
|---------|---------|---------|
| RCE（远程代码执行） | 5 | CVE-2024-xxx, CVE-2024-yyy |
| SQL 注入 | 3 | CVE-2024-zzz, ... |
| 缓冲区溢出 | 2 | ... |
| 供应链后门 | 1 | CVE-2024-3094 |

## 按受影响软件索引

| 受影响软件 | CVE 数量 | 相关 CVE |
|-----------|---------|---------|
| Linux Kernel | 4 | CVE-2024-xxx, ... |
| OpenSSL | 2 | ... |
| xz-utils / liblzma | 1 | CVE-2024-3094 |

• 以 vuln_type 和 affected_component 为核心维度交叉索引
• 目的：用户按漏洞类型或软件名称搜索时，一眼定位到相关 CVE
• 每次新增或更新 CVE 后同步刷新统计数字

Step 6: 输出报告摘要

向用户呈现以下内容的简要报告：

1. 基本信息：CVE ID, CVSS 评分, 严重程度, 受影响组件
2. 一句话总结：该漏洞的核心要点（不超过 50 字）
3. 关键发现：发现者、利用状态、是否已有公开 PoC
4. 概念性 PoC：是否已生成概念性 PoC 分析（✅ 是 / ❌ 信息不足以生成）
5. 缓解/防御/修复状态：是否有已知缓解措施、检测规则和官方修复版本（简明标注如 ✅ 有 / ⚠️ 部分 / ❌ 暂无）
6. 数据库路径：报告文件保存位置 CVE-Reports/<year>/<CVE-ID>/
7. 信息来源数量：成功从几个来源获取了信息（注明成功/失败数量）

如果 Step 2 执行过程中有来源降级或失败，在此一并报告。

Step 7: 数据库搜索与查询（使用集中式索引）

当用户要求查询已有数据库内容时，优先使用集中式索引 cve-index.json 进行快速搜索，仅在需要完整报告时访问具体文件：

搜索策略

1. 使用集中式索引搜索（首选，高效）：

   • 使用 Read 读取 CVE-Reports/cve-index.json（单文件，一次读取全部 CVE 元数据）
   • 在读取的内容中按条件筛选（通过关键词匹配 vuln_type、affected_component、cwe、severity、year 等字段）
   • 以表格形式呈现筛选结果，每行包含：CVE ID、漏洞类型、受影响软件、严重程度、摘要
   • 优点：无论数据库规模多大（10 条或 1000 条），只需读取 1 个文件，无文件系统遍历开销

2. 使用搜索脚本（推荐，精确筛选）：

   # 按漏洞类型搜索
   python cve-lookup/scripts/search_cve.py --database CVE-Reports --vuln-type RCE
   
   # 按受影响软件 + 严重程度组合搜索
   python cve-lookup/scripts/search_cve.py --database CVE-Reports --software OpenSSL --severity HIGH
   
   # 关键词搜索
   python cve-lookup/scripts/search_cve.py --database CVE-Reports --keyword "buffer overflow"
   
   # 数据库统计
   python cve-lookup/scripts/search_cve.py --database CVE-Reports --stats
   
   # 列出所有漏洞类型
   python cve-lookup/scripts/search_cve.py --database CVE-Reports --list-types
   

   脚本支持多条件组合筛选、JSON 格式输出、详细模式，适合复杂查询。

3. 使用漏洞类型对照表搜索（辅助，可视化）：

   • 使用 Read 读取 CVE-Reports/lookup-table.md
   • 按漏洞类型或软件名称定位到相关 CVE 组
   • 适合"有哪些 RCE 漏洞"或"Linux Kernel 受影响"这类宽泛分类查询

4. 直接访问 CVE 目录（获取完整报告）：

   • 当用户需要查看某条 CVE 的完整报告时，读取 CVE-Reports/<year>/<CVE-ID>/report.md
   • 年份从 cve-index.json 的 year 字段获取，无需遍历目录

查询场景示例

查询场景	搜索策略	操作
"查RCE漏洞"	读 cve-index.json → 筛 vuln_type 包含 RCE	1 次 Read
"OpenSSL有哪些漏洞"	读 cve-index.json → 筛 affected_component 含 OpenSSL	1 次 Read
"2024年的CRITICAL漏洞"	读 cve-index.json → 筛 year=2024 AND severity=CRITICAL	1 次 Read
"看CVE-2024-3094的完整报告"	读 cve-index.json 获取 year → 读 report.md	2 次 Read
"统计CWE分布"	读 cve-index.json → 按 cwe 字段聚合计数	1 次 Read

备用方案

如果 cve-index.json 不存在（如旧版本数据库），降级到 Glob 搜索：

• 使用 Glob pattern: CVE-Reports/*/*/metadata.json 遍历所有 metadata.json
• 读取后逐条筛选
• 添加 Note 提示用户执行"重建索引"以生成集中式索引

Step 8: 数据库维护操作

当用户要求执行数据库维护时：

• 更新已有 CVE：重新执行 Step 1-6 刷新某条 CVE 的数据，新报告覆盖旧报告目录
• 清理空目录：删除没有有效数据（report.md 只有"暂无数据"）的空 CVE 目录
• 重建索引：遍历所有 <year>/<CVE-ID>/metadata.json，重新生成 index.md、cve-index.json 和 lookup-table.md（Step 5 的全部索引文件）

  # 推荐使用脚本一次性重建所有索引：
  python cve-lookup/scripts/append_to_index.py --database CVE-Reports --rebuild
  

• 导出数据：按用户要求导出指定 CVE 或年份范围的 cve-index.json 子集或 metadata 数据
• 数据库完整性检查：检查每个 CVE 目录是否包含 report.md 和 metadata.json，缺少则报告；同时验证 cve-index.json 中的条目是否与文件系统中的 CVE 目录一致

Step 9: 生成分类概览报告（可选）

当用户要求按特定维度生成漏洞概览时：

1. 遍历所有 metadata.json，按用户指定的维度（年份、CWE 分类、严重程度、受影响组件）聚合
2. 生成分类概览报告 CVE-Reports/taxonomy.md，包含统计图表或表格
3. 支持按严重程度筛选（"列出所有 CRITICAL 级别的漏洞"）
4. 支持按 CWE 分类筛选（"列出所有 CWE-89 SQL 注入漏洞"）

Constraints

源驱动与防编造

• Always 在写报告前建立"信息清单"，明确哪些字段有来源、哪些未找到、哪些矛盾
• Always 每项事实性陈述必须标注信息来源（URL 或来源名称），不得有无来源的断言
• Never 推断、猜测或补全搜索结果中不存在的信息 —— "暂无数据"是正常且预期的
• Never 为了填充模板而编造内容 —— 模板中的示例值（如 cvss_score: 9.8、severity: CRITICAL）不得直接使用，必须以实际搜索结果为准
• Never 在来源矛盾时自行裁决 —— 必须保留所有说法并标注差异

数据质量

• Always 从至少 3 个不同来源获取 CVE 信息（含 1 个官方来源），避免单一来源偏差
• Always 在报告中标注信息来源和可信度（高/中/待验证）
• Always 区分临时缓解措施和永久修复方案，不得混为一谈
• Always 在防御方案中注明适用范围（网络层/主机层/应用层），避免笼统建议
• Never 提供未经验证的缓解措施 —— 每项措施必须有来源支撑
• Never 删除模板中的任何字段 —— 无数据时填写"暂无数据"
• 报告必须使用模板中的标准结构，不得自行简化格式
• 生成的报告无字数限制：各章节以信息完整性和分析深度为目标，不限字数

安全与合规

• Always 在 PoC 和概念性 PoC 部分添加明确免责声明
• Always 在概念性 PoC 中仅使用伪代码和自然语言描述，不生成可执行的攻击代码
• Always 在概念性 PoC 的每段代码块前注明其"概念性"属性
• Never 在未验证的情况下断言某个 PoC 是否有效
• Never 报告生成过程中执行或运行任何 PoC 代码
• Never 对尚未修复的漏洞提供不准确的修复建议
• Never 在概念性 PoC 中包含真实的 shellcode、ROP 链、反连 IP 等实际利用载荷

边界处理

• 概念性 PoC 分析仅在有足够的技术分析信息（漏洞原理、触发条件、利用方式至少各一项有明确来源）时生成；信息不足以推导时跳过该章节并注明原因
• 中英文混合场景优先使用中文输出报告
• 如果 CVE 编号格式校验失败，立即报告错误并停止执行，不进行模糊搜索

数据库管理

• Always 每次新增 CVE 后更新 index.md 的统计信息（总数、按年份分布、严重程度分布）
• Always 在 metadata.json 中仅写入搜索结果中存在的数据，缺失字段填写 null，不得使用默认值或估算值
• Always 重建索引（Step 8）时遍历所有 metadata.json 重新生成统计，不依赖 index.md 中的旧数据
• Always 在新增或更新 CVE 后同步刷新 cve-index.json 和 lookup-table.md，确保索引与数据一致
• Always 执行数据库搜索时优先尝试读取 cve-index.json（单文件一次读取），仅在索引不存在时降级为 Glob 遍历
• Never 在数据库搜索时修改或写入任何 CVE 数据 —— 搜索操作为只读
• Never 在不通知用户的情况下执行数据库清空、批量删除等破坏性操作 —— 需要显式确认
• Never 在 cve-index.json 或 lookup-table.md 中出现与实际文件系统不一致的记录（如索引中存在但目录已删除的 CVE）
• metadata.json 中的 vuln_type 字段必须从 CWE 分类和搜索结果中的技术描述提取，不得凭空编造
• metadata.json 中的 tags 字段应基于 CWE 分类和搜索结果中的描述推断，而非凭空编造
• 更新已有 CVE 时保留旧的 metadata.json 备份（命名为 metadata.json.bak），除非用户明确要求覆盖

Examples

✅ Do This — 源驱动报告（正确做法）

用户输入：

/cve-lookup CVE-2024-3094

期望行为：

1. 解析出 CVE ID：CVE-2024-3094，校验格式通过
2. 从 NVD、MITRE、GitHub Advisory、Exploit-DB、官方安全公告、CNNVD 等多个来源搜索
3. 先建立信息清单：明确 NVD 提供了 CVSS 9.8 + CWE-506；MITRE 提供了描述；GitHub 提供了受影响版本；厂商公告提供了修复版本 5.6.1 — 发现者信息未在任何来源中找到 → 标记为"暂无数据"
4. 在 CVE-Reports/2024/CVE-2024-3094/report.md 生成报告，在 CVE-Reports/2024/CVE-2024-3094/metadata.json 生成参考数据，每个字段要么有来源标注，要么标注"暂无数据"或 null
5. 更新 CVE-Reports/index.md 索引（更新年份统计和总表）
6. 输出摘要

✅ Do This — 信息不足时的正确处理

场景： 搜索一个刚发布的 CVE，仅 NVD 和 MITRE 有基本信息

正确做法：

• 在报告中如实说明"已搜索 9 个来源，仅 NVD 和 MITRE 返回有效信息"
• 概述表格中填写已有信息（CVSS、描述），其余字段填"暂无数据"
• "发现过程"章节写明"搜索未找到该漏洞的发现过程信息（已搜索：NVD、MITRE、GitHub Advisory、Exploit-DB、安全博客）"
• "概念性 PoC 分析"章节跳过，注明"信息不足以构建概念性 PoC（缺少：漏洞原理技术分析、触发条件细节）"
• 报告可信度标记为"低"

✅ Do This — 数据库查询与统计（正确做法）

用户输入：

帮我查一下数据库里2024年的CRITICAL漏洞

期望行为：

1. 使用 Glob 搜索 CVE-Reports/2024/*/metadata.json
2. 读取所有匹配的 metadata.json，筛选 severity == "CRITICAL" 的条目
3. 以表格形式呈现结果（CVE ID、CWE、受影响组件、摘要）
4. 不读取或输出完整的 report.md 内容（除非用户要求）

用户输入：

统计一下数据库里所有漏洞的CWE分布

期望行为：

1. 遍历所有 */*/metadata.json 文件
2. 按 CWE 分类聚合计数
3. 输出饼图/表格形式的 CWE 分布统计
4. 同时统计受影响组件排名前十

✅ Do This — 数据库维护（正确做法）

用户输入：

帮我重建数据库索引

期望行为：

1. 使用 Glob 搜索所有 */*/metadata.json
2. 遍历每个文件，提取年份、CVE ID、severity、CWE、affected_component
3. 重新生成 CVE-Reports/index.md，包含最新的年份统计和完整列表
4. 报告重建完成：总 CVE 数、年份覆盖范围

✅ Do This — 使用集中式索引快速搜索（高效做法）

用户输入：

查一下数据库里有哪些RCE漏洞

期望行为（使用集中式索引）：

1. 使用 Read 读取 CVE-Reports/cve-index.json（1 次 I/O，无论数据库多大）
2. 在返回的 JSON 数组中筛选 vuln_type 包含 "RCE" 的条目
3. 以表格形式输出结果（CVE ID、漏洞类型、受影响软件、严重程度、摘要）
4. 不遍历文件系统，不读取任何 metadata.json

效率对比：

• ❌ 旧方式（Glob 遍历）：打开 N 个 metadata.json 文件，N 次 I/O
• ✅ 新方式（集中式索引）：读取 1 个 cve-index.json，1 次 I/O

用户输入：

看看lookup-table里有哪些软件被影响最多

期望行为：

1. 使用 Read 读取 CVE-Reports/lookup-table.md
2. 从"按受影响软件索引"表格中提取统计
3. 按 CVE 数量排序，输出受影响软件 Top N

❌ Not This — 编造与推断（错误做法）

用户输入：

/cve-lookup CVE-2024-3094

错误行为：

• ❌ 编造发现者：搜索结果中未找到发现者信息，但报告中写了"由某安全研究员发现"（编造）
• ❌ 复制模板示例值：模板中 cvss_score: 9.8 是示例，但搜索结果中 CVSS 为 7.5，仍写成 9.8
• ❌ 推断攻击链：搜索结果中仅有漏洞描述，却自行推演完整的利用步骤和攻击场景
• ❌ 静默跳过缺少的信息：未找到缓解措施时，不写"暂无数据"也不做任何说明，直接跳过该章节
• ❌ 仅从单一来源搜索，未交叉验证
• ❌ 直接执行 PoC 脚本（严重安全违规）
• ❌ 将临时缓解措施与永久修复方案混在一起，没有明确区分
• ❌ 防御方案仅写"更新到最新版本"，缺乏分层建议和来源引用
• ❌ 概念性 PoC 直接包含可执行的攻击代码而非伪代码（严重安全违规）

Notes

• NVD API 2.0 无 API key 时限制为 5 次/30 秒，建议获取免费 API key 以获得 50 次/30 秒的配额
• MITRE CVE API 为公开接口，无需认证：https://cveawg.mitre.org/api/cve/<CVE-ID>
• GitHub Advisory Database 可通过 https://github.com/advisories/<GHSA-ID> 访问
• CISA KEV 目录 JSON feed：https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json（JSON Schema 更新于 2024-06-25）
• Exploit-DB 搜索可通过 https://www.exploit-db.com/search?cve=YYYY-XXXX 进行
• CNNVD(https://www.cnnvd.org.cn) 和 CNVD(https://www.cnvd.org.cn) 无公开 API，通过 WebSearch 搜索公开页面
• 阿里云 AVD(https://avd.aliyun.com) 提供开放查询接口，可作为中文数据的替代来源
• 对于较旧的 CVE（2020 年之前），部分来源可能已下线或不完整
• 对于 0-day 或刚发布的 CVE，信息可能较少，报告中应如实标注"信息有限"并在 Step 6 摘要中向用户说明
• 如果 CVE 编号指向保留（Reserved）或拒绝（Rejected）状态，在报告中明确标注并仅提供基本信息，不生成完整分析
• 报告文件为 Markdown 格式，可直接在 VSCode 中预览或转换为 PDF
• 缓解措施仅适用于临时规避，不能替代彻底修复，报告中应明确这一前提
• 防御方案中的检测规则（YARA/Sigma/Suricata）可能需根据实际环境调整，报告中应注明"需根据环境适配"
• 如果官方尚未发布修复版本，修复方案章节应如实标注并建议替代迁移路径或持续关注厂商公告
• 概念性 PoC 分析仅基于公开的技术分析推导，不代表漏洞在实际环境中一定可被利用
• 概念性 PoC 中的伪代码仅供理解漏洞原理，不保证在真实环境中可运行
• 如果搜索到的技术分析信息不足以支撑概念性 PoC 推导，应在报告中注明原因并跳过该章节
• 报告模板完整版位于 references/report-template.md，修改报告结构时应同步更新该文件

数据库相关

• 数据库根目录为 CVE-Reports/，位于当前 VSCode 工作目录根（workspace root），与 skill 安装位置无关
• 目录结构 CVE-Reports/<year>/<CVE-ID>/ 支持通过 Glob 高效搜索（按年份索引，无需遍历所有文件）
• metadata.json 使用标准 JSON 格式，便于其他工具读取和处理（如 jq、Python json 模块）
• 索引文件 index.md、lookup-table.md 和分类报告 taxonomy.md 均为 Markdown 格式，可在 VSCode 中直接预览
• cve-index.json 是集中式索引 JSON，包含所有 CVE 的关键字段（cve_id、year、severity、cwe、vuln_type、affected_component、summary），一次 Read 即可获取全部数据用于搜索筛选
• lookup-table.md 是漏洞类型对照表，以 vuln_type 和 affected_component 为核心维度交叉索引，适合人类快速浏览
• 搜索效率大幅提升：无论数据库中有 10 条还是 1000 条 CVE，搜索操作只需读取 cve-index.json 一个文件（1 次 I/O），无需遍历文件系统读取 N 个 metadata.json
• 重建索引（Step 8）会同时重新生成 index.md、cve-index.json 和 lookup-table.md
• 删除 CVE 时仅删除对应 <year>/<CVE-ID>/ 目录，不影响其他年份和其他 CVE；但删除后需要重建索引以保持 cve-index.json 与文件系统一致
• 如果 cve-index.json 不存在（如从旧版本升级），Step 7 会自动降级为 Glob 搜索，建议用户执行"重建索引"以启用高效搜索
• 由于 Glob 工具可能存在 head_limit 限制，建议优先使用集中式索引搜索而非 Glob 遍历
• 多条 CVE 数据采集建议间隔 NVD 的 API 频率限制（无 key: 5次/30秒，有 key: 50次/30秒）

Python 脚本说明

cve-lookup/scripts/ 目录下提供了 4 个 Python 脚本：

0. check_env.py — 环境诊断工具（独立脚本，建议首次使用前运行）

   • 检查 Python 版本、必需模块、配套脚本完整性、磁盘访问权限
   • 支持 --verbose 详细输出 / --json JSON 格式 / --quiet 仅错误
   • 用法：python cve-lookup/scripts/check_env.py
   • 诊断范围：Python >= 3.8、json/os/sys/argparse/importlib/datetime/typing/re/subprocess

1. generate_metadata.py — 从结构化数据生成标准化的 metadata.json

   • 自动校验字段格式、类型和范围
   • 内置 CWE→vuln_type 映射表，自动推断漏洞类型
   • 支持命令行参数和 stdin 两种输入方式
   • python generate_metadata.py --validate <file> 可校验已有文件
   • 用法：python cve-lookup/scripts/generate_metadata.py --cve-id CVE-2024-3094 --year 2024 ...

2. append_to_index.py — 将 CVE 元数据追加/更新到集中式索引

   • 一次命令同时更新 cve-index.json、lookup-table.md、index.md
   • 自动排序（按年份降序、严重程度降序）和去重
   • 支持 --rebuild 模式：遍历所有 metadata.json 重建全部索引
   • 用法：python cve-lookup/scripts/append_to_index.py --database CVE-Reports --metadata <file>
   • 重建：python cve-lookup/scripts/append_to_index.py --database CVE-Reports --rebuild

3. search_cve.py — 从 cve-index.json 中快速搜索和筛选

   • 支持按漏洞类型、受影响软件、严重程度、年份、CWE、关键词等组合筛选
   • 支持 --stats 统计模式（年份分布、严重程度、漏洞类型 Top、软件 Top）
   • 支持 --list-types / --list-software 列出所有类型/软件
   • 支持 --json JSON 输出和 --detail 详细模式
   • 用法：python cve-lookup/scripts/search_cve.py --database CVE-Reports --vuln-type RCE

• 所有脚本均使用 Python 标准库，无外部依赖
• 首次使用前建议运行环境诊断：python cve-lookup/scripts/check_env.py
• 可使用 python cve-lookup/scripts/check_env.py --verbose 查看详细模块状态
• 可使用 python cve-lookup/scripts/check_env.py --json 获取 JSON 诊断报告
• 脚本路径相对于 VSCode 工作目录根（workspace root）
• 当 skill 安装在项目级 .claude/skills/cve-lookup/ 时，脚本路径为 .claude/skills/cve-lookup/scripts/<脚本名>.py
• 当 skill 安装在用户级 ~/.claude/skills/cve-lookup/ 时，脚本路径为 ~/.claude/skills/cve-lookup/scripts/<脚本名>.py
• 如果无法确定安装位置，使用 Glob 搜索 **/cve-lookup/scripts/*.py 定位脚本