Cve Doctor

cve-doctor

You are helping the user triage a single CVE / security advisory in a JavaScript or TypeScript project. The goal is to resolve it with the least-invasive change possible, preserving the project's semver intent and Dependabot/Renovate visibility. A package-manager override is the absolute last resort.

Guiding principles

1. Investigate before acting. Do not install packages, edit package.json, or run update until you have walked the full chain and presented options.
2. User decides at every branch. When there are multiple viable fix paths, list them ranked least → most invasive and wait for the user to pick. Never silently pick the "easiest" option for them.
3. Overrides are a last resort. A pnpm.overrides / npm.overrides / yarn.resolutions entry hides the problem from future automated scans and creates a drift-debt. Only suggest it after every upstream path has been exhausted, and only with explicit "yes, do it" from the user.
4. Unmaintained upstream is information, not a verdict. If a blocking parent looks abandoned, report the specific signals (archived flag, last commit date, last release date) and let the user decide whether to fork, switch packages, or override.

Phase 0 — Collect input

1. Read $ARGUMENTS from the invocation.
2. Parse it:
   • Dependabot alert URL of the form https://github.com/<owner>/<repo>/security/dependabot/<n>: run gh api repos/<owner>/<repo>/dependabot/alerts/<n> to fetch the alert JSON.
   • CVE ID (CVE-YYYY-NNNN) or GHSA ID (GHSA-*): run gh api /advisories/<id> to fetch the advisory. If the advisory has multiple vulnerabilities[], ask the user which package+ecosystem applies in this project.
   • Empty: ask the user for a Dependabot alert URL or CVE/GHSA ID. Do not proceed without one.
3. From the fetched data, extract and display to the user:
   • Package name + ecosystem
   • Severity (CVSS score if available)
   • Short summary
   • vulnerable_version_range[] and first_patched_version for each range
   • Alert state (if applicable): open, fixed, dismissed, auto_dismissed
4. Short-circuit: if the alert state is fixed or auto_dismissed, report that the alert is already resolved and stop. Do not continue to Phase 1.

Phase 1 — Detect the package manager

Check the project root for lockfiles (in this priority order when multiple exist — but ask the user if ambiguous):

Record the detected PM. All commands below branch on this value — use the matrix at the bottom of this file.

Phase 2 — Is this a direct dependency?

1. Grep the vulnerable package name in package.json (dependencies, devDependencies, peerDependencies, and any workspace package.jsons).
2. If it's a direct dep:
   • Check whether the latest version on the registry (<pm> view <pkg> version) is outside all vulnerable ranges.
   • Check whether our declared semver range admits a patched version.
   • If yes to both → this is a one-shot fix. Propose the single targeted update command (see matrix) and ask: "Want me to run this?" Then stop here.
   • If no (declared range pins to an unpatched major) → also ask the user whether they want to bump the major, and outline the risks. Stop here; it's not a transitive-chain problem.
3. If it's not direct → continue to Phase 3.

Phase 3 — Walk the dependency chain

1. Run the PM-specific "why" command and capture the full output.

2. Parse it into a flat list of (parent-package@parent-version, declared-range-for-vuln-pkg) tuples. Include every path, not just the first.

3. Identify every distinct installed version of the vulnerable package in the lockfile (grep the lockfile for ^\s+<pkg>: or equivalent). For each version, check it against every vulnerable_version_range from Phase 0.

4. For each vulnerable installed version, and for each immediate parent:

   • Look up the parent's latest published version and its declared range for the vulnerable package: <pm> view <parent>@latest dependencies.<vuln-pkg>.
   • Look up the parent's currently-installed version's declared range.
   • Classify the parent:
     • Auto-resolves on refresh: the installed parent's declared range already admits a patched version (the lockfile is simply stale).
     • Fixed in newer parent version: current parent blocks, but latest parent admits a patch.
     • Blocks even at latest: current AND latest parent versions both pin to a vulnerable range. This is a hard blocker — continue to Phase 4 for this parent.

5. Print a compact summary table:

   Vulnerable version  | Parent                  | Status
   <pkg>@<v>           | <parent>@<v>            | Auto-resolves / Needs parent bump to <v'> / Hard blocker
   

Phase 4 — Investigate hard-blocking parents

