claude-code-community-ireland/dependency-audit

Dependency Audit

Evaluating New Dependencies

Before adding any dependency, run through this evaluation checklist. Every "no" answer is a risk that must be explicitly accepted.

Evaluation Checklist

• [ ] Maintenance: Last commit within 6 months? Issues responded to? More than one maintainer?
• [ ] Adoption: More than 1,000 weekly downloads (npm) or equivalent? Used by known projects?
• [ ] Bundle size: Checked via bundlephobia.com or equivalent? Is tree-shaking supported?
• [ ] License: Compatible with your project license? (See license matrix below)
• [ ] Security: No open CVEs? Has a security policy? Publishes signed releases?
• [ ] API surface: Does it do one thing well, or is it a kitchen-sink package?
• [ ] Alternatives: Have you checked if the standard library or an existing dep covers this?
• [ ] Transitive deps: How many transitive dependencies does it pull in?

Quick Evaluation Commands

# npm — check package info
npm info <package> --json | jq '{name, version, license, homepage, maintainers}'

# Check download stats
npm info <package> --json | jq '.downloads'

# Bundle size (requires bundlephobia API or website)
# Visit: https://bundlephobia.com/package/<package>

# Check for known vulnerabilities before installing
npm audit --dry-run --package-lock-only

# Python — check package metadata
pip show <package>
pip index versions <package>

# Rust — check crate info
cargo info <crate>

Decision Framework

| Factor | Accept | Investigate | Reject | |----------------------|------------------------------|--------------------------------|-------------------------------| | Weekly downloads | > 50,000 | 1,000 - 50,000 | < 1,000 | | Last commit | < 3 months | 3 - 12 months | > 12 months | | Open issues | < 50 with triage | 50 - 200 | > 200 untriaged | | Maintainers | >= 2 | 1 active | 0 active | | Transitive deps | < 5 | 5 - 20 | > 20 | | Bundle size (JS) | < 10 KB gzipped | 10 - 50 KB | > 50 KB (for a single feature)| | License | MIT, Apache-2.0, BSD | ISC, MPL-2.0 | GPL, AGPL, SSPL, unlicensed |

---

Security Vulnerability Scanning

npm / Yarn

# Run audit against known vulnerability databases
npm audit

# Fix automatically where possible
npm audit fix

# Fix with major version bumps (review changes carefully)
npm audit fix --force

# Generate machine-readable report
npm audit --json > audit-report.json

# Yarn equivalent
yarn audit
yarn audit --json

pip (Python)

# Install safety or pip-audit
pip install pip-audit

# Run audit
pip-audit

# Output in JSON
pip-audit --format json --output audit-report.json

# Check a requirements file without installing
pip-audit -r requirements.txt

Cargo (Rust)

# Install cargo-audit
cargo install cargo-audit

# Run audit
cargo audit

# Fix where possible
cargo audit fix

# Generate JSON report
cargo audit --json

Go

# Built-in vulnerability scanning (Go 1.18+)
govulncheck ./...

CI Integration

Run audits on every pull request. Fail the build on critical or high severity findings.

# GitHub Actions example
- name: Security audit
  run: |
    npm audit --audit-level=high
    if [ $? -ne 0 ]; then
      echo "::error::Security vulnerabilities found"
      exit 1
    fi

---

Automated Dependency Updates

Dependabot Configuration

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
      timezone: "America/New_York"
    open-pull-requests-limit: 10
    reviewers:
      - "team-platform"
    labels:
      - "dependencies"
      - "automated"
    # Group minor and patch updates to reduce PR noise
    groups:
      production-deps:
        patterns:
          - "*"
        update-types:
          - "minor"
          - "patch"
      dev-deps:
        dependency-type: "development"
        update-types:
          - "minor"
          - "patch"
    # Ignore major version bumps for specific packages
    ignore:
      - dependency-name: "aws-sdk"
        update-types: ["version-update:semver-major"]

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"

Renovate Configuration

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    "group:monorepos",
    "group:recommended"
  ],
  "schedule": ["before 9am on monday"],
  "prConcurrentLimit": 10,
  "labels": ["dependencies", "automated"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "matchCurrentVersion": "!/^0/",
      "automerge": true,
      "automergeType": "pr",
      "platformAutomerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependencies", "breaking-change"],
      "automerge": false
    },
    {
      "matchPackagePatterns": ["eslint", "prettier", "@types/*"],
      "groupName": "linting and types",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    }
  ],
  "vulnerabilityAlerts": {
    "enabled": true,
    "labels": ["security"],
    "prPriority": 10
  }
}

Update Strategy

| Update Type | Strategy | Review Required | |-------------|------------------------------------------|-----------------| | Patch | Auto-merge if tests pass | No | | Minor | Auto-merge for stable deps (>= 1.0.0) | Spot-check | | Major | Manual review, check migration guide | Yes | | Security | Prioritize, merge within 24-48 hours | Yes |

---

Lock File Hygiene

Rules

1. Always commit lock files (package-lock.json, yarn.lock, Pipfile.lock, Cargo.lock, go.sum)
2. Never manually edit lock files — use the package manager commands
3. Review lock file diffs in PRs — large unexplained changes may indicate supply chain issues
4. Use exact versions in lock files — never delete and regenerate without reason
5. One lock file per project — do not mix npm and yarn in the same project

Resolving Lock File Conflicts

