submariner-io/shipyard/cve-fix

CVE Fix Workflow

This skill scans Go modules for CVEs using grype, updates go.mod to fix each one, verifies fixes with a rescan gate, and prints a ready-to-run PR command. Use it on any Go repository with a .grype.yaml or standard layout.

Prerequisites

The workflow uses the following tools. Install the command-line prerequisites; Grype can be installed automatically and the LLM reviewer is optional.

• grype — the skill installs a checksum-verified latest release into

skills/cve-fix/bin/ when needed; no manual install or sudo is required. Set CVE_FIX_GRYPE_VERSION=vX.Y.Z to pin a reproducible version. The fallback uses the same requested version and checks the container's reported version before accepting its scan. Without an explicit version, the default fallback pins Grype v0.112.0 to a reviewed multi-architecture SHA256 digest. Set CVE_FIX_GRYPE_IMAGE to a reviewed digest for a mirror. Other explicitly requested versions use their release tag; set an image digest as well when those versions require identical images across runs. Advance the default digest in the helper and this example only after regression checks and live scan comparisons pass. A Docker/Podman fallback remains usable when local installation is unavailable:

``bash scanner_digest='sha256:391bfda62888fb4e98ff5c4c81598f7431a3c1eac3f8519d69d1ff00df247c1d' scanner_image="anchore/grype:v0.112.0@$scanner_digest" docker volume create grype-db && \ docker run --rm -e GRYPE_DB_CACHE_DIR=/root/.cache/grype/db \ -v grype-db:/root/.cache/grype "$scanner_image" db update ``

• bash 4+ — mapfile and other builtins require bash 4+. macOS ships

bash 3.2 (GPLv2); install a newer version:

``bash brew install bash ``

Linux (Ubuntu 22.04+) ships bash 5.1 and is unaffected.

• claude or codex CLI — optional; used for LLM-assisted review of unresolved

CVEs. The Make interface uses Claude by default for compatibility; select Codex with CVE_FIX_AGENT=codex. The remediation and verification gates remain usable without the selected CLI: the workflow falls back to deterministic companion evidence and does not report an unconfirmed result as clean. Install either optional reviewer via:

``bash npm install -g @anthropic-ai/claude-code npm install -g @openai/codex ``

• go — Go toolchain (go get, go mod tidy); install from <https://go.dev/dl/>

• jq — used to read Go's JSON module graph output and scanner results.

• python3 — used by the configuration parser and verification helpers.

• base64 — used to pass structured CVE requirements between the scripts.

• make — used for make clean, make unit, and make -C skills/cve-fix

• timeout — GNU coreutils; bounds builds, tests, and optional reviewers.

On macOS, install coreutils and add its libexec/gnubin directory to PATH so the scripts can invoke timeout (the prefixed gtimeout name alone is insufficient).

Invoke the documented entry points instead of reproducing individual remediation steps ad hoc. The scripts own mutation, verification, and rollback behavior.

Single Repo (default)

If the arguments do NOT contain all, resolve the actual loaded SKILL.md path, then use its sibling scripts/ directory. In the source checkout that directory is skills/cve-fix/scripts; in an installed plugin it is next to the loaded skill. Set CVE_SCRIPTS to that resolved absolute directory and verify that fix-all.sh exists there.

For Claude Code's existing standalone installation, if the runtime does not expose the loaded path, retain the established fallback: use skills/cve-fix/scripts from the current checkout when present, otherwise ~/.claude/plugins/cve-fix/scripts. Do not use this fallback to select an arbitrary second copy when the loaded path is known.

Take the optional repository and branch directly from the user's invocation, preserving their order. Invoke the script once with quoted positional arguments. Do not depend on $ARGUMENTS, a manifest-injected environment variable, or a home-directory search. The script already accepts zero, one, or two arguments and validates them itself:

# CVE_SCRIPTS is the resolved absolute scripts directory.
# Current repository and branch
bash "$CVE_SCRIPTS/fix-all.sh"
 
# Current repository, specified branch
bash "$CVE_SCRIPTS/fix-all.sh" "0.23"
 
# Named or absolute-path repository, specified branch
bash "$CVE_SCRIPTS/fix-all.sh" "myrepo" "0.24"

fix-all.sh does everything: detect config, create fix branch, scan for CVEs, fix each deterministically, run tests, agent-review all results, and print the PR command.

When a project build is configured, each dependency update must pass it before commit. An incompatible update rolls back and leaves its CVEs actionable for review. Findings already removed by another dependency update require current scanner evidence before being reported as fixed.

Vendoring belongs to each tracked module. A scoped dependency update regenerates and commits that module's vendor tree, including nested trees when the root is not vendored; rejected updates restore the original trees and untracked files. Unchanged sibling module and vendor files remain outside the update.

Exit code 0: All CVEs addressed. Review commits and run the printed PR command.

Exit code 2: The run needs attention:

• Counted partial fix — GATE_REMAINING > 0: CVEs were confirmed present after

all fix attempts. The PR command is still emitted (with a "Partial CVE fix" title) when the other verification and repository policy gates pass; merge when acceptable.

