dependency-supply-chain-security

依赖项与供应链安全

依赖项风险

你的应用包含数百个 npm 包。每个包都是由他人编写、并以完整权限在你的应用中运行的代码。

统计数据令人警醒

根据 Sonatype 的《2024 年软件供应链现状报告》：

• 245,000 个恶意包发布到 npm（2023 年）
• 供应链攻击增加了 700%（与 2022 年相比）
• 应用平均有 200 多个依赖项
• 每个依赖项平均有 5 个传递依赖项（即依赖项的依赖项）

真实的供应链攻击事件

event-stream 事件（2018 年）： 一个广受欢迎的 npm 包（每周下载量达 200 万次）遭到劫持。攻击者添加了窃取加密货币钱包密钥的代码。在事件被发现前，数千个应用受到影响。

ua-parser-js 事件（2021 年）： 一个每周下载量达 800 万次的包遭到入侵。攻击者添加了加密货币挖矿和窃取密码的代码。

colors.js / faker.js 事件（2022 年）： 维护者为了抗议而故意破坏这些包，导致数百万个应用无法运行。这一事件凸显了单点故障风险。

我们的依赖项安全架构

当前状态

• ✅ 所有依赖项均为最新版本
• ✅ Next.js 15.5.4（最新稳定版）
• ✅ 0 个已知漏洞（npm audit）
• ✅ 已提交 Package-lock.json（确保构建可复现）

为什么特别使用 Next.js 15.5.4

我们从 15.3.5 升级到 15.5.4，以修复三个安全漏洞：

• 缓存键混淆（中危）
• 内容注入（中危）
• 通过 Middleware 重定向进行 SSRF 攻击（中危）

保持框架更新至关重要。 根据 Snyk 的研究，80% 的漏洞会在数天内有可用补丁，但平均修复时间为 148 天。

实现文件

• scripts/security-check.sh - 运行 npm audit，并显示过时的包
• package-lock.json - 锁定确切版本（确保供应链一致性）

运行安全审计

基本审计

# Check for vulnerabilities
npm audit

# Output shows:
# - Severity (critical, high, moderate, low)
# - Vulnerability description
# - Affected package
# - Recommended fix

仅审计生产依赖项

# Only check production dependencies (ignores devDependencies)
npm audit --production

每次生产部署前都要运行此检查。 结果必须显示：0 个漏洞

自动化安全检查脚本

# Run our comprehensive security check
bash scripts/security-check.sh

脚本执行的操作：

1. 运行 npm audit（显示漏洞）
2. 运行 npm outdated（显示过时的包）
3. 提供修复命令

预期输出：

=== Security Audit ===
found 0 vulnerabilities

=== Outdated Packages ===
Package    Current  Wanted  Latest  Location
next       15.5.4   15.5.4  15.5.4  node_modules/next

✓ All packages up to date!

修复漏洞

自动修复（安全）

# Fix vulnerabilities with patch/minor version updates
npm audit fix

执行的操作：

• 更新到最新补丁版本（例如，1.2.3 → 1.2.4）
• 更新到最新次要版本（例如，1.2.3 → 1.3.0）
• **安全：**不会带来破坏性变更

强制修复（有风险）

# Fix vulnerabilities with major version updates
npm audit fix --force

⚠️ **警告：**这可能会引入破坏性变更！

执行的操作：

• 更新到最新主要版本（例如，1.2.3 → 2.0.0）
• 如果 API 已更改，可能会导致代码无法运行

运行 --force 后：

1. 检查更改内容：git diff package.json package-lock.json
2. 阅读已更新包的迁移指南
3. 运行测试：npm test
4. 手动测试应用
5. 只有在一切正常时才提交

手动更新

# Update specific package
npm update package-name

# Update to specific version
npm install [email protected]

# Update all packages to latest (respecting semver)
npm update

依赖项更新策略

每月例行维护（30 分钟）

# 1. Check for outdated packages
npm outdated

# 2. Review what's outdated and why
# Check changelogs for major updates

# 3. Update safe packages (patch/minor)
npm update