# npm — regenerate from package.json
rm package-lock.json
npm install

# Yarn — regenerate
rm yarn.lock
yarn install

# After resolving, verify nothing unexpected changed
git diff package-lock.json | head -100

Integrity Verification

# npm — verify installed packages match lock file
npm ci  # Clean install from lock file (CI environments)

# Yarn — same concept
yarn install --frozen-lockfile

# pip — verify hashes
pip install --require-hashes -r requirements.txt

---

License Compatibility Matrix

Common License Compatibility

| Dependency License | MIT Project | Apache-2.0 Project | GPL-3.0 Project | Proprietary Project | |--------------------|-------------|---------------------|------------------|---------------------| | MIT | OK | OK | OK | OK | | Apache-2.0 | OK | OK | OK (GPL-3+ only) | OK | | BSD-2/3-Clause | OK | OK | OK | OK | | ISC | OK | OK | OK | OK | | MPL-2.0 | OK | OK | OK | OK (file-level) | | LGPL-2.1/3.0 | OK | OK | OK | OK (dynamic linking)| | GPL-2.0 | NO | NO | OK (same version)| NO | | GPL-3.0 | NO | NO | OK | NO | | AGPL-3.0 | NO | NO | NO (unless AGPL) | NO | | SSPL | NO | NO | NO | NO | | Unlicensed | NO | NO | NO | NO |

License Scanning

# npm — check all dependency licenses
npx license-checker --summary
npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0"
npx license-checker --production --csv > licenses.csv

# Python
pip install pip-licenses
pip-licenses --format=table
pip-licenses --fail-on="GPL-3.0;AGPL-3.0"

# Rust
cargo install cargo-license
cargo license

License Policy

• Maintain an approved license allow-list in CI
• Flag any new dependency with an unapproved license as a blocking issue
• "Unlicensed" means "all rights reserved" — never use unlicensed code
• When in doubt, consult legal before merging

---

Vendoring vs Package Management

When to Vendor

• The dependency is abandoned but you need it
• You need to patch a critical bug upstream has not fixed
• You are building for an air-gapped environment
• The dependency is very small (< 100 lines) and unlikely to change

When NOT to Vendor

• The dependency is actively maintained
• Security patches are regularly published
• The dependency has its own complex dependency tree
• You would be taking on maintenance burden you cannot sustain

Vendoring Procedure

1. Copy the source into a vendor/ or third_party/ directory
2. Record the original source, version, and license in a VENDORED.md file
3. Apply your patches as separate, clearly commented commits
4. Set a calendar reminder to check for upstream updates quarterly

---

Monorepo Dependency Management

Hoisting Strategy

# npm workspaces — hoist shared deps to root
npm install <package> -w packages/shared

# Yarn workspaces — nohoist for packages that need isolation
# package.json
{
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": ["**/react-native", "**/react-native/**"]
  }
}

Monorepo Rules

1. Shared dependencies go in the root package.json
2. Package-specific dependencies go in that package's package.json
3. Version consistency — all packages should use the same version of shared deps
4. Use a tool like syncpack or manypkg to enforce version consistency

# Check for version mismatches across packages
npx syncpack list-mismatches

# Fix version mismatches
npx syncpack fix-mismatches

---

Vulnerability Response Procedure

Severity Classification

| Severity | CVSS Score | Response Time | Example | |----------|-----------|---------------|--------------------------------------| | Critical | 9.0-10.0 | 4 hours | Remote code execution, auth bypass | | High | 7.0-8.9 | 24 hours | SQL injection, privilege escalation | | Medium | 4.0-6.9 | 1 week | XSS in admin panel, info disclosure | | Low | 0.1-3.9 | Next sprint | Minor info leak, DoS requiring auth |

Response Steps

1. Assess: Determine if your usage of the dependency triggers the vulnerability
2. Mitigate: Apply a workaround if a patch is not immediately available
3. Patch: Update to a fixed version as soon as one is available
4. Verify: Confirm the vulnerability is resolved with scanning tools
5. Document: Record the vulnerability, your response, and timeline in an incident log

Assessment Template

## Vulnerability Assessment: CVE-YYYY-XXXXX

**Package**: example-lib
**Installed Version**: 2.3.1
**Fixed Version**: 2.3.2
**Severity**: High (CVSS 8.1)

### Are We Affected?
[ ] We use the affected function/feature
[ ] The vulnerable code path is reachable in our application
[ ] External input reaches the vulnerable code

### Mitigation
- Describe workaround if patch is not yet available

### Action
- [ ] Update to fixed version
- [ ] Run tests
- [ ] Deploy to staging and verify
- [ ] Deploy to production
- [ ] Close vulnerability ticket

---

Dependency Hygiene Checklist (Periodic Review)

Run this checklist quarterly or when onboarding a new team member.

• [ ] Run npm audit / pip-audit / cargo audit — zero critical or high findings
• [ ] Remove unused dependencies (npx depcheck, pip-extra-reqs)
• [ ] Verify all lock files are committed and up to date
• [ ] Check for deprecated packages (npm outdated)
• [ ] Review license compliance report — no unapproved licenses
• [ ] Confirm Dependabot or Renovate is running and PRs are being merged
• [ ] Review vendored dependencies for upstream updates
• [ ] Verify CI fails on audit findings above your threshold
• [ ] Document any accepted risks with justification and expiration date