mathews-tom/dependency-audit

Dependency Audit

Comprehensive dependency risk assessment: license compatibility analysis, maintenance health scoring, CVE detection, bloat identification, and transitive dependency risk mapping. Produces an actionable report with prioritized remediation steps organized by urgency (security → license → maintenance → bloat).

Reference Files

| File | Contents | Load When | | ------------------------------------- | -------------------------------------------------------------------------- | ------------------------ | | references/license-compatibility.md | License compatibility matrix, copyleft detection, commercial-safe licenses | Always | | references/health-metrics.md | Maintenance health indicators, scoring criteria, abandonment detection | Always | | references/bloat-detection.md | Identifying unused deps, duplicate functionality, heavy transitive trees | Bloat analysis requested | | references/cve-sources.md | CVE databases, advisory sources, vulnerability severity interpretation | Security audit requested |

Prerequisites

• Access to the project's dependency files (pyproject.toml, requirements.txt, package.json, Cargo.toml, go.mod)
• Lock file (for exact versions and transitive dependencies)
• Project license (to determine compatibility requirements)

Workflow

Phase 1: Parse Dependency Tree

1. Direct dependencies — Packages explicitly declared in the project.
2. Transitive dependencies — Dependencies of dependencies. Often 10-50x the direct count.
3. Version constraints — Pinned (==1.2.3), ranged (>=1.0,<2.0), or floating (*).
4. Development vs production — Separate dev/test dependencies from production.

Tools:

• Python: uv pip list, pip-audit, pipdeptree
• Node.js: npm list --all, npm audit
• Rust: cargo tree, cargo audit

Phase 2: Audit Licenses

For each dependency:

1. Identify the license — Check package metadata, LICENSE file, pyproject.toml.

2. Classify compatibility — Against the project's own license:

   | License | Commercial OK | Copyleft | Risk Level | | ------------------------- | ------------------------ | ---------------- | ---------- | | MIT, BSD, ISC, Apache 2.0 | Yes | No | Low | | LGPL | With care | Weak | Medium | | GPL-2.0, GPL-3.0 | No (unless GPL project) | Strong | High | | AGPL | No (unless AGPL project) | Strong + network | Critical | | Unknown | Cannot determine | Unknown | Critical |

3. Flag issues — Copyleft licenses in proprietary projects, unknown licenses, license changes between versions.

Phase 3: Assess Maintenance Health

For each dependency, evaluate maintenance signals:

| Indicator | Healthy | Warning | Abandoned | | -------------------- | -------------- | ----------- | ------------------------ | | Last release | < 6 months | 6-18 months | > 18 months | | Commits (90 days) | 10+ | 1-9 | 0 | | Open issues response | < 2 weeks | 2-8 weeks | > 8 weeks or no response | | Bus factor | 3+ maintainers | 2 | 1 | | CI status | Passing | Flaky | Failing or absent |

Phase 4: Check Security

1. Known CVEs — Check against advisory databases:

   • Python: pip-audit, PyPI advisory database
   • Node.js: npm audit, GitHub Advisory Database
   • General: NVD (National Vulnerability Database)

2. Severity classification — CVSS score interpretation:

   | CVSS Score | Severity | Action | | ---------- | -------- | ---------------------- | | 9.0-10.0 | Critical | Upgrade immediately | | 7.0-8.9 | High | Upgrade within days | | 4.0-6.9 | Medium | Upgrade within weeks | | 0.1-3.9 | Low | Upgrade at convenience |

3. Fix availability — Is there a patched version? If not, what's the workaround?

Phase 5: Detect Bloat

1. Unused dependencies — Dependencies imported nowhere in the codebase.
2. Duplicate functionality — Multiple packages doing the same thing (2 HTTP clients, 2 JSON parsers).
3. Heavy transitive trees — Packages that pull in dozens of sub-dependencies for a simple feature.
4. Size analysis — Large packages used for small functionality.

Phase 6: Report

Produce a prioritized report with action items.

Output Format

## Dependency Audit: {Project Name}

### Summary
| Metric | Count |
|--------|-------|
| Direct dependencies | {N} |
| Transitive dependencies | {N} |
| License issues | {N} |
| Maintenance concerns | {N} |
| Security vulnerabilities | {N} |
| Bloat candidates | {N} |

### License Compliance