# 4. Run audit
npm audit

# 5. Fix vulnerabilities
npm audit fix

# 6. Test everything
npm test
npm run build

# 7. Commit if successful
git add package.json package-lock.json
git commit -m "chore: update dependencies"

每次生产部署前

# Must show 0 vulnerabilities
npm audit --production

如果发现漏洞：

1. 运行 npm audit fix
2. 进行全面测试
3. 如果修复导致问题，调查是否有其他包可替代
4. 绝不要在存在已知漏洞的情况下部署

框架主要版本更新（每季度）

当 Next.js 发布主要版本更新时（例如，15.x → 16.x）：

# 1. Read upgrade guide
# https://nextjs.org/docs/upgrading

# 2. Create new branch
git checkout -b upgrade-nextjs-16

# 3. Update Next.js
npm install next@latest react@latest react-dom@latest

# 4. Follow migration guide
# Update deprecated APIs
# Test all features

# 5. Run full test suite
npm test
npm run build
npm run lint

# 6. Test locally
npm run dev
# Click through all features

# 7. Deploy to staging first
# Test in production-like environment

# 8. If successful, deploy to production

防范供应链攻击

1. Package-lock.json（始终提交）

# Package-lock.json ensures:
# - Exact versions installed
# - Reproducible builds
# - Detect tampering

✅ 务必将 package-lock.json 提交到 git

❌ 不要将 package-lock.json 添加到 .gitignore

2. 验证包完整性

# npm automatically verifies package integrity using
# checksums from package-lock.json

# If integrity check fails:
# Error: integrity checksum failed

这有助于防范：

• npm 注册表中的篡改包
• 下载过程中的中间人攻击
• 已损坏的包

3. 安装前审查新软件包

添加新软件包前：

1. 查看 npm 页面： https://www.npmjs.com/package/PACKAGE_NAME

   • 每周下载量（越热门，通常经过的审查越多）
   • 最近更新时间（是否在积极维护？）
   • 依赖它的软件包数量（是否广泛使用？）
   • GitHub 星标数和问题数

2. 检查是否存在仿冒包名：

   • react ✅（正确）
   • raect ❌（名称拼写错误的软件包，可能有恶意）
   • reacct ❌（名称拼写错误的软件包，可能有恶意）

3. 检查软件包维护者：

   • 查看是否有经过验证的维护者
   • 查看 GitHub 个人资料
   • 维护者越多越好

4. 查看 GitHub：

   • 星标数（受欢迎程度指标）
   • 未解决的问题（是否在维护？）
   • 最近的提交
   • 代码质量

5. 安装后运行审计：

   npm install new-package
   npm audit
   

4. 使用 npm ci 进行干净安装

# In CI/CD pipelines, use:
npm ci

# Instead of:
npm install

为什么使用 npm ci：

• 严格按照 package-lock.json 安装
• 如果 package.json 和 package-lock.json 不同步，则安装失败
• 安装前会移除 node_modules
• 用于 CI/CD 时速度更快、可靠性更高

5. 避免使用危险软件包

切勿安装符合以下条件的软件包：

• 下载量极低（每周少于 100 次）
• 刚刚发布（等待几周再安装）
• 名称可疑（仿冒包名）
• 请求不寻常的权限
• 没有可见的源代码

危险软件包示例（真实事件）：

• crossenv（cross-env 的拼写错误，曾有恶意行为）
• babelcli（babel-cli 的拼写错误，曾有恶意行为）
• mongose（mongoose 的拼写错误，曾有恶意行为）

依赖混淆攻击

这是什么

攻击者发布与您的内部软件包同名的恶意软件包。npm 可能会安装恶意软件包。

真实示例

# Internal package (not on npm)
"@mycompany/auth": "1.0.0"

# Attacker publishes to npm
"@mycompany/auth": "99.0.0"

# npm might install attacker's version!

预防

1. 为内部软件包使用带作用域的软件包：

   {
     "name": "@mycompany/internal-package"
   }
   

