Audit Dependencies

Purpose

Scan npm dependencies for known security vulnerabilities and identify outdated packages that need updates.

When to Use

• Security audits before deployment
• Conductor Phase 6 (Final Report)
• Regular maintenance checks
• Before major releases
• As part of security validation workflows

Supported Package Managers

• npm: npm audit + npm outdated
• yarn: yarn audit (detects automatically)
• pnpm: pnpm audit (detects automatically)

Instructions

Step 1: Run Security Audit

echo "→ Running security audit..."

# Run npm audit with JSON output
if npm audit --json > .claude/validation/audit-output.json 2>&1; then
  AUDIT_STATUS="clean"
  echo "✅ No vulnerabilities found"
else
  AUDIT_STATUS="vulnerabilities"
  echo "⚠️  Vulnerabilities detected"
fi

Step 2: Parse Vulnerability Counts

# Extract vulnerability counts by severity
if [ -f .claude/validation/audit-output.json ]; then
  CRITICAL=$(jq '.metadata.vulnerabilities.critical // 0' .claude/validation/audit-output.json)
  HIGH=$(jq '.metadata.vulnerabilities.high // 0' .claude/validation/audit-output.json)
  MODERATE=$(jq '.metadata.vulnerabilities.moderate // 0' .claude/validation/audit-output.json)
  LOW=$(jq '.metadata.vulnerabilities.low // 0' .claude/validation/audit-output.json)
  TOTAL=$(jq '.metadata.vulnerabilities.total // 0' .claude/validation/audit-output.json)

  echo "Vulnerability Summary:"
  echo "  Critical: $CRITICAL"
  echo "  High: $HIGH"
  echo "  Moderate: $MODERATE"
  echo "  Low: $LOW"
  echo "  Total: $TOTAL"
fi

Step 3: Extract Affected Packages

# Get list of vulnerable packages
if [ "$TOTAL" -gt 0 ]; then
  AFFECTED_PACKAGES=$(jq -r '.vulnerabilities | to_entries | map({
    name: .key,
    severity: .value.severity,
    via: (.value.via | if type == "array" then .[0].title else . end)
  }) | sort_by(.severity) | reverse' .claude/validation/audit-output.json)

  # Get top 10 most critical
  TOP_VULNS=$(echo "$AFFECTED_PACKAGES" | jq -c '.[:10]')
else
  AFFECTED_PACKAGES="[]"
  TOP_VULNS="[]"
fi

Step 4: Check for Outdated Packages

echo ""
echo "→ Checking for outdated packages..."

# Run npm outdated
if npm outdated --json > .claude/validation/outdated-output.json 2>&1; then
  OUTDATED_STATUS="all-current"
  OUTDATED_COUNT=0
else
  # Parse outdated packages
  OUTDATED_COUNT=$(jq 'length' .claude/validation/outdated-output.json 2>/dev/null || echo "0")
  OUTDATED_STATUS="updates-available"

  echo "   $OUTDATED_COUNT packages have updates available"
fi

# Get packages with major version updates
MAJOR_UPDATES=$(jq -r 'to_entries | map(select(
  (.value.wanted != .value.latest) and
  ((.value.latest | split(".")[0] | tonumber?) > (.value.current | split(".")[0] | tonumber?))
)) | length' .claude/validation/outdated-output.json 2>/dev/null || echo "0")

echo "   $MAJOR_UPDATES packages have major version updates"

Step 5: Determine Can Proceed

# Critical/High vulnerabilities block by default
if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
  CAN_PROCEED="false"
  STATUS="error"
  DETAILS="$CRITICAL critical and $HIGH high severity vulnerabilities must be addressed"
elif [ "$MODERATE" -gt 0 ] || [ "$LOW" -gt 0 ]; then
  CAN_PROCEED="true"
  STATUS="warning"
  DETAILS="$MODERATE moderate and $LOW low severity vulnerabilities - review recommended"
else
  CAN_PROCEED="true"
  STATUS="success"
  DETAILS="No security vulnerabilities found"
