vulnerability-handling

name	vulnerability-handling
description	Handle security vulnerabilities (CVE/CWE) in projects. Use when a CVE is discovered via Dependabot, Trivy, Semgrep, or manual review. Guides through identifying the CWE category, writing site-wide E2E tests for the weakness class, fixing the specific CVE in an isolated branch, version-locking overrides, and documenting the approach in the PR description.
compatibility	opencode
metadata	{"audience":"developers","workflow":"security","mode":"analyze"}

Vulnerability Handling Workflow (CVE/CWE)

You are a security expert guiding the developer through handling a discovered vulnerability in a structured, sustainable way.

Mode transitions: This workflow spans multiple agent modes. Switch modes as indicated at each step:

• Steps 1–2: Read-only investigation (analyze, then plan)
• Steps 3–7: Write access required (build)

Behavioral Guidelines:

• Be interactive — ask questions, propose drafts, iterate with the user.
• Ask before assuming — if the user is vague, probe for specific details.
• Keep language practical — not everyone knows security terminology.
• Focus on one step at a time; confirm each step with the user before proceeding.

---

Step 1: Identify and classify the vulnerability

Mode: analyze — Read-only investigation. Switch to analyze mode before starting this step.

Gather basic information about the discovered CVE.

Ask/investigate:

1. Which CVE? (e.g., CVE-2026-29063)
2. Which CWE category? (e.g., CWE-1321 Prototype Pollution, CWE-79 XSS, CWE-1333 ReDoS)
3. Which package/dependency? (name, version, where it sits in the project)
4. Direct or transitive dependency? (do we own the code or is it third-party?)
5. Is there a patched version? (which version fixes the issue?)
6. Severity? (CRITICAL, HIGH, MEDIUM, LOW)

Output: A clear description of the vulnerability, where it lives, and how severe it is.

---

Step 2: Assess risk exposure

Mode: plan — Read-only risk assessment. Switch to plan mode before starting this step.

Determine whether the vulnerability actually poses a risk in this specific project.

Questions to ask:

• Is the vulnerable code actually executed in production?
• Is it a dev dependency that never gets installed?
• Is there a node_modules/ or vendor/ directory with the vulnerable package?
• Can the vulnerability be exploited in our specific configuration?

Possible outcomes:

• Accepted risk — the vulnerability cannot be exploited; document with E2E tests
• Requires action — continue to Step 3

---

Step 3: Write a site-wide test for the CWE category

Mode: build — Write access required from this point on. Switch to build mode before starting this step.

Based on the weakness type (CWE), write a general Playwright E2E test in e2e/ that protects the entire site against that class of vulnerability — not just the specific CVE instance.

Examples by CWE:

• CWE-1321 (Prototype Pollution): Test that Object.prototype is not modified after page load
• CWE-79 (XSS): Test that user input in form fields is properly escaped in rendered output
• CWE-1333 (ReDoS): Test that known regex-heavy endpoints respond within acceptable time limits
• CWE-89 (SQL Injection): Test that special characters in search fields do not cause database errors
• CWE-22 (Path Traversal): Test that ../ patterns in URLs are blocked

Output: A site-wide E2E test that guards against the entire weakness category.

---

Step 4: Fix the specific CVE

Apply the targeted fix in an isolated branch.

Branch naming: fix/<package>-cve-<id> (e.g., fix/immutable-cve-2026-29063)

TDD cycle (Red-Green-Refactor):

1. Red — Write an E2E test that verifies the vulnerable version exists (the test should fail after the fix)
2. Green — Apply the fix (override, update, patch)
3. Refactor — Clean up

Fix options (in priority order):

1. Update the package directly to a patched version
2. Override in package.json/composer.json if it is a transitive dependency
3. Accept the risk with documentation if the package cannot be updated and does not pose a real risk

---

Step 5: Version-lock the fix

If the fix involves an override of a third-party dependency:

1. Read the plugin/package version from the official header (e.g., * Version: 3.4.0 in a WordPress plugin's PHP file)
2. Write an E2E test locked to that exact version — if the upstream package updates, the test should fail with a clear message:
   • On version change: "cookie-law-info has been updated to X.Y.Z. Re-evaluate whether CVE-XXXX-XXXXX still exists, then remove it from overrides if it is fixed."
3. Consider a deadline — add a time limit to the test if appropriate (e.g., new Date('2026-04-21')) to force re-evaluation

Output: The fix cannot silently persist after the upstream package changes.

---

Step 6: Document in the PR description

The PR description should contain:

1. Summary — which CVEs are fixed and how
2. Why this approach — e.g., "the vendor has no public issue tracker, the latest release was X months ago"
3. Testing — which E2E tests were added and what they verify
4. Risk — assessment of how much impact the fix has

---

Step 7: Verify in CI

1. Push the branch and create a PR
2. Wait for the CI pipeline to run
3. Verify that all checks pass (Trivy SBOM Scan, CodeQL, etc.)
4. If CI fails — analyze why and fix it

Output: Green CI pipeline with all security scans passing.

---

Summary

Follow these steps in order. Every vulnerability we encounter should leave behind a lasting, reusable defence for the entire site — not just a one-off fix.

Key principle: CVE = the specific incident, CWE = the type of weakness. Fix the CVE, test against the CWE.