AgentSkillsCN

dependency-audit

当您需要审查项目依赖关系、深入探究供应链安全、排查过时依赖包,或评估新增依赖项时,此技能将助您事半功倍。

SKILL.md
--- frontmatter
name: dependency-audit
description: "Use when reviewing project dependencies, investigating supply chain security, checking for outdated packages, or evaluating new dependencies to add."

Dependency Audit

Overview

Every dependency is code you didn't write, can't fully control, and must trust. The average npm project has 200+ transitive dependencies. Each one is a potential vulnerability, a potential breaking change, and a potential abandoned project.

Core principle: Every dependency is a liability until proven otherwise. Justify every one.

The Iron Law

code
NO NEW DEPENDENCY WITHOUT JUSTIFICATION. NO UNAUDITED DEPENDENCY IN PRODUCTION. NO DEPENDENCY WITHOUT AN EXIT STRATEGY.

When to Use

  • Adding a new dependency (always audit before adding)
  • Running periodic dependency health checks (quarterly minimum)
  • After security advisory notifications (CVE alerts)
  • Investigating unexplained behavior (could be dependency bug)
  • During any codebase audit
  • Before major version upgrades
  • When build/install times are growing

When NOT to Use

  • Choosing between two technologies (that's a design decision, not an audit)
  • Evaluating your own code quality (use code-review or architecture-audit)
  • If the project has zero external dependencies (rare but possible)

Anti-Shortcut Rules

code
YOU CANNOT:
- Say "dependencies look fine" — run the actual audit command and read the output
- Say "no vulnerabilities" — run npm audit / pip audit / equivalent AND check the output
- Say "package is maintained" — check last publish date, open issues count, contributor count
- Say "we need this dependency" — verify what fraction of it you use (one function from 500KB?)
- Skip transitive dependencies — they're the largest attack surface
- Say "license is fine" — verify the specific license against your project's license requirements
- Trust download counts alone — popular packages can be compromised too
- Say "we'll update later" — document WHEN and add it to the backlog with a deadline

Common Rationalizations (Don't Accept These)

RationalizationReality
"Everyone uses this package"Popularity ≠ security. Popular packages are bigger targets for supply chain attacks.
"It's only a dev dependency"Dev dependencies execute during build. A compromised build dependency compromises your artifact.
"We only use one function from it"Then implement that function yourself. Don't ship 500KB for one utility.
"It's been around forever""Around forever" often means "unmaintained." Check last commit date.
"The vulnerability doesn't affect us"Prove it with evidence. Most "doesn't affect us" claims are wishful thinking.
"We'll update when we have time"You won't have time until the CVE becomes an incident. Schedule it now.
"Pinning versions protects us"Pinning prevents auto-updates but also prevents auto-patches. You must actively manage pinned versions.

Iron Questions

code
1. If this dependency disappeared tomorrow, how hard would it be to replace?
2. What exactly do we use from this dependency? (list specific functions/features)
3. Could we implement this ourselves in less than 100 lines?
4. Who maintains this? Is it one person or an organization?
5. When was the last release? When was the last commit?
6. Does this dependency pull in heavy transitive dependencies?
7. Is the license compatible with our project?
8. What's our update strategy for this dependency? (auto / manual / pinned)
9. If this dependency has a breaking change, how much of our code changes?
10. Are there lighter alternatives that cover our specific use case?

The Audit Process

Phase 1: Inventory

code
1. LIST all direct dependencies and their versions
2. COUNT total dependencies (direct + transitive)
3. IDENTIFY outdated packages (how far behind latest?)
4. FLAG deprecated packages
5. IDENTIFY duplicate packages (same package, different versions)
6. CALCULATE total dependency weight (disk size, download size)

Detection:

bash
# Node.js
npm ls --all --depth=0          # Direct dependencies
npm ls --all | wc -l            # Total dependency count
npm outdated                     # Outdated packages
npx depcheck                     # Unused dependencies

# Python
pip list                         # All installed
pip list --outdated              # Outdated packages
pip show [package]               # Package details
pipdeptree                       # Dependency tree

# General
du -sh node_modules/             # Total size (Node)
find node_modules -name "package.json" | wc -l  # Package count (Node)

Phase 2: Security Scan

code
# Run the appropriate audit command
npm audit                           # Node.js
pip audit                           # Python (pip-audit)
bundle-audit check                  # Ruby
composer audit                      # PHP
cargo audit                         # Rust
dotnet list package --vulnerable    # .NET

For each vulnerability:

FieldRequired InfoImpact Assessment
PackageWhich dependency?Direct or transitive?
SeverityCritical / High / Medium / LowDoes it match your risk tolerance?
CVECVE identifierIs it verified?
Fix Available?Patched version exists?Can you upgrade without breaking changes?
ExploitabilityCan it be exploited in YOUR usage?Network-accessible? User-input-driven?
WorkaroundAlternative mitigation?Can you patch behavior without upgrading?

Vulnerability triage decision tree:

code
Is it Critical or High severity?
├── Yes → Is there a fix available?
│   ├── Yes → Upgrade immediately
│   └── No → Is it exploitable in your context?
│       ├── Yes → Find alternative dependency or implement workaround
│       └── No → Document risk, monitor for fix, set review date
└── No (Medium/Low) → Schedule for next dependency update cycle

Phase 3: Health Assessment (Per Major Dependency)

CriterionHealthy (🟢)Concerning (🟡)Dangerous (🔴)
Last published< 6 months ago6 months - 2 years> 2 years
Open issuesActively triagedGrowing backlogHundreds unaddressed
Contributors5+ active2-41 (bus factor = 1)
Downloads/weekStable or growingDecliningRapidly declining
LicenseMIT, Apache, BSDLGPLGPL (for proprietary), No license
Bundle sizeAppropriate for features usedLarger than neededMassive (> 500KB for one feature)
DependenciesFew (< 10 transitive)Moderate (10-50)Deep tree (> 100 transitive)
TypeScript supportBuilt-in types@types packageNo types
Security historyNo CVEsPast CVEs, all resolvedActive unresolved CVEs
Breaking change frequencySemantic versioning followedOccasional surprisesFrequent breakage

Phase 4: Necessity Check

For each dependency, justify its existence:

code
1. WHAT does it do that we actually use?
2. HOW MUCH of it do we use? (% of API surface)
3. COULD we implement this ourselves? (< 100 lines = do it yourself)
4. IS there a smaller alternative?
5. COULD a native platform API replace this? (fetch vs axios, Intl vs moment)
6. IS it a direct dependency or should it be a dev dependency?

Common unnecessary dependencies:

TypeExampleQuestionAlternative
Full utility liblodashUsing > 5 functions?Import individual functions or use native
Date librarymoment.js (deprecated!)Any date formatting?dayjs (2KB), date-fns, native Intl
CSS frameworkFull Bootstrap (300KB)Using > 10% of it?Tailwind (purged), custom CSS
HTTP clientaxiosJust making GET/POST?Native fetch API
Polyfillsbabel polyfillsTarget browsers need them?Check caniuse.com
Wrappersnode-fetchNode 18+ target?Native fetch (built-in)
UUID generationuuid packageSimple IDs?crypto.randomUUID() (native)

Phase 5: License Compliance

LicenseCommercial UseCopyleft?Risk LevelNotes
MITNo🟢 NoneMost permissive
Apache 2.0No🟢 LowPatent clause — gives patent rights
BSD (2/3-clause)No🟢 NoneSimple and permissive
ISCNo🟢 NoneSimplified MIT
GPL v2/v3⚠️Yes🔴 HighMust open-source YOUR code if distributed
LGPL✅ (if dynamically linked)Partial🟡 MediumComplex compliance rules
AGPL❌ (for SaaS)Yes🔴 CriticalNetwork use triggers copyleft
No LicenseUnknown🔴 CriticalCannot legally use — all rights reserved by default
Dual LicenseDependsVaries🟡 CheckRead both options carefully

Detection:

bash
# Node.js - List all licenses
npx license-checker --summary

# Check for problematic licenses
npx license-checker --failOn "GPL-3.0;AGPL-3.0"

Phase 6: Supply Chain Security

code
1. ARE lockfiles committed? (package-lock.json, yarn.lock, poetry.lock)
2. ARE dependency versions pinned? (exact versions, not ranges)
3. IS there a .npmrc or pip.conf restricting registries?
4. ARE pre/post install scripts reviewed? (npm scripts can execute arbitrary code)
5. IS there a policy for reviewing new dependencies before adding?
6. ARE you using a private registry or proxy? (Artifactory, Verdaccio)
7. IS two-factor authentication enabled on your npm/PyPI account?

Output Format

markdown
# Dependency Audit: [Project Name]

## Summary
- **Direct Dependencies:** N
- **Total (with transitive):** N
- **Outdated:** N (N critical behind)
- **Deprecated:** N
- **Known Vulnerabilities:** N (N Critical, N High)
- **Unused Dependencies:** N
- **Total node_modules Size:** XMB

## Vulnerabilities
| Package | Severity | CVE | Fix Available | Exploitable | Action |
|---------|----------|------|-------------|------------|--------|
| express | 🔴 Critical | CVE-2024-XXXX | ✅ v4.18.3 | Yes | Upgrade now |

## Health Assessment (Top 10 Dependencies)
| Package | Version | Last Published | Contributors | License | Assessment |
|---------|---------|---------------|-------------|---------|------------|
| react | 18.2.0 | 2 months ago | 100+ | MIT | 🟢 Healthy |

## Unnecessary Dependencies
| Package | Reason | Alternative | Savings |
|---------|--------|------------|---------|
| moment | Deprecated | dayjs | ~280KB |
| lodash | Only uses _.get | Optional chaining | ~60KB |

## License Compliance
| License | Count | Risk |
|---------|-------|------|
| MIT | 45 | 🟢 |
| Apache-2.0 | 12 | 🟢 |
| GPL-3.0 | 1 | 🔴 |

## Findings
[Standard severity format]

## Verdict: [PASS / CONDITIONAL PASS / FAIL]

Red Flags — STOP and Investigate

  • Dependencies with known critical CVEs (unpatched)
  • Packages with no license (legally unusable)
  • Dependencies last updated > 2 years ago in active use
  • Single-maintainer critical dependencies (bus factor = 1)
  • GPL dependencies in proprietary code
  • > 500 transitive dependencies (supply chain risk surface)
  • Deprecated packages still in use (moment.js, request, etc.)
  • No lockfile committed (non-deterministic builds)
  • Pre/post install scripts that download remote code
  • Duplicate packages at different versions

Integration

  • Part of: Full audit with architecture-audit
  • Complements: security-audit for vulnerability context
  • Triggers: incident-response if critical CVE found
  • Informs: ci-cd-audit for build pipeline security
  • Relates: performance-audit for bundle size impact