package-audit（包审核）

Package Audit Skill

This skill helps you scan for and fix security vulnerabilities in npm dependencies.

When to Use This Skill

• Scanning for security vulnerabilities
• Before production deployments
• Resolving CVE alerts
• Regular security audits
• Dependency health checks
• Compliance requirements
• Pre-commit security checks

Security Audit Tools

pnpm audit

Built-in vulnerability scanner:

# Run audit
pnpm audit

# Output example:
# ┌───────────────┬──────────────────────────────────────────────────────────────┐
# │ moderate      │ Prototype Pollution in lodash                                │
# ├───────────────┼──────────────────────────────────────────────────────────────┤
# │ Package       │ lodash                                                       │
# ├───────────────┼──────────────────────────────────────────────────────────────┤
# │ Vulnerable    │ <4.17.21                                                     │
# ├───────────────┼──────────────────────────────────────────────────────────────┤
# │ Patched in    │ >=4.17.21                                                    │
# ├───────────────┼──────────────────────────────────────────────────────────────┤
# │ Path          │ lodash                                                       │
# └───────────────┴──────────────────────────────────────────────────────────────┘

Snyk

Advanced vulnerability scanning:

# Install Snyk CLI
pnpm add -g snyk

# Authenticate
snyk auth

# Test for vulnerabilities
snyk test

# Monitor project
snyk monitor

# Fix vulnerabilities
snyk fix

Running Audits

Basic Audit

# Audit all packages
pnpm audit

# Audit specific workspace
pnpm -F @sgcarstrends/api audit

# Audit production dependencies only
pnpm audit --prod

# Get JSON output
pnpm audit --json > audit-report.json

Severity Levels

# Only show high/critical
pnpm audit --audit-level=high

# Audit levels:
# - info
# - low
# - moderate
# - high
# - critical

Automated Fix

# Automatically fix vulnerabilities
pnpm audit --fix

# Dry run (preview fixes)
pnpm audit --fix --dry-run

Understanding Audit Results

Vulnerability Report

┌───────────────┬──────────────────────────────────────────────────────────────┐
│ High          │ Regular Expression Denial of Service                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ semver                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Vulnerable    │ <5.7.2 || >=6.0.0 <6.3.1 || >=7.0.0 <7.5.2                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=5.7.2 <6.0.0 || >=6.3.1 <7.0.0 || >=7.5.2                 │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://github.com/advisories/GHSA-c2qf-rxjj-qqgw           │
└───────────────┴──────────────────────────────────────────────────────────────┘

Key Information:

• Severity: critical, high, moderate, low, info
• Package: Affected package name
• Vulnerable: Vulnerable version range
• Patched in: Fixed version range
• Path: Dependency path (direct or transitive)

JSON Report Analysis

# Generate JSON report
pnpm audit --json > audit.json

# Parse with jq
cat audit.json | jq '.vulnerabilities | length'
cat audit.json | jq '.vulnerabilities | group_by(.severity)'

# Filter critical vulnerabilities
cat audit.json | jq '.vulnerabilities[] | select(.severity == "critical")'

Fixing Vulnerabilities

Direct Dependencies

# Step 1: Identify vulnerable package
pnpm audit

# Step 2: Check available versions
pnpm view package-name versions

# Step 3: Update catalog
# pnpm-workspace.yaml
catalog:
  lodash: ^4.17.21  # Updated from ^4.17.19

# Step 4: Install
pnpm install

# Step 5: Verify fix
pnpm audit

Transitive Dependencies

# Step 1: Identify dependency chain
pnpm why vulnerable-package

# Output:
# parent-package 1.0.0
# └─┬ intermediate-package 2.0.0
#   └── vulnerable-package 3.0.0

# Step 2: Update parent package
catalog:
  parent-package: ^2.0.0  # Newer version with fixed dependency

# Step 3: Or use overrides (last resort)
{
  "pnpm": {
    "overrides": {
      "vulnerable-package": "^3.1.0"
    }
  }
}

Using Overrides

// package.json
{
  "pnpm": {
    "overrides": {
      // Fix specific vulnerability
      "lodash": "^4.17.21",

      // Fix across all dependencies
      "semver@<7.5.2": "^7.5.2",

      // Fix in specific dependency
      "some-package>vulnerable-dep": "^2.0.0"
    }
  }
}

Snyk Integration

Setup

# Install Snyk
pnpm add -g snyk

# Authenticate
snyk auth

# Test project
snyk test

# Monitor for new vulnerabilities
snyk monitor

Snyk Commands

# Test for vulnerabilities
snyk test

# Test with severity threshold
snyk test --severity-threshold=high

# Test specific file
snyk test --file=package.json

# Ignore specific vulnerabilities
snyk ignore --id=SNYK-JS-LODASH-1018905

# Generate HTML report
snyk test --json | snyk-to-html -o snyk-report.html

Snyk Configuration

