Security Vulnerability Remediation

Playbook for analyzing and remediating security vulnerabilities in this Electron/Node.js project. Applies to both CI (Cursor agent in GitHub Actions) and local development.

Project Context

• Package manager: pnpm 11 (lockfile: pnpm-lock.yaml)
• Scanner: Grype with config at .grype.yaml (only reports vulnerabilities with a fix available)
• Audit: pnpm audit --prod --audit-level=moderate
• Existing overrides: overrides block in pnpm-workspace.yaml — used to pin transitive dependencies to patched versions (pnpm 11 no longer reads the pnpm field from package.json)
• Production deps: listed under dependencies in package.json
• Dev-only deps: listed under devDependencies in package.json — not shipped to users

Remediation Workflow

Follow these steps in order. Stop at the first step that resolves the vulnerability.

Step 1 — Identify Vulnerabilities

Run both scanners and capture the output:

grype . --config .grype.yaml
pnpm audit --prod --audit-level=moderate

For each finding, record:

• CVE ID (e.g. CVE-2024-12345)
• Affected package and installed version
• Fixed version (if available)
• Severity (critical / high / medium)
• Whether the package is a direct or transitive dependency

Step 2 — Trace the Dependency

For each vulnerable package, understand who pulls it in:

pnpm why <package-name>

Record:

• Which direct dependency depends on it
• How many versions of the package are installed
• Whether it appears under dependencies (production) or devDependencies (dev-only)

Step 3 — Attempt an Upgrade

Check if a patch/minor upgrade of the direct dependency resolves the CVE:

pnpm update <direct-dependency>

Or, if the vulnerable package is a direct dependency itself, update its version range in package.json.

After the change:

1. Run pnpm install to regenerate the lockfile
2. Re-run grype . --config .grype.yaml to verify the vulnerability is gone

If the upgrade resolves it, this step is complete. Move to the next vulnerability.

Step 4 — Apply a pnpm Override

If no non-breaking upgrade is available, or the fix requires a major version bump of a transitive dependency that is safe to force:

Add or update an entry in the overrides block inside pnpm-workspace.yaml. You MUST follow the existing override style used in the project. Current overrides look like this:

overrides:
  fast-xml-parser: '>=5.5.9'
  lodash-es: '>=4.17.23'
  tar: '>=7.5.7'

Rules for overrides (follow strictly):

1. Always use the >= prefix for values — this allows future patches. Example: '>=1.2.3'.

2. BEFORE writing any override, check pnpm why <package> for multiple major versions. This is mandatory. If the tree contains more than one major line, an unscoped override would force ALL consumers onto the overridden version, breaking packages that expect a different major.

3. Use a simple top-level override ONLY when one major line exists — if every installation of the package is on the same major, a single package: '>=fixed' entry is safe:

   some-package: '>=1.2.3'
   

4. Use parent-scoped overrides when multiple majors coexist — scope the override to the dependency path that pulls in the vulnerable version using 'parent>package' syntax:

   'parent-pkg>vulnerable-pkg': '>=2.0.1'
   

   This only overrides vulnerable-pkg when required by parent-pkg, leaving other consumers on their compatible major. Pick the nearest direct parent that exclusively uses the vulnerable major line.

   WRONG — never use an unscoped override when multiple majors exist:

   vulnerable-pkg: '>=2.0.1'
   

   This would force every consumer onto v2, breaking those that depend on v1.

5. Only override actually vulnerable versions — if pnpm why shows multiple major lines but only one is in the advisory's vulnerable range, override only that version's path. Do not add overrides for versions that are not vulnerable.

6. Three valid override-key forms — pick the most surgical one that resolves the advisory:

   1. package: '>=fixed' — top-level, only when a single major line exists in the tree (see Rule 3).

   2. 'parent>package': '>=fixed' — parent-scoped, when multiple majors coexist and a specific parent pulls in the vulnerable major (see Rule 4).

   3. 'package@versionRange': fixedVersion — version-range-keyed, when multiple vulnerable major lines coexist and each needs its own targeted bump regardless of importer. The range lives in the key; the value is a fixed target version (no >= prefix). Example from this repo (pnpm-workspace.yaml):

      'brace-expansion@>=4.0.0 <5.0.5': 5.0.5
      'brace-expansion@>=2.0.0 <2.0.3': 2.0.3
      'brace-expansion@<1.1.13': 1.1.14
      

      Prefer this form over many parent-scoped entries when the advisory spans multiple majors. Avoid it when a single-major top-level (form 1) or one parent>package (form 2) would do — those are easier to read.

After the change:

1. Run pnpm install to regenerate the lockfile
2. Re-run grype . --config .grype.yaml to verify the vulnerability is gone

Step 5 — Add a Grype Ignore (Last Resort)

Only if ALL of the following are true:

• The upgrade/override did not resolve the issue or would break functionality
• The vulnerable package is not a production dependency (only in devDependencies tree)
• The vulnerability's attack vector does not apply to a desktop Electron app

Add an ignore entry to .grype.yaml:

ignore:
  - vulnerability: CVE-XXXX-XXXXX
    package:
      name: <package-name>
      type: npm
    reason: >-
      <package-name> is a dev-only dependency (used by <parent-package> for <purpose>).
      <CVE-ID> requires <attack-vector> which does not apply to this Electron desktop app.
      Fix requires a breaking major upgrade of <parent> that cannot be safely applied.

Every ignore MUST include a reason explaining why it is safe to suppress.

Step 6 — Impact Analysis

For each vulnerability processed, write a summary containing:

Output

When running in plan mode (Phase 1): write all findings and proposed actions to remediation-plan.md in the repository root. Do not modify project files.

When running in implementation mode (Phase 2): read remediation-plan.md, apply the changes to pnpm-workspace.yaml (overrides / audit ignores), package.json (direct dep upgrades), pnpm-lock.yaml, and .grype.yaml as needed, then verify with grype. Update remediation-plan.md with verification results.

Also write a concise pr-body.md for the pull request description using this exact structure:

## Summary

<1-2 sentence description of what was fixed and why>

## Changes

| CVE | Package | Severity | Production | Action | Verified  |
| --- | ------- | -------- | ---------- | ------ | --------- |
| ... | ...     | ...      | Yes/No     | ...    | Pass/Fail |

## Files Modified

- `pnpm-workspace.yaml`: <what changed, e.g. added override / ignoreGhsas entry>
- `package.json`: <what changed, e.g. bumped direct dep>
- `.grype.yaml`: <what changed, if applicable>

## Verification

- `pnpm audit --prod`: <Pass/Fail>
- `grype . --config .grype.yaml`: <Pass/Fail>

Keep the PR body short and scannable. The full analysis stays in remediation-plan.md for reference but is not used in the PR.

Also write a single-line conventional-commit-style title to remediation-title.txt summarizing the specific changes, for example:

• fix(security): upgrade tar to 7.5.7, override lodash (CVE-2025-1234, CVE-2025-5678)
• fix(security): add grype ignore for tmp (dev-only, CVE-2025-9999)
• fix(security): override fast-xml-parser >=5.5.9 (CVE-2025-4321)

Keep it under 72 characters. Mention the key packages and CVEs, not a generic description.

Important Constraints

• Do NOT run git commands — git operations are handled by the CI workflow
• Do NOT run gh commands — PR creation is handled by the CI workflow
• Do NOT modify .env files
• Always run pnpm install after modifying package.json or pnpm-workspace.yaml to regenerate the lockfile
• Always re-run grype . --config .grype.yaml after each remediation to verify
• Prefer the least invasive fix: upgrade > override > ignore