kidoz/vulners-py
GitHub: kidoz/vulners-py
面向 Vulners API 的严格类型 Python SDK，提供同步/异步双客户端，覆盖漏洞搜索、审计、归档与订阅等全量接口能力。
Stars: 0 | Forks: 0
# vulners-py
[](https://www.python.org/)
[](LICENSE)
[](https://pypi.org/project/vulners-py/)
一个现代化、严格类型的 Python SDK，专为 [Vulners API](https://docs.vulners.com/docs/api/) 设计。
它提供了相匹配的同步和异步客户端、不可变的 Pydantic v2 模型、具有弹性的
HTTP 处理机制，并且不包含已废弃的顶层兼容性别名。
## 功能
- 搜索、文档检索、软件/主机/包/SBOM 审计以及 Smart Audit。
- 支持 ZIP、gzip、JSON 和 NDJSON 归档解码，并提供流式传输到磁盘的选项。
- 报告、v4 订阅、传统的邮件/轮询订阅、STIX、CPE 以及搜索辅助工具。
- 从 `VULNERS_API_KEY` 加载 API key，支持基于 `.env` 的开发工作流。
- 重试/退避机制、`Retry-After`、按端点限流、HTTP/2 支持以及类型化的异常。
- 严格的 mypy、Ruff 和 pytest 检查，并包含同步/异步契约测试。
VScanner 已被有意排除，因为它已被废弃。
## 环境要求
- Python 3.10 或更高版本
- 一个 [Vulners API key](https://vulners.com)
## 安装说明
```
uv add vulners-py
```
或者：
```
pip install vulners-py
```
可选的性能扩展包：
```
uv add "vulners-py[http2,orjson]"
```
## 身份验证
创建一个不提交到版本控制的本地 `.env` 文件：
```
VULNERS_API_KEY=your-api-key
```
在运行应用程序之前将其加载到环境中：
```
set -a
source .env
set +a
```
该密钥也可以通过 `Vulners(api_key="...")` 显式传递。传输层使用
`X-Api-Key` 进行身份验证，绝不将密钥放在 URL 中，并丢弃 HTTP cookie。客户端和传输层的
字符串表示形式绝不会包含该密钥。
在将 SDK 集成到您的应用之前，请使用内置的预检（一次低成本的只读调用；成功时退出代码为 `0`，未设置密钥时为 `2`）确认 `.env` 中的密钥已被接受：
```
uv run python examples/check_connection.py # synchronous
uv run python examples/async_check_connection.py # asynchronous
```
请参阅 [`examples/`](examples/) 获取从 `.env` 加载 `VULNERS_API_KEY` 的可运行代码片段。
## 快速入门
### 同步
```
from vulners import Vulners
with Vulners() as client:
page = client.search.bulletins("wordpress 4.7", limit=10)
document = client.documents.get("CVE-2024-23622")
for bulletin in page.documents:
print(bulletin.id, bulletin.title)
print(document)
```
### 异步
```
import asyncio
from vulners import AsyncVulners
async def main() -> None:
async with AsyncVulners() as client:
async for bulletin in client.search.exploits_iter("CVE-2021-44228"):
print(bulletin.id)
asyncio.run(main())
```
## 命名空间
| 命名空间 | 功能 |
| --- | --- |
| `search` | 公告、漏洞利用、迭代器、历史记录以及 Web 漏洞匹配 |
| `documents` | 获取单个/多个文档、引用、KB seeds 和 KB 更新 |
| `audit` | 软件、主机、Linux、库、经典 OS、Windows、CVE、SBOM 以及 Smart Audit |
| `archive` | v3/v4 集合、增量更新、distributives 以及 Getsploit 下载 |
| `reports` | 漏洞、IP、扫描和主机报告 |
| `subscriptions` | v4 生命周期以及 `.email` 下的传统邮件订阅 |
| `webhooks` | 传统的轮询/webhook 订阅 |
| `stix` | 按公告 ID 生成 STIX bundle |
| `misc` | 建议、自动补全、CPE 查询和 WAF 规则 |
### 审计示例
```
from pathlib import Path
from vulners import Vulners
from vulners.types import AuditSoftware
with Vulners() as client:
matches = client.audit.software(
(AuditSoftware(product="curl", vendor="haxx", version="8.0"),)
)
packages = client.audit.library(("pkg:pypi/requests@2.20.0",))
sbom = client.audit.sbom(Path("bom.json"))
```
[Smart Audit](https://docs.vulners.com/docs/api/smart-audit/) 是一个预览版端点，按
提交的软件字符串计费。调用 `client.audit.smart(...)` 可能会产生账户费用。
### 归档示例
```
from pathlib import Path
from vulners import Vulners
with Vulners() as client:
records = client.archive.collection_update("exploitdb", "2026-07-17T00:00:00")
client.archive.collection_v4(
"exploitdb",
raw=True,
destination=Path("exploitdb.ndjson.gz"),
)
```
解码后的归档调用会返回不可变的 `ArchiveRecord` 对象。`raw=True` 需要指定目标
并在不将归档加载到内存的情况下流式传输响应。
### 订阅
```
from vulners import Vulners
from vulners.types import LuceneSubscriptionQuery, WebhookSubscriptionDelivery
query = LuceneSubscriptionQuery(query="cvss:[9 TO *] AND family:cve")
delivery = WebhookSubscriptionDelivery(
address="https://example.com/vulners",
crontab="0 * * * *",
)
with Vulners() as client:
created = client.subscriptions.create("Critical CVEs", query, delivery)
print(created.id)
```
创建、更新和删除调用会更改远程账户状态。传统的邮件订阅位于
`client.subscriptions.email` 下；传统的轮询订阅位于 `client.webhooks` 下。
## 错误处理
```
from vulners import AuthenticationError, RateLimitError, Vulners, VulnersAPIError
try:
with Vulners() as client:
client.search.bulletins("wordpress")
except AuthenticationError:
print("Check VULNERS_API_KEY")
except RateLimitError as error:
print(f"Retry after {error.retry_after!r} seconds")
except VulnersAPIError as error:
print(f"Vulners API error {error.status_code}: {error.message}")
```
## 从旧版包装器迁移
| 旧版包装器 | `vulners-py` |
| --- | --- |
| `find(query)` / `search_bulletins(query)` | `client.search.bulletins(query)` |
| `find_all(query)` | `client.search.bulletins_iter(query)` |
| `find_exploit(query)` | `client.search.exploits(query)` |
| `get_bulletin(id)` | `client.documents.get(id)` |
| `audit_software(...)` | `client.audit.software(...)` |
| `winaudit(...)` | `client.audit.winaudit(...)` |
| `vulnssummary_report(...)` | `client.reports.vulns_summary(...)` |
不包含已废弃的顶层别名或 `DeprecationWarning` 垫片。
## 开发说明
开发环境需要 [uv](https://docs.astral.sh/uv/) 和
[just](https://github.com/casey/just)。然后安装所有可选和开发依赖项：
```
uv sync --all-extras
just check
```
可用的 recipes：
```
just fmt
just lint
just typecheck
just test
just check
```
测试默认使用模拟的 HTTP 契约。使用从 `.env` 加载的密钥
运行有边界的只读集成测试套件：
```
set -a
source .env
set +a
VULNERS_LIVE=1 uv run pytest tests/test_integration.py
```
该集成测试套件特意排除了会计费的 Smart Audit/SBOM 请求、归档批量
下载和订阅状态更改操作。
## 许可证
在 [MIT License](LICENSE) 下分发。版权所有 © 2026 Aleksandr Pavlov
。
标签：API客户端, Python, XSS, 安全规则引擎, 异步编程, 无后门, 漏洞情报, 逆向工具