Dependency Audit

Read-only analysis patterns for dependency security, license compliance, and health assessment. This skill does NOT auto-upgrade packages -- it helps you understand your dependency landscape and make informed decisions.

Security-First Principles

npm audit fix --force

Security Audit Workflow

Step 1: Run the Audit

# npm (built-in)
npm audit

# npm -- JSON output for parsing
npm audit --json

# Yarn
yarn audit

# pnpm
pnpm audit

Step 2: Read the Report

# Example npm audit output
┌───────────────┬──────────────────────────────────────────────┐
│ Severity      │ high                                         │
├───────────────┼──────────────────────────────────────────────┤
│ Package       │ lodash                                       │
│ Dependency of │ my-library                                   │
│ Path          │ my-library > lodash                          │
│ More info     │ https://github.com/advisories/GHSA-xxxx-xxxx │
└───────────────┴──────────────────────────────────────────────┘

Step 3: Assess Each Vulnerability

Step 4: Determine Fix Strategy

# SAFE: See what non-breaking fixes are available
npm audit fix --dry-run

# SAFE: Apply only semver-compatible fixes
npm audit fix

# DANGEROUS: Never run without understanding consequences
# npm audit fix --force    <-- CAN INTRODUCE BREAKING CHANGES

# INVESTIGATE: When audit fix doesn't resolve
npm ls <vulnerable-package>          # See dependency tree
npm explain <vulnerable-package>     # See why it's installed

Step 5: Handle Unresolvable Vulnerabilities

When a vulnerability exists in a transitive dependency with no fix available:

# Check if the vulnerable code path is actually used
# Read the advisory -- is it relevant to your usage?

# Option A: Override the transitive dependency (npm)
# In package.json:
{
  "overrides": {
    "vulnerable-package": ">=fixed-version"
  }
}

# Option B: Override the transitive dependency (yarn)
# In package.json:
{
  "resolutions": {
    "vulnerable-package": ">=fixed-version"
  }
}

# Option C: Exclude from audit (document why)
# Create .nsprc or use npm audit --omit=dev for dev-only deps

Third-Party Scanning Tools

npm audit

Snyk CLI Usage

# Install
npm install -g snyk

# Authenticate
snyk auth

# Test for vulnerabilities (read-only)
snyk test

# Monitor project (sends to dashboard)
snyk monitor

# Test a specific package before installing
snyk test <package-name>

OSV-Scanner Usage

# Install
go install github.com/google/osv-scanner/cmd/osv-scanner@latest

# Scan lock file
osv-scanner --lockfile=package-lock.json

# Scan entire directory
osv-scanner -r .

License Compatibility

Common License Types

Compatibility Matrix (Can A Include B?)

Checking Licenses

# List all dependency licenses
npx license-checker --summary

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

# Export full report
npx license-checker --csv --out licenses.csv

# Production only (skip devDependencies)
npx license-checker --production --summary

CI License Check

# GitHub Actions step
- name: Check licenses
  run: |
    npx license-checker --production \
      --failOn "GPL-2.0;GPL-3.0;AGPL-3.0;SSPL-1.0" \
      --excludePackages "known-exception@1.0.0"

Dependency Health Indicators

Red Flags

npm view <pkg> time

scripts.postinstall

Health Check Commands

# View package metadata
npm view <package-name>

# Check when last published
npm view <package-name> time --json | jq 'to_entries | sort_by(.value) | last'

# See who maintains it
npm view <package-name> maintainers

# Check download counts (popularity signal)
npm view <package-name> --json | jq '.dist-tags, .versions | length'

# List all postinstall scripts in dependencies
npm ls --json | jq '.. | .scripts?.postinstall? // empty'

# Check package size before installing
npx package-phobia <package-name>

Before Adding a New Dependency

Ask these questions before

npm install

