audit-trace

audit-trace

audit-trace is a local-first CLI for npm / pnpm / Yarn projects. It combines lockfile-aware dependency graphs with audit output so you can see which top-level dependencies introduce a vulnerable package, short remediation hints, and CI-friendly diagnostics (structured CiDiagnostic codes for logs, job summaries, or PR comments).

Why use this instead of npm audit (alone)?

npm audit is good at one thing: surfacing advisories for what is installed. It is weaker at explaining them in a way that matches how teams actually fix issues:

What you often need	npm audit	audit-trace
Who owns it? Which direct dependency pulled in the vulnerable package?	Usually a flat or cryptic path; easy to lose the chain in large trees	Ownership paths from the lockfile graph, grouped so shared prefixes are not repeated dozens of times
Clarity	Severity and package names, but little narrative structure	Merged dependency trie, severity-colored vulnerable leaves, and prod / dev context where the graph allows it
Action	“Run npm audit fix” / generic hints	Remediation-oriented suggestions (e.g. overrides) when the advisory data supports it
CI	Exit codes and JSON, often with little why	--ci + diagnostics you can pipe to summaries or PR comments; --ci-verbose for a short human explanation

Simplicity here means: one run gives you a single, readable view—what is wrong, where it enters the tree, and how serious it is—without hunting through node_modules or reconstructing chains manually. Explainability means: the tool combines graph + audit, not audit alone, so answers read as “this direct dependency → this chain → this package (severity)” instead of a flat list of advisories.

audit-trace does not replace the registry advisory source: it still relies on your package manager’s audit (or a saved --audit-file). It adds structure, ownership, and reporting on top.

Requirements

• Node.js 18+

Install

npm install -g audit-trace
# or use npx
npx audit-trace report

From source:

git clone <repo>
cd audit-trace
npm install
npm run build
node dist/cli.js --help

Quick start

cd your-project
audit-trace report
audit-trace report --json
audit-trace report --ci --fail-on high --prod-only

Interactive UI (Ink)

audit-trace report --interactive

Use ↑/↓ to browse findings, q to quit.

Commands

Command	Description
report (default)	Run package-manager audit + lockfile graph; print ownership paths & remediation hints
why <pkg>	Shortest path(s) from workspace root(s) to a package in the lockfile graph
graph <pkg>	Enumerate paths (capped) between roots and the package
impact <pkg>	Transitive consumers (reverse reachability in the graph)
diff <before> <after>	Compare two lockfiles (--kind npm|pnpm) — added/removed package keys

Flags (report)

• --json / --markdown / --html — output modes
• --ci — apply exit-code policy and print structured CI diagnostics to stderr
• --ci-verbose — more explanatory CI text
• --fail-on <level> — critical | high | moderate | low | info | none (default: high in CI contexts; in local runs without --ci, exit code stays 0 unless --ci is passed)
• --prod-only — drop findings whose traced paths are dev-only (best-effort; requires dev flags in the lockfile)
• --audit-file <path> — parse audit JSON instead of invoking npm|pnpm|yarn audit
• --pm npm\|pnpm\|yarn — force audit runner
• --entry <file> — optional entry for madge-based reachability heuristic (tags titles)

CiDiagnostic codes

Stable codes emitted in JSON (diagnostics[]) and echoed in human CI summaries:

Code	Meaning
NO_LOCKFILE	No supported lockfile at project root — graph/ownership is degraded
AUDIT_SOURCE_FALLBACK	Audit subprocess failed or returned empty — verify tool versions
FILTER_CONTEXT	Some items excluded by --prod-only / future filters
FAIL_HIGH_PROD	High/critical findings matched the failure threshold
FAIL_POLICY	Generic policy failure (--fail-on and severity counts)
GRAPH_BUILD_WARN	Reserved for graph/parser warnings

GitHub Actions

See examples/github-actions/ci.yml for a sample workflow posting JSON + human-readable sections.

Plugins (experimental)

Plugins can implement hooks such as afterGraphBuilt, afterAuditNormalized, onCiDiagnostics, and formatReport. Register via the internal plugins/registry API (local imports) — a config file loader can be added later.

Development

npm test
npm run build

Limitations

• Yarn Berry lockfiles and audits differ by release; classic yarn.lock + yarn audit --json are the primary targets.
• Reachability via madge is heuristic (static graph); dynamic require is not modeled.
• Remediation prefers overrides / resolutions when audit provides patched ranges; otherwise a manual upgrade path is suggested.

License

MIT