Security Vuln Remediation

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