nonebot-plugin-depsafe 0.1.0

NoneBot2 dependency vulnerability lookup plugin powered by OSV.dev

nonebot-plugin-depsafe

开源依赖安全助手是一个面向 NoneBot2 的依赖安全查询插件。它可以在群聊中查询 PyPI、npm、Maven、Go、crates.io 等生态包的公开漏洞信息，适合课程作业、开源项目维护提醒、机器人辅助安全查询等场景。

插件数据来源为 OSV.dev。本插件只查询公开漏洞数据库，不提供攻击利用能力。

功能特性

• 查询指定生态、包名、版本是否存在公开漏洞
• 支持 PyPI 和 npm 的批量依赖查询
• 支持 requirements.txt 风格的 package==version 输入
• 支持 npm 简单 package@version 输入
• 展示漏洞 ID、CVE/GHSA aliases、摘要、CVSS/severity、影响范围、fixed 版本、发布时间、更新时间和参考链接
• 支持通过 OSV/GHSA/PYSEC 等漏洞 ID 查询漏洞详情
• 对参数不足、不支持生态、网络超时、API 异常、未查询到漏洞等情况给出清晰提示

安装方式

使用 nb-cli 安装：

nb plugin install nonebot-plugin-depsafe

使用 pip 安装：

pip install nonebot-plugin-depsafe

加载方式

如果没有使用 nb-cli 自动加载，可以在 NoneBot 项目的 pyproject.toml 中加入：

[tool.nonebot]
plugins = ["nonebot_plugin_depsafe"]

配置项

本插件无需配置项，不需要 API Key。安装并加载插件后即可使用。

命令列表

命令	英文 alias	说明	示例
/依赖安全	/depsafe	查询单个依赖版本的公开漏洞	/依赖安全 PyPI jinja2 2.4.1
/批量依赖安全	/depsafe-batch	批量查询 PyPI 或 npm 依赖	/批量依赖安全 PyPI
/漏洞详情	/vuln-detail	查询漏洞详情	/漏洞详情 GHSA-xxxx-xxxx-xxxx
/依赖安全帮助	/depsafe-help	查看插件帮助	/依赖安全帮助

说明：

• 正式使用入口是 NoneBot 聊天命令：/依赖安全、/批量依赖安全、/漏洞详情、/依赖安全帮助。
• scripts/smoke_test_osv.py 仅用于开发者验证 OSV.dev API 连通性和核心查询链路的冒烟测试脚本，不是插件的正式使用入口。

单包查询示例

/依赖安全 PyPI jinja2 2.4.1
/依赖安全 npm lodash 4.17.20
/依赖安全 Maven org.apache.logging.log4j:log4j-core 2.14.1
/依赖安全 Go github.com/gin-gonic/gin 1.6.0
/依赖安全 crates.io time 0.1.44

返回示例：

⚠️ 依赖安全查询
查询对象：npm lodash 4.17.20
结果：发现公开漏洞
漏洞数量：1
建议：建议升级到不受影响版本，并参考官方公告确认修复版本。

漏洞概览：
1. ID：GHSA-xxxx-xxxx-xxxx
   aliases：CVE-2021-xxxx、GHSA-xxxx-xxxx-xxxx
   summary：示例漏洞摘要
   severity/CVSS：CVSS_V3 CVSS:3.1/...
   affected：npm lodash（ECOSYSTEM: introduced 0, fixed 4.17.21）
   fixed：4.17.21
   published/modified：2021-01-01T00:00:00Z / 2021-01-02T00:00:00Z
   references：https://example.com/advisory

批量查询示例

默认按 PyPI requirements.txt 风格解析：

/批量依赖安全
flask==0.12
jinja2==2.4.1
requests==2.19.0

显式指定 PyPI：

/批量依赖安全 PyPI
flask==0.12
jinja2==2.4.1
requests==2.19.0

显式指定 npm：

/批量依赖安全 npm
lodash@4.17.20
axios@1.6.0

说明：

• 空行和 # 注释行会被忽略
• package>=version 这类范围查询暂不支持，插件会提示只支持精确版本
• 每次最多检查 20 个依赖，超过请拆分

批量返回会分为三组：

• 存在公开漏洞的依赖
• 未发现公开漏洞的依赖
• 解析失败的行

漏洞详情示例

/漏洞详情 GHSA-xxxx-xxxx-xxxx
/漏洞详情 PYSEC-xxxx-xx
/漏洞详情 OSV-xxxx

如果输入 CVE ID 且 OSV.dev 不能直接通过该 ID 获取详情，插件会提示先使用 /依赖安全 查询相关包版本，或使用对应的 GHSA/OSV/PYSEC ID。

支持生态说明

单包查询支持：

• PyPI
• npm
• Maven
• Go
• crates.io

批量查询当前支持：

