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
audit-trace brief

AI-ready brief (vibe coding)

audit-trace brief
audit-trace brief --top 3 --prod-only
audit-trace brief --json

Produces a prioritized fix plan with ownership context and a paste-ready prompt block for AI assistants (Cursor, Copilot, etc.). When no vulnerabilities are found, output switches to a clean status message instead of an empty fix plan.

• --top <n> — max action groups (default: 5)
• --pkg <name> — focus on one vulnerable package
• --no-prompt — omit the AI prompt block
• --prod-only, --audit-file, --pm — same as report

Monorepos and Workspaces

If you are working in a monorepo workspace (e.g., npm or pnpm workspaces), you can run audit-trace inside the root workspace folder to analyze the whole monorepo, or run it directly inside any subpackage directory under packages/ to audit and trace dependencies specifically for that subpackage:

# Audit a specific subpackage from its directory
cd packages/my-sub-package
audit-trace report

This works by automatically traversing up to find the workspace root containing the lockfile, running the audit at the workspace level, and then filtering the dependency graph and findings to only show vulnerabilities that are transitive dependencies of the subpackage.

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 | | brief | AI-ready security brief with prioritized fix plan and paste-ready prompt | | 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