# .snyk
version: v1.25.0
ignore:
  # Ignore low severity
  'SNYK-JS-LODASH-1018905':
    - '*':
        reason: Low severity, no fix available
        expires: 2024-12-31

  # Ignore specific path
  'SNYK-JS-AXIOS-1234567':
    - 'dev-dependency > axios':
        reason: Dev dependency only
        expires: never

CI Integration

GitHub Actions

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

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install
      - run: pnpm audit --audit-level=moderate

      # Fail on high/critical vulnerabilities
      - name: Check for high/critical vulnerabilities
        run: |
          AUDIT_OUTPUT=$(pnpm audit --json)
          HIGH=$(echo $AUDIT_OUTPUT | jq '.metadata.vulnerabilities.high // 0')
          CRITICAL=$(echo $AUDIT_OUTPUT | jq '.metadata.vulnerabilities.critical // 0')

          if [ $HIGH -gt 0 ] || [ $CRITICAL -gt 0 ]; then
            echo "High or critical vulnerabilities found!"
            exit 1
          fi

  snyk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: snyk/actions/setup@master
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install

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

      - name: Snyk monitor
        run: snyk monitor
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

Automated Dependency Updates

Dependabot

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10

    # Auto-merge security patches
    groups:
      security:
        patterns:
          - "*"
        update-types:
          - "patch"

    # Ignore major versions
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]

Renovate

// renovate.json
{
  "extends": ["config:base"],
  "vulnerabilityAlerts": {
    "enabled": true,
    "automerge": true
  },
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "matchCurrentVersion": "!/^0/",
      "automerge": true,
      "automergeType": "branch"
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    }
  ]
}

Best Practices

1. Regular Audits

# ❌ Only audit before deployment
pnpm audit  # Once every few months

# ✅ Regular schedule
# - Daily: Automated CI checks
# - Weekly: Manual review
# - Before deployment: Final check

2. Prioritize Fixes

# ❌ Try to fix everything at once
pnpm audit --fix

# ✅ Prioritize by severity
# 1. Critical: Fix immediately
# 2. High: Fix within 1 week
# 3. Moderate: Fix within 1 month
# 4. Low: Fix when convenient

3. Verify Fixes

# ❌ Just update and deploy
pnpm audit --fix
git push

# ✅ Test after fixing
pnpm audit --fix
pnpm test          # Run tests
pnpm build         # Build check
pnpm dev           # Manual testing
git commit && git push

4. Document Decisions

# .snyk
ignore:
  'SNYK-JS-LODASH-1018905':
    - '*':
        reason: >
          Low severity prototype pollution.
          Package only used in dev scripts.
          No fix available yet.
          Monitoring for updates.
        expires: 2024-12-31
        created: 2024-01-15

Handling Common Scenarios

No Fix Available

# Issue: Vulnerability with no fix

# Options:
# 1. Wait for fix (monitor regularly)
snyk monitor

# 2. Find alternative package
pnpm remove vulnerable-package
pnpm add alternative-package

# 3. Accept risk (document decision)
# Add to .snyk with expiration date

Breaking Changes in Fix

# Issue: Fix requires major version upgrade

# Solution:
# 1. Review breaking changes
pnpm view package-name changelog

# 2. Create migration branch
git checkout -b upgrade/package-name

# 3. Update and test
catalog:
  package-name: ^2.0.0  # Major version
pnpm install
pnpm test

# 4. Fix breaking changes
# 5. Commit and merge

False Positives

# Issue: Vulnerability doesn't affect your code

# Solution: Ignore with justification
# .snyk
ignore:
  'SNYK-ID':
    - 'package-name':
        reason: >
          False positive.
          Vulnerable code path not used in our application.
          Only affects feature X which we don't use.
        expires: never

Security Audit Checklist

• Run pnpm audit regularly
• Fix critical and high vulnerabilities immediately
• Monitor for new vulnerabilities (Snyk/Dependabot)
• Document ignored vulnerabilities
• Review security patches before applying
• Test thoroughly after fixes
• Keep audit logs for compliance
• Update security policy as needed

References

• pnpm Audit: https://pnpm.io/cli/audit
• Snyk: https://snyk.io
• npm Security Advisories: https://github.com/advisories
• OWASP Dependency Check: https://owasp.org/www-project-dependency-check
• Related files:

- .snyk - Snyk configuration - .github/dependabot.yml - Dependabot config - Root CLAUDE.md - Security guidelines

Best Practices Summary

1. Regular Audits: Run audits daily in CI, weekly manually
2. Prioritize Severity: Fix critical/high first, then moderate/low
3. Automate Security: Use Dependabot or Renovate
4. Test Fixes: Always test after applying security patches
5. Document Decisions: Explain ignored vulnerabilities
6. Monitor Continuously: Use Snyk monitor for ongoing tracking
7. Review Dependencies: Regularly review and remove unused packages
8. Stay Informed: Subscribe to security advisories for key packages