dependency-scanning

依赖扫描

此技能使 Agent 能够分析项目的直接和传递依赖，查找已知安全漏洞、过时软件包和许可证合规问题。Agent 会解析清单文件和锁定文件，查询漏洞数据库（NVD、GitHub Advisory、OSV），生成包含 CVE 标识符和修复建议的结构化报告，并可采用标准格式生成软件物料清单（SBOM）。

工作流

1. 检测软件包生态系统和清单文件 — 通过查找依赖清单（例如 package.json 和 package-lock.json（Node.js）、requirements.txt 和 Pipfile.lock（Python）、pom.xml 或 build.gradle（Java）、go.sum（Go）或 Gemfile.lock（Ruby））来确定项目使用的语言生态系统。检测包含多个清单文件的单体仓库结构。

2. 解析完整依赖树 — 解析锁定文件，构建包含传递依赖的完整依赖图。确定依赖深度、共享的子依赖和版本约束。标记代码中使用但未在清单中声明的虚假依赖。

3. 对照漏洞数据库扫描 — 查询 National Vulnerability Database（NVD）、GitHub Advisory Database 和 OSV，检查每个已解析软件包及其版本。通过 CPE 或 PURL 标识符匹配结果。记录 CVE ID、CVSS 分数、严重级别、受影响的版本范围，以及可用时的修复版本。

4. 评估许可证合规性 — 提取每项依赖的声明许可证，并与项目的许可证政策进行比较。标记专有项目中使用的著佐权许可证（GPL、AGPL），识别未声明许可证的软件包，并检测直接和传递依赖之间的许可证冲突。

5. 生成 SBOM 和漏洞报告 — 生成 CycloneDX 或 SPDX 格式的软件物料清单。按严重级别排序生成漏洞报告，其中包括 CVE 标识符、受影响的依赖路径、可用的修复版本，以及漏洞代码路径是否可达。

6. 建议并应用修复 — 建议解决漏洞所需的最低版本升级，避免引入破坏性变更。在可行的情况下，自动生成更新后的清单文件和锁定文件。标记无可用修复的情况，并建议替代软件包或变通方法。

支持的技术

• Node.js：npm audit、yarn audit、Snyk、Dependabot
• Python：pip-audit、Safety、Snyk、Dependabot
• Java：OWASP Dependency-Check、Snyk、Maven Enforcer Plugin
• Go：govulncheck、Nancy、Snyk
• 容器：Trivy、Grype（扫描镜像中的操作系统软件包和应用依赖）
• SBOM 格式：CycloneDX（JSON/XML）、SPDX（JSON/Tag-Value）
• CI/CD 集成：GitHub Actions、GitLab CI、Jenkins、CircleCI

用法

向 Agent 提供项目目录或特定清单文件的路径。也可以指定许可证政策或目标合规标准。Agent 将执行完整扫描并提供按优先级排列的漏洞报告。

提示词示例：

Scan the Node.js project in /app for dependency vulnerabilities. Generate a CycloneDX SBOM and flag any GPL-licensed transitive dependencies.

示例

示例 1：扫描 Node.js 项目

命令：

npm audit --json > audit-report.json

漏洞报告（摘录）：

#	严重级别	软件包	已安装版本	修复版本	CVE	依赖路径
1	严重	jsonwebtoken	8.5.1	9.0.0	CVE-2022-23529	直接依赖
2	高	minimatch	3.0.4	3.0.5	CVE-2022-3517	express > send > mime > minimatch
3	高	qs	6.5.2	6.5.3	CVE-2022-24999	express > qs
4	中	semver	5.7.1	5.7.2	CVE-2022-25883	nodemon > semver
5	低	cookie	0.4.1	0.4.2	CVE-2024-47764	express > cookie

在 package.json 中自动生成的修复：

{
  "dependencies": {
    "jsonwebtoken": "^9.0.0",
    "express": "^4.19.2"
  },
  "overrides": {
    "minimatch": "3.0.5",
    "semver": "5.7.2"
  }
}

