Audit Dependencies

Audit Dependencies

Overview

A four-step dependency audit that goes past npm audit / pip-audit / cargo audit output into the actual import graph. The skill enforces that every claim ("we don't use that import path", "this dep is dead", "this CVE doesn't apply") is backed by evidence from the code, not from a tool's verdict alone. The audit produces a list of dependencies with three columns: declared, transitively pulled, actually called. Anything in column 1 or 2 but not column 3 is a candidate for removal. Anything called but unpinned, deprecated, or vulnerable is an action item. Senior ICs use it before adding a new dep, before a major version bump, or after a CVE lands.

When to Use

• After a CVE alert from npm audit, pip-audit, GitHub Dependabot, Snyk, or similar
• Before adding a new third-party package to the project
• Before a major-version upgrade of a framework, ORM, or runtime
• When node_modules / site-packages / target size feels disproportionate
• When evaluating whether a package can be removed
• During quarterly or release-cycle hygiene

When NOT to Use

• A patch-version bump on a dep you actively use, with no behavioral changes in the changelog. Just bump it.
• A dependency you added in this same PR. You know what it does.
• An audit on a deploy artifact you don't own (audit upstream, not the binary).

Process

Step 1: Snapshot

Goal: Capture the current declared dependency state in a form you can diff later.

Inputs: The project's manifest file(s) — package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, etc.

Actions:

1. Run the ecosystem's lockfile-respecting list command:
   • npm ls --all (or pnpm ls --depth=Infinity)
   • pip list --format=json
   • cargo tree
   • go list -m all
2. Pipe to a file. Date-stamp it. This is your before-state.
3. Note the count of direct deps and total deps (direct + transitive).

Output: A snapshot file at a known path. A two-line note: <N> direct, <M> transitive.

Step 2: Build the call graph

Goal: Determine which declared and transitively-pulled dependencies are actually imported by your code.

Inputs: The snapshot from Step 1 + access to the source tree.

Actions:

1. For each direct dependency, search the source tree for imports of it. Use the ecosystem's import syntax:
   • JS/TS: import .* from ['"]<name>['"] and require\(['"]<name>['"]\)
   • Python: ^(from|import) <name>(\.|$| )
   • Rust: use <crate>:: and extern crate <crate>;
   • Go: literal package path matches
2. Record the count of import sites per dep.
3. Zero-import direct deps are candidates for removal. Mark them.
4. For transitive deps that look load-bearing (security-related: jsonwebtoken, cryptography, openssl, lodash, requests), check if your code imports them directly. If yes, promote to a direct dep so you control its version.

Output: A table per dep: <name> | <declared version> | <import sites> | <verdict: keep | remove | promote>.

Step 3: Cross-check the scanner

Goal: Reconcile your import-graph evidence with what npm audit / pip-audit / cargo audit reports, and decide whether each advisory applies.

Inputs: The Step 2 table, plus the output of the ecosystem's audit tool.

Actions:

1. Run the audit tool. Capture the full report.
2. For each advisory, look up the affected package in your Step 2 table.
3. Crucial check: does your code call the vulnerable function? An advisory on a package you import does not automatically apply if the vulnerable code path is in a sub-module you never reach. Read the advisory; locate the affected function; grep your code for it.
4. Classify each advisory:
   • APPLIES — patch: vulnerable code path is reachable; upgrade available.
   • APPLIES — workaround: vulnerable code path is reachable; no patch yet, mitigate at call site.
   • DOES NOT APPLY: the vulnerable code path is not reachable from your code. Document the proof in the audit artifact.

Output: Each advisory annotated with a verdict and a one-line proof (<file:line> showing reach or absence of the vulnerable function).

Step 4: Write the audit

Goal: Produce an artifact with actions, not opinions.

Inputs: The Step 2 table and Step 3 advisory verdicts.

Actions:

1. Write a Markdown artifact at docs/audits/deps-<YYYY-MM-DD>.md with sections:
   • Snapshot (Step 1 counts)
   • Removals (zero-import direct deps; estimated diff in transitive count)
   • Promotions (transitive → direct, with version pin)
   • Advisory verdicts (each with proof line)
   • Action items (single bulleted list of changes to apply, in order)
2. The action items list is the deliverable. Each item is a concrete change ("Remove lodash from package.json — 0 import sites in src/. Re-run pnpm install to verify transitive count drops by N.").
3. Open a PR for the action items. Each PR change links back to the audit.

Output: The audit artifact at the dated path, plus a PR (or sequence of PRs) applying the action items.

Rationalizations

Evidence Requirements

Red Flags

• A dep you marked remove is removed by the PR but tests still pass and bundle size doesn't change. You may have searched for the wrong import name (alias? re-export?). Re-grep before merging.
• The audit tool reports a CVE on a dep you marked remove. The CVE may be moot, but verify removal closes it before declaring done.
• You found a vulnerable function reachable from your code but the package has no patch yet. Don't just file an issue — apply a workaround at your call site (validation, sandboxing, or wrapping) and document it in the audit.
• More than 30% of direct deps have zero import sites. The project is using a dependency manifest as a wishlist. Coordinate with the team before mass removal.
• A scanner says "high severity" on a dep that doesn't appear in your Step 2 table. The lockfile and the manifest are out of sync. Rebuild the lockfile.

References

• Software Engineering at Google, Wright et al. (O'Reilly, 2020), Chapter 21 "Dependency Management" — the "diamond dependency problem" and the case for reading import graphs over manifest declarations.