Audit Dependencies

Dependency Auditor

Audit project dependencies for security vulnerabilities and outdated packages, then apply safe updates.

When to Activate

• User wants to check for vulnerable or outdated packages
• Security audit requested
• Dependency maintenance needed
• Before a release or deployment
• User asks to update or fix dependency issues

Options

Quick Process

1. Detect: Identify package manager and manifest
2. Audit: Run security audit to find CVEs
3. Outdated: Check for newer versions available
4. Analyze: Prioritize findings by severity
5. Fix (if requested): Apply safe updates
6. Report: Summarize findings and actions taken

Step 1: Detect Package Manager

Check for lockfiles to identify the package manager:

# Check in order of specificity
ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

When yarn.lock is present, detect the Yarn version before choosing the audit command:

# Returns "1.x.x" for Classic, "2.x.x" or higher for Berry
yarn --version 2>/dev/null

• If the version starts with 1, use yarn audit --json (Classic).
• If the version is 2 or higher, use yarn npm audit --json (Berry).

If no lockfile found, check package.json and default to npm.

Step 2: Security Audit

Run the audit and capture JSON output:

# npm
npm audit --json 2>/dev/null

# yarn (classic)
yarn audit --json 2>/dev/null

# pnpm
pnpm audit --json 2>/dev/null

Parse vulnerabilities grouped by severity:

• critical — exploit available, immediate action required
• high — serious vulnerability, fix soon
• moderate — moderate risk, fix when possible
• low — minimal risk

Step 3: Check Outdated Packages

# npm
npm outdated --json 2>/dev/null

# yarn
yarn outdated --json 2>/dev/null

# pnpm
pnpm outdated --format json 2>/dev/null

For each outdated package, note:

• current: installed version
• wanted: latest version within the semver range in package.json
• latest: latest published version

Step 4: Analyze and Prioritize

Build a prioritized action list:

1. CVE packages — packages with known CVEs, sorted by severity
2. Outdated patch — packages behind on patches (e.g., 1.2.3 → 1.2.9)
3. Outdated minor — packages behind on minor versions (e.g., 1.2.x → 1.5.x)
4. Outdated major — packages behind on major versions (e.g., 1.x → 3.x) — flag for manual review

Step 5: Apply Updates (when --fix is requested)

Safe updates (patch only, unless --minor also specified):

# npm — fix only auto-fixable vulnerabilities (patch-safe)
npm audit fix 2>/dev/null

# npm — also update within semver range (only when --minor is set)
# WARNING: `npm update` installs the highest version satisfying the declared
# semver range, which can move caret ranges to newer minor releases.
# Only run this when --minor was explicitly requested.
npm update 2>/dev/null  # only if --minor flag is set

# For specific packages (use the `wanted` version for patch-only, `latest` only with --minor):
npm install <package>@<wanted-version> 2>/dev/null

When --minor is not set:

• Run npm audit fix only (which is restricted to patch-level fixes).
• Do not run npm update — it may apply minor version upgrades even within caret ranges.
• Pin specific installs to the wanted version (patch boundary), not latest.

When --minor is set:

• Run npm audit fix followed by npm update to also advance within semver ranges.
• Installing at latest is permitted for packages where a newer minor is available.

Never automatically update across major versions — flag these for manual review.

After applying updates, run audit again to confirm vulnerabilities are resolved.

Step 6: Report Summary

Output a structured report:

## Dependency Audit — <project-name>
**Package manager**: <npm|yarn|pnpm|bun>
**Packages scanned**: <N>

### Security Vulnerabilities
- 🔴 Critical: <N> (e.g., package-name@1.2.3 — CVE-XXXX-XXXX)
- 🟠 High: <N>
- 🟡 Moderate: <N>
- ⚪ Low: <N>

### Outdated Packages
- Patch updates available: <N> packages
- Minor updates available: <N> packages
- Major updates available: <N> packages (manual review required)

### Actions Taken
<list of updates applied if --fix was used, or "None — run with --fix to apply safe updates">

### Manual Review Required
<list of major version bumps or breaking changes that need human decision>

Examples

"Audit my dependencies"                          # full audit, report only
"Run npm audit and fix what's safe"              # audit + apply patches
"Check for vulnerable packages --fix --minor"   # audit + update to latest minor
"Dependency health check --scope security"      # only report CVEs
"Show me what would change --dry"               # audit + planned updates, no changes

Notes

• Always check CHANGELOG or release notes for major version bumps before updating
• Some npm audit findings are in dev dependencies — assess risk based on usage context
• If running in CI, pass --json output to exit code check (npm audit --audit-level=high)
• Yarn 2+ (berry) has a different audit command: yarn npm audit