dependency-audit

When to use

Trigger when:

• "Audit our dependencies" / "any CVEs in prod?" / "is log4shell present".
• Renovate / Dependabot fatigue — user wants a single prioritized list.
• Pre-release gate: block shipping on Critical CVEs in direct deps.
• Incident: a new CVE was just published, "are we vulnerable".

Do not use for SAST (use security-audit) or container layer CVEs (use container-scan).

Inputs

• REPO_PATH (default: .) — source tree to audit.
• OUT_DIR (default: ./dep-audit-out).
• MIN_SEVERITY (default: MEDIUM) — filter floor.
• INCLUDE_DEV (default: 0) — include dev-only deps.
• FAIL_ON (default: CRITICAL) — exit-code gate severity.
• Optional env:
  • GITHUB_TOKEN — raises GitHub Advisory rate limits.
  • OSV_API_URL — override osv.dev endpoint (for air-gapped).

Outputs

• Per-ecosystem raw: osv.json, npm-audit.json, pip-audit.json, govulncheck.json, cargo-audit.json, dependency-check.json.
• dep-audit.normalized.json — unified records.
• dep-audit-report.md — grouped-by-severity report with fix table.

Unified record:

{
  "ecosystem": "npm",
  "package": "lodash",
  "installed_version": "4.17.20",
  "path": ["@my/app", "express-session", "lodash"],
  "direct": false,
  "cve": ["CVE-2021-23337"],
  "ghsa": "GHSA-35jh-r3h4-6jhm",
  "cvss": 7.2,
  "severity": "high",
  "summary": "Command Injection in lodash",
  "fixed_in": "4.17.21",
  "fix_kind": "patch",
  "references": ["https://nvd.nist.gov/vuln/detail/CVE-2021-23337"]
}

Tool dependencies

• osv-scanner >= 1.7 (universal, required).
• Ecosystem tools (optional, each enables a manifest type):
  • npm / yarn / pnpm for JS.
  • pip-audit for Python.
  • govulncheck for Go.
  • cargo-audit for Rust.
  • OWASP dependency-check for Maven/Gradle.
• jq.

Procedure

1. Detect manifests. Presence rules:
   • package.json + lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml) -> JS.
   • requirements.txt, pyproject.toml, Pipfile.lock -> Python.
   • go.mod -> Go.
   • Cargo.lock -> Rust.
   • pom.xml, build.gradle* -> JVM.
2. Run ../security-audit/scripts/run-sca.sh "$REPO_PATH" "$OUT_DIR" — it already knows how to dispatch per ecosystem.
3. Normalize each raw output into the unified schema. Key steps:
   • OSV -> one record per results[].packages[].vulnerabilities[].
   • npm-audit v2 -> walk vulnerabilities map; direct: true if via[].dependency == <root>.
   • pip-audit -> dependencies[].vulns[].
   • govulncheck -> records where finding.osv != null and the trace reaches internal/functions (callable, not just imported).
   • cargo-audit -> vulnerabilities.list[].
4. Build dependency path for each transitive finding using the lockfile (npm ls <pkg> --json, pip show, go mod graph, cargo tree -i <pkg>). Populate path and direct.
5. Compute CVSS: prefer NVD cvssMetricV31.baseScore; fall back to GHSA severity string -> numeric midpoint (Low=2, Medium=5, High=8, Critical=9.5).
6. Filter below $MIN_SEVERITY.
7. Produce dep-audit-report.md:
   • Section per severity.
   • Table columns: Package | Installed | Fixed in | CVE | Severity | Direct/Transitive | Path.
   • "Fix plan" section with a concrete upgrade command per ecosystem (e.g. npm install [email protected], poetry add cryptography@^42.0.5, go get golang.org/x/[email protected]).
8. Exit non-zero if any finding has severity >= $FAIL_ON.