fix-cve-dep

name	fix-cve-dep
description	Upgrade a vulnerable npm dependency end-to-end — version bump, resolutions pin, yarn install, license regeneration, and commit. Invoke for any CVE, security advisory, or dependency vulnerability ticket (Jira CRW-*, GHSA-*, or a user request to "fix the X vulnerability" or "upgrade Y for security"). Handles ClearlyDefined indexing checks, .deps/ file updates, and produces a properly formatted commit automatically.
argument-hint	[package-name] [fix-version] [jira-ticket]

Fix CVE Dependency Upgrade

Required input

• Package name (e.g. axios, ws, ip-address)
• Minimum fix version from the CVE description
• Jira ticket ID (e.g. CRW-11204)

If $ARGUMENTS is missing fields, extract them from context (open Jira ticket, branch name, etc.).

Workflow

1. Check current version

grep -A 3 '"<package>@npm' yarn.lock | head -6

If current ≥ fix version, document as already fixed and stop.

2. Find the best upgrade target

Pick the latest indexed version, not just the minimum fix version:

yarn npm info <package> dist-tags 2>/dev/null | grep latest

For each candidate (latest, latest-1, fix-version), check ClearlyDefined score:

curl -s --max-time 10 \
  "https://api.clearlydefined.io/definitions/npm/npmjs/-/<package>/<version>" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('scores',{}).get('effective',0), d.get('licensed',{}).get('declared','?'))"

Choose the highest-versioned package with score > 0 and a resolved SPDX license. A newer un-indexed version resolves via semver (^) and breaks yarn license:generate — pin the exact indexed version.

3. Update package.json

Update in ALL locations:

• Root package.json → resolutions field (exact version, e.g. "<package>": "1.16.1")
• Any workspace package.json with it as a direct dep (update range, e.g. "<package>": "^1.16.1")

grep -rn '"<package>"' packages/*/package.json package.json

Pinning rules:

• Use exact version (no ^) in resolutions to prevent resolution to newer un-indexed versions
• For packages crossing a major semver boundary (e.g. ^9.x → 10.x), the resolutions override is mandatory

4. Reinstall and verify

yarn install
grep -A 2 '"<package>@npm' yarn.lock | head -4   # confirm lock updated

5. Regenerate license files

yarn license:generate

If UNRESOLVED exits:

Check ClearlyDefined individually:

curl -s --max-time 10 \
  "https://api.clearlydefined.io/definitions/npm/npmjs/-/<dep>/<version>" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('scores',{}).get('effective',0), d.get('licensed',{}).get('declared','?'))"

• Score > 0: batch API timed out — retry (usually succeeds on attempt 2–4)
• Score = 0: not yet indexed — add to .deps/EXCLUDED/prod.md (runtime) or .deps/EXCLUDED/dev.md (dev only):

| `<package>@<version>` | [clearlydefined](https://clearlydefined.io/definitions/npm/npmjs/-/<package>/<version>) |

Then re-run yarn license:generate.

6. Verify

yarn license:check   # must exit 0

7. Commit

git add package.json packages/*/package.json yarn.lock \
  .deps/dev.md .deps/prod.md .deps/EXCLUDED/dev.md .deps/EXCLUDED/prod.md

Commit message:

fix(deps): upgrade <package> to <version> to fix <vulnerability-type> (<JIRA>)

<Package> versions prior to <fix-version> <vulnerability description>.
Upgrade from <old-version> to <new-version> (pinned in resolutions) and
regenerate license dependency files.

CVE reference: <CVE-ID or GHSA>
Fixed in: <package> <fix-version>

Assisted-by: {AGENT_NAME}
Signed-off-by: {AUTHOR_NAME} <{AUTHOR_EMAIL}>

8. Push

git push -u origin <branch>

Special cases

Package crosses major semver boundary (e.g. 9.x → 10.x)

The fix version exceeds the range declared by transitive dependents ("ip-address": "^9.0.5" won't accept 10.x). Add a hard pin:

"ip-address": "10.2.0"

Multiple CVEs in one PR

Fix all packages in a single commit; list each in the commit body:

1. <package-a> — fixes <type> (CRW-XXXXX)
2. <package-b> — fixes <type> (CRW-XXXXX)

ClearlyDefined batch API failures

The batch API sometimes returns HTTP 502 or times out. Always retry before adding packages to EXCLUDED. Usually succeeds on attempt 2–4.