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).

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