audit-dependencies

Audit Dependencies

Overview

Fix dependency vulnerabilities reported by .github/workflows/audit-dependencies.sh. Prefer fixes in this order: direct dependency bump > lockfile update > pnpm override. Every override requires justification for why simpler approaches aren't feasible.

Core Workflow

digraph audit {

Step-by-Step

1. Run the Audit Script

$ARGUMENTS is the severity passed to the skill (defaults to high if omitted). The script runs pnpm audit --prod --json and filters for actionable vulnerabilities (those with a patched version available). high includes critical.

Parse the output to build a deduplicated list of vulnerable packages with:

• Package name and current version
• Fixed version requirement
• Full dependency chain (e.g., packages/plugin-sentry > @sentry/nextjs > rollup)

2. For Each Vulnerable Package

Trace the dependency chain

Identify whether the vulnerable package is:

• Direct dependency: Listed in a workspace package's package.json
• Transitive dependency: Pulled in by another package

Try direct bump first

For transitive deps, walk up the chain to find the nearest package you control:

1. Check if bumping the parent package resolves the vulnerability
   • pnpm view <parent>@latest dependencies.<vulnerable-pkg>
   • Check intermediate versions too (the fix may exist in a minor bump)
2. If the parent bump resolves it, research breaking changes:
   • Check changelogs/release notes
   • Search GitHub issues for compatibility problems
   • Review the API surface used in this repo (read the source files)
   • Check if the version range crosses a major version boundary
3. Present findings to user with risk assessment

Parallelize research: When multiple packages need breaking change analysis, dispatch parallel agents (one per package) to research simultaneously.

Check if a lockfile update is sufficient

Before reaching for an override, check whether the parent's version specifier is pinned (exact version like 3.10.3) or ranged (like ^2.3.1, ~4.0.3):

If the range already includes the fixed version, a lockfile update is all that's needed:

No package.json changes required — the lockfile was just stale.

Fall back to override only when justified

Add a pnpm override in root package.json only when:

• The parent pins an exact version that doesn't satisfy the fix
• No version of the parent package fixes the vulnerability
• The parent bump has high breaking change risk (major API changes, no test coverage, requires code changes across many files)
• The user explicitly decides to defer the parent bump to a separate PR

Override format: "<parent>><vulnerable-pkg>": "^<fixed-version>"

Override syntax rules:

• Use ^ ranges, not >=. >= can cross major versions and cause unexpected resolutions (e.g., "picomatch": ">=2.3.2" can resolve to 4.x).
• pnpm only supports single-level parent scoping: "parent>pkg" works, "grandparent>parent>pkg" does not.
• pnpm does not support version selectors in override keys: "pkg@^2" does not work.
• If the same vulnerable package appears through many transitive paths, a global override may be needed. Be careful that it doesn't affect unrelated consumers on a different major version — use parent-scoped overrides when the package spans multiple major versions across the tree.
• pnpm only honors overrides in the root workspace package.json. Overrides in workspace packages are ignored.

Before adding any override, verify the target version exists:

3. Present Plan to User

Before applying fixes, present a summary table to the user showing each vulnerability, the proposed fix strategy (direct bump / lockfile update / override), and justification. Get confirmation before proceeding.

4. Apply Fixes

• Edit package.json files for direct bumps
• Run pnpm update <pkg> --recursive for lockfile-only fixes
• Edit root package.json pnpm.overrides for overrides (keep alphabetical)
• If a direct bump changes behavior, update consuming code (e.g., adding allowOverwrite: true when an API default changes)

5. Install and Verify

If install fails due to native build errors (e.g., better-sqlite3), fall back to:

Then re-run the audit script with the same severity:

The audit script must exit 0. If vulnerabilities remain, check for additional instances of the same dependency in other workspace packages.

6. Build and Verify

For packages with changed dependencies, also run their specific build:

7. Look Up CVEs

For each fixed vulnerability, find the GitHub Security Advisory (GHSA):

• Check https://github.com/<org>/<repo>/security/advisories for each package
• Search the web for <package-name> GHSA <fixed-version>
• Record: GHSA ID, CVE ID, severity, one-line description
• Prefer GHSA links (https://github.com/advisories/GHSA-xxxx-xxxx-xxxx) over NVD links

Parallelize CVE lookups: Dispatch parallel agents to search for CVEs across all packages simultaneously.

8. Commit and Create PR

Commit with conventional commit format:

Create PR using gh pr create with this body structure:

Common Mistakes