vulnersCom/api

## 为什么选择 Vulners？ [Vulners](https://vulners.com) 将 **230 多个数据源** — CVE、漏洞利用、厂商公告、 CISA KEV、EPSS 和 AI 风险评分 — 聚合到一个可查询的漏洞情报图谱中，让您可以 **超越原始的 CVSS** 来优先处理需要修复的漏洞。它是 API 优先的，不需要代理或网络访问： 以标准格式发送资产数据，即可获得按风险优先级排序的情报。 此 SDK 是使用 Python 在该图谱之上进行构建的最快方式： - 🔎 **情报** — 搜索并丰富 CVE、公告和通告，获取 CVSS、EPSS、KEV 和漏洞利用上下文 - 🧨 **漏洞利用** — 追踪活跃的漏洞利用情况，并获取针对特定产品或 CVE 的概念验证代码 - 🖥️ **评估** — 查找影响您的软件、Linux/Windows 主机、KB、库和 SBOM 的漏洞 - 🗄️ **数据集** — 将完整图谱（及每小时更新）流式传输到您自己的 pipeline 和镜像中 - 🔔 **告警** — 订阅匹配查询条件的新漏洞，并通过 webhook 获取通知 - 🤖 **AI 就绪** — 内置的 [MCP server](#ai-agents-mcp)、类型化的公告模型和完善的响应结构定义，可帮助 AI agent 基于实时的漏洞事实进行决策 ## 安装 ``` pip install -U vulners ``` 要求 **Python 3.10+**。只需简单的 `pip install vulners` 即可拉取实现快速、现代 网络传输所需的一切 — [`httpx`](https://www.python-httpx.org/)、[`pydantic`](https://docs.pydantic.dev/) 和 [`orjson`](https://github.com/ijl/orjson)，以及 HTTP/2 (`h2`)、响应压缩 (`brotli`/`zstandard`)、ISA-L 加速的 gzip (`isal`) 和流式归档解码 (`ijson`/`stream-unzip`) — 所有这些都带有预构建的 wheel，因此无需任何构建步骤。 ### 从分支检出安装（未发布版本） 最新的预发布版本位于 **`v4.0`** 分支上（尚未发布到 PyPI）。检出该分支 并从源码安装： ``` git clone -b v4.0 https://github.com/vulnersCom/api.git cd api pip install -e . # editable install from the checkout ``` 或者直接安装该分支，无需克隆： ``` pip install "git+https://github.com/vulnersCom/api.git@v4.0" ``` ## 快速入门 ``` from vulners import Vulners # 在 https://vulners.com 获取免费的 API key（或 export VULNERS_API_KEY）。 with Vulners(api_key="YOUR_API_KEY_HERE") as v: # Look up a CVE — you get back a typed model (or None if it isn't found). log4shell = v.search.get_bulletin("CVE-2021-44228") if log4shell is not None and log4shell.cvss is not None: print(log4shell.id, "—", log4shell.title) print(log4shell.cvss.score, log4shell.cvss.vector) # Search with Lucene syntax. `limit` is the page size; read the first page here # (iterating the page itself auto-paginates the whole result window). page = v.search.query("type:cve AND cvss.score:[9 TO 10]", limit=10) for bulletin in page.data: print(bulletin.id, bulletin.title) ``` ### 异步 相同的 API 也可在 `AsyncVulners` 上使用： ``` import asyncio from vulners import AsyncVulners async def main(): async with AsyncVulners(api_key="YOUR_API_KEY_HERE") as v: page = await v.search.query("Fortinet AND RCE", limit=20) for bulletin in page.data: print(bulletin.id, bulletin.title) asyncio.run(main()) ``` ## 使用示例 针对每个任务的可运行脚本位于 [`samples/`](samples/) 目录下 — 包含一组 **v4** 脚本和一组对应的 **v3（旧版）** 脚本，供您并列参考。 ### 查找针对 CVE 的公开漏洞利用 ``` for exploit in v.search.query("bulletinFamily:exploit AND CVE-2023-20198", limit=10).data: print(exploit.id, exploit.href) ``` ### 审计已安装软件的已知 CVE ``` # 混合使用 product/version dict 和原始的 CPE 2.3 字符串。 for item in v.audit.software([{"product": "openssl", "version": "1.0.1"}, "cpe:2.3:a:apache:log4j:2.14.1"]): print(item["matched_criteria"], "->", len(item["vulnerabilities"]), "vulnerabilities") ``` ### 根据已安装的包审计 Linux 主机 ``` report = v.audit.linux_audit(os_name="debian", os_version="10", packages=["openssl 1.1.1d-0+deb10u3 amd64"]) for issue in report["issues"]: print(issue["package"]) ``` ### 流式传输归档（延迟加载，无需缓存 GB 级数据） ``` for record in v.archive.iter_collection("cve"): ... # each record is yielded as it arrives (a lazily-streamed JSON array) ``` ### 处理错误 ``` from vulners import Vulners, APIError, RateLimitError try: with Vulners(api_key="YOUR_API_KEY_HERE") as v: cve = v.search.get_bulletin("CVE-2021-44228") except RateLimitError as err: print("slow down; retry after", err.retry_after, "s") except APIError as err: print(err.status_code, err.error_code, err.message) # the server's problem description ``` ## 数据模型 API 返回的每个文档都是一个**公告**，SDK 将它们建模为三个类型化层， 以便您的编辑器和类型检查器能够准确了解您所需的任意详细程度的结构定义： - **`Bulletin`** — 每个文档都携带的基础字段（`id`、`title`、`cvss`、`published` 等）。 - **系列模型**（`CveBulletin`、`ExploitBulletin`、`ScannerBulletin` 等） — 每个 `bulletinFamily` 对应一个，用于添加该系列共有的字段。 - **集合模型** — 每个集合 `type` 对应一个，用于添加特定于该数据源的字段。 `search`/`archive`/`audit` 会返回最适合文档的具体模型（`type` → `bulletinFamily` → `Bulletin`）。每个字段都是可选的（缺失即为 `None`），并且每个模型 都保留了 `extra="allow"`，因此当 API 在 SDK 对其建模之前新增了字段时，该字段仍会存在于对象上 — 绝不会丢失任何数据。 ``` from vulners import Vulners, CveBulletin with Vulners() as v: # reads VULNERS_API_KEY cve = v.search.get_bulletin("CVE-2021-44228") if isinstance(cve, CveBulletin): print(cve.cwe) # typed, cve-specific field — IDE-completed ``` 完整的层级结构 — 每个系列和集合的字段、描述和示例， 均根据实时数据生成 — 可在 **[数据模型参考](https://vulnersCom.github.io/api/reference/bulletins/)** 中浏览。 ## 代理 使用 `proxy=` 通过代理路由流量，或者让客户端自动获取标准的代理 环境变量： ``` from vulners import Vulners # 显式指定（一个 URL，或用于经过身份验证的代理的 httpx.Proxy(..., auth=(user, pass))） v = Vulners(api_key="YOUR_API_KEY_HERE", proxy="http://proxy.corp.example:8080") # 或从环境变量中获取 — HTTPS_PROXY / HTTP_PROXY / ALL_PROXY，并遵循 NO_PROXY： # export HTTPS_PROXY="http://proxy.corp.example:8080" v = Vulners(api_key="YOUR_API_KEY_HERE") ``` 当您不传递 `proxy=` 并保留 `trust_env=True`（默认值）时，将使用环境代理。有关 经过身份验证的代理以及将代理与自定义 TLS 结合使用的信息，请参阅 [代理、超时和重试](https://vulnersCom.github.io/api/how-to/proxy-timeout-retries/)。 ## AI agent (MCP) 通过内置的 [Model Context Protocol](https://modelcontextprotocol.io) server，将实时的 Vulners 情报发送给 AI agent 和智能助手： ``` pip install "vulners[mcp]" VULNERS_API_KEY=... vulners-mcp # run the MCP server ``` 它提供简洁、类型化的工具 — 搜索公告、查询 CVE、查找漏洞利用以及审计 软件/Linux/主机 — 任何兼容 MCP 的客户端（Claude、IDE agent 等）都可以调用它们。请参阅 [`AGENTS.md`](AGENTS.md)。 ## 向后兼容性 **从 3.x 升级是无缝替换的。** 整个 v3 API — `VulnersApi`、`VScannerApi`、每个方法， 以及所有的导入路径 — 在 4.0 中均保持不变： ``` import vulners api = vulners.VulnersApi(api_key="YOUR_API_KEY_HERE") # still works exactly as before cve = api.search.get_bulletin("CVE-2021-44228") # returns a dict, as it always did ``` 新代码应首选使用上文的 `Vulners` / `AsyncVulners` 客户端。您可以按照自己的节奏进行迁移 — 请参阅 [迁移指南](https://vulnersCom.github.io/api/explanation/migration/)。 ## 获取 API key 1. 在 **[vulners.com](https://vulners.com)** 创建一个免费帐户。 2. 按照 [身份验证指南](https://docs.vulners.com/docs/quickstart/authentication/#how-to-obtain-api-key) 生成一个 key。 3. 将其传递给 `Vulners(api_key=...)`，或者导出 `VULNERS_API_KEY` 让客户端自动读取。 切勿提交您的 API key。SDK 使用 `X-Api-Key` 请求头进行身份验证；少数旧版 endpoint 在服务器要求时也会额外发送 key — 位于请求正文中（ 订阅和 webhook 修改操作以及 `win_audit`）或查询字符串中（`webhooks.read()`）。在 每次请求中，它都会在跨域重定向时剥离该 key，拒绝重定向到内部 地址，并确保其不会出现在异常消息和对象的 repr 中。 ## 文档 | 资源 | 链接 | |---|---| | 📘 SDK 文档 | https://vulnersCom.github.io/api/ | | 🧬 数据模型（公告层级结构） | https://vulnersCom.github.io/api/reference/bulletins/ | | 🔌 SDK API 参考（客户端、资源、异常） | https://vulnersCom.github.io/api/reference/clients/ | | 🧭 迁移（v3 → v4） | https://vulnersCom.github.io/api/explanation/migration/ | | 📖 Vulners 平台文档 | https://docs.vulners.com/docs/ | | 🧪 交互式 API (Swagger) | https://docs.vulners.com/docs/api/swagger/ | | 🔑 身份验证 / API key | https://docs.vulners.com/docs/quickstart/authentication/ | | 💡 示例 | [`samples/`](samples/) | | 🤝 贡献指南 | [CONTRIBUTING.md](CONTRIBUTING.md) | | 🔒 安全策略 | [SECURITY.md](SECURITY.md) | ## 兼容性 - **Python:** 3.10, 3.11, 3.12, 3.13, 3.14 - **平台:** Linux, macOS, Windows - **Vulners API:** v3 和 v4 endpoint ## 安全性 在 SDK 中发现了安全问题？请私下报告 — 请参阅 [SECURITY.md](SECURITY.md)。请勿公开 提交漏洞问题。 ## 许可证 基于 **MIT 许可证** 分发。请参阅 [LICENSE](LICENSE)。

标签：API封装, Python, XSS, 无后门, 漏洞情报, 漏洞查询, 运行时操纵, 逆向工具