• Is this package actively maintained? (Commits in last 6 months)
• Does it have more than one maintainer?
• Are there open, unresolved security issues?
• Is the license compatible with my project?
• What is the install size and bundle size impact?
• Does it have post-install scripts? Are they necessary?
• Could I implement this functionality in <50 lines?
• Is this a direct dependency or could it be a devDependency?

Safe Upgrade Strategy

The Read-Analyze-Test-Upgrade Cycle

Never upgrade blindly. Follow this cycle for each upgrade.

Step 1: Identify Available Updates

# See what's outdated (read-only)
npm outdated

# More detail
npm outdated --long

# Output:
# Package    Current  Wanted  Latest  Location
# express    4.18.2   4.18.3  5.0.0   my-app
# lodash     4.17.20  4.17.21 4.17.21 my-app

Step 2: Categorize Updates

x.y.Z

4.18.2

4.18.3

x.Y.z

4.18.2

4.19.0

X.y.z

4.18.2

5.0.0

Step 3: Read Changelogs

# Check the changelog before upgrading
npm view <package-name> repository.url
# Then visit the repo and read CHANGELOG.md or Releases

Step 4: Upgrade in Isolation

# Upgrade one package at a time
npm install <package-name>@<version>

# Run tests immediately
npm test

# Check for type errors (TypeScript)
npx tsc --noEmit

# Check for lint issues
npm run lint

Step 5: Verify and Commit

# Verify the lock file changed as expected
git diff package-lock.json | head -50

# Commit the single upgrade
git add package.json package-lock.json
git commit -m "chore(deps): upgrade <package> to <version>"

Lock File Hygiene

Why Lock Files Matter

Lock File Rules

npm ci

npm install

ci

# CORRECT: Clean install from lock file (CI)
npm ci

# CORRECT: Install and update lock file (development)
npm install

# WRONG: Deleting lock file to "fix" issues
# rm package-lock.json && npm install   <-- loses pinned versions

Bundle Size Analysis

Measuring Impact

# Check bundle size of a package (before installing)
npx bundlephobia <package-name>

# Analyze your bundle
npx webpack-bundle-analyzer dist/stats.json

# Check what's in node_modules
npx cost-of-modules

# Compare alternatives
npx bundlephobia lodash vs ramda vs lodash-es

Size Budget Rules

du -sh node_modules

time npm ci

Reducing Bundle Size

import debounce from 'lodash/debounce'

import { debounce } from 'lodash'

lodash-es

lodash

date-fns

moment

const lib = await import('heavy-lib')

npm ls <pkg>

CI Integration

Audit in CI Pipeline

name: Dependency Audit
on:
  pull_request:
    paths:
      - 'package.json'
      - 'package-lock.json'
  schedule:
    # Run weekly audit on Monday mornings
    - cron: '0 8 * * 1'

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - name: Security audit
        run: npm audit --audit-level=high

      - name: License check
        run: npx license-checker --production --failOn "GPL-2.0;GPL-3.0;AGPL-3.0"

      - name: Check for outdated (informational)
        run: npm outdated || true

Anti-Patterns

npm audit fix --force

npm audit fix

"*"

""

^

package-lock.json

yarn.lock

npm install

npx

npx

--ignore-scripts

npm audit

devDependencies

npm ci --omit=dev

Quick Reference: Audit Decision Tree

npm audit reports vulnerability
  |
  +--> Is it in a devDependency only?
  |      YES --> Lower priority (not in production)
  |      NO  --> Continue
  |
  +--> Is there a patch/minor fix available?
  |      YES --> npm audit fix (safe)
  |      NO  --> Continue
  |
  +--> Is the vulnerable code path used in your app?
  |      NO  --> Document accepted risk, revisit monthly
  |      YES --> Continue
  |
  +--> Is there a major version fix?
  |      YES --> Read changelog, test upgrade in branch
  |      NO  --> Continue
  |
  +--> Can you use overrides/resolutions?
  |      YES --> Pin transitive dep to fixed version
  |      NO  --> Continue
  |
  +--> Find alternative package or implement inline