Tracing transitive vulnerabilities

Tracing Transitive Vulnerabilities

Overview

The auditing-npm-dependencies and auditing-python-dependencies skills each surface CVEs, but they don't answer the question that actually decides remediation order: which of these findings can I clear by bumping ONE direct dep, and which require deeper intervention?

That question is the core of supply-chain triage. A high-CVSS CVE in [email protected] is alarming on first read. If it's pulled in by five different direct deps, the right fix may not be to bump any of them — it may be a single root-level overrides entry pinning lodash@^4.17.21. The triage discussion goes very differently when you can quote: "this CVE is reachable via 5 paths, all of which flow through webpack, which has a fixed version available." That shifts a project-wide panic to a one-line PR.

This skill walks the project's dependency graph (via npm ls, pipdeptree, or equivalent), intersects it with the CVE findings already produced by the per-language audit skills, and emits a trace report that includes:

• For each CVE: the full path(s) from direct dep → ... → vulnerable package
• For each direct dep: the count of CVEs reachable through it
• "Highest-leverage upgrade" recommendation — the single direct-dep bump that clears the most findings at once
• "Unreachable" findings — CVEs whose vulnerable version range is forced by EVERY parent in the path, requiring overrides or vendor-patch
• "Deep transitive" findings (≥3 levels from a direct dep) — these are highest-risk for hidden surprises because the relationship to your code is most opaque

When the skill produces findings

Finding	Severity	Threshold	Affected control
Critical CVE at deep transitive depth (≥3)	HIGH	Depth ≥3 + severity CRITICAL — blast radius unclear	CWE-1395
High CVE reachable only via overrides	HIGH	No direct-dep version clears the finding	CWE-1395
Multi-CVE direct-dep hotspot	MEDIUM	Single direct dep is ancestor for ≥3 separate CVEs	(informational)
Direct-dep bump clears N findings	INFO	Reports the recommended bump	(operational)
Unreachable CVE (no fix in any reachable version)	HIGH	Finding has no fix-available across the whole graph	CWE-1395
Circular dep with CVE	MEDIUM	Cycle in the dep graph involves a vulnerable package	(operational)

Prerequisites

• Python 3.9+
• npm or pip available (depending on project type)
• pipdeptree (optional but recommended for Python; falls back to pip show chains if absent — slower but works)
• An existing audit JSON file from auditing-npm-dependencies or auditing-python-dependencies, OR the willingness to let this skill run those audits itself

Instructions

Step 1 — Identify the scan target

The skill auto-detects whether the project is npm-flavored (package.json + node_modules) or Python-flavored (pyproject.toml / requirements.txt / installed venv).

Step 2 — Acquire audit data

The skill can run the per-language audit itself, or consume a pre-produced audit JSON:

# Self-running mode
python3 ./scripts/trace_vulns.py /path/to/project

# Pre-produced mode (faster on re-runs)
python3 plugins/security/penetration-tester/skills/auditing-npm-dependencies/scripts/audit_npm.py \
    /path/to/project --format json --output /tmp/audit.json
python3 ./scripts/trace_vulns.py /path/to/project --audit-input /tmp/audit.json

Step 3 — Walk the graph

For npm, the skill calls npm ls --json --all to enumerate the full installed tree. For Python, it calls pipdeptree --json-tree or falls back to recursive pip show.

The resulting graph is intersected with the per-package CVE findings, producing a path list for each vulnerability.

Step 4 — Triage by leverage

The report ranks findings by:

1. Severity (CRITICAL → HIGH → MEDIUM → LOW)
2. Depth in the graph (deeper = more uncertain blast radius)
3. Number of reachable paths (more paths = harder to clear with a single bump)

For each direct dep, the report aggregates:

• Total reachable CVE count
• Severity breakdown
• Suggested bump version (if available)

Step 5 — Plan the upgrades

Use the "highest-leverage upgrade" recommendation as the first PR. Then re-run this skill against the post-upgrade state to confirm how many findings dropped. Iterate until the residual is overrides / vendor work only.

Examples

Example 1 — Triage a noisy audit

# Run base audit
python3 plugins/security/penetration-tester/skills/auditing-npm-dependencies/scripts/audit_npm.py \
    . --format json --output /tmp/npm-audit.json

# Trace
python3 ./scripts/trace_vulns.py . --audit-input /tmp/npm-audit.json \
    --format markdown --output /tmp/trace.md

/tmp/trace.md is human-readable: per-CVE path lists + recommended bumps + leverage analysis.

Example 2 — Highest-leverage upgrade discovery

python3 ./scripts/trace_vulns.py . --format json --leverage-only \
    | jq '.[] | select(.cve_count >= 3)'

Surfaces direct deps that, if bumped, would clear ≥3 CVEs at once.

Example 3 — Deep-transitive risk report

python3 ./scripts/trace_vulns.py . --min-depth 3 --format markdown \
    --output deep-trace.md

Limits output to findings at depth ≥3 from a direct dep — the hardest-to-triage class.

Output

JSON / JSONL / Markdown per lib/report.py. Exit codes: 0 clean, 1 high/critical, 2 error.

Each Finding includes:

• id — trace::<cve-id>::<vulnerable-package>
• severity — re-derived based on depth + reachability
• category — transitive-trace
• summary — short description of the path situation
• evidence — original CVE, dep path(s), depth, parent direct-deps, recommended bump
• references — link back to the source audit finding

A "leverage report" section in markdown output lists the top-N direct-dep bumps ranked by aggregate CVE-clearance count.

Error Handling

• npm ls fails to produce a complete tree (lockfile out of sync) → emits an INFO Finding flagging the desync and proceeds with partial data.
• pipdeptree not installed → falls back to pip show recursion; emits INFO finding recommending pipdeptree install for accuracy.
• No audit findings input AND no audit tool available → exits 2 with operational error advising the operator to provide an audit JSON via --audit-input.
• Graph contains cycles → cycles are detected and broken; each package in the cycle is reported once at its shallowest depth.

Resources

• references/THEORY.md — Why deep transitive deps are disproportionately risky, dependency-graph traversal theory, SBOM (Software Bill of Materials) standards (CycloneDX, SPDX 3.0), reachability theory for vulnerability analysis, exploit-prediction-scoring-system (EPSS) integration plans
• references/PLAYBOOK.md — Per-runtime trace patterns, SBOM generation patterns (cyclonedx-cli, syft, anchore), graph-based upgrade planning, when to override vs vendor-patch, integration with the per-language audit skills