示例 2：使用 pip-audit 扫描 Python 项目

命令：

pip-audit -r requirements.txt --format json --output audit.json --fix --dry-run

漏洞报告（摘录）：

#	严重程度	包	已安装版本	修复版本	CVE	描述
1	严重	cryptography	38.0.0	41.0.6	CVE-2023-49083	加载 PKCS7 证书时发生空指针解引用
2	高	requests	2.28.0	2.31.0	CVE-2023-32681	向重定向后的主机泄露 Proxy-Authorization 标头
3	高	Jinja2	3.1.1	3.1.3	CVE-2024-22195	通过 xmlattr 过滤器进行跨站脚本攻击
4	中	setuptools	65.0.0	70.0.0	CVE-2024-6345	通过下载函数远程执行代码

自动生成的 requirements.txt（已修复）：

cryptography==41.0.6    # was 38.0.0 — fixes CVE-2023-49083
requests==2.31.0        # was 2.28.0 — fixes CVE-2023-32681
Jinja2==3.1.3           # was 3.1.1 — fixes CVE-2024-22195
setuptools>=70.0.0      # was 65.0.0 — fixes CVE-2024-6345
Flask==3.0.0
gunicorn==21.2.0

最佳实践

• 每次 CI 构建都进行扫描 — 将依赖项扫描集成到 CI 流水线中，以便在代码合并前，而非部署后，发现新漏洞。
• 固定依赖项版本并使用锁定文件 — 使用锁定文件进行可复现构建，确保 CI 中扫描的确切版本与部署到生产环境的版本一致。
• 监控传递依赖项 — 典型项目中超过 80% 的漏洞来自传递依赖项。务必解析并扫描完整的依赖树，而不仅仅是直接依赖项。
• 自动创建更新 PR — 使用 Dependabot、Renovate 或 Snyk，在修复版本可用时自动创建拉取请求，缩短风险暴露时间。
• 维护许可证允许列表 — 定义获批的许可证列表（例如 MIT、Apache-2.0、BSD），并阻止引入不允许的许可证依赖项的构建。
• 为每个发行版本生成 SBOM — 将 CycloneDX 或 SPDX SBOM 与发行构件一同存储，以支持供应链透明度和事件响应。

安全边界

• 仅在用户拥有或明确授权评估的系统上操作，并在测试前记录获批范围。
• 从被动检查或只读检查开始。在主动扫描、漏洞利用、生成负载或进行可能造成干扰的修复之前，先取得明确批准。
• 切勿泄露机密、提取无关数据、削弱生产环境控制措施，或超出获批目标范围。
• 保存证据、尽量减少影响、在系统不稳定时停止，并为每项重大变更提供回滚或遏制步骤。

边缘情况

• 没有可用修复的漏洞 — 如果存在 CVE，但尚未发布修补版本，请评估应用程序是否会执行存在漏洞的代码路径。如果会，请考虑替换依赖项或应用本地补丁。
• 包含多种生态系统的单体仓库 — 单个代码仓库可能包含 Node.js、Python 和 Go 服务，并使用各自独立的清单文件。应分别扫描每种生态系统，并生成统一报告。
• 私有注册表和内部包 — 托管在私有 npm 注册表或内部 PyPI 服务器上的包不会出现在公开漏洞数据库中。请维护私有安全公告源，或使用支持自定义数据源的 Trivy 等工具扫描内部包。
• 由覆盖规则引发的版本冲突 — 通过 npm overrides 或 pip constraints 强制将传递依赖项升级到较新版本，可能导致运行时不兼容。应用自动修复后，务必运行测试套件。
• 已归档或不再维护的依赖项 — 某个包可能没有已知 CVE，但也没有活跃的维护者。请将不再维护的包视为供应链风险，并规划迁移到仍在积极维护的替代方案。