Query-farm/vgi-cve

一个用于 DuckDB 的 Query.Farm VGI worker。

# vgi-cve [](https://github.com/Query-farm/vgi-cve/actions/workflows/ci.yml) 一个用 **Go** 编写的 [VGI](https://query.farm) worker，用于从 [NVD 2.0 API](https://nvd.nist.gov/developers/vulnerabilities) 查询 **CVE / 漏洞数据**并计算 **CVSS v3.1 分数** —— 所有这些都作为 DuckDB/SQL 函数公开。它是一款防御性的漏洞管理工具。 基于 [`vgi-go`](https://github.com/Query-farm/vgi-go) SDK 构建；通过 stdio 进行 VGI 协议通信。Catalog 名称为：`cve`。 ``` INSTALL vgi FROM community; LOAD vgi; -- LOCATION is the path to the compiled worker binary. ATTACH 'cve' AS cve (TYPE vgi, LOCATION '/path/to/vgi-cve-worker'); -- Offline CVSS math (no network): SELECT cve.cvss_base_score('CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'); -- 9.8 SELECT cve.cvss_severity(9.8); -- CRITICAL -- Look up a CVE from the NVD API: SELECT id, cvss_score, cvss_severity, cwe FROM cve.cve('CVE-2021-44228'); -- Keyword search (paginated, bounded to 100 results): SELECT id, cvss_severity, published FROM cve.cve_search('log4j'); -- CVEs affecting a CPE name: SELECT cve_id, cvss_score, cvss_severity FROM cve.cpe_cves('cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*'); ``` ## 函数 分为两个系列：**离线标量函数**（纯 CVSS 数学计算，无网络请求，确定性）和**表函数**（实时 NVD 2.0 API 查询）。 ### 离线 CVSS 标量函数（无网络） | 函数 | 返回值 | 描述 | | --- | --- | --- | | `cvss_severity(score DOUBLE)` | `VARCHAR` | 根据 CVSS v3 标准将基础分数映射为 `NONE`/`LOW`/`MEDIUM`/`HIGH`/`CRITICAL`。 | | `cvss_base_score(vector VARCHAR)` | `DOUBLE` | 根据向量字符串（例如 `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H` → `9.8`）计算 CVSS v3.1 基础分数。实现了官方 v3.1 基础方程式，包括变更范围路径和规范中的“Roundup”。 | ### NVD 2.0 表函数（需要网络） | 函数 | 返回值 | 描述 | | --- | --- | --- | | `cve(cve_id)` | `id, description, cvss_score DOUBLE, cvss_severity VARCHAR, cvss_vector, published, last_modified, cwe` | 根据 ID 获取单个 CVE（返回一行，如果 id 为 NULL 则返回零行）。 | | `cve_search(keyword)` | `id, description, cvss_score, cvss_severity, published` | 对 CVE 描述进行关键字搜索；支持分页，结果上限为 100 条。 | | `cpe_cves(cpe)` | `cve_id, cvss_score, cvss_severity` | 影响特定 CPE 2.3 名称的 CVE；支持分页，有数量上限。 | 没有 CVSS 指标的 CVE 将返回 **NULL** 的 `cvss_score`。 ### 命名选项（表函数） 每个表函数都接受相同的可选命名参数（使用 DuckDB 的 `name := value` 语法）： | 选项 | 默认值 | 含义 | | --- | --- | --- | | `base_url` | 真实的 NVD endpoint | 覆盖 NVD 2.0 的基础 URL（用于指向 mock/proxy）。 | | `api_key` | `''` | NVD API key，作为 `apiKey` header 发送。可提高 NVD 的速率限制。 | ``` SELECT id, cvss_score FROM cve.cve('CVE-2021-44228', api_key := 'your-nvd-key'); ``` ## 行为与健壮性 - **离线优先。** `cvss_severity` 和 `cvss_base_score` 不会发起网络调用，并且是完全确定性的——非常适合为您数据中已有的向量进行评分。 - **NULL / 缺失输入 → 无结果。** 如果 id/keyword/cpe 为 NULL，则返回零行。 - **无 CVSS 指标 → NULL 分数。** 仍在分析中的记录会返回 NULL 的 `cvss_score`，而不是具有误导性的 `0`。 - **有界与限时。** 搜索结果会分页显示，但会在达到 100 行时停止；每次 HTTP 调用都有 30 秒的超时限制，因此如果 endpoint 缓慢或无法访问，会快速失败。 - **明确的错误，绝不崩溃或挂起。** HTTP 4xx/5xx 错误、NVD 速率限制 (429)、未知的 CVE id (404) 或格式错误的 JSON 都将作为清晰的 DuckDB 错误返回。 ## 构建 需要 Go 1.25+。 ``` make build # builds ./vgi-cve-worker and ./mockserver ``` `vgi-cve-worker` 二进制文件通过 stdio 进行 VGI 协议通信；可以通过在 DuckDB 中使用 `ATTACH ... (TYPE vgi, LOCATION '…')` 指向它。 ## 测试 ``` make test-unit # pure-Go unit tests (offline CVSS + httptest mock NVD) make test-sql # haybarn-unittest SQL end-to-end against a local mock NVD make test # both ``` `make test-sql` 需要在 `PATH` 中存在 [`haybarn-unittest`](https://query.farm)： ``` uv tool install haybarn-unittest export PATH="$HOME/.local/bin:$PATH" ``` 它会构建 worker 和一个小型的 **mock NVD server**（`cmd/mockserver`，提供预设的 NVD 2.0 JSON 数据），在一个空闲端口上启动该 mock，通过 `base_url` 选项将表函数指向它，运行测试套件，最后停止 mock。 ## NVD API 条款与速率限制 此 worker 会调用由 NIST 运营的公共 **NVD 2.0** 漏洞 API。 请遵守 [NVD 使用条款](https://nvd.nist.gov/developers/terms-of-use)和速率限制：未经身份验证的客户端会受到严格的限流（大约在每 30 秒的滚动窗口内只允许少量请求）。请申请一个免费的 [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) 并通过 `api_key := '…'` 传入以提高限额。CVE 数据由 NIST/NVD 提供；本项目未得到 NIST 的认可或与其有任何关联。 ## 许可 - 此 worker 采用 **MIT** 许可协议 —— 详见 [`LICENSE`](./LICENSE)。 - 它仅使用 Go **标准库**（`net/http`、`encoding/json`）来实现 NVD 客户端和 CVSS 数学计算，并使用 [`vgi-go`](https://github.com/Query-farm/vgi-go) SDK（及其 Arrow 依赖）来实现 VGI 协议 —— 相关条款请参阅该代码库。 ## 作者与许可 由 [Query.Farm](https://query.farm) 编写。 版权所有 2026 Query Farm LLC - https://query.farm

标签：CVE查询, CVSS评分, DuckDB, EVTX分析, Go语言, GPT, NVD, 数据库扩展, 日志审计, 漏洞管理, 程序破解