2. 配置 npm，仅对您的作用域使用内部注册表：

   # .npmrc
   @mycompany:registry=https://npm.mycompany.com
   

3. 不要将内部软件包发布到公共 npm

Scripts/security-check.sh

#!/bin/bash

echo "================================="
echo "Security & Dependency Check"
echo "================================="
echo ""

echo "=== Security Audit ==="
npm audit --production

echo ""
echo "=== Outdated Packages ==="
npm outdated

echo ""
echo "================================="
echo "To fix vulnerabilities:"
echo "  npm audit fix              (safe patch/minor updates)"
echo "  npm audit fix --force      (risky major updates)"
echo ""
echo "To update outdated packages:"
echo "  npm update                 (respects semver)"
echo "  npm update package-name    (specific package)"
echo "================================="

使用 Snyk 提升安全性

安装 Snyk

npm install -g snyk

# Authenticate
snyk auth

扫描漏洞

# Test project
snyk test

# Monitor project (continuous monitoring)
snyk monitor

# Test specific package before installing
snyk test package-name

添加到 CI/CD

# .github/workflows/security.yml
name: Security Audit

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    # Run daily at 2am
    - cron: '0 2 * * *'

jobs:
  security:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run npm audit
        run: npm audit --production

      - name: Check for outdated packages
        run: npm outdated || true

      - name: Run Snyk test
        run: npx snyk test --severity-threshold=high
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

监控新漏洞

GitHub Dependabot

在 GitHub 中启用：

1. 前往仓库设置
2. 选择“安全性与分析”
3. 启用“Dependabot alerts”
4. 启用“Dependabot security updates”

功能：

• 每天扫描依赖项
• 发现漏洞时创建 PR
• 自动更新到修复版本
• 由您审核并合并

CI/CD 中的 npm Audit

# Add to CI/CD pipeline
npm audit --production --audit-level=moderate

以下情况会导致构建失败：

• 发现任何中危或更高级别的漏洞
• 强制您在部署前修复漏洞

依赖安全可防范的问题

✅ 已知漏洞利用——定期审计可发现 CVE ✅ 恶意软件包注入——验证可防止篡改 ✅ 供应链攻击——package-lock.json + 验证 ✅ 依赖混淆——带作用域的软件包 + 注册表配置 ✅ 仿冒包名攻击——安装前手动验证 ✅ 过时的易受攻击代码——定期更新 ✅ 零日漏洞利用窗口——快速修补可降低风险

应避免的常见错误

❌ 不要忽略 npm audit 警告 ❌ 不要使用已弃用的软件包 ❌ 不要跳过依赖项更新后的测试 ❌ 不要将 package-lock.json 添加到 .gitignore ❌ 不要在检查前安装软件包 ❌ 不要在未经测试的情况下运行 npm audit fix --force

✅ 每次部署前都运行 npm audit ✅ 提交 package-lock.json ✅ 安装前验证新软件包 ✅ 每月更新依赖项 ✅ 启用 Dependabot 警报 ✅ 在 CI/CD 中使用 npm ci

命令速查

# Check for vulnerabilities
npm audit
npm audit --production

# Fix vulnerabilities
npm audit fix              # Safe
npm audit fix --force      # Risky, test thoroughly

# Check outdated packages
npm outdated

# Update packages
npm update                 # All packages
npm update package-name    # Specific package

# Install from lock file (CI/CD)
npm ci

# Run security check script
bash scripts/security-check.sh

# Test with Snyk
npx snyk test

参考资料

• npm Audit 文档：https://docs.npmjs.com/cli/v8/commands/npm-audit
• OWASP 依赖检查：https://owasp.org/www-project-dependency-check/
• Sonatype 供应链报告：https://www.sonatype.com/state-of-the-software-supply-chain
• Snyk：https://snyk.io/
• GitHub Dependabot：https://docs.github.com/en/code-security/dependabot

后续步骤

• 部署前检查：使用 security-testing 技能
• CI/CD 集成：将 npm audit 添加到流水线
• 监控：启用 GitHub Dependabot 警报
• 增强扫描：安装 Snyk