---
name: "dependency_audits"
description: "npm/pip audit workflows, SBOM basics, and fixing vulnerable dependencies for agent-run codebases. Triggers on: audit dependencies, check for vulnerable packages, fix CVE, generate SBOM, review a requirements file or package.json."
metadata: { "includeInPrompt": true }
---

## Purpose

Run dependency vulnerability audits for agent-managed codebases (npm and pip ecosystems), triage findings by severity and fixability, apply safe fixes, and produce SBOMs when handing code to others. Covers the audit -> triage -> fix -> retest -> re-audit loop plus SBOM generation. Scoped to npm and pip only — it does not cover container image scanning, secrets, or license compliance.

## Workflow

1. **Audit npm.** `npm audit` prints the advisories table. `npm audit --json` gives machine-readable output; top-level keys (verified against npm 10 source) are `auditReportVersion`, `vulnerabilities` (per-package findings), and `metadata` (severity counts under `metadata.vulnerabilities`, dep-type counts under `metadata.dependencies`).
2. **Filter noise.** Default to `npm audit --audit-level=moderate` so low/info advisories don't drown the signal. Values allowed: `info|low|moderate|high|critical|none` (verified from `npm audit --help`).
3. **Find why a dep is there.** `npm ls <pkg>` shows the dependency chain — this is how you identify the parent package pulling in a vulnerable transitive dep. `npm outdated` shows Current/Wanted/Latest drift for every package.
4. **Fix npm.** Prefer `npm audit fix` — it upgrades only within semver ranges, so it rarely breaks things. `npm audit fix --force` can jump major versions and break APIs; use it only when no safe fix exists, and re-run the full build + test suite afterward.
5. **Audit pip.** `pip-audit` audits the active environment; `pip-audit -r requirements.txt` audits a requirements file (repeat `-r` for multiple files). `-f json` emits `dependencies` and `fixes` as the top-level keys. Add `--aliases` to include alias IDs for each vulnerability (note: `-v` is just verbose logging, not aliases).
6. **Fix pip.** `pip-audit --fix -r requirements.txt` upgrades vulnerable packages and rewrites the requirements file in place with patched pins (verified: it rewrites `package==x.y.z` pins, annotating subdependencies it pinned explicitly). For manual bumps, `pip install -U <pkg>` then re-pin.
7. **Triage before fixing.** For each finding, note: direct vs transitive dependency, severity, and whether a fix is available (both tools list fix versions). Transitive vulns are only fixable via the parent's upgrade — use `npm ls` (npm) or the requirements resolver output (pip) to find the parent, and upgrade it instead of the transitive package directly.
8. **Fix order.** audit -> triage -> fix -> lockfile update (run the package manager so `package-lock.json` / the pinned requirements reflect the fix) -> retest (build + tests) -> re-audit to confirm zero remaining findings at your audit level.
9. **Generate an SBOM.** An SBOM is a machine-readable inventory of components and versions. Two common formats: CycloneDX and SPDX. Verified working: `npm sbom --sbom-format=cyclonedx` (emits CycloneDX 1.5 JSON) and `npm sbom --sbom-format=spdx` (SPDX 2.3). `pip-audit -f cyclonedx-json` (or `cyclonedx-xml`) emits an SBOM for the pip side. Prefer CycloneDX when the recipient doesn't specify — it's the more common default for tooling.
10. **When an SBOM matters.** Generate one when shipping code to others, responding to a security incident, or when a consumer/procurement process asks for it. Skip it for personal scratch projects — the audit loop alone is enough there.

## Output Contract

Every audit engagement ends with:
- **Findings summary:** count of vulnerabilities by severity (info/low/moderate/high/critical), split into direct vs transitive, with fix-available versions listed.
- **Triage table:** for each finding (or grouped by package): severity, direct/transitive, parent package if transitive, and recommended action (safe fix available / needs `--force` or major bump / no fix — monitor).
- **Changed files:** exactly which files were modified (e.g. `package.json`, `package-lock.json`, `requirements.txt`) and what changed.
- **Verification:** re-audit output showing findings cleared (or explicitly deferred), plus confirmation that build/tests still pass after fixes.

## Operating Rules

- **Commit lockfiles.** Always commit `package-lock.json` (and pinned `requirements.txt`) alongside any fix — an audit that isn't reproducible from the lockfile is unverifiable.
- **Audit in CI as practice.** Run `npm audit --audit-level=high` (or equivalent severity gate) in CI; npm's documented semantics are: exit code 1 when findings at or above the specified level are present, 0 when clean — wire that exit code to the build result.
- **Prefer safe fixes in CI.** Default to semver-safe fixes (`npm audit fix`, pinned `pip-audit --fix`) in automated pipelines. Escalate anything needing `--force` or a major version bump to a human review — prefer not to auto-merge across majors because breakage is likely.
- **Don't fix transitives directly.** Upgrading a transitive package by hand just gets overwritten on the next install; always upgrade the parent instead.
- **Re-audit after every fix batch.** Treat "fix applied" as unverified until the re-audit shows the finding gone at your chosen audit level.
- **Soften severity gates to the codebase.** `moderate` is a reasonable default gate for active projects; use `high` for noisy legacy codebases you can't fully remediate yet, and document deferred items in the output contract rather than ignoring them.