mez-0/vulnify

# vulnify 一个 CVE 摄取与富化流水线，它基于 CVEProject、NVD、CISA KEV、EPSS 和 OSV 构建并整合出一个单一的、标准化的 SQLite 数据库 —— 此外还提供了一个用于查看结果的 Streamlit 浏览器。 每次发布时都会提供一个完全填充的 SQLite 数据库，因此您无需为初始摄取等待数小时。 ## 包含内容 - 来自上游 CVEProject `cvelistV5` zip 包的**完整 CVE 语料库** - 用于 CVSS 指标、CPE 配置、漏洞状态和参考的 **NVD 批量合并** - **CISA 已知被利用漏洞**，包含 `date_added`、`due_date`、勒索软件标志和所需行动 - 批量处理的 **EPSS** 利用概率 + 百分位 - 每个 CVE 的 **OSV** 包映射 - **Streamlit 浏览器**，提供约 70 个预构建的数据视图 - **支持恢复的流水线状态** —— 中断后会从上次停止的地方继续 当前快照（2026 年 5 月发布）： | | 数量 | |--|--:| | CVE | 347,248 | | 供应商 | 21,183 | | 产品 | 70,266 | | KEV 条目 | 1,586 | | 表 | 20 | ## 文档 更深入的参考资料位于 [`docs/`](docs/)： - **[数据源](docs/DATASOURCES.md)** — 每个上游数据源、端点和许可证。 - **[流水线](docs/PIPELINE.md)** — 摄取 → 富化、水位线/恢复、级联+修复模型、三态原则。 - **[Schema](docs/SCHEMA.md)** — 20 张表的布局及查询注意事项。 - **[MCP server](docs/MCP.md)** — 7 个工具、各 Agent 设置、故障排除。 - **[浏览器](docs/EXPLORE.md)** — Streamlit 仪表板，逐个选项卡介绍。 ## 快速开始（使用预构建的数据库） 如果您只想查询数据而不想运行流水线： ``` # 1. Clone 并选择你需要的 extras git clone https://github.com/mez-0/vulnify.git cd vulnify uv sync --extra mcp # for agents / MCP server # 或者： uv sync --extra explore # 用于 Streamlit dashboard # 或者： uv sync --all-extras # 用于所有内容 # 2. 获取最新的 release DB gh release download -R mez-0/vulnify --pattern vulnify.db.zst zstd -d vulnify.db.zst -o vulnify.db # 3. 将 .env 指向该 DB cat > .env < 免费获取一个 key，并在 `.env` 中设置 `VULNIFY_NVD_API_KEY`。 ### 跳过阶段 `vulnify-gather` 暴露了多个标志，允许您重新运行单个富化阶段，而无需重新摄取： ``` vulnify-gather --skip-ingestion # don't re-download the CVEProject zip vulnify-gather --skip-nvd # skip NVD bulk merge vulnify-gather --skip-kev # skip CISA KEV vulnify-gather --skip-epss # skip EPSS batch vulnify-gather --skip-osv # skip OSV per-CVE lookups vulnify-gather --skip-nuclei # skip Nuclei exploit-template ingest vulnify-gather --skip-exploitdb # skip Exploit-DB artefact ingest vulnify-gather --skip-metasploit # skip Metasploit module-metadata ingest ``` 流水线会将阶段水位线写入 `pipeline_run` 表，因此重新运行是幂等的 —— NVD 仅获取自上次水位线以来的更改，KEV 进行完全重新同步，EPSS 仅更新过期的分数。 利用阶段（Nuclei / Exploit-DB / Metasploit）会在 `~/.vulnify/cache` 下获取并缓存其语料库，并根据语料库版本（commit SHA / 内容哈希）设置水位线。只要此次收集运行了 cvelistV5 摄取，它们就会重新解析 —— 摄取过程会级联删除已更改 CVE 的相关产出物，因此它们会在下一次运行时被修复 —— 否则会自动跳过未更改的语料库。显式指定的 `--skip-*` 始终具有最高优先级。三态的 `exploit.public_poc` / `exploit.metasploit` 汇总布尔值会从产出物中物化而来：在关联的源运行完成之前为 `null`，之后为 `true`/`false`。 ## 配置 所有配置都位于项目根目录的 `.env` 中（由 `vulnify.settings` 加载）。 | 变量 | 必需 | 默认值 | 用途 | |--|:-:|--|--| | `VULNIFY_SQLITE_PATH` | 是 | `vulnify.db` | SQLite 数据库的存放位置。留空或未设置会将 CVEProject 摄取切换为仅打印模式。 | | `VULNIFY_SCHEMA_SQL_PATH` | 是 | `vulnify/db/schema.sql` | 用于引导新数据库的 DDL。 | | `VULNIFY_KEV_JSON_PATH` | 否 | `known_exploited_vulnerabilities.json` | CISA KEV 目录的本地副本。如果未设置且默认文件不存在，提供程序将进行获取。 | | `VULNIFY_NVD_API_KEY` | 否 | — | NVD API key。如果没有它，您的速率限制约为 5 次请求 / 30 秒。 | | `VULNIFY_CACHE_DIR` | 否 | `~/.vulnify/cache` | exploit 语料库（Nuclei / Exploit-DB / Metasploit）的缓存位置。 | 相对路径将基于项目根目录进行解析。 ## 架构 ``` ┌───────────────────┐ │ gather.py (CLI) │ └─────────┬─────────┘ │ ▼ ┌─────────────────────────────┐ │ providers/cveproject.py │ bulk download + parse └──────────────┬──────────────┘ │ ▼ ┌─────────────────────────────┐ │ db/sqlite_store.py │ upsert into normalised tables └──────────────┬──────────────┘ │ ▼ ┌───────────────────┴────────────────────┐ │ providers/enrichment.py │ │ ├── cisa_kev (CISA KEV catalog) │ │ ├── nvd (CVSS, CPE, status) │ │ ├── epss (probability scores) │ │ ├── osv (package mappings) │ │ └── exploit_ingest (Nuclei/EDB/MSF) │ └────────────────────┬───────────────────┘ │ ▼ ┌────────────────────┴────────────────────┐ ▼ ▼ ┌───────────────────────────────┐ ┌───────────────────────────────┐ │ explore/app.py (Streamlit) │ │ vulnify/mcp.py (FastMCP) │ └───────────────────────────────┘ └───────────────────────────────┘ ``` ### 源码布局 ``` vulnify/ ├── vulnify/ │ ├── gather.py # `vulnify-gather` CLI (ingestion + enrichment) │ ├── mcp.py # `vulnify-mcp` FastMCP server (stdio) │ ├── settings.py # .env loader + path resolvers │ ├── constants.py # Severity, SourceTrust, ExploitMaturity enums │ ├── cvss_severity.py # CVSS-base -> severity bucketing │ ├── http.py # shared httpx client + file/zip download helpers │ ├── models/ # dataclass models (CVE, Vendor, Product, CVSS, …) │ ├── providers/ │ │ ├── cveproject.py # CVEProject bulk parser │ │ ├── nvd.py # NVD 2.0 API client + per-CVE merge │ │ ├── cisa_kev.py # KEV catalog ingest │ │ ├── epss.py # FIRST EPSS batch enrichment │ │ ├── osv.py # OSV per-CVE package lookup │ │ ├── exploit_ingest.py # Nuclei/Exploit-DB/Metasploit artefact ingest │ │ ├── vendor_advisories.py │ │ ├── enrichment.py # phase orchestrator │ │ └── enrichment_resume.py │ └── db/ │ ├── schema.sql # 20-table normalised schema + FTS5 index │ ├── sqlite_store.py # connection + upsert API │ ├── readonly.py # shared read-only sqlite3 helper │ ├── cve_upsert.py # CVE/vendor/product writes │ ├── migrate.py # idempotent migrations + FTS5 backfill │ ├── pipeline_state.py # phase watermarks │ └── sql_conversion.py # model <-> row helpers ├── explore/ │ ├── app.py # Streamlit dashboard │ ├── data.py # overview queries │ └── data_views.py # per-chart queries └── tests/ # pytest suite (no network, no real DB) ``` ## Schema 概览 20 张表，全部标准化，并启用了外键。包含顶层 CVE 表，以及为高基数数据（CPE 匹配、参考、CVSS 指标、exploit 信号 + 产出物、KEV 列表、情报）建立的独立表，以便您能够干净地进行 join 查询。 ``` cve — primary CVE record vendor — deduped vendors (case/whitespace-normalised) product — products owned by a vendor cve_vendor — many-to-many with `role` (assigner, affected, source, …) affected_product — CVE <-> product affected/not-affected with notes version_range — per affected_product version constraints cwe / cve_cwe — weakness taxonomy cvss — every CVSS vector from any source, deduped on (source, version, vector) cpe_match — NVD configuration leaf matches exploit — exploit availability + maturity (tri-state summary bools) exploit_artefact — per-CVE exploit evidence (Nuclei/Exploit-DB/Metasploit) kev — CISA KEV listing fields per CVE intel — generic threat-intel rows (kind/value/source) intel_string_list — backing list values for intel rows reference — URL references with trust + source reference_tag — many-to-many for ref tag vocabulary tag / cve_tag — CVE-level tags pipeline_run — per-phase watermarks for resume ``` 完整的 DDL 位于 [`vulnify/db/schema.sql`](vulnify/db/schema.sql)；包含查询注意事项的详细说明位于 [docs/SCHEMA.md](docs/SCHEMA.md)。 ## MCP server (`vulnify-mcp`) `vulnify.mcp` 通过 [Model Context Protocol](https://modelcontextprotocol.io) 将 SQLite 数据库暴露给 AI Agent。它是一个使用 stdio 通信的 FastMCP server，因此像 Claude Code、Claude Desktop 和 Cursor 这样的 Agent 可以在需要时将其作为子进程启动。 ### 第 1 步 — 设置项目 ``` git clone https://github.com/mez-0/vulnify.git cd vulnify uv sync --extra mcp ``` ### 第 2 步 — 获取 SQLite 数据库 有两种选择： **选项 A — 预构建（推荐）。** 下载发布资产并解压： ``` gh release download -R mez-0/vulnify --pattern vulnify.db.zst zstd -d vulnify.db.zst -o vulnify.db ``` **选项 B — 从源码构建。** 需要数小时；请参阅[从头构建数据库](#building-the-db-from-scratch)。 ### 第 3 步 — 将服务器指向数据库 在项目根目录下创建 `.env` 文件，并指定绝对路径： ``` echo "VULNIFY_SQLITE_PATH=$(pwd)/vulnify.db" > .env echo "VULNIFY_SCHEMA_SQL_PATH=vulnify/db/schema.sql" >> .env ``` ### 第 4 步 — 冒烟测试 确认服务器能正常启动并干净地关闭。它使用 stdio 通信，因此只需发送 `Ctrl-D` (EOF) 即可退出： ``` uv run vulnify-mcp

标签：AI代理, CVE, GPT, Kubernetes, MCP, SQLite, 威胁情报, 开发者工具, 数字签名, 数据流水线, 漏洞管理, 运行时操纵, 逆向工具