secure-dependency-health-check

安全依赖健康检查

通过评估安全健康状况、漏洞历史、流行度、社区活跃度和维护状态，帮助开发者和 AI Agent 在选择开源软件包时做出明智的决策。

核心原则：明智地选择依赖项，以尽量降低供应链风险。

---

快速开始

收到推荐软件包的请求时：

1. 确定功能需求
2. 调研候选软件包
3. 对每个候选软件包运行 snyk_package_health_check
4. 对比并推荐健康状况最佳、最安全的选项

---

阶段 1：了解需求

目标：在推荐软件包之前，明确用户的需求。

步骤 1.1：确定候选项

如果用户提供了候选项：

• 记录每个软件包的名称和版本（如果已指定）
• 确定软件包生态系统

如果用户需要建议：

• 搜索满足功能需求的软件包
• 根据流行度／相关性选出 2-4 个优选候选项

---

阶段 2：安全与健康状况分析

目标：评估每个候选软件包的安全状况和整体健康状况。

步骤 2.1：为每个候选项运行软件包健康检查

对每个候选软件包，使用软件包名称、版本和生态系统（npm、pypi、maven、nuget 或 golang）运行 snyk_package_health_check。返回的关键字段：

• overall_rating：「Healthy」或「Review recommended」——用作主要评估指标
• security：按严重程度（critical/high/medium/low）统计的漏洞数量及安全评级
• maintenance：生命周期状态、最新发布日期、is_archived 标志和维护评级（「Healthy」、「Sustainable」或「Inactive」）
• popularity：下载量、依赖该软件包的软件包／代码仓库数量及流行度评级
• community：关注者数量、社区文件是否存在及评级（「Active」或「Sustainable」）
• latest_version：最近发布的版本
• recommendation：对整体评估的易读摘要

步骤 2.2：查看工具结果

从工具响应中提取以下信息，以便进行比较：

• 整体评级（「Healthy」与「Review recommended」）
• 安全评级和按严重程度划分的漏洞明细
• 维护评级和生命周期状态（检查 is_archived、latest_release_published_at）
• 流行度和社区评级

步骤 2.3：淘汰条件

无论整体评级如何，遇到以下情况都应立即淘汰该软件包：

• 发现存在严重或高危漏洞的安全问题
• 维护评级为「Inactive」或软件包已归档（is_archived: true）
• 3 年或更久没有发布新版本（检查 latest_release_published_at）
• 已知的恶意软件包（供应链攻击）
• 存在拼写抢注迹象（名称与热门软件包相似）

---

阶段 3：生成推荐

目标：给出清晰、可执行的比较结果。

步骤 3.1：比较表

## Package Comparison: [Use Case]

| Criteria | Package A | Package B | Package C |
|----------|-----------|-----------|-----------|
| **Overall Rating** | Healthy | Review recommended | Healthy |
| **Security Rating** | Security issues found | Security issues found | No known security issues |
| **Critical CVEs** | 0 | 1 | 0 |
| **High CVEs** | 1 | 2 | 0 |
| **Maintenance** | Healthy | Inactive | Healthy |
| **Last Release** | 2 weeks ago | 8 months ago | 1 month ago |
| **Downloads** | 500K | 2M | 300K |
| **Popularity** | Influential project | Influential project | Influential project |

### Recommendation: **Package C**

**Reasons**:
1. "Healthy" overall rating with no known security issues
2. Healthy maintenance rating - actively maintained with recent release
3. Fewest vulnerabilities across all severity levels

**Trade-offs**:
- Fewer downloads than Package B (less battle-tested)
- Consider if specific features of Package A/B are required

**Recommended version**: Use the `latest_version` from the tool response to pin an exact version.

步骤 3.2：替代方案情境

如果没有软件包达到安全门槛：

## Warning: No Secure Option Available

All evaluated packages have significant security concerns:
- Package A: 2 Critical CVEs (actively exploited)
- Package B: Abandoned - no updates in 3 years
- Package C: Multiple high-severity vulnerabilities with no fix available

### Alternatives:
1. **Implement in-house**: For simple functionality
2. **Fork and fix**: If one package is close but has fixable issues
3. **Wait**: If updates are expected soon
4. **Accept risk**: With documented justification and monitoring

---

阶段 4：集成指南

目标：帮助用户安全地添加推荐的软件包。

步骤 4.1：安装后扫描

建议在安装后运行 snyk_sca_scan，以确认完整依赖树不会引入意外漏洞。

步骤 4.2：监控建议

建议提交锁定文件、启用漏洞通知，并定期检查安全更新。

---

错误处理

找不到软件包

• 确认软件包名称和生态系统
• 检查是否有拼写错误
• 搜索其他名称

扫描失败或数据不足

• 对于某些软件包，工具可能会返回「Snyk 没有关于此软件包的足够信息」
• 重试一次；如果仍然没有数据，则改为手动调研
• 报告部分结果，并注明工具无法评估此软件包

没有候选项达到门槛

• 说明每个候选项未达标的原因
• 建议替代方案（内部开发、派生项目、等待）
• 记录用户仍决定继续使用时的风险

---

约束

1. 绝不推荐存在已知漏洞的包
2. 推荐时始终注明确切版本
3. 如果无法完成全面分析，请说明限制
4. 如果用户提供了新的约束，请更新建议