tracing-transitive-vulnerabilities

What this skill does

# 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:

```bash
# 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

```bash
# 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

```bash
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

```bash
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