dependency_audits v1.0.0

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.