Metadata-Version: 2.4
Name: nonebot-plugin-depsafe
Version: 0.1.0
Summary: NoneBot2 dependency vulnerability lookup plugin powered by OSV.dev
Project-URL: Homepage, https://github.com/Wyh-max-star/nonebot-plugin-depsafe
Project-URL: Repository, https://github.com/Wyh-max-star/nonebot-plugin-depsafe
Project-URL: Issues, https://github.com/Wyh-max-star/nonebot-plugin-depsafe/issues
Author: Wyh-max-star nonebot-plugin-depsafe contributors
License: MIT
License-File: LICENSE
Keywords: dependency,nonebot,nonebot2,osv,plugin,security
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: nonebot2>=2.2.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# nonebot-plugin-depsafe

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

插件数据来源为 [OSV.dev](https://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 安装：

```bash
nb plugin install nonebot-plugin-depsafe
```

使用 pip 安装：

```bash
pip install nonebot-plugin-depsafe
```

## 加载方式

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

```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 连通性和核心查询链路的冒烟测试脚本，不是插件的正式使用入口。

## 单包查询示例

```text
/依赖安全 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
```

返回示例：

```text
⚠️ 依赖安全查询
查询对象：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 风格解析：

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

显式指定 PyPI：

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

显式指定 npm：

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

说明：

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

批量返回会分为三组：

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

## 漏洞详情示例

```text
/漏洞详情 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 环境中执行：

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

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

```powershell
where python
where pytest
python --version
python -m pytest -q
```

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

```bash
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 数据变化：

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

```text
(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：成功
```

```text
(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 适配器测试

中文查询

![屏幕截图 2026-06-04 121216](figures\屏幕截图 2026-06-04 121216.png)

英文查询

![屏幕截图 2026-06-04 150737](D:\学习\作业\信安\大三下\开源软件\大作业\project3\nonebot-plugin-depsafe\figures\屏幕截图 2026-06-04 150737.png)

## 开源协议

本项目使用 MIT License。
