## 工具 针对 NIST NVD API 2.0 提供了五个用于漏洞研究、CPE 审计和变更跟踪的工具： | 工具 | 描述 | |:-----|:------------| | `nvd_search_cves` | 按关键字、严重程度、CWE、日期范围或 CISA KEV 状态搜索 CVE。 | | `nvd_get_cve` | 根据 ID 获取一个或多个 CVE — 包含完整的 CVSS 分数、CWE、CPE 配置、KEV 字段和参考信息。 | | `nvd_search_cpes` | 按产品关键字或部分匹配字符串搜索 NVD CPE 字典。 | | `nvd_audit_cpe` | 通过 CPE 名称或虚拟匹配字符串，查找影响特定产品版本的所有 CVE。 | | `nvd_get_cve_history` | 检索 CVE 的变更历史 — 包括分数修订、状态转换和参考信息添加。 | ### `nvd_search_cves` 用于漏洞监控和分类工作流的主要发现工具。 - 跨 CVE 描述的全文关键字搜索（词与词之间为 AND 语义） - 按 CVSS v2/v3/v4 标签进行严重程度过滤（LOW、MEDIUM、HIGH、CRITICAL） - CWE 弱点过滤（例如 `CWE-79`、`NVD-CWE-Other`） - CISA KEV 过滤 — 将结果限制为已知被利用的漏洞 - 便捷日期简写：使用 `pubDays` 和 `lastModDays` 进行“过去 N 天”查询 - 显式的 ISO 8601 日期范围参数（`pubStartDate`/`pubEndDate` 等），最大跨度为 120 天 - 自动限制超过 120 天的便捷日期参数，并在 `queryMeta` 中报告被限制的值 - 通过 `limit`（最多 2000）和 `offset` 进行分页 - 结果总是简明的；调用 `nvd_get_cve` 获取完整详情 ### `nvd_get_cve` 根据 ID 获取一个或多个 CVE 的完整详情或简要摘要。 - 每次调用最多可批量处理 100 个 CVE ID - 完整模式：包含 v2.0、v3.0、v3.1 和 v4.0 的所有 CVSS 分数；CWE 弱点；CPE 配置；CISA KEV 字段；参考信息 - 简要模式（`brief: true`）：包含 ID、状态、最高严重程度、KEV 名称 — 建议在批次大于 10 时使用 - `includeReferences: false` 可去除参考信息数组并减小响应大小 - 按 ID 的一致性检查：`queryMeta.missingIds` 列出 NVD 未返回的任何请求 ID ### `nvd_search_cpes` 在审计之前查找产品标识符。 - 关键字搜索（例如 `"apache http server"`、`"openssl"`）或部分 CPEv2.3 匹配模式 - 返回完整的 CPE 名称、人类可读的标题、弃用状态以及替代的 CPE - 最多可分页 10,000 条记录 — 当 `totalResults > returned` 时，请缩小关键字范围 - 在使用 `nvd_audit_cpe` 之前使用此功能 — CPE 名称是复杂的字符串；盲目猜测会审计错误的产品 ### `nvd_audit_cpe` 针对特定产品版本的完整 CVE 审计。 - 两种模式：精确的 `cpeName`（NVD 自动应用 `isVulnerable`）或带有可选版本范围边界的 `virtualMatchString` - 通过 `versionStart`/`versionEnd` 进行版本范围控制，并支持包含/排除类型控制 - 客户端严重程度过滤器（`severityMin`）以剔除低价值条目 - 返回完整的 CVE 记录（ID、CVSS 分数、CWE、CPE 配置、KEV 字段、参考信息） - 在 `queryMeta` 中回显使用的 CPE 标识符，以便调用者可以验证是否查询了正确的产品 ### `nvd_get_cve_history` 随时间跟踪 CVE 的生命周期。 - 按时间倒序返回变更事件：CVSS 修订、状态转换、参考信息添加、CPE 配置更新 - 通过 `limit` 和 `offset` 进行分页 - 注意：如果没有 API key，NVD 历史记录端点会明显变慢 — 请设置 `NVD_API_KEY` 并提高 `NVD_REQUEST_TIMEOUT_MS` 以确保可靠运行 ## 资源 | 类型 | 名称 | 描述 | |:-----|:-----|:------------| | Resource | `nvd://cve/{cveId}` | 根据 ID 获取完整的 CVE 记录 — 对于单个 ID，其数据与 `nvd_get_cve` 相同，作为可用于注入上下文的稳定 URI。 | 所有资源数据也可以通过工具访问。 ## 功能特性 基于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) 构建： - 声明式的工具、资源和 prompt 定义 — 每个基元对应一个文件，框架负责处理注册和验证 - 统一的错误处理 — 处理程序抛出异常，框架负责捕获、分类和格式化 - 可插拔的身份验证：`none`、`jwt`、`oauth` - 可替换的存储后端：`in-memory`、`filesystem`、`Supabase`、`Cloudflare KV/R2/D1` - 结构化日志记录，支持可选的 OpenTelemetry 追踪 - STDIO 和 Streamable HTTP 传输 NVD 专用： - 令牌桶速率限制器强制执行 NVD 的 5 req/30s（无 key）和 50 req/30s（有 key）限制，并自动排队 - 从窗口和限制推导出的滑动窗口最小请求间隔 — 无突发请求，无 403 错误 - 通过 `withRetry` 自动重试并退避；在 403 响应时解析 `Retry-After` 标头 - HTML 响应防护机制可捕获以 HTML 格式提供而非 403 的 NVD 速率限制页面 对 Agent 友好的输出： - 每个响应都包含 `queryMeta` — 总结果数、返回数量、页面偏移量以及任何日期限制事件，以便 Agent 推理实际查询的内容 - 批量 CVE 查找中的 `missingIds` — 按 ID 进行一致性检查，而不是静默的部分结果 - 审计响应中的 CPE 回显 — 反馈 `cpeName` 或 `virtualMatchString`，以便调用者验证是否审计了正确的产品 ## 快速开始 将以下内容添加到您的 MCP 客户端配置文件中。 ``` { "mcpServers": { "nist-nvd-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/nist-nvd-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "NVD_API_KEY": "your-api-key" } } } } ``` 或者使用 npx（不需要 Bun）： ``` { "mcpServers": { "nist-nvd-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/nist-nvd-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "NVD_API_KEY": "your-api-key" } } } } ``` 或者使用 Docker： ``` { "mcpServers": { "nist-nvd-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "NVD_API_KEY=your-api-key", "ghcr.io/cyanheads/nist-nvd-mcp-server:latest" ] } } } ``` 对于 Streamable HTTP，设置传输方式并启动服务器： ``` MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NVD_API_KEY=... bun run start:http # 服务器监听于 http://localhost:3010/mcp ``` ### 前置条件 - [Bun v1.3.0](https://bun.sh/) 或更高版本（或 Node.js v24+）。 - 可选：[NVD API key](https://nvd.nist.gov/developers/request-an-api-key) — 免费，可将速率限制从 5 req/30s 提高到 50 req/30s。 ### 安装说明 1. **克隆仓库：** ``` git clone https://github.com/cyanheads/nist-nvd-mcp-server.git ``` 2. **进入目录：** ``` cd nist-nvd-mcp-server ``` 3. **安装依赖：** ``` bun install ``` 4. **配置环境：** ``` cp .env.example .env # 编辑 .env 并设置 NVD_API_KEY（如果有的话） ``` ## 配置说明 | 变量 | 描述 | 默认值 | |:---------|:------------|:--------| | `NVD_API_KEY` | NVD API key。如果没有它，速率限制为 5 req/30s；如果有，则为 50 req/30s。在 [nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key) 免费获取。 | — | | `NVD_REQUEST_TIMEOUT_MS` | 每次请求的超时时间（毫秒）。如果没有 API key，历史记录端点会很慢 — 如果在没有 key 的情况下使用 `nvd_get_cve_history`，请将其提高到 60000。 | `10000` | | `MCP_TRANSPORT_TYPE` | 传输方式：`stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP 服务器的端口。 | `3010` | | `MCP_AUTH_MODE` | 认证模式：`none`、`jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别 (RFC 5424)。 | `info` | | `LOGS_DIR` | 日志文件目录（仅限 Node.js）。 | `/logs` | | `OTEL_ENABLED` | 启用 [OpenTelemetry 监控](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 | `false` | 有关可选覆盖的完整列表，请参见 [`.env.example`](./.env.example)。 ## 运行服务器 ### 本地开发 - **构建并运行：** # 一次性构建 bun run rebuild # 运行构建好的服务器 bun run start:stdio # 或者 bun run start:http - **运行检查和测试：** bun run devcheck # 代码检查、格式化、类型检查、安全检查 bun run test # Vitest 测试套件 bun run lint:mcp # 根据 spec 验证 MCP 定义 ### Docker ``` docker build -t nist-nvd-mcp-server . docker run --rm -e NVD_API_KEY=your-key -p 3010:3010 nist-nvd-mcp-server ``` Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志记录到 `/var/log/nist-nvd-mcp-server`。默认情况下会安装 OpenTelemetry 的 peer dependencies — 使用 `--build-arg OTEL_ENABLED=false` 进行构建以忽略它们。 ## 项目结构 | 目录 | 用途 | |:----------|:--------| | `src/index.ts` | `createApp()` 入口点 — 注册工具/资源并初始化服务。 | | `src/config` | 使用 Zod 进行服务器特定的环境变量解析和验证。 | | `src/mcp-server/tools` | 工具定义（`*.tool.ts`）。 | | `src/mcp-server/resources` | 资源定义（`*.resource.ts`）。 | | `src/services/nvd-http` | 带有令牌桶速率限制和重试功能的 NVD HTTP 客户端。 | | `src/services/nvd-cve` | CVE 服务 — 搜索、按 ID 获取、CPE 审计、变更历史、规范化。 | | `src/services/nvd-cpe` | CPE 服务 — 字典搜索和规范化。 | `tests/` | 镜像 `src/` 的单元和集成测试。 | ## 开发指南 有关开发指南和架构规则，请参见 [`CLAUDE.md`](./CLAUDE.md)。简短版本如下： - 处理程序抛出异常，框架负责捕获 — 工具逻辑中无需 `try/catch` - 使用 `ctx.log` 进行请求范围内的日志记录，使用 `ctx.state` 进行租户范围内的存储 - 通过 `src/mcp-server/*/definitions/index.ts` 中的 barrel 文件注册新工具和资源 - 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出 schema；绝不编造缺失的字段 ## 贡献 欢迎提交 Issues 和 pull requests。在提交之前请运行检查和测试： ``` bun run devcheck bun run test ``` ## 许可证 Apache-2.0 — 有关详情，请参见 [LICENSE](LICENSE)。

标签：CVE审计, MCP服务器, MITM代理, NVD, TypeScript, 安全合规, 安全插件, 漏洞查询, 用户代理, 网络代理, 自动化攻击, 请求拦截