dependency_audit v1.0.0

name: "dependency_audit" description: "Run a full dependency audit: CVE triage with reachability, license compliance checks (copyleft and unknown licenses), abandoned-package signals, and the quarterly prune of deps you no longer need. Triggers when a project needs a security or license review of its dependency tree, when new advisories appear, or on a scheduled audit cadence."

Dependency Audit

Purpose

Answer three questions about the code you did not write: is it dangerous, is it legal, and is it maintained. A proper audit covers the resolved transitive tree (not just the manifest), triages every advisory for reachability instead of panic-listing, enforces the project's license policy, flags abandoned packages before they become incidents, and ends with a pruning list of what to cut.

Workflow

1. Inventory the tree. Work from the lockfile, never the manifest. Run bin/dep-audit.py [path]: it detects ecosystems, lists direct vs transitive counts per ecosystem, and runs whatever scanners are installed. If no lockfile exists, stop and say so — auditing a manifest without a lockfile audits versions that may never have shipped. (Pair with dependency_pinning to fix that first.)
2. Scan for vulnerabilities. Run the ecosystem scanners listed in references/scanner-commands.md over the full resolved graph. Record the raw findings, then triage each advisory:

• Severity (CVSS), plus EPSS score and CISA KEV listing when available. CVSS alone mis-ranks.
• Direct or transitive? A direct dep is your decision; a transitive one needs a remediation path (overrides, resolutions, constraints, parent bump).
• Reachable? Is the vulnerable code path actually called by your code? A CVE in an unused code path is a different beast from one in your request handler. govulncheck answers this properly; other tools do not. When you cannot determine reachability, write "not verified", never presume.
• Dev or prod? Dev-only findings get a different threat model and their own section, not a mix-in.

1. Check licenses. Extract licenses for the full transitive production tree (--production / --omit=dev; build tooling is not distributed, exclude it). Compare against the project's allowlist (see references/license-policy.md). Flag: forbidden copyleft (GPL/AGPL in proprietary code, SSPL anywhere), unknown or missing licenses, and license changes between versions of a dep. A license switch upstream is a new risk.
2. Score maintenance health. For each direct dep (spot-check transitives): last release date, repo archived/deprecated status, commit activity, open-issue responsiveness. Release age alone does not prove abandonment, a stable finished library is fine. You need age plus silence: 4+ years since last release and no commits, or a stated deprecation/archival. Single-maintainer packages deep in the tree are a bus-factor risk; flag them.
3. Find the prune list. Candidates to cut: deps only used in dead code paths, multiple packages solving the same problem (two HTTP clients, three date libs), deps replaceable by stdlib builtins, packages with 50+ transitive deps doing a simple job, direct git/tarball references the audit tools cannot see. npm ls deprecation warnings and npm outdated / pip list --outdated / cargo outdated seed this list.
4. Report. Produce the audit report per the Output Contract below. Group findings into action tracks, not one panic list. Then remediate what the policy says to remediate, re-run the scanners, and confirm the findings cleared.

Output Contract

A finished audit report contains:

• Tree summary: ecosystems found, direct count, transitive count, total unique packages, lockfile status.
• Triage table (one row per advisory): Package | Installed | Severity | CVE/GHSA id | Fixed in | Direct or transitive | Reachable in our code (yes/no/not verified) | Action.
• License table: license type | package count | status against policy; violations listed individually with remediation (replace, isolate, accept with sign-off).
• Abandoned/deprecated table: package | last release | signal (stated or inferred) | replacement if known.
• Prune list: package | why it can go (dead usage, duplicate, stdlib covers it) | effort estimate.
• Accepted risks: advisory or package, why it is accepted, owner, review date. An unrecorded acceptance is a lie of omission.
• Tracks: fix now (reachable High/Critical, license violations) | fix soon (unreachable/medium, unmaintained with replacement) | routine batch (patch/minor bumps) | monitor (slightly outdated, healthy).

Operating Rules

1. Lockfile or it did not happen. The audit is only as real as the resolved tree. No committed lockfile means step one is dependency_pinning, not triage.
2. Severity is not priority. Rank by reachability and exploitability, not by the color of the badge. A reachable medium outranks an unreachable critical.
3. Report reachability explicitly. A report of 200 unreviewed advisories teaches everyone to ignore the scanner. Triaged and honest, or do not ship the report.
4. Prod tree for licenses, full tree for vulns. License policy judges what you distribute; vulnerability scanning covers everything the build touches.
5. Unknown means investigate, never presume. Unknown license, unknown reachability, unknown maintainer: flag it and verify. A silent presumption of safety is how incidents are born.
6. Every accepted risk gets an owner and a date. If nobody owns it and it never gets re-reviewed, it is not an acceptance, it is neglect.
7. Install scripts are code. postinstall/preinstall in an unfamiliar package gets read during the audit, not skimmed over.
8. Watch the names. Typosquats (one transposition off a popular package), sudden ownership transfers, and version jumps like 1.0.4 to 99.0.0 are supply-chain attacks, not CVEs. Scanners will not catch them. You do.
9. Schedule it. New advisories appear for old versions every day. Wire the scanner into CI to fail on new High/Critical, enable Dependabot/Renovate, and run this audit on a real cadence (monthly for active projects, quarterly at minimum).