dependency-audit

依赖项审计

全面评估依赖项风险：许可证兼容性分析、维护健康度评分、CVE 检测、冗余识别，以及传递依赖风险映射。生成可执行的报告，并按紧急程度（安全 → 许可证 → 维护 → 冗余）列出优先修复步骤。

参考文件

文件	内容	加载时机
references/license-compatibility.md	许可证兼容性矩阵、Copyleft 检测、适合商业用途的许可证	始终
references/health-metrics.md	维护健康度指标、评分标准、弃用检测	始终
references/bloat-detection.md	识别未使用的依赖项、重复功能、庞大的传递依赖树	请求冗余分析时
references/cve-sources.md	CVE 数据库、公告来源、漏洞严重性解读	请求安全审计时

前提条件

• 可访问项目的依赖项文件（pyproject.toml、requirements.txt、 package.json、Cargo.toml、go.mod）
• 锁定文件（用于确定准确版本和传递依赖）
• 项目许可证（用于确定兼容性要求）

工作流

阶段 1：解析依赖树

1. 直接依赖 — 项目中明确声明的软件包。
2. 传递依赖 — 依赖项的依赖项。数量通常是直接依赖的 10–50 倍。
3. 版本约束 — 固定版本（==1.2.3）、范围（>=1.0,<2.0）或浮动版本（*）。
4. 开发与生产 — 将开发／测试依赖项与生产依赖项分开。

工具：

• Python：uv pip list、pip-audit、pipdeptree
• Node.js：npm list --all、npm audit
• Rust：cargo tree、cargo audit

阶段 2：审计许可证

针对每个依赖项：

1. 识别许可证 — 查看软件包元数据、LICENSE 文件、pyproject.toml。

2. 判断兼容性 — 与项目自身的许可证进行比对：

   许可证	可用于商业用途	Copyleft	风险级别
   MIT、BSD、ISC、Apache 2.0	是	否	低
   LGPL	谨慎使用	弱	中
   GPL-2.0、GPL-3.0	否（除非项目采用 GPL）	强	高
   AGPL	否（除非项目采用 AGPL）	强 + 网络	严重
   未知	无法确定	未知	严重

3. 标记问题 — 专有项目中的 Copyleft 许可证、未知许可证，以及不同版本之间的许可证变更。

阶段 3：评估维护健康度

针对每个依赖项，评估维护情况：

指标	健康	警告	已弃用
最近一次发布	< 6 个月	6–18 个月	> 18 个月
提交次数（90 天）	10+	1–9	0
对未解决问题的响应	< 2 周	2–8 周	> 8 周或无响应
公交因子	3+ 名维护者	2 名	1 名
CI 状态	通过	不稳定	失败或缺失

阶段 4：检查安全性

1. 已知 CVE — 对照公告数据库进行检查：

   • Python：pip-audit、PyPI 公告数据库
   • Node.js：npm audit、GitHub Advisory Database
   • 通用：NVD（国家漏洞数据库）

2. 严重程度分类 — CVSS 分数解读：

   CVSS 分数	严重程度	操作
   9.0-10.0	严重	立即升级
   7.0-8.9	高	在几天内升级
   4.0-6.9	中	在几周内升级
   0.1-3.9	低	方便时升级

3. 修复方案可用性 — 是否有已修复的版本？如果没有，有什么临时解决方法？

阶段 5：检测臃肿

1. 未使用的依赖项 — 在代码库中没有被导入的依赖项。
2. 功能重复 — 多个包实现相同功能（2 个 HTTP 客户端、2 个 JSON 解析器）。
3. 庞大的传递依赖树 — 为简单功能引入数十个子依赖项的包。
4. 体积分析 — 用于实现简单功能的大型包。

阶段 6：报告

生成一份包含待办事项且按优先级排序的报告。

输出格式

## Dependency Audit: {Project Name}

### Summary
| Metric | Count |
|--------|-------|
| Direct dependencies | {N} |
| Transitive dependencies | {N} |
| License issues | {N} |
| Maintenance concerns | {N} |
| Security vulnerabilities | {N} |
| Bloat candidates | {N} |

### License Compliance

| Package | Version | License | Compatible | Issue |
|---------|---------|---------|------------|-------|
| {pkg} | {ver} | MIT | Yes | None |
| {pkg} | {ver} | GPL-3.0 | No | Copyleft in proprietary project |
| {pkg} | {ver} | Unknown | Unknown | License not identifiable |

### Maintenance Health

| Package | Last Release | Commits (90d) | Maintainers | Status |
|---------|-------------|---------------|-------------|--------|
| {pkg} | {date} | {N} | {N} | {Healthy/Warning/Abandoned} |

### Security Vulnerabilities

| Package | Version | CVE | Severity | Fix Available | Fixed In |
|---------|---------|-----|----------|---------------|----------|
| {pkg} | {ver} | {CVE-ID} | {severity} | {Yes/No} | {version} |

### Bloat Analysis

| Package | Install Size | Used By | Recommendation |
|---------|-------------|---------|----------------|
| {pkg} | {size} | {usage description} | {Remove/Replace/Keep} |

### Action Items

#### Immediate (Security)
1. Upgrade {pkg} to {version} — fixes {CVE-ID} ({severity})

#### Short-term (License)
1. Review {pkg} GPL usage — may require license change or removal

#### Medium-term (Maintenance)
1. Find alternative to {pkg} — abandoned since {date}

#### Long-term (Bloat)
1. Remove {pkg} — unused in codebase
2. Replace {pkg} with lighter alternative

### Transitive Risk
- {direct-dep} depends on {transitive-dep} which has {issue}

校准规则

1. 优先检查生产依赖项。 开发／测试依赖项的风险较低，因为它们不会随产品发布给用户。应以更严格的标准审计生产依赖项。
2. 传递依赖风险确实存在。 一个采用 MIT 许可证的直接依赖项，可能会引入采用 GPL 许可证的传递依赖项。务必检查完整的依赖树。
3. 停止维护不等于无法使用。 一款成熟、稳定的库即使一年未更新，也可能完全没有问题。应评估该库是“已完成”还是“被忽视”。
4. 安全问题不容妥协。 必须立即处理严重和高危 CVE。应跟踪中危 CVE。低危 CVE 可等到下一轮依赖项更新时处理。

错误处理

问题	解决方案
没有可用的锁定文件	根据声明的依赖项进行审计。请注意，没有锁定文件时，传递依赖分析并不完整。
缺少许可证元数据	检查软件包的仓库中是否有 LICENSE 文件。注明无法确定许可证的软件包。
软件包注册表不可用	使用缓存的元数据和本地锁定文件数据。
依赖项过多，无法手动审计	优先级排序：先检查生产依赖项，再检查直接依赖项，最后检查存在已知问题的传递依赖项。

何时不应审计

以下情况应提出异议：

• 项目只是不会发布的原型——待确定是否投入生产后再审计
• 用户需要的是更新依赖项，而不是审计——这是另一项任务（dependabot、renovate）
• 项目没有依赖项（仅使用标准库）——没有需要审计的内容

似是而非的理由

似是而非的理由	实际情况
“这是一个值得信赖的软件包”	信任并非安全模型——值得信赖的软件包也会遭到入侵（event-stream、ua-parser-js、colors.js）
“只是升级了一个次要版本”	次要版本也可能引入漏洞、更改行为或增加传递依赖项——语义化版本是一种承诺，而非保证
“我们没有使用存在漏洞的函数”	传递依赖项可能会使用——攻击面包括加载到进程中的任何代码
“这个 CVE 严重程度较低”	单独看严重程度较低的问题，在你的使用情境中可能很严重——例如，内部服务中一个“低危”的 SSRF 漏洞若能访问云元数据，就可能造成严重影响
“等出现已知漏洞利用再更新”	出现已知漏洞利用意味着你已经落后——应在 SLA 规定的时限内修补，而不是等到遭到入侵后
“依赖项太多，无法审计”	这本身就是问题，而不是借口——依赖项数量过多本身就是一项风险发现

风险信号

• 只审计直接依赖，忽略传递依赖树
• 未检查漏洞代码路径是否可达，就排除 CVE
• 未检查许可证兼容性——专有代码库中使用 GPL 属于法律问题
• 未进行交叉核对，就接受单个扫描器给出的“未发现已知漏洞”结论
• 忽略依赖的年限——2 年以上没有更新的包存在风险
• 跳过锁文件分析（固定版本与浮动版本）

验证

• 已扫描直接依赖和传递依赖
• 已保存漏洞扫描器输出：npm audit / pip-audit / cargo audit
• 每项 CVE 发现均包含：严重性、受影响的版本范围、升级路径、可达性评估
• 已根据项目许可证验证许可证兼容性
• 已检查顶层依赖的年限和维护状态
• 存在锁文件且已验证版本固定情况——生产环境中没有浮动范围