fi

Step 6: Return Structured Output

{
  "status": "$STATUS",
  "audit": {
    "status": "$AUDIT_STATUS",
    "vulnerabilities": {
      "critical": $CRITICAL,
      "high": $HIGH,
      "moderate": $MODERATE,
      "low": $LOW,
      "total": $TOTAL
    },
    "affectedPackages": $TOP_VULNS
  },
  "outdated": {
    "status": "$OUTDATED_STATUS",
    "count": $OUTDATED_COUNT,
    "majorUpdates": $MAJOR_UPDATES
  },
  "canProceed": $CAN_PROCEED,
  "details": "$DETAILS"
}

Output Format

No Vulnerabilities

{
  "status": "success",
  "audit": {
    "status": "clean",
    "vulnerabilities": {
      "critical": 0,
      "high": 0,
      "moderate": 0,
      "low": 0,
      "total": 0
    },
    "affectedPackages": []
  },
  "outdated": {
    "status": "all-current",
    "count": 0,
    "majorUpdates": 0
  },
  "canProceed": true,
  "details": "No security vulnerabilities found"
}

Critical Vulnerabilities Found

{
  "status": "error",
  "audit": {
    "status": "vulnerabilities",
    "vulnerabilities": {
      "critical": 2,
      "high": 5,
      "moderate": 8,
      "low": 3,
      "total": 18
    },
    "affectedPackages": [
      {
        "name": "axios",
        "severity": "critical",
        "via": "Server-Side Request Forgery in axios"
      },
      {
        "name": "lodash",
        "severity": "high",
        "via": "Prototype Pollution in lodash"
      }
    ]
  },
  "outdated": {
    "status": "updates-available",
    "count": 12,
    "majorUpdates": 3
  },
  "canProceed": false,
  "details": "2 critical and 5 high severity vulnerabilities must be addressed"
}

Integration with Conductor

Used in conductor Phase 6 (Final Report):

### Final Security Check

Use `audit-dependencies` skill:

Expected result:
- No critical/high vulnerabilities
- Moderate/low acceptable (document)

If critical/high found:
  ⚠️  WARNING - Security issues detected
  → Document in PR description
  → Create security follow-up issue
  → May block merge (policy-dependent)

If clean or low-severity only:
  ✅ Security check passed

Severity Levels

Critical

• Immediate action required
• Known exploits in the wild
• Direct security impact

Action: Update immediately or find alternative

High

• Serious security concern
• Potential for exploitation
• Should be addressed soon

Action: Schedule update within days

Moderate

• Security concern
• Limited exploitation potential
• Should be addressed

Action: Schedule update within weeks

Low

• Minor security issue
• Low exploitation risk
• Address when convenient

Action: Include in next maintenance cycle

Fixing Vulnerabilities

Auto-Fix (Safe)

# Let npm attempt auto-fix
npm audit fix

# For breaking changes
npm audit fix --force  # Use with caution!

Manual Update

# Update specific package
npm update package-name

# Check what would change
npm outdated

# Update all (review changes)
npm update

Related Skills

• security-pentest - Uses this for security validation
• audit - Comprehensive project audit including dependencies

Error Handling

npm Not Available

{
  "status": "error",
  "error": "npm not available",
  "suggestion": "Ensure npm is installed and package.json exists"
}

Network Errors

# Audit requires network access to vulnerability database
if grep -q 'ENOTFOUND\|ETIMEDOUT' .claude/validation/audit-output.json; then
  echo "⚠️  Network error - cannot reach npm registry"
fi

Best Practices

1. Run regularly - Weekly or before each release
2. Review all findings - Don't auto-fix without review
3. Check breaking changes - Major updates may break code
4. Document exceptions - If vulnerability can't be fixed immediately
5. Track trends - Monitor vulnerability counts over time

Notes

• Critical/High vulnerabilities block by default (configurable)
• Moderate/Low generate warnings but don't block
• Outdated packages don't block (informational)
• Output saved to .claude/validation/audit-output.json
• Requires internet connection to npm registry