| Package | Version | License | Compatible | Issue |
|---------|---------|---------|------------|-------|
| {pkg} | {ver} | MIT | Yes | None |
| {pkg} | {ver} | GPL-3.0 | No | Copyleft in proprietary project |
| {pkg} | {ver} | Unknown | Unknown | License not identifiable |

### Maintenance Health

| Package | Last Release | Commits (90d) | Maintainers | Status |
|---------|-------------|---------------|-------------|--------|
| {pkg} | {date} | {N} | {N} | {Healthy/Warning/Abandoned} |

### Security Vulnerabilities

| Package | Version | CVE | Severity | Fix Available | Fixed In |
|---------|---------|-----|----------|---------------|----------|
| {pkg} | {ver} | {CVE-ID} | {severity} | {Yes/No} | {version} |

### Bloat Analysis

| Package | Install Size | Used By | Recommendation |
|---------|-------------|---------|----------------|
| {pkg} | {size} | {usage description} | {Remove/Replace/Keep} |

### Action Items

#### Immediate (Security)
1. Upgrade {pkg} to {version} — fixes {CVE-ID} ({severity})

#### Short-term (License)
1. Review {pkg} GPL usage — may require license change or removal

#### Medium-term (Maintenance)
1. Find alternative to {pkg} — abandoned since {date}

#### Long-term (Bloat)
1. Remove {pkg} — unused in codebase
2. Replace {pkg} with lighter alternative

### Transitive Risk
- {direct-dep} depends on {transitive-dep} which has {issue}

Calibration Rules

1. Production dependencies first. Dev/test dependencies have lower risk since they don't ship to users. Audit production dependencies with higher scrutiny.
2. Transitive risk is real. A direct dependency with MIT license may pull in a GPL transitive dependency. Always check the full tree.
3. Abandoned is not broken. A mature, stable library that hasn't been updated in a year may be perfectly fine. Evaluate based on whether the library is "done" vs "neglected."
4. Security is non-negotiable. Critical and High CVEs must be addressed immediately. Medium CVEs should be tracked. Low CVEs can wait for the next dependency update cycle.

Error Handling

| Problem | Resolution | | --------------------------------------- | ------------------------------------------------------------------------------------------------------ | | No lock file available | Audit based on declared dependencies. Note that transitive analysis is incomplete without a lock file. | | License metadata missing | Check the package's repository for LICENSE file. Note packages where license cannot be determined. | | Package registry unavailable | Work from cached metadata and local lockfile data. | | Too many dependencies to audit manually | Prioritize: production deps first, then direct deps, then transitive deps with known issues. |

When NOT to Audit

Push back if:

• The project is a prototype that won't ship — defer audit until production decision
• The user wants dependency updates, not audit — different task (dependabot, renovate)
• The project has no dependencies (pure standard library) — nothing to audit

Rationalizations

| Rationalization | Reality | |---|---| | "It's a trusted package" | Trust is not a security model — trusted packages get compromised (event-stream, ua-parser-js, colors.js) | | "Only a minor version bump" | Minor versions can introduce vulnerabilities, change behavior, or add transitive dependencies — semver is a promise, not a guarantee | | "We don't use the vulnerable function" | Transitive dependencies might — and attack surface includes any code loaded into the process | | "The CVE is low severity" | Low severity in isolation can be critical in your context — a "low" SSRF in an internal service with cloud metadata access is critical | | "We'll update when there's a known exploit" | Known exploits mean you're already behind — patch within SLA, not after breach | | "Too many dependencies to audit" | That's the problem, not an excuse — high dependency count IS a risk finding |

Red Flags

• Auditing only direct dependencies while ignoring transitive dependency tree
• Dismissing CVEs without checking if the vulnerable code path is reachable
• No license compatibility check — GPL in a proprietary codebase is a legal finding
• Accepting "no known vulnerabilities" from a single scanner without cross-referencing
• Ignoring dependency age — unmaintained packages with no updates in 2+ years are a risk
• Skipping lockfile analysis (pinned vs. floating versions)

Verification

• [ ] Both direct and transitive dependencies scanned
• [ ] Vulnerability scanner output captured: npm audit / pip-audit / cargo audit
• [ ] Each CVE finding includes: severity, affected version range, upgrade path, reachability assessment
• [ ] License compatibility verified against project license
• [ ] Dependency age and maintenance status checked for top-level deps
• [ ] Lockfile present and version pinning verified — no floating ranges in production