• Infrastructure failure — gate scan or tests could not complete: results are

unconfirmed. The PR command is suppressed; resolve the reported errors and re-run.

• PR readiness failure — the base fetch or final refresh failed, the base moved,

or a commit lacks a sign-off: the PR command is suppressed even when the CVE scan is clean. Resolve the reported prerequisite and re-run.

Exit code 1: Error (skill setup or invocation problem).

These are script exit codes. GNU Make returns 2 when a recipe fails, including setup errors. The all recipe keeps each script's status and gives setup errors priority over partial results; read its error output or invoke the scripts directly when the exact exit code is needed.

Multi-Repo ("all")

If the arguments contain all (e.g., /cve-fix all 0.23 or $shipyard:cve-fix all 0.23), do NOT run the single-repository commands above. Instead:

1. Resolve the actual loaded SKILL.md path and use its sibling scripts/

directory. When Claude Code does not expose that path, use the same established standalone-install fallback as the single-repository flow.

1. Find the repo registry using the resolution order below.
2. Extract the branch from the remaining arguments (e.g., 0.23).
3. Delegate one worker per repository when native delegation is available;

otherwise process the repositories sequentially. Each worker runs bash "$CVE_SCRIPTS/fix-all.sh" "NAME" "BRANCH" directly and must not invoke this skill recursively.

Report per repo: CVEs found, fixed, ignored, and PR command. Workers clean up their own child processes. Never run broad process/container cleanup from one worker because other repository runs may still be active.

Installation and Invocation

To use the skill outside the shipyard source checkout, install the existing Shipyard plugin through its marketplace:

codex plugin marketplace add submariner-io/shipyard
codex plugin add shipyard@submariner

Codex invokes the installed skill as $shipyard:cve-fix. The existing Claude installation remains supported:

cp -r skills/cve-fix ~/.claude/plugins/cve-fix

After installation, /cve-fix works in Claude Code and $shipyard:cve-fix works in Codex. The make -C skills/cve-fix interface still works from the source tree.

Usage

Claude Code uses /cve-fix; Codex uses $shipyard:cve-fix. In either runtime:

• cve-fix - current repo, current branch
• cve-fix 0.23 - current repo, specified branch
• cve-fix master - current repo, OpenShift master branch
• cve-fix myrepo 0.24 - repo name from repos.yaml
• cve-fix /absolute/path/to/repo 0.24 - absolute path
• cve-fix all 0.23 - all repos in repos.yaml

Branches may precede or follow an explicit repository. In the current repo, standard main/master names and locally known feature branches are supported. Arguments are order-independent. Short versions like 0.23 auto-expand to release-0.23. Repos are absolute paths or names from repos.yaml.

Registry resolution order (first match wins):

1. $CVE_FIX_REPOS environment variable (any path)
2. ${XDG_CONFIG_HOME:-~/.config}/cve-fix/repos.yaml
3. repos.yaml in the skill directory (git-ignored)
4. No registry: absolute repository paths still work; named/all runs fail with

setup instructions. repos.yaml.example is a template, not executable input.

To use repo names, resolve CVE_SCRIPTS as described above, then create a registry file and populate it with your repos:

# Option A: XDG location (shared across skill installations, recommended)
registry_dir="${XDG_CONFIG_HOME:-$HOME/.config}/cve-fix"
mkdir -p "$registry_dir"
cp "$CVE_SCRIPTS/../repos.yaml.example" "$registry_dir/repos.yaml"
# Edit "$registry_dir/repos.yaml"
 
# Option B: in-repo location (git-ignored)
cp "$CVE_SCRIPTS/../repos.yaml.example" "$CVE_SCRIPTS/../repos.yaml"
# Edit "$CVE_SCRIPTS/../repos.yaml"

Absolute paths always work without any registry.

From the source checkout:

make -C skills/cve-fix fix REPO=myrepo BRANCH=0.24                # Claude reviewer (default)
make -C skills/cve-fix fix REPO=myrepo BRANCH=0.24 CVE_FIX_AGENT=codex
make -C skills/cve-fix fix REPO=/absolute/path BRANCH=0.24         # absolute path
make -C skills/cve-fix all BRANCH=0.23 CVE_FIX_AGENT=codex        # all repos with Codex
make -C skills/cve-fix test                                        # run unit tests

CVE_FIX_AGENT accepts exactly claude or codex. It defaults to claude, so existing Make invocations are unchanged. CVE_FIX_MODEL, when set, selects the model for whichever reviewer is active. If the selected CLI is unavailable, the existing deterministic-evidence fallback remains in effect.

Per-Repo Configuration

Place a .cve-fix.yaml file in the repo root to override auto-detected settings. All fields are optional — omitted fields use auto-detected defaults.

Common Issues

Empty scanner catalog

Grype can return zero findings after its cataloger skips the entire checkout, including checkouts under /dev/shm on Linux. The workflow rejects a reported zero-package catalog when tracked Go modules declare dependencies, and attempts the container fallback. If both scans lack coverage, move the checkout to a normal filesystem path or correct the cataloger exclusions before rerunning.