CVE Remediation

Use this skill to remediate dependency vulnerabilities with minimal, evidence-backed package changes.

Operating Rules

1. Read AGENTS.md and relevant repo Codex skills before editing.
2. Read scoped AGENTS.md and required docs for affected components, especially src/apps_sdk/AGENTS.md for Apps SDK widget work.
3. Start from git status -sb; do not mix remediation into an unrelated dirty worktree or stale branch.
4. Prefer package manifest and lockfile changes only. Do not change source code unless no compatible package-only fix exists.
5. Keep the affected-library scope tight. Do not opportunistically upgrade unrelated dependencies.
6. Never hand-edit generated lockfiles. Regenerate them with the package manager.

Identify Scope

Map the finding to the owning workspace and package manager:

• Root backend: pyproject.toml, uv.lock
• Agents: src/agents/pyproject.toml, src/agents/uv.lock
• Demo UI: src/ui/package.json, src/ui/pnpm-lock.yaml
• Apps SDK widget: src/apps_sdk/web/package.json, src/apps_sdk/web/pnpm-lock.yaml

Use rg, pnpm list, pnpm why, uv tree, and lockfile searches to find all resolved copies of the vulnerable package.

Verify Advisory Data

Treat scanner output as the starting signal, not the complete fix plan.

1. Verify affected and fixed versions using public or primary sources where possible:
   • OSV API
   • GitHub Security Advisories
   • npm or PyPI registry metadata
   • official release notes or changelogs
2. Query exact candidate versions before introducing them.
3. Do not assume "newest" is safe; newer versions can have different advisories or compatibility issues.
4. If BDSA or commercial scanner details are not public, say that explicitly and use public advisory plus registry evidence.
5. Avoid full pnpm audit or equivalent external audit uploads unless the user explicitly approves sharing the workspace dependency graph. Prefer per-package OSV queries for exact packages and versions.

Example OSV querybatch pattern:

curl -sS -X POST https://api.osv.dev/v1/querybatch \
  -H 'Content-Type: application/json' \
  -d '{"queries":[{"version":"VERSION","package":{"name":"PACKAGE","ecosystem":"npm"}}]}'

Choose the Fix

1. Choose the smallest safe compatible version that clears the finding.
2. For direct dependencies, update the manifest range and regenerate the lockfile.
3. For transitive dependencies, prefer the parent package's compatible update when an override causes build or runtime failures.
4. Use overrides only when they are compatible, tested, and clearly scoped.
5. If a candidate fails validation, try the next safe package-only path and document why the failed candidate was rejected.
6. If no safe package-only path exists, stop and explain the tradeoff before changing source code.

Apply Package Updates

For pnpm workspaces:

pnpm install --lockfile-only
pnpm install --frozen-lockfile

For uv workspaces:

uv lock --upgrade-package PACKAGE

Use the repo's existing dependency style: keep existing overrides, package managers, and version range conventions unless the advisory requires a different approach.

Prove the Vulnerable Version Is Gone

After regenerating locks, verify both absence and final resolution:

rg -n 'VULNERABLE_VERSION|package@VULNERABLE_VERSION|package: VULNERABLE_VERSION' <changed package and lock files>
pnpm list PACKAGE --depth 10
pnpm why PACKAGE
uv tree | rg 'PACKAGE|VULNERABLE_VERSION'

For pnpm, remember pnpm why may return no output when a package is only an optional peer or no longer installed. Pair it with lockfile scans and pnpm list.

Validate

Run affected CI parity checks. Broaden when shared tooling or lockfiles affect multiple areas.

Frontend UI (src/ui):

pnpm lint
pnpm format:check
pnpm typecheck
pnpm test:run

Apps SDK widget (src/apps_sdk/web):

pnpm lint
pnpm typecheck
pnpm test:run
pnpm build

Backend:

uv run ruff check src/merchant/ src/payment/ src/apps_sdk/ tests/
uv run ruff format --check src/merchant/ src/payment/ src/apps_sdk/ tests/
uv run pyright src/merchant/ src/payment/ src/apps_sdk/
uv run pytest tests/ -v --tb=short

Always run:

git diff --check

Browser or runtime verification is only required when runtime behavior, API behavior, UI behavior, or integration flow changes. Package-only build tool changes still need build and test evidence.

Git and PR

1. Create or switch to a codex/ branch based on current origin/main unless the user directs otherwise.
2. Stage only intended package manifests and lockfiles.
3. Commit with a dependency-focused message.
4. Push and open a PR when requested.
5. PR body must include:
   • summary of package changes
   • advisory/version evidence
   • exact tests and outcomes
   • any skipped checks and why
   • scanner identifier when available

Before final response, run git status -sb and report the branch, commit, PR URL, tests, and any residual warnings.