## 工具 4 个用于查询 OSV.dev 漏洞数据库的工具 — 单个软件包查询、批量依赖审计以及完整公告获取： | 工具 | 描述 | |:---|:---| | `osv_query_package` | 通过名称、生态系统和版本号查询单个软件包版本的已知漏洞 | | `osv_query_batch` | 针对软件包元组数组的批量漏洞查询 — 只需一次调用即可完成完整的依赖列表或 SBOM 审计 | | `osv_get_vulnerability` | 获取单个 OSV 漏洞 ID 对应的完整公告记录 | | `osv_list_ecosystems` | 返回支持的生态系统标识符字符串列表 | ### `osv_query_package` 主要的“此软件包版本是否存在漏洞？”查询工具。 - 接受 `name`、`ecosystem`（区分大小写且需精确匹配 — 请使用 `osv_list_ecosystems` 进行验证）和 `version` 参数 - 返回所有匹配的公告：OSV ID、CVE 别名、CVSS 严重性向量、推导出的严重性标签、首个安全版本、受影响的版本范围（SEMVER/ECOSYSTEM/GIT）以及 CWE ID - `aliases` 字段会展示 CVE ID，可链接至 `nist-nvd-mcp-server` 以获取 CVSS 基础分数、EPSS 利用概率和 CISA KEV 状态 - 无需 API key — OSV.dev 完全公开且不需要密钥 ### `osv_query_batch` 用于依赖审计、SBOM 扫描和 lockfile 分类的主要工具。 - 接受 `{name, ecosystem, version}` 元组数组（每次调用支持 1–1000 个软件包） - 在调用 API 之前会对所有生态系统进行预验证 — 只要有一个无效的生态系统字符串就会导致整个批次失败（这是 OSV API 的行为） - 返回与输入位置对应的各软件包结果，包含 `vulnerable`、`vulnCount`、`vulns`（包含 `aliases` 和 `severityLabel`）以及 `fixedVersions` - 包含聚合摘要：`totalPackages`、`vulnerableCount`、`cleanCount`、`errorCount`、`totalVulns`、`worstSeverity` ### `osv_get_vulnerability` 通过 OSV ID 获取完整的公告记录。 - 接受任何 OSV ID 前缀：`GHSA-` (GitHub)、`PYSEC-` (Python)、`RUSTSEC-` (Rust)、`GO-` (Go)、`DSA-`/`DLA-` (Debian)、`CVE-`（直接的 CVE 回退） - 返回：摘要、完整的公告详情文本、所有 CVE 别名、所有受影响的软件包及其版本范围、修复版本、CVSS 严重性向量、CWE 弱点 ID 以及参考链接（ADVISORY、FIX、REPORT 等） - 在 `osv_query_package` 或 `osv_query_batch` 返回漏洞 ID 后使用此工具，以获取完整的公告上下文 — 修复指导、受影响软件包的范围或资格标准 ### `osv_list_ecosystems` 返回有效的生态系统标识符字符串列表。生态系统字符串是**区分大小写的精确匹配** — `"pypi"` 不等于 `"PyPI"`。在查询之前调用此工具，以验证来自 lockfile 或用户输入的生态系统字符串。该列表是静态的（源自 OSV schema 规范），偶尔可能无法及时涵盖新添加的生态系统。 ## 功能 基于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) 构建： - 声明式工具定义 — 每个工具对应一个文件，由框架负责注册和验证 - 统一的错误处理 — handler 负责抛出，框架负责捕获、分类和格式化 - 可插拔的身份验证：`none`、`jwt`、`oauth` - 可替换的存储后端：`in-memory`、`filesystem`、`Supabase`、`Cloudflare KV/R2/D1` - 结构化日志记录，可选的 OpenTelemetry 追踪 - STDIO 和 Streamable HTTP 传输 OSV 特有功能： - 无需 API key — OSV.dev 完全公开、无密钥，且没有公布的速率限制 - 在 `osv_query_batch` 中并行执行的单个软件包查询会返回包含 `aliases` (CVE ID) 在内的完整记录，这是上游批量 endpoint 所省略的 - 生态系统预验证可防止 OSV “要么全有要么全无”的批量拒绝行为 对 Agent 友好的输出： - `aliases` (CVE ID) 在每个漏洞条目中都显著展示 — 这是用于链接至 `nist-nvd-mcp-server` 以获取 CVSS 基础分数、EPSS 和 CISA KEV 状态的主要组合点 - `severityLabel` 源自 `database_specific.severity` (GHSA 记录) 或最高的 CVSS 基础分数；当两者均不可用时为 `null`，而不是凭空捏造 - 在 `osv_query_package` 输出中回显查询参数 (`queryMeta`)，以便 agent 可以验证请求是否被正确应用 - 批量聚合摘要（`worstSeverity`、`vulnerableCount`、`cleanCount`）便于快速进行分类，无需逐行阅读软件包数据 ## 快速开始 ### 公共托管实例 公共实例位于 `https://osv-advisory.caseyjhand.com/mcp` — 无需安装。通过 Streamable HTTP 将任何 MCP client 指向它： ``` { "mcpServers": { "osv-advisory-mcp-server": { "type": "streamable-http", "url": "https://osv-advisory.caseyjhand.com/mcp" } } } ``` ### 自托管 / 本地运行 将以下内容添加到您的 MCP client 配置文件中。无需 API key — OSV.dev 完全公开。 ``` { "mcpServers": { "osv-advisory-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/osv-advisory-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或者使用 npx（不需要 Bun）： ``` { "mcpServers": { "osv-advisory-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/osv-advisory-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或者使用 Docker： ``` { "mcpServers": { "osv-advisory-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/osv-advisory-mcp-server:latest" ] } } } ``` 对于 Streamable HTTP，请设置传输方式并启动服务器： ``` MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # 服务器监听于 http://localhost:3010/mcp ``` ### 前置条件 - [Bun v1.3.0](https://bun.sh/) 或更高版本（或 Node.js v24+）。 - 无需 API key — OSV.dev 完全公开。 ### 安装 1. **克隆代码库：** ``` git clone https://github.com/cyanheads/osv-advisory-mcp-server.git ``` 2. **进入目录：** ``` cd osv-advisory-mcp-server ``` 3. **安装依赖：** ``` bun install ``` 4. **配置环境：** ``` cp .env.example .env # 如有需要请编辑 .env（无必填变量） ``` ## 配置 所有配置都会在启动时进行验证。无需特定于服务器的环境变量 — OSV.dev 无需密钥且完全公开。 | 变量 | 描述 | 默认值 | |:---------|:------------|:--------| | `OSV_REQUEST_TIMEOUT_MS` | 调用 OSV.dev API 的 HTTP 请求超时时间（以毫秒为单位）。 | `10000` | | `MCP_TRANSPORT_TYPE` | 传输方式：`stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP 服务器的端口。 | `3010` | | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint 路径。 | `/mcp` | | `MCP_PUBLIC_URL` | 用于终止 TLS 的反向代理部署的公共源覆盖。 | 无 | | `MCP_AUTH_MODE` | 身份验证模式：`none`、`jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别 (RFC 5424)。 | `info` | | `LOGS_DIR` | 日志文件的目录（仅适用于 Node.js）。 | `/logs` | | `STORAGE_PROVIDER_TYPE` | 存储后端。 | `in-memory` | | `OTEL_ENABLED` | 启用 [OpenTelemetry 监测](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)（spans、指标、完成日志）。 | `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 osv-advisory-mcp-server . docker run --rm -p 3010:3010 osv-advisory-mcp-server ``` Dockerfile 默认使用 HTTP 传输、无状态 session 模式，并将日志输出到 `/var/log/osv-advisory-mcp-server`。OpenTelemetry 的 peer 依赖默认会被安装 — 构建时使用 `--build-arg OTEL_ENABLED=false` 可将其省略。 ## 项目结构 | 目录 | 用途 | |:----------|:--------| | `src/index.ts` | `createApp()` 入口点 — 注册工具并初始化服务。 | | `src/mcp-server/tools` | 工具定义 (`*.tool.ts`) — `osv_query_package`、`osv_query_batch`、`osv_get_vulnerability`、`osv_list_ecosystems`。 | | `src/services/osv-api` | OSV.dev REST API 服务 — 获取、重试、响应标准化。 | | `tests/` | 映射 `src/` 结构的单元测试和集成测试。 | ## 开发指南 有关开发指南和架构规则，请参见 [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md)。简短版本如下： - Handler 负责抛出，框架负责捕获 — 工具逻辑中无需 `try/catch` - 使用 `ctx.log` 进行请求范围内的日志记录，使用 `ctx.state` 进行租户范围内的存储 - 通过 `src/mcp-server/tools/definitions/index.ts` 中的 barrel 文件注册新工具 - 包装外部 API 调用：验证原始数据 → 标准化为领域类型 → 返回输出 schema；绝不凭空捏造缺失的字段 ## 贡献 欢迎提交 issue 和 pull request。提交前请运行检查和测试： ``` bun run devcheck bun run test ``` ## 许可证 Apache-2.0 — 详情请参见 [LICENSE](LICENSE)。

标签：CISA项目, MCP服务器, MITM代理, XSS, 依赖审计, 域名收集, 模型上下文协议, 漏洞情报, 漏洞查询, 自动化攻击, 请求拦截