For each parent in the "hard blocker" category, gather (all read-only):

1. Latest release metadata — <pm> view <parent> version repository time.modified.
2. Repository signals — from the repository URL, run:
   • gh api repos/<owner>/<repo> → capture archived, pushed_at, updated_at, open_issues_count.
   • gh search issues "<CVE-ID>" repo:<owner>/<repo> --state=all → any existing discussion?
   • gh search issues "<vuln-pkg>" repo:<owner>/<repo> --state=open → any open issue mentioning the vulnerable dep?
   • gh pr list --repo <owner>/<repo> --search "<vuln-pkg>" --state=all → any open or merged PR bumping it?
3. Classify the blocker and report to the user:
   • (a) Upstream PR exists — link the PR and its state. Suggest: wait for merge, or (if urgent) pin to a git-URL fork of the merged branch.
   • (b) Upstream issue exists, no PR — link the issue and its age. Suggest: +1 the issue, or contribute a PR.
   • (c) No discussion upstream, repo actively maintained — propose opening an issue. Pre-fill a suggested title/body citing the CVE ID, vulnerable range, and patched version.
   • (d) Unmaintained signals — report each of the following that applies, verbatim, and let the user judge:
     • Repo archived: true
     • pushed_at older than 12 months
     • Latest npm release older than 12 months
     • No open-issues response from maintainers in the last 6 months Do not pronounce a package "abandoned" — state the facts and let the user decide.
   • (d-alt) Known alternative package exists — if the blocker is in a narrow category (e.g. request → undici/node-fetch, node-sass → sass), mention the alternative as context but do not recommend migrating without explicit user interest.

Phase 5 — Present ranked options

Produce a single summary to the user with the applicable options only, in this order (skip any that don't apply to this CVE):

1. Lockfile refresh — if Phase 3 found at least one chain that auto-resolves.
   • Command: see matrix.
   • Side effects: lockfile only; no package.json change; full Dependabot visibility preserved.
2. Bump a maintained intermediate parent — if Phase 4 classified any blocker as (a) or found a newer parent version that admits the patch.
   • Command: bump the declared range of whatever pins that parent (often the user's own package.json).
   • Side effects: package.json minor diff; may need to review the parent's changelog.
3. Switch to an alternative package — only if the blocker is (d) + a well-known drop-in exists. Phrase as a significant codebase change; do not propose command-level automation for this.
4. Package-manager override (last resort) — only if all chains have hard blockers and none of options 1–3 apply or are acceptable.
   • Command: see matrix.
   • Ask explicitly: "This will add an override that hides the issue from Dependabot/Renovate on future scans. Upstream blocker: <link>. Do you want to proceed? (yes/no)"
   • Do not proceed without an explicit affirmative.

After presenting, ask: "Which option do you want to apply?" and wait.

Phase 6 — Apply the chosen option

1. Run the PM-specific command(s) for the chosen option.
2. Verify the fix: re-grep the lockfile for every installed version of the vulnerable package, and assert each is outside every vulnerable_version_range from Phase 0.
3. Print a before/after table.
4. Suggest a commit message following conventional commits:
   • Option 1 (lockfile only): fix(deps): bump <pkg> to patched versions (<CVE-ID>)
   • Option 2 (parent bump): fix(deps): bump <parent> to pick up patched <pkg> (<CVE-ID>)
   • Option 4 (override): fix(deps): override <pkg> to patched versions (<CVE-ID>)
5. Do not create the branch, commit, or push. Leave that to the user.

Package-manager command matrix

All commands assume the CWD is the project root.

Override syntax notes

• pnpm supports per-major overrides via "<pkg>@<major>": "<range>" (e.g. "lodash@4": ">=4.17.21"). Use this when multiple majors are installed and only some are vulnerable.
• npm supports nested overrides ("<parent>": { "<pkg>": "<range>" }). Prefer the flat form unless you need surgical scope.
• yarn resolutions support glob patterns ("**/<pkg>": "<range>") — useful for workspace-wide application.

Final checklist

Before reporting success:

• Every installed version of the vulnerable package is outside every vulnerable_version_range.
• If an override was used, the override is scoped to the minimum range required (not a global pin).
• A commit message is suggested but not executed.
• The Dependabot alert URL is referenced in the suggested commit body for traceability.