• PyPI：package==version
• npm：package@version

数据来源

插件通过异步 HTTP 请求调用 OSV.dev API：

• /query：单包版本查询
• /querybatch：批量依赖查询
• /vulns/{id}：漏洞详情查询

查询不需要 API Key。查询结果仅代表 OSV.dev 当前收录的数据，建议结合官方公告、包管理器审计结果、锁文件和项目实际依赖树综合判断。

当前版本展示 OSV.dev 首次响应结果，极端大量结果的分页处理将在后续版本支持。

安全边界

• 只查询公开漏洞数据库
• 不提供 exploit
• 不提供 payload
• 不进行主动扫描
• 不扫描内网或公网目标
• 不替代专业 SCA 工具

常见问题

为什么查询不到漏洞不代表绝对安全？

公开漏洞数据库可能存在同步延迟、收录遗漏或版本映射差异。没有查询到公开漏洞只能说明当前数据源未返回结果，不代表依赖绝对安全。

为什么 CVE ID 有时不能直接查详情？

OSV.dev 的详情接口更稳定支持 OSV/GHSA/PYSEC 等 ID。部分 CVE ID 可能只是漏洞 aliases，不能直接作为详情 ID 查询。可以先用 /依赖安全 查询相关包版本，再使用返回的 GHSA/OSV/PYSEC ID 查询详情。

为什么只支持精确版本？

OSV.dev 查询依赖漏洞时需要明确的包版本。范围表达式如 package>=version 不能唯一确定实际安装版本，容易产生误报或漏报，因此 MVP 阶段只支持精确版本。

本地开发和测试

在你的 Conda 环境中执行：

conda activate your_conda_env
python -m pip install -e .[test]
python -m pytest -q

如果 Windows/Conda 下 pytest 指向了错误环境，可以检查：

where python
where pytest
python --version
python -m pytest -q

源码仓库开发验证：真实 OSV.dev API smoke test 不放入默认单元测试，避免网络波动影响测试稳定性。该脚本面向源码仓库开发者，pip 安装后的运行环境不一定包含 scripts/ 目录。需要验证真实 API 时，在源码仓库中执行：

python scripts/smoke_test_osv.py

该脚本会真实查询：

• PyPI jinja2 2.4.1
• npm lodash 4.17.20
• PyPI 批量：flask==0.12、jinja2==2.4.1、requests==2.19.0
• 使用前序查询返回的第一个漏洞 ID 调用 /vulns/{id} 查询详情

运行示例（节选）

以下是一次本地开发环境的实际输出示例，结果会随 OSV.dev 数据变化：

(pytorch2.3.1) D:\学习\作业\信安\大三下\开源软件\大作业\project3\nonebot-plugin-depsafe>python -m pytest -q
.....................                                               [100%]
21 passed in 1.36s

(pytorch2.3.1) D:\学习\作业\信安\大三下\开源软件\大作业\project3\nonebot-plugin-depsafe>python scripts/smoke_test_osv.py
OSV.dev smoke test for nonebot-plugin-depsafe
================================================
连接 OSV.dev：开始请求
查询对象：PyPI jinja2 2.4.1
是否成功连接 OSV.dev：是
返回真实漏洞条目数量：14
收集到的示例漏洞 ID 数量：5
第一个漏洞 ID：GHSA-462w-v97r-4m45
...
漏洞详情查询 ID：GHSA-462w-v97r-4m45
漏洞详情是否成功获取：是
漏洞详情 summary：Jinja2 sandbox escape via string formatting
连接 OSV.dev：成功

(pytorch2.3.1) D:\学习\作业\信安\大三下\开源软件\大作业\project3\nonebot-plugin-depsafe>python scripts/query_osv.py PyPI jinja2 2.4.1
⚠️ 依赖安全查询
查询对象：PyPI jinja2 2.4.1
结果：发现公开漏洞
漏洞数量：14
建议：建议升级到不受影响版本，并参考官方公告确认修复版本。

漏洞概览：
1. ID：GHSA-462w-v97r-4m45
   aliases：CVE-2019-10906
   summary：Jinja2 sandbox escape via string formatting
   severity/CVSS：CVSS_V3 CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N；CVSS_V4 CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:N/VI:N/VA:N/SC:H/SI:N/SA:N
   affected：PyPI jinja2（ECOSYSTEM: introduced 0, fixed 2.10.1）
   fixed：2.10.1
   published/modified：2019-04-10T14:30:24Z / 2024-09-24T21:03:59.802687Z
   references：https://nvd.nist.gov/vuln/detail/CVE-2019-10906；https://usn.ubuntu.com/4011-2
... 还有 11 个漏洞未展示，可使用 /漏洞详情 <漏洞ID> 查询。

Console 适配器测试

中文查询


英文查询


开源协议

本项目使用 MIT License。