Package Doctor Skill 技能

Package Doctor 是一款开源 Python 依赖包安全扫描工具，帮助开发者识别项目中存在已知漏洞或已被上游弃用的 Python 包，并阻止 AI 编程 Agent 安装不安全的依赖。该工具支持 CI 集成、pre-commit 钩子以及 Claude Code 专用插件三种使用方式，通过 CISA 已知被利用漏洞列表（KEV）和 FIRST EPSS 评分对漏洞进行优先级排序，让开发者优先处理真正存在现实威胁的依赖问题。

核心功能

漏洞分级与优先级排序

Package Doctor 采用双维度评估模型：不仅要判断一个包是否存在已知 CVE 漏洞，还要评估该漏洞是否可被攻击者实际利用。具体来说，工具会检查该包是否处于信任边界——即是否负责解析、解码或认证攻击者可控制的数据——同时结合 CISA KEV 列表和 FIRST EPSS 评分，将大量安全公告压缩为真正值得立即处理的那几个。

可达性分析

每个扫描结果都会标注该漏洞包是否被项目代码实际导入使用。工具会追踪 import 语句，告诉你具体在哪个代码位置引入了有问题的依赖，从而避免修复从未实际调用的死代码中的漏洞。这一功能大幅降低了误报率，让开发者聚焦真实风险。

Claude Code 插件拦截

作为 Claude Code 的 PreToolUse 和 PostToolUse 钩子，Package Doctor 能够在 AI Agent 安装依赖之前进行拦截：阻止安装包含已知漏洞的包、阻止安装已被官方归档的弃用包、阻止安装发布不足 30 天的新包（防止恶意包伪装），并提供具体的拦截原因，帮助 AI 重新选择安全的替代方案。

多格式锁文件支持

工具支持读取 uv.lock、poetry.lock、Pipfile.lock、pyproject.toml、Pipfile、setup.cfg、setup.py 和 requirements.txt 等常见 Python 依赖锁定格式，并能够理解不同格式之间的版本约束语义。

CI / SARIF 集成

在 CI 流程中，一条 GitHub Action 即可扫描代码仓库，在发现需要修复的信任边界问题时让构建失败，并将完整报告写入任务摘要。同时支持输出 SARIF 格式的扫描结果，可直接对接 GitHub 代码扫描功能。

预提交钩子支持

除了 CI 集成外，Package Doctor 还支持作为 pre-commit 钩子运行，在每次提交前检查依赖安全性，适合在团队内部推广统一的安全基线。

安装配置

方式一：pip 安装

pip install package-doctor

方式二：GitHub Action 集成

在项目 .github/workflows/ 目录下添加 workflow 文件，使用 binuka200/package-doctor@v1.0.0 action，工具会自动扫描依赖并在发现问题时让构建失败。

方式三：Pre-commit 钩子

Package Doctor 支持作为 pre-commit 钩子运行，在 git commit 前自动检查依赖安全性，适合在团队内部推广统一的安全规范。

使用步骤

步骤一：扫描项目依赖

package-doctor scan

扫描项目所有依赖，输出包含已知漏洞和被弃用包的完整报告，按 exploit 和 replace 两个维度分类。

步骤二：查看单个包的详细证据

package-doctor explain pillow

针对特定依赖包输出详细的漏洞判定依据，包括 CVE 编号、利用概率评分、信任边界判定理由等。

步骤三：安装前检查新包

package-doctor check requests pillow==10.0.0

在向项目中添加新依赖前，运行此命令检查目标版本是否存在已知漏洞或被弃用。

步骤四：配置 Claude Code 钩子

在 Claude Code 项目的 .claude/settings.json 中添加 PreToolUse 和 PostToolUse 钩子配置，指向 package-doctor hook claude-code，AI 在安装任何依赖前都会自动经过安全检查。

技术实现

Package Doctor 的核心判断逻辑基于两个轴：漏洞的严重程度，以及该包是否处于数据信任边界。信任边界的判定来自维护者手工审核的 1,500 多个包目录，每个包都有对应的人类可读的判断理由，而非简单的规则匹配。漏洞可达性分析通过追踪源代码中的 import 语句实现，在 60 个开源仓库和 13,043 个包上的测试中，78,642 个导入点里有 78,612 个能够精确匹配。

在数据源方面，工具整合了 OSV（Open Source Vulnerabilities）、CISA KEV 和 FIRST EPSS 三个权威漏洞数据库，确保覆盖已知被实际利用的漏洞以及具有较高利用概率的潜在风险。

适用场景

• AI 编程工作流安全：在使用 Claude Code、Cursor 等 AI 编程工具时，防止 AI 引入含有已知漏洞或恶意行为的依赖包
• CI/CD 安全门禁：在持续集成流程中加入依赖安全检查，确保主分支代码不引入高危漏洞
• 季度依赖维护审计：相比 per-commit 的 CVE 检查，Package Doctor 更适合季度性的深度维护审查，发现长期未更新但仍被使用的依赖包
• 开源项目安全审查：快速扫描一个开源项目所有依赖的安全状态，识别需要优先处理的高风险依赖
• 团队安全基线建设：通过 pre-commit 钩子在团队内统一推广依赖安全规范，减少人为疏忽导致的安全风险

适用人群

• 使用 AI 编程工具（Claude Code、Cursor、Windsurf 等）的开发者
• 关注 Python 项目依赖安全的后端工程师和安全工程师
• 需要定期审计开源项目依赖的技术负责人
• 在 CI/CD 流程中需要加入安全门禁的 DevOps 团队

官方链接

• GitHub：https://github.com/binuka200/package-doctor
• PyPI：https://pypi.org/project/package-doctor/