依赖安全审计

核心原则

• 默认只读。用户只要求“检查、审计、报告”时，不修改 manifest、lockfile、源码、CI 或外部服务。
• 以实际解析版本和可追溯 advisory 为证据。不要凭包名、版本年龄或记忆猜测 CVE、修复版本、可达性与许可证。
• 优先使用项目锁定的包管理器和已有审计命令。不要为完成审计而裸跑 npx，也不要擅自执行 pip install、go install、cargo install 等下载命令。
• 把“发现问题”“建议修复”“执行修改”分开。任何会改依赖或 lockfile 的动作都需要用户明确授权。
• 许可证部分只陈述事实、适用场景和待确认事项，不作法律结论。

工作流程

1. 确认范围与授权

• 确认目标目录、生态、工作区范围和生产 / 开发依赖是否都要检查。
• 说明将运行的命令、是否访问网络、可能向 registry 或漏洞服务发送哪些包元数据。
• 先检查工作树和现有改动。不要覆盖、回退或混入用户未提交的修改。
• 若缺少锁文件、工具或网络，继续完成可验证部分，并把覆盖缺口写入报告；不要用推测填空。

2. 建立依赖清单

• 查找 manifest 与 lockfile：package.json、package-lock.json、pnpm-lock.yaml、yarn.lock、requirements*.txt、Pipfile.lock、poetry.lock、uv.lock、go.mod、go.sum、Cargo.toml、Cargo.lock、pom.xml、Gradle 文件和 Gemfile.lock。
• 用 lockfile 或包管理器解析结果确定实际版本；manifest 中的范围不能证明最终安装版本。
• 从 packageManager、锁文件、wrapper、CI 和项目文档确认包管理器及版本。存在多个互相冲突的锁文件时，先报告歧义。
• 标记直接 / 传递依赖、生产 / 开发范围与 workspace 归属。无法确定时写“未知”。

3. 选择只读检查

只运行与项目实际生态匹配、当前环境已可用的命令：

生态	首选证据	只读命令示例
npm	package-lock.json、项目 npm 版本	npm audit --json、npm outdated --json
pnpm	pnpm-lock.yaml、项目 pnpm 版本	pnpm audit --json、pnpm outdated --format json
Yarn	yarn.lock、项目 Yarn 版本	使用该版本文档支持的只读 audit / outdated 命令
Python	当前虚拟环境、锁文件	已安装时运行 pip-audit --format json；版本盘点可用 python -m pip list --outdated --format=json
Go	go.mod / go.sum	已安装时运行 govulncheck -json ./...；go list -m -json all
Rust	Cargo.lock	已安装时运行 cargo audit --json；不要擅自安装子命令
JVM / Ruby	wrapper、lockfile、项目任务	优先运行仓库已有的审计任务；不要临时向构建文件注入插件

命令不存在时，记录“未执行”及原因，再单独提出可选安装方案，等待用户授权。不要把工具缺失写成“未发现漏洞”。

4. 核验漏洞证据

每个问题至少记录：

• advisory ID、来源链接和查询时间；
• 实际解析版本、受影响范围和已知修复版本；
• 直接 / 传递依赖与生产 / 开发范围；
• 严重度来源、CVSS 版本和分数（若来源提供）；
• 可达性证据。只有工具或代码路径分析能够证明时才写“可达”或“不可达”。

区分“依赖树中存在受影响版本”和“漏洞在当前程序中可被利用”。不同工具结果冲突时并列证据，不擅自选择更严重的结论。

5. 核验版本与许可证

• 版本健康度记录当前解析版本、最新稳定版、弃用声明、发布日期和升级跨度。不要仅因“超过两年未更新”自动判定有漏洞。
• 从包元数据、SPDX 标识、仓库 LICENSE 和许可证例外中核验事实；来源不一致时保留冲突。
• 不把 GPL、AGPL 或其他 copyleft 许可证统称为“传染性许可证”，也不固定映射成高 / 中 / 低风险。
• 结合分发方式、链接方式、SaaS 使用、修改情况、双重许可和 SPDX exception 列出待确认事项。需要法律判断时明确建议咨询合规或法律人员。

6. 输出中文报告

# 📋 依赖安全审计报告

**项目与范围**：{路径、workspace、生产/开发依赖}
**扫描时间**：{含时区}
**证据基线**：{manifest、lockfile、包管理器版本、提交 SHA}

## 执行覆盖

| 检查项 | 工具与版本 | 结果 | 覆盖缺口 |
|--------|------------|------|----------|

## 漏洞证据

| 严重度 | 包与解析版本 | Advisory / 来源 | 受影响范围 | 修复版本 | 范围 | 可达性 | 置信度 |
|--------|----------------|-----------------|------------|----------|------|--------|--------|

## 版本健康度

| 包与解析版本 | 最新稳定版 | 弃用 / 维护证据 | 升级跨度 | 建议 |
|----------------|------------|-----------------|----------|------|

## 许可证事实与待确认事项

| 包与版本 | SPDX / 许可证 | 证据来源 | 使用场景 | 待确认事项 |
|----------|----------------|----------|----------|------------|

## 建议与优先级

1. {立即缓解但不修改依赖的措施}
2. {建议升级及其依据}
3. {需要补充验证或合规确认的事项}

若没有发现问题，写“在本次工具与范围覆盖内未发现”，同时保留未扫描生态、缺失 lockfile、网络失败和不可达性未分析等限制。

7. 在明确授权后修复

• 确认允许修改的目录、包、版本范围、包管理器和目标分支；工作树不干净时先隔离或征求处理方式。
• 使用项目原生包管理器和精确版本执行最小升级。不要默认运行 npm audit fix、pip-audit --fix、--force 或批量大版本升级。
• 将直接依赖与传递依赖、补丁 / 次版本与大版本分批处理；先阅读 changelog、迁移指南和运行时要求。
• 每批修改后检查 manifest 与 lockfile diff，重新运行审计、项目测试、构建和 lint。外部服务或生产行为需要额外确认。
• 记录残余风险和回滚方式。只回退本次产生的修改，不覆盖用户原有改动。

安全边界

• 不输出或上传 Token、私有 registry 凭据、内部包源码和完整环境变量。
• 对私有依赖使用组织批准的 registry、代理和漏洞源；不把内部包名发送到未授权服务。
• 先给可验证的临时缓解措施，再给升级建议；不要因为严重度高就跳过环境、兼容性和回滚验证。