
compliance
Security compliance and vulnerability analysis tools for Go projects
- version
- 0.4.1
- GitHub stars
- 123
Install
/plugin install compliance@ai-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceSkills 9
analyze-cve
Performs comprehensive security vulnerability analysis for Go projects. Given a CVE identifier — supplied directly, or resolved from a Jira ticket — it resolves and clones the affected repository, gathers vulnerability intelligence, analyzes the codebase for impact, generates a risk report, optionally applies fixes, and optionally opens a GitHub pull request after a verified fix.
Explicit invocation uses the following argument syntax:
/compliance:analyze-cve <CVE-ID> [--repo=<url-or-component>] [--algo=vta|rta|cha|static] [--auto-approve=yes|no]
/compliance:analyze-cve --jira=<PROJ-NNN> [--repo=...] [--algo=...] [--auto-approve=yes|no]
/compliance:analyze-cve --jql="<JQL query>" [--repo=...] [--algo=...] [--auto-approve=yes|no]
Repository resolution works in four ways, in priority order: (1) an explicit --repo= (full URL or short image/component name), (2) in direct-CVE mode only, exactly one pre-cloned repository already present in this workspace's repos/ directory when --repo= was not passed — in Jira/JQL mode that sole candidate is instead validated against the ticket's resolved image/branch before reuse, never assumed, (3) an image name extracted from a Jira ticket's summary/labels/custom fields when --jira=/--jql= was used, or (4) an interactive prompt for the repository URL or image name. See Phase 0.7 in the implementation reference for the full resolution and cloning logic.
Designed for both interactive use and headless execution (e.g. claude --print "/compliance:analyze-cve --jira=OCPBUGS-12345 --auto-approve=yes") for scheduled/periodic runs.
Arguments
Exactly one of the following input modes is required:
<CVE-ID>— Direct CVE identifier (format:CVE-YYYY-NNNNN, case-insensitive). Use when you already know the CVE.--jira=PROJ-NNN— Jira ticket key (e.g.--jira=OCPBUGS-12345). This skill fetches the ticket and extracts the CVE ID, affected image name, and enrichment context (CVSS, CWE, priority, workarounds) from it.--jql="..."— JQL query (e.g.--jql="project = OCPBUGS AND labels = needs-cve-analysis"). Fetches a batch of matching issues, filters out any already labeledai-cve-analyzed, and processes exactly one of the remainder per run (see Phase 0.3). Re-running the same JQL periodically works through the queue over multiple invocations.
Optional flags:
--repo=<url-or-component>: Repository to analyze. Accepts:- A full GitHub URL:
--repo=https://github.com/openshift/cert-manager-operator - A short image/component name:
--repo=cert-manager-operator-rhel9(resolved via the image-repo-mapping skill) - If omitted, Phase 0.7 checks for exactly one pre-cloned repo in this workspace first, then resolves from the Jira ticket's image name (if
--jira/--jqlwas used), then prompts the user.
- A full GitHub URL:
--algo(default:vta): Call graph construction algorithm.vta— Most precise, fewest false positives (recommended)rta— Good balance of precision and speedcha— Fast, less precisestatic— Fastest, least precise
--auto-approve=yes|no(default:no): Run end-to-end without interactive approval prompts. See Autonomous Mode in the implementation reference. Intended for scheduled/headless runs.
Running This Skill
Read and follow references/implementation.md for the full phase-by-phase procedure once the arguments above are parsed — do not paraphrase or improvise it. It covers, in order:
- Autonomous Mode — the full
AUTO_APPROVEdecision table (what's gated vs. what always hard-fails) - Security — Credential Handling — rules that apply to every command this skill runs
- Runtime Configuration —
AI_HELPERS_WORKSPACE,FORK_ORG - Implementation — Phase 0 (setup) through Phase 6 (PR creation), including the Repo Guard and each sub-skill's input/output contract
- Return Value — the report format this skill produces
Examples
-
Basic CVE analysis against an explicit repo:
/compliance:analyze-cve CVE-2024-45338 --repo=https://github.com/openshift/cert-manager-operator -
With specific algorithm:
/compliance:analyze-cve CVE-2024-45338 --repo=https://github.com/openshift/cert-manager-operator --algo=rta -
Starting from a Jira ticket (repo/branch resolved automatically from the ticket's image name):
/compliance:analyze-cve --jira=OCPBUGS-12345 -
Unattended run from a JQL queue, applying fixes and opening a PR without prompts:
claude --print "/compliance:analyze-cve --jql=\"project = OCPBUGS AND labels = needs-cve-analysis ORDER BY created ASC\" --auto-approve=yes"
Prerequisites
All tools below are required. This skill exits with an error if any are missing.
# Install all required Go tools
go install golang.org/x/vuln/cmd/govulncheck@latest
go install golang.org/x/tools/cmd/callgraph@latest
go install golang.org/x/tools/cmd/digraph@latest
# git is also required (Phase 0.7 repository cloning) — install via your OS package manager
Optional:
graphvizfor visual call graph generation (brew install graphvizorsudo apt-get install graphviz)gh(GitHub CLI, authenticated viagh auth login) for Phase 6 pull-request creation. Missingghdoes not fail Phase 0 — analysis and local fixes still run; Phase 6 is skipped until it's available.- An Atlassian MCP server (e.g. the
jiraplugin's bundled Rovo MCP) orjira-clifor--jira=/--jql=input modes and posting reports back to Jira
Internet access is recommended for CVE data fetching but not required if you can provide CVE details manually.
Notes
- Focuses on Go-specific vulnerabilities.
- Resolves and clones the target repository automatically — via
--repo=, Jira image-name mapping, or reusing a repo already cloned into.work/compliance/analyze-cve/repos/by a previous run — see Phase 0.7. All analysis and fix-application phases run against that clonedREPO_DIR, not the directory this skill happened to be invoked from. - Falls back to user-provided information if internet access fails.
- Does NOT make changes, commits, or pull requests without explicit approval — either interactive, or given once upfront via
--auto-approve=yes(see Autonomous Mode). - Reports are saved locally (
.work/compliance/analyze-cve/, gitignored) and not committed to git — see Runtime Configuration to relocate this base directory. - Never process or disclose embargoed CVEs — if a Jira ticket's Embargo Status is
True, this skill stops immediately and outputs nothing about the ticket.
Call Graph Reachability Analysis
Provides highest-confidence vulnerability assessment by proving whether vulnerable functions can actually be reached during program execution.
When to Use This Skill
Use this skill when:
- You need definitive proof that a vulnerable function is or isn't reachable
- Medium/high confidence analysis shows possible vulnerability but needs confirmation
- Generating evidence for security compliance or audit requirements
govulncheckis unavailable or didn't find the CVE- You need visual proof of execution paths for stakeholders
Prerequisites
Required Tools
callgraph:go install golang.org/x/tools/cmd/callgraph@latestdigraph:go install golang.org/x/tools/cmd/digraph@latest- Go workspace with
go.modfile
Optional Tools
graphviz(for visualization):brew install graphviz(macOS) orsudo apt-get install graphviz(Linux)sfdpordotcommand (part of graphviz)
Input Requirements
- CVE vulnerable function signature (e.g.,
<package-path>.<function-name>) - Package path from CVE analysis
- Workspace path to analyze
- Algorithm preference (optional, default:
vta) — passed via--algofrom parent command CVE_ID— used to construct the output directoryOUT_DIR(optional, default:${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}) — where artifacts are written; same workspace base as Phase 0.7'sREPOS_BASE
Critical Rules
- Always use
timeout -k 10— plaintimeoutsends SIGTERM butcallgraphcan ignore it when stuck in SSA construction or type resolution.-k 10sends SIGKILL after 10s grace, guaranteeing termination.- Never run
callgraphon./...for repos with more than ~50 packages. Target specific main packages (e.g../cmd/controller,./main.go) and let the tool pull in transitive deps automatically.- Always redirect output to a file (
> file 2>&1). Never pipe callgraph output to another command — if the reader closes, callgraph can hang on SIGPIPE.
Timeout and Algorithm Convention
- Use the algorithm specified by the user via
--algo(default:vta). - All
callgraphinvocations usetimeout -k 10 300(5 minutes + 10s force-kill) to prevent hanging. - Scope: target the specific main package (e.g.
./cmd/controller), not./.... Thecallgraphtool resolves transitive deps automatically — there is no need to include the entire repo. - If the chosen algorithm times out: fall back to the next faster algorithm (
vta→rta→cha), then narrow scope further to a single binary entry point.
Implementation Steps
Step 1: Verify Tools Are Available
# Check for callgraph
which callgraph || echo "callgraph not found - install with: go install golang.org/x/tools/cmd/callgraph@latest"
# Check for digraph
which digraph || echo "digraph not found - install with: go install golang.org/x/tools/cmd/digraph@latest"
# Optional: Check for graphviz
which sfdp || echo "graphviz not found - visual graphs won't be generated (optional)"
Decision Point:
- IF callgraph OR digraph missing → Exit this skill, return to parent analysis
- IF both present → Continue
Step 2: Identify Main Packages and Build Call Graph
First, discover the main packages that serve as entry points:
# Find main packages
MAIN_PKGS=$(find . -name "main.go" -exec dirname {} \; | sort -u)
echo "Main packages: ${MAIN_PKGS}"
Pick the most relevant main package for the analysis (typically the controller or server binary, not CLI tools or test helpers). If unsure, prefer the package that imports the vulnerable package's parent tree.
# Select exactly one TARGET_PKG before running callgraph
if [ -z "${TARGET_PKG:-}" ]; then
TARGET_PKG=$(printf '%s\n' ${MAIN_PKGS} | grep -E '(^|/)(cmd/)?(controller|manager|operator|server|main)(/|$)' | head -1)
[ -z "${TARGET_PKG}" ] && TARGET_PKG=$(printf '%s\n' ${MAIN_PKGS} | head -1)
fi
# Normalize to a package path callgraph accepts (./cmd/foo or .)
case "${TARGET_PKG}" in
.|./) TARGET_PKG="." ;;
*) TARGET_PKG="./${TARGET_PKG#./}" ;;
esac
if [ -z "${TARGET_PKG}" ] || [ "${TARGET_PKG}" = "./" ]; then
echo "ERROR: No main package found for call graph analysis"
exit 1
fi
echo "Selected TARGET_PKG=${TARGET_PKG}"
ALGO="${USER_ALGO:-vta}"
OUT_DIR="${OUT_DIR:-${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}}"
mkdir -p "${OUT_DIR}"
# TARGET_PKG is the specific main package (e.g. ./cmd/controller, .)
# NEVER use ./... — it causes VTA to explode on large repos
echo "Building call graph: algo=${ALGO}, target=${TARGET_PKG}"
timeout -k 10 300 env CGO_ENABLED=0 callgraph -algo "${ALGO}" -format=digraph "${TARGET_PKG}" > "${OUT_DIR}/callgraph.txt" 2>&1
CG_EXIT=$?
echo "callgraph exit: ${CG_EXIT}, lines: $(wc -l < "${OUT_DIR}/callgraph.txt")"
Progressive fallback if the command times out or fails:
# Fallback 1: faster algorithm
if [ $CG_EXIT -eq 124 ] || [ $CG_EXIT -eq 137 ]; then
echo "⚠ ${ALGO} timed out — falling back to rta"
timeout -k 10 300 env CGO_ENABLED=0 callgraph -algo rta -format=digraph "${TARGET_PKG}" > "${OUT_DIR}/callgraph.txt" 2>&1
CG_EXIT=$?
fi
# Fallback 2: fastest algorithm
if [ $CG_EXIT -eq 124 ] || [ $CG_EXIT -eq 137 ]; then
echo "⚠ rta timed out — falling back to cha"
timeout -k 10 300 env CGO_ENABLED=0 callgraph -algo cha -format=digraph "${TARGET_PKG}" > "${OUT_DIR}/callgraph.txt" 2>&1
CG_EXIT=$?
fi
if [ $CG_EXIT -eq 124 ] || [ $CG_EXIT -eq 137 ]; then
echo "✗ All algorithms timed out — call graph analysis skipped"
fi
Error Handling:
- IF build fails (compilation errors) → Note in report that call graph cannot be built
- IF command times out → Fallback chain:
vta→rta→cha, all on the same target package - IF all algorithms time out → Skip call graph, assign NEEDS_REVIEW
- IF successful → Continue to Step 3
Output: ${OUT_DIR}/callgraph.txt containing the call graph rooted at the target binary
Step 3: Check if Vulnerable Function Exists in Graph
Extract the vulnerable function signature from CVE details.
# Search for exact function in the cached call graph
VULN_FUNC="<package-path>.<vulnerable-function>"
cat "${OUT_DIR}/callgraph.txt" | digraph nodes | grep "${VULN_FUNC}$"
Decision Point:
- IF function found in this
TARGET_PKGgraph → Continue to Step 4 - IF function NOT found in this graph → Try the next candidate from
MAIN_PKGS(differentTARGET_PKG) before concluding - IF every examined main package shows no path → Return NEEDS_REVIEW (or MEDIUM if other evidence exists) — do not assign LOW RISK from a single unexamined or inconclusive graph
Step 4: Find Execution Paths from Entry Points
Search for paths from main entry points to the vulnerable function.
# Find path from main() to vulnerable function using cached call graph
ENTRY_POINT="command-line-arguments.main"
VULN_FUNC="<package-path>.<vulnerable-function>"
cat "${OUT_DIR}/callgraph.txt" | \
digraph somepath "${ENTRY_POINT}" "${VULN_FUNC}"
Alternative Entry Points to Check:
command-line-arguments.main(main program)- Test entry points:
*_test.gotest functions - Init functions:
*.init - HTTP handlers if it's a web service
Interpretation:
- IF path found → Vulnerable function IS reachable → HIGH RISK
- IF no path found → Check alternative entry points
- IF still no path → Function may be in unreachable code → MEDIUM RISK
Output: Text representation of call chain or empty result
Step 5: Generate DOT Graph for Visualization
If path exists, generate visual representation:
# Generate DOT format from cached call graph
cat "${OUT_DIR}/callgraph.txt" | \
digraph somepath "${ENTRY_POINT}" "${VULN_FUNC}" | \
digraph to dot > "${OUT_DIR}/callgraph.dot"
# Convert to SVG (if graphviz available)
if which sfdp > /dev/null; then
sfdp -Tsvg -o"${OUT_DIR}/callgraph.svg" -Goverlap=scale "${OUT_DIR}/callgraph.dot"
echo "Visual graph saved to: ${OUT_DIR}/callgraph.svg"
else
echo "Graphviz not available - DOT file saved to: ${OUT_DIR}/callgraph.dot"
fi
Output Files:
${OUT_DIR}/callgraph.dot- DOT notation of call path${OUT_DIR}/callgraph.svg- Visual graph (if graphviz available)
Step 6: Parse and Format Call Chain
Extract human-readable call chain from digraph output:
# Get call chain as text from cached call graph
cat "${OUT_DIR}/callgraph.txt" | \
digraph somepath "${ENTRY_POINT}" "${VULN_FUNC}" | \
digraph to dot | \
grep " -> " | \
sed 's/"//g' | \
sed 's/;//g'
Example Output:
command-line-arguments.main -> <package-path>.Handler
<package-path>.Handler -> <package-path>.ProcessFunction
<package-path>.ProcessFunction -> <vulnerable-package>.<vulnerable-function>
Format for Report:
Execution Path Found:
main → Handler → ProcessFunction → <vulnerable-function> (VULNERABLE)
Step 7: Assess Risk Level
HIGH RISK:
- Reachable path from main() to vulnerable function
- Action: Proceed to remediation
MEDIUM RISK:
- Function in graph but no direct path from main()
- Action: Recommend manual review + remediation
LOW RISK:
- Function not found in call graph
- Action: Recommend manual review to confirm
Return Value
Return structured result to parent analysis:
{
"method": "call-graph-reachability",
"algorithm": "vta",
"vulnerable_function": "<package-path>.<vulnerable-function>",
"found_in_graph": true,
"reachable_from_main": true,
"call_chain": "main → Handler → ProcessFunction → <vulnerable-function>",
"risk_level": "HIGH",
"evidence": {
"callgraph_file": "${OUT_DIR}/callgraph.txt",
"dot_file": "${OUT_DIR}/callgraph.dot",
"svg_file": "${OUT_DIR}/callgraph.svg"
}
}
Error Handling
Build Failures
- IF project doesn't compile → Note in report, cannot perform call graph analysis
- Suggest: Fix compilation errors first
Very Large Codebases
- IF chosen algorithm times out (>5 minutes) → Fall back to next faster algorithm (
vta→rta→cha) - IF all algorithms time out on the chosen main package → Try a narrower entry point (single binary)
- IF still failing → Skip call graph, assign NEEDS_REVIEW, document the limitation
- NEVER use
./...as scope — always target a specific main package
Missing Entry Points
- IF
command-line-arguments.mainnot found → Look for other entry points - Web services: Check HTTP handler registrations
- Libraries: Call graph analysis may not be applicable
Tool Installation Issues
- IF tools cannot be installed → Fall back to lower confidence methods
- Document limitation in final report
Example: Generic Analysis Workflow
# Setup
CVE_ID="CVE-YYYY-NNNNN"
OUT_DIR="${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}"
mkdir -p "${OUT_DIR}"
# Step 1: Build call graph targeting a specific main package
timeout -k 10 300 env CGO_ENABLED=0 callgraph -algo vta -format=digraph ./cmd/controller > "${OUT_DIR}/callgraph.txt" 2>&1
# Step 2: Check if function is called
digraph nodes < "${OUT_DIR}/callgraph.txt" | grep "<package-path>.<vulnerable-function>$"
# Step 3: Find path from main
digraph somepath command-line-arguments.main "<package-path>.<vulnerable-function>" < "${OUT_DIR}/callgraph.txt"
# Step 4: Generate visual graph (if graphviz available)
digraph somepath command-line-arguments.main "<package-path>.<vulnerable-function>" < "${OUT_DIR}/callgraph.txt" | \
digraph to dot | sfdp -Tsvg -o"${OUT_DIR}/callgraph.svg"
# Result: HIGH RISK — reachable path found
Integration with analyze-cve
This skill is called from Method 5 of the codebase-impact-analysis skill.
When to Invoke:
- After basic dependency checks show package is present
- Mandatory whenever the vulnerable package is in
go.mod(see codebase-impact-analysis Method 5) — not just for "highest confidence" - When tools are available (checked in Phase 0)
Return to Parent:
- Provide risk level (HIGH/MEDIUM/LOW)
- Include evidence (call chain, graph files)
- Update report with reachability findings
Codebase Impact Analysis
Determines whether a Go codebase is impacted by a specific CVE by applying multiple analysis methods with increasing confidence, collecting evidence, and assigning a risk level.
When to Use This Skill
Use this skill when:
- A CVE profile has been gathered (from the cve-intelligence-gathering skill)
- You need to determine if the current Go project is affected
- You need to assign a risk level with supporting evidence
Prerequisites
Required Tools (validated in Phase 0 of the analyze-cve skill)
gotoolchain withgo.modin workspace rootgovulncheck:go install golang.org/x/vuln/cmd/govulncheck@latestcallgraph:go install golang.org/x/tools/cmd/callgraph@latestdigraph:go install golang.org/x/tools/cmd/digraph@latest
Required Inputs
From Phase 1 (cve-intelligence-gathering skill):
- CVE ID
- Affected package/module name(s)
- Vulnerable version range
- Fixed version (if available)
- Vulnerable function signatures (if known)
From Parent Command:
--algopreference for call graph analysis (default:vta)REPO_DIR— the repository cloned in Phase 0.7 (e.g..work/compliance/analyze-cve/repos/hypershift). All commands below run against this directory, not necessarily the shell's current working directory.
Implementation Steps
Step 1: Identify Go Module Dependencies
# Parse dependencies from go.mod
go list -m all
# Get detailed dependency info
go list -m -json all
- Read
go.modfrom workspace root - Parse direct and indirect dependencies
- Extract module versions
Step 2: Cross-Reference Vulnerable Packages
Apply the following methods in order. Each provides increasing confidence.
Method 1: Dependency Matching
- Compare CVE-affected packages with
go.moddependencies - Check if affected package versions are in use
- Account for version ranges and semantic versioning
# Check if vulnerable package is a dependency
go list -m <vulnerable-package>
Decision Point:
- IF package NOT in dependencies → Skip to risk assignment (likely LOW RISK)
- IF package found → Continue to Method 2
Method 2: Go Vulnerability Scanner
CRITICAL RULES — read before running anything:
- Run govulncheck AT MOST ONCE per analysis run. Keep all Method 2 scratch and cache files under
${OUT_DIR}/(same per-CVE workspace as call-graph artifacts). The canonical result is${OUT_DIR}/govulncheck-source.txt— if it already exists and is non-empty for this run, read it and do not re-run.- Never pipe govulncheck to
head,tail,grep, or any other command. Always redirect to a file (> file 2>&1). Piping causes govulncheck to hang (SIGPIPE) when the reader closes.- "No findings" is a valid and final result — it means the CVE is not yet in the Go vuln database. Proceed to Method 3 immediately. Do NOT re-run in a different mode or format.
- Always use
timeout -k 10to force-kill if SIGTERM is ignored. Plaintimeoutsends SIGTERM but govulncheck can ignore it when stuck in package loading.
This method has 4 sequential steps. If any step fails or times out, skip the remaining steps and proceed to Method 3 — govulncheck is one signal, not the only one.
OUT_DIR="${OUT_DIR:-${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}}"
mkdir -p "${OUT_DIR}"
Step 2a — go.mod check (instant)
VULN_PKG="google.golang.org/grpc" # replace with actual vulnerable package
echo "=== Step 2a: go.mod check for ${VULN_PKG} ==="
grep "${VULN_PKG}" "${REPO_DIR}/go.mod" && echo "FOUND in go.mod" || echo "NOT FOUND in go.mod"
- IF NOT FOUND → record "package not in module graph" as LOW signal; skip Steps 2b–2d entirely; proceed to Method 3
- IF FOUND → note the version; continue
Step 2b — Pre-flight: download modules and verify toolchain (max 2 min)
Large repos (300+ deps like spiffe-spire) need all modules cached before govulncheck can load them. Separate this from the scan to isolate network issues from analysis hangs.
cd "${REPO_DIR}"
echo "=== Step 2b: Pre-flight ==="
# Download all modules (network-bound, do first)
echo "Downloading modules..."
timeout -k 10 120 env CGO_ENABLED=0 go mod download > "${OUT_DIR}/go-mod-download.txt" 2>&1
if [ $? -ne 0 ]; then
echo "⚠ go mod download failed or timed out — govulncheck may fail"
cat "${OUT_DIR}/go-mod-download.txt"
fi
# Verify the Go toolchain can load the package graph (CGO disabled first — many repos fail only with CGO enabled)
echo "Loading package list (CGO_ENABLED=0)..."
timeout -k 10 60 env CGO_ENABLED=0 go list ./... > "${OUT_DIR}/go-list-packages.txt" 2>&1
LIST_EXIT=$?
PKG_COUNT=$(wc -l < "${OUT_DIR}/go-list-packages.txt" 2>/dev/null || echo 0)
echo "Package count: ${PKG_COUNT}, exit code: ${LIST_EXIT}"
if [ $LIST_EXIT -ne 0 ]; then
echo "go list with CGO_ENABLED=0 failed — retrying after CGO probe (Step 2c) before skipping govulncheck"
fi
- IF
go listsucceeds withCGO_ENABLED=0→ continue to Step 2c, then 2d - IF
go liststill fails after Step 2c's CGO probe (with the chosenCGO_SETTING) → write the error to${OUT_DIR}/govulncheck-source.txt, skip Steps 2c–2d, proceed to Method 3
Step 2c — CGO probe (max 60s, skip if compiler absent)
echo "=== Step 2c: CGO probe ==="
CGO_SETTING=0
if command -v gcc >/dev/null 2>&1 || command -v cc >/dev/null 2>&1; then
timeout -k 10 60 env CGO_ENABLED=1 go build ./... > "${OUT_DIR}/cgo-probe.txt" 2>&1
if [ $? -eq 0 ]; then
CGO_SETTING=1
echo "✓ CGO works — using CGO_ENABLED=1"
else
echo "✗ CGO build failed — using CGO_ENABLED=0"
fi
else
echo "✗ No C compiler — using CGO_ENABLED=0"
fi
echo "CGO_ENABLED=${CGO_SETTING}"
if [ $LIST_EXIT -ne 0 ]; then
echo "Retrying go list with CGO_ENABLED=${CGO_SETTING}..."
timeout -k 10 60 env CGO_ENABLED=${CGO_SETTING} go list ./... > "${OUT_DIR}/go-list-packages.txt" 2>&1
LIST_EXIT=$?
PKG_COUNT=$(wc -l < "${OUT_DIR}/go-list-packages.txt" 2>/dev/null || echo 0)
echo "Retry package count: ${PKG_COUNT}, exit code: ${LIST_EXIT}"
if [ $LIST_EXIT -ne 0 ]; then
echo "✗ go list failed after CGO probe — skipping govulncheck entirely"
echo "go list failed (exit ${LIST_EXIT})" > "${OUT_DIR}/govulncheck-source.txt"
cat "${OUT_DIR}/go-list-packages.txt" >> "${OUT_DIR}/govulncheck-source.txt"
fi
fi
- IF
go liststill fails after retry →${OUT_DIR}/govulncheck-source.txtis populated; skip Step 2d and proceed to Method 3 - IF
go listsucceeds → continue
Step 2d — govulncheck scan (max 5 min)
Use -scan=package first (fast, checks if CVE is in vuln DB and package imported). Only escalate to symbol-level if package-level finds something.
if [ ! -s "${OUT_DIR}/govulncheck-source.txt" ] && [ $LIST_EXIT -eq 0 ]; then
# Package-level scan first (fast — no symbol resolution)
echo "=== Step 2d: govulncheck package scan ==="
timeout -k 10 120 env CGO_ENABLED=${CGO_SETTING} govulncheck -scan=package ./... > "${OUT_DIR}/govulncheck-package.txt" 2>&1
PKG_EXIT=$?
echo "govulncheck -scan=package exit: ${PKG_EXIT}"
cat "${OUT_DIR}/govulncheck-package.txt"
# Check if the package scan found anything worth escalating to symbol level
if grep -qi "Vulnerability\|finding\|${VULN_PKG}" "${OUT_DIR}/govulncheck-package.txt" 2>/dev/null; then
echo "=== Step 2d: govulncheck symbol scan (escalating — CVE found at package level) ==="
timeout -k 10 300 env CGO_ENABLED=${CGO_SETTING} govulncheck ./... > "${OUT_DIR}/govulncheck-source.txt" 2>&1
SOURCE_EXIT=$?
if [ $SOURCE_EXIT -eq 124 ] || [ $SOURCE_EXIT -eq 137 ]; then
echo "govulncheck symbol scan timed out or was killed — using package-level results"
cp "${OUT_DIR}/govulncheck-package.txt" "${OUT_DIR}/govulncheck-source.txt"
fi
else
echo "Package scan found no findings — CVE likely not in Go vuln DB yet"
cp "${OUT_DIR}/govulncheck-package.txt" "${OUT_DIR}/govulncheck-source.txt"
fi
echo "govulncheck complete"
else
echo "=== govulncheck (using cached result) ==="
fi
cat "${OUT_DIR}/govulncheck-source.txt"
# Verify repo is still accessible after govulncheck
echo "=== Post-govulncheck repo check ==="
ls "${REPO_DIR}/go.mod" > /dev/null 2>&1 && echo "✓ Repo intact at ${REPO_DIR}" || echo "✗ WARNING: Repo missing at ${REPO_DIR}"
- IF CGO was disabled → note in report: "CGO-gated code paths excluded from analysis"
- IF package scan found no findings → CVE is not in Go vuln DB; do NOT escalate to symbol scan; proceed to Method 3
- IF symbol scan timed out → use package-level results instead; proceed to Method 3
- Save
${OUT_DIR}/govulncheck-source.txtas a workflow artifact
Decision Point — govulncheck is ONE signal. Always continue to Method 3 next.
- IF scan reports vulnerable symbols called → Strong evidence for HIGH RISK; still continue to Method 3
- IF scan reports no findings → CVE likely not yet in Go vuln database. Do NOT re-run. Proceed to Method 3.
- IF scan timed out or was skipped → Proceed to Method 3; note the gap in the report
Method 3: Direct Dependency Check
# Verify package is included (directly or transitively)
go list -mod=mod <vulnerable-package>
Note: Package presence alone doesn't prove vulnerable functions are called.
Method 4: Source Code Analysis
- Search for import statements of vulnerable packages in source code
- Use grep/codebase_search to find package usage
- Search for vulnerable function/method names in codebase
- Identify actual code paths that use vulnerable functions
- Check if vulnerable functions are called in reachable code
Method 5: Call Graph Reachability Analysis (Mandatory when package is present)
Delegate to the call-graph-analysis skill.
- Pass:
--algopreference from user, vulnerable function signature, package path - Receive: Risk level, call chain, evidence files
Scope rule: Never invoke
callgraphwith./.... Always target a specific main package (e.g../cmd/controller,.). The tool resolves transitive dependencies automatically. Running on./...causes VTA to exhaust resources on repos with >50 packages (external-secrets has 138, spiffe-spire has 300+). See the call-graph-analysis skill for the progressive fallback chain (vta→rta→cha).
This method is REQUIRED whenever the vulnerable package is present in go.mod — regardless of what Methods 2, 3, or 4 found. Source code analysis (Method 4) is heuristic: it can miss indirect calls through interfaces, generated code, and runtime dispatch. Only a call graph provides provable reachability.
Valid reasons to skip call graph:
- Package is NOT in
go.mod(genuinely unreachable — LOW RISK by definition) - Codebase does not compile (note the limitation; rely on other methods)
- Vulnerable function signature is unknown (note the gap; rely on govulncheck and source analysis)
NOT a valid reason to skip:
- Source code analysis found no direct calls to the vulnerable function
- govulncheck did not flag it (CVE may not be in the Go vuln DB yet)
- The analysis "feels" complete from earlier methods
Method 6: Configuration and Context Analysis
- Review if vulnerable features are actually enabled
- Check if vulnerable code paths are behind feature flags
- Verify if inputs can reach vulnerable functions
- Consider security controls (input validation, sandboxing)
Confidence Levels
Each method provides increasing confidence:
- Basic Presence (Low) — Package in
go.mod(Method 1, 3) - Import & Version Analysis (Medium) — Package imported, version in vulnerable range, function names found (Method 4)
- Vulnerability Scanner (Medium-High) —
govulncheckconfirms reachable vulnerable symbols (Method 2) - Call Graph Reachability (Definitive) — Proven execution path from entry point to vulnerable function (Method 5)
- Context Analysis — Mitigating or aggravating factors (Method 6)
Required minimum: If the package is in go.mod, the analysis is not complete until Method 5 has run or a valid skip reason has been documented. Never stop at Method 4 alone.
Step 3: Build Evidence Package
Collect evidence from all methods used:
- Dependency Evidence:
go.modentries,go listoutput, version info - Static Code Evidence: File paths, line numbers, code snippets showing usage
- Reachability Evidence: Call graph output, execution paths, DOT visualization (saved to
${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/{CVE-ID}/callgraph.svg, outsideREPO_DIR) - Scanner Evidence:
govulncheckoutput, vulnerability findings - Mitigation Factors: Input validation, disabled features, feature flags, security controls
Step 4: Assign Risk Level
Evaluate all evidence and assign a risk level. The determination should be data-driven, not formula-based.
HIGH RISK:
- Call graph shows a reachable path to the vulnerable function, OR
- Symbol-level
govulncheckconfirms called vulnerable symbols (package-level import alone is not sufficient)
MEDIUM RISK:
- Package + vulnerable version in dependencies, usage evidence present, but call graph could not run (build failure or unknown function signature) — reachability not definitively proven
LOW RISK:
- Package not in dependencies (call graph skipped — genuinely unreachable), OR version not in vulnerable range, OR call graph ran and found no reachable path
NEEDS REVIEW:
- Package is in
go.modbut call graph was skipped for any reason other than package absence or build failure — escalate; do not leave as LOW based on source code analysis alone - Conflicting signals or incomplete analysis
Rule: If package is in
go.modand call graph was skipped because source analysis "found nothing", assign NEEDS REVIEW, not LOW RISK. Document the skip reason explicitly.
Return Value
Return structured result to parent command:
{
"skill": "codebase-impact-analysis",
"status": "success",
"risk_level": "<HIGH|MEDIUM|LOW|NEEDS_REVIEW>",
"methods_used": ["dependency_matching", "govulncheck", "direct_dependency_check", "source_code_analysis", "call_graph", "context_analysis"],
"evidence": {
"dependency": {
"package_found": true,
"current_version": "<version>",
"dependency_type": "<direct|indirect>",
"in_vulnerable_range": true
},
"govulncheck": {
"ran": true,
"cve_found": true,
"vulnerable_symbols_called": true
},
"call_graph": {
"ran": true,
"algorithm": "<vta|rta|cha|static>",
"reachable_from_main": true,
"call_chain": "main -> handler -> parse -> VULN",
"evidence_files": ["callgraph.dot", "callgraph.svg"],
"skip_reason": "<null if ran | 'package_not_in_gomod' | 'build_failure' | 'unknown_function_signature'>"
},
"source_analysis": {
"import_found": true,
"function_usage_found": true,
"files": ["<file1>:<line>", "<file2>:<line>"]
},
"mitigation_factors": []
},
"confidence_assessment": {
"level": "<HIGH|MEDIUM|LOW>",
"methods_count": 4,
"gaps": ["<any gaps in analysis>"]
}
}
Error Handling
Build Failures
- IF project doesn't compile → Note limitation, skip call graph analysis, rely on other methods
Missing CVE in govulncheck Database
- IF govulncheck doesn't know about this CVE → Continue with other methods, note gap
Large Codebases
- IF call graph times out → Follow fallback strategy in call-graph-analysis skill: algorithm fallback (
vta→rta→cha), always targeting a specific main package. Never use./...as scope.
Incomplete CVE Information
- IF vulnerable function signature unknown → Skip call graph, note
skip_reason: unknown_function_signature, assign MEDIUM at best — do NOT assign LOW based on source analysis alone
Source Code Analysis Shows No Usage
- This is NOT a valid reason to skip call graph. Proceed with Method 5.
- Source code search misses interface dispatch, generated code, and indirect call paths.
Integration with analyze-cve
This skill is called from Phase 2 of the analyze-cve skill, after the Repo Guard has confirmed REPO_DIR still exists.
Input: CVE profile from Phase 1, --algo preference from user, REPO_DIR set in Phase 0.7
Output: Risk level, evidence package, confidence assessment
Next: The analyze-cve skill uses risk level to decide whether to generate report and proceed to remediation
Create Fix PR
Opens a GitHub pull request for the CVE fix already applied in REPO_DIR (Phase 5). Never commits, pushes, or opens a PR without explicit approval — interactive, or AUTO_APPROVE=yes recorded once upfront (see Autonomous Mode). Direct CVE mode (no --jira=/--jql=) still creates the PR; it just omits Jira Fixes: links and the Jira follow-up comment.
Called from Phase 6 of the analyze-cve skill after Phase 5 verification succeeds.
When to Use This Skill
Use this skill when:
- Phase 5 applied a fix in
REPO_DIRand verification passed - The user approved creating a GitHub PR
embargo_statusis notTrue
Do not use this skill to apply the fix itself (that is Phase 5) or to post the analysis report (that is report-to-jira in Phase 4).
Required Inputs
From the parent command:
| Input | Source | Required |
|---|---|---|
REPO_DIR | Phase 0.7 | Yes |
GIT_BRANCH | Phase 0.7 (mapped release branch, e.g. release-4.17) | Yes |
REPO_URL | Phase 0.7 | Yes |
CVE_ID | Phase 0.5 / direct CVE mode | Yes |
SOURCE_TICKET | --jira= / --jql= | No |
AUTO_APPROVE | Phase 0 (--auto-approve, default no) | Yes |
FORK_ORG | Caller environment (e.g. CI/RWS runner) | No — enables Fork Mode when set |
PHASE5_FILES | Phase 5 allowlist (incl. untracked) | Yes |
| Module path, old version, new version | Phase 4 / 5 | Yes if a dependency bump |
| Short CVE description | Phase 1 | Recommended |
| Phase 5 change summary | Phase 5 "Document Changes" | Yes |
Prerequisites
Hard requirements for this skill. Phase 0 does not treat gh as required (warn-only). This skill must not assume either tool is present — re-check both, then fail if either is missing. Do not create a PR another way.
which git 2>/dev/null || echo "MISSING: git"
which gh 2>/dev/null || echo "MISSING: gh"
gh auth status 2>/dev/null || echo "MISSING: gh auth"
- IF
gitis missing → print install instructions and returnstatus: failed(git_missing). Stop. Do not commit or push. - IF
ghis missing → print install instructions (https://cli.github.com/) and returnstatus: failed(gh_missing). Stop. Do not commit or push. - IF
gh auth statusfails → printgh auth logininstructions and returnstatus: failed(gh_unauthenticated). Stop. Do not commit or push. - Do not print token or login output that contains credentials.
Credential rule: Never print, echo, or log tokens, PATs, or
ghauth output that contains credentials. Reference credentials only via environment variable names.
Fork Mode (FORK_ORG set)
By default (no FORK_ORG) this skill pushes the fix branch directly to the cloned repo's own origin and opens a same-repo branch→base PR. That requires the authenticated gh/git identity to have direct write access to every upstream repo image-repo-mapping might resolve to (e.g. openshift/cert-manager-operator, openshift/cert-manager, openshift/secrets-store-csi-driver-operator, ...). In an unattended CI/RWS runner that isn't a collaborator on all of those repos, that's the wrong default.
IF the environment variable FORK_ORG is set (e.g. a bot-owned org), push to a fork under that org instead and open a cross-repo PR — mirrors the fork/upstream model used elsewhere for automated OpenShift PRs. This section only changes where the branch is pushed and how the PR's --head is specified; Step 0 (safety gates), Step 1 (org/repo/base-branch resolution from origin), Step 2 (conflicting-PR detection), and Step 3b (commit, allowlist validation) are unchanged and still operate against REPO_DIR/ORG/REPO/BASE_BRANCH resolved from origin.
Resolve the fork repo
FORK_REPO="${FORK_ORG}/${REPO}" # REPO = repo name parsed from origin in Step 1, e.g. "cert-manager-operator"
Ensure the fork exists and is actually a fork of this repo
Never assume a repo at ${FORK_REPO} is the right push target just because the name matches — verify its fork lineage first. Reusing an unrelated (or unexpectedly renamed/transferred) repo that happens to occupy that name would push the fix branch and open a PR from somewhere unintended.
if FORK_JSON=$(gh repo view "${FORK_REPO}" --json isFork,parent 2>/dev/null); then
IS_FORK=$(echo "$FORK_JSON" | jq -r '.isFork')
PARENT_FULL_NAME=$(echo "$FORK_JSON" | jq -r '.parent.fullName // empty')
else
IS_FORK=""
PARENT_FULL_NAME=""
fi
- IF
${FORK_REPO}exists (thegh repo viewabove succeeded) and (IS_FORKis not exactlytrueorPARENT_FULL_NAMEis not exactly${ORG}/${REPO}) → stop immediately, do not add theforkremote or push anything, and returnstatus: failed(fork_wrong_lineage). - IF
${FORK_REPO}exists and lineage matches → skip fork creation below, continue to Step 3a. - IF
${FORK_REPO}does not exist → create it:
gh repo fork "${ORG}/${REPO}" --org "${FORK_ORG}" --remote=false --clone=false --default-branch-only=false
FORK_CREATE_EXIT=$?
- IF
FORK_CREATE_EXITis non-zero → stop immediately and returnstatus: failed(fork_create_failed). Do not poll, do not add theforkremote, do not push — the create call already reported failure, so there is nothing to wait for. - IF
FORK_CREATE_EXITis0→ the fork was accepted; poll briefly, since GitHub creates forks asynchronously:
for i in $(seq 1 10); do
gh repo view "${FORK_REPO}" >/dev/null 2>&1 && break
sleep 3
done
- IF the fork still doesn't exist after polling → return
status: failed(fork_create_failed). Do not fall back to pushing toorigin— that would silently switch to requiring direct upstream write access, which is exactly whatFORK_ORGwas set to avoid.
3a (fork mode). Branch — same as default mode
Branch creation/naming is identical to the non-fork case below (BRANCH_NAME derived from CVE_ID/SOURCE_TICKET, checked out from BASE_BRANCH).
3c (fork mode). Push to the fork, not origin
git -C "${REPO_DIR}" remote add fork "https://github.com/${FORK_REPO}.git" 2>/dev/null \
|| git -C "${REPO_DIR}" remote set-url fork "https://github.com/${FORK_REPO}.git"
# Keep the fork in sync with the upstream base branch before pushing a branch built on top of it,
# so the PR diff is just this fix — not a stale-fork drift diff.
git -C "${REPO_DIR}" fetch origin "${BASE_BRANCH}"
git -C "${REPO_DIR}" push fork "refs/remotes/origin/${BASE_BRANCH}:refs/heads/${BASE_BRANCH}" --force-with-lease 2>/dev/null || true
git -C "${REPO_DIR}" push -u fork "${BRANCH_NAME}"
Never force-push ${BASE_BRANCH} on origin (the upstream repo) — the force-with-lease sync above only ever targets the fork remote's copy of that branch name, never origin.
Step 4 (fork mode). Create the PR across fork → upstream
Do not use gh pr create --head "${FORK_ORG}:${BRANCH_NAME}". gh pr create --head only supports a user-owned head repo via the owner:branch syntax — per gh pr create --help: "Using an organization as the owner is currently not supported" (tracked at cli/cli#10093). Since FORK_ORG may be a GitHub organization, use the REST API's head_repo parameter instead (via gh api), which unambiguously names the head repository regardless of whether FORK_ORG is a user or an org:
printf '%s' "${PR_BODY}" > "${WORK_CVE}/pr-body.md"
PR_URL=$(gh api \
"repos/${ORG}/${REPO}/pulls" \
-f head_repo="${FORK_REPO}" \
-f head="${BRANCH_NAME}" \
-f base="${BASE_BRANCH}" \
-f title="${PR_TITLE}" \
-F body=@"${WORK_CVE}/pr-body.md" \
--jq '.html_url')
head is the bare branch name here (no owner: prefix) — disambiguation comes entirely from the separate head_repo field, so this works whether FORK_ORG/FORK_REPO is user- or org-owned. Everything else (title/body construction, stacked-PR update path) is unchanged; PR_URL is captured directly from the API response instead of gh pr create's output.
Auth note
gh auth status in Prerequisites must reflect a token with public_repo (classic PAT) or equivalent fork/push/PR scope on ${FORK_ORG} and PR-creation scope against the upstream repo — this is set up by the caller before this skill runs (not part of this skill). Never echo the token itself.
Step 0: Safety Gates
-
IF
embargo_status = True→ abort immediately. Do not commit, push, create a PR, or mention ticket contents. -
IF Phase 5 did not complete successfully → return
status: skipped(phase5_incomplete). -
Confirm there are local changes to commit:
git -C "${REPO_DIR}" status --porcelain git -C "${REPO_DIR}" diff --stat- IF working tree is clean and HEAD is already on a fix branch with the Phase 5 remediation committed (dependency bump, source, or config) → validate that branch's changes against
PHASE5_FILES(see the check in Step 3b) before skipping to Step 4. A clean worktree only means nothing is uncommitted; it does not prove the existing commit(s) contain only Phase 5 paths. IF the branch diff vs${BASE_BRANCH}contains paths outsidePHASE5_FILES→ always returnstatus: failed(phase5_files_mismatch) immediately. Never gated byAUTO_APPROVEand never prompt. - IF working tree is clean and HEAD is still
${GIT_BRANCH}with no Phase 5 commit → returnstatus: skipped(no_local_changes).
- IF working tree is clean and HEAD is already on a fix branch with the Phase 5 remediation committed (dependency bump, source, or config) → validate that branch's changes against
-
IF
AUTO_APPROVE=no(and the parent hasn't already recorded a yes) → Ask:Phase 5 applied the fix locally. Create a GitHub PR against <GIT_BRANCH>?- IF no → return
status: skipped(user_declined). Leave the working tree as-is. - IF yes → continue. Still do not commit until Step 3.
IF
AUTO_APPROVE=yes→ treat as yes, skip the prompt, continue. Still do not commit until Step 3. - IF no → return
Step 1: Resolve GitHub Repo and Base Branch
git -C "${REPO_DIR}" remote get-url origin
Parse ORG/REPO from the origin URL (github.com/openshift/hypershift.git → openshift/hypershift). If origin is SSH (git@github.com:org/repo.git), parse the same way.
BASE_BRANCH = GIT_BRANCH from Phase 0.7 (the mapped release branch the clone is on). Do not open the PR against main unless that is actually GIT_BRANCH.
Step 2: Detect Conflicting Open PRs
Title match only. Do not inspect PR files, body, module versions, or go.mod diffs.
gh pr list --repo "${ORG}/${REPO}" --state open --base "${BASE_BRANCH}" \
--json number,title,url,headRefName,author
A PR is a match if its title contains (case-insensitive) either this CVE_ID, or SOURCE_TICKET (when set).
IF none → continue to Step 3 with strategy new.
IF any match:
-
AUTO_APPROVE=no→ present the list and wait for the user:Open PR(s) on <ORG/REPO> base <BASE_BRANCH> already have this CVE/Jira in the title: #<N> <title> <url> head=<branch> How should I proceed? 1. stack — check out that PR branch, commit this fix on top, push (PR updates) 2. wait — stop; do not open a competing PR 3. independent — new branch from <BASE_BRANCH> (may need rebase later)Choice Action stackgit fetch origin <headRefName> && git checkout <headRefName> && git pull. Re-apply leftover Phase 5 changes if they are not already on that branch (same method as Phase 5 — bump, patch, or config edit). Strategy =stack.waitReturn status: skipped(user_wait_for_pr) including the existing PR URL.independentWarn that a second PR on the same base may need rebase later. If go.modis in this diff, mention possible module-file conflicts. Strategy =new.No answer Do not guess. Ask again. -
AUTO_APPROVE=yes→ alwayswait, automatically, with no exceptions: returnstatus: skipped(user_wait_for_pr_auto) including the existing PR URL. Never auto-choosestack(that pushes commits onto a branch nobody reviewed for this run) orindependent(that opens a second, possibly duplicate/conflicting PR) unattended. Log clearly that this run stopped because of the existing PR, so a human can revisit with--auto-approve=noif a different resolution is actually wanted.
Step 3: Branch, Commit, Push
Work only inside REPO_DIR.
Vendor: Phase 5 already ran go mod vendor/make vendor (if applicable) and included any resulting paths in PHASE5_FILES before verification. Do not run vendor sync here — doing so after PHASE5_FILES was written would generate paths that never make it into the allowlist and get silently dropped from the commit. IF a dependency bump is present in PHASE5_FILES but vendor/ looks out of sync (e.g. go mod vendor reports diffs) → stop and tell the user to re-run Phase 5, rather than fixing it here.
3a. Branch
New PR (strategy = new):
git -C "${REPO_DIR}" fetch origin "${BASE_BRANCH}"
git -C "${REPO_DIR}" checkout "${BASE_BRANCH}"
git -C "${REPO_DIR}" pull --ff-only origin "${BASE_BRANCH}"
SLUG="$(echo "${CVE_ID}" | tr '[:upper:]' '[:lower:]')"
if [ -n "${SOURCE_TICKET}" ]; then
BRANCH_NAME="fix/${SLUG}-$(echo "${SOURCE_TICKET}" | tr '[:upper:]' '[:lower:]')"
else
BRANCH_NAME="fix/${SLUG}"
fi
git -C "${REPO_DIR}" checkout -b "${BRANCH_NAME}"
Re-apply the Phase 5 changes on this branch if checking out BASE_BRANCH discarded uncommitted work. Prefer not discarding: stash before checkout if the working tree is dirty, then stash pop onto BRANCH_NAME.
Stack (strategy = stack): already on the existing PR branch. Set BRANCH_NAME to that head ref. Do not create a new branch.
3b. Commit
Stage only PHASE5_FILES, not the whole worktree. That allowlist is written in Phase 5 (phase5-files.txt) and includes new untracked files. go.mod, go.sum, go.work, and vendor/ are common for dependency version bumps, but other CVE remediations may only touch source, config, Dockerfiles, or scripts.
WORK_CVE is in the command's own workspace (.work/), not inside REPO_DIR. Paths in the allowlist are relative to REPO_DIR.
WORK_CVE="${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}"
PHASE5_FILES="${WORK_CVE}/phase5-files.txt"
IF phase5-files.txt is missing or empty → rebuild it from Phase 5 "Document Changes" (and phase5-before.status if present). IF the allowlist still cannot be determined → always return status: failed (phase5_files_missing) immediately. Never gated by AUTO_APPROVE and never prompt. Do not fall back to whole-worktree git diff / git add -A / git add . in any case.
# inspect current tree for sanity, but do not use it as the stage set
git -C "${REPO_DIR}" status --porcelain
while IFS= read -r f; do
[ -n "${f}" ] || continue
git -C "${REPO_DIR}" add -- "${f}"
done < "${PHASE5_FILES}"
git add -- <path> stages modifications, deletions, and untracked files. Examples of what belongs on the allowlist:
- Dependency bump:
go.mod,go.sum, andgo.work/vendor/only if Phase 5 changed them - Code/config fix: the source or config files Phase 5 added or edited
- Mixed: the union of those paths
Do not add .work/, analysis reports, or credentials. Do not add pre-existing dirty files that are absent from PHASE5_FILES. Do not git add go.mod / vendor/ unless they are on the allowlist.
Validate the staged set exactly matches the allowlist. The loop above only adds allowlisted paths — it does not prove the index is free of anything else (e.g. leftover pre-existing staged files). Diff the two sets and reject extras instead of committing them silently:
git -C "${REPO_DIR}" diff --cached --name-only > "${WORK_CVE}/staged-files.txt"
EXTRA="$(comm -23 <(sort "${WORK_CVE}/staged-files.txt") <(sort "${PHASE5_FILES}"))"
if [ -n "${EXTRA}" ]; then
echo "Unstaging paths not in PHASE5_FILES:"
echo "${EXTRA}"
while IFS= read -r x; do
[ -n "${x}" ] || continue
git -C "${REPO_DIR}" restore --staged -- "${x}"
done <<< "${EXTRA}"
fi
MISSING="$(comm -23 <(sort "${PHASE5_FILES}") <(sort "${WORK_CVE}/staged-files.txt"))"
if [ -n "${MISSING}" ]; then
echo "ERROR: PHASE5_FILES paths missing from the staged set:"
echo "${MISSING}"
exit 1 # return status: failed (phase5_files_incomplete)
fi
IF any path was rejected → tell the user which paths were unstaged and why before continuing. Re-run the diff after unstaging to confirm the index now matches PHASE5_FILES exactly (accounting for deletions).
On a stack branch, or when Step 0 skipped ahead because a Phase 5 commit already existed, run the equivalent check against the branch, not just the index:
git -C "${REPO_DIR}" diff --name-only "${BASE_BRANCH}...HEAD" > "${WORK_CVE}/branch-files.txt"
comm -23 <(sort "${WORK_CVE}/branch-files.txt") <(sort "${PHASE5_FILES}")
IF that reports any path outside PHASE5_FILES → stop; do not push or open/update the PR. Always return status: failed (phase5_files_mismatch) immediately, for manual follow-up. Never gated by AUTO_APPROVE and never prompt.
Commit message. Match the actual Phase 5 change, not a canned module bump. Use the repo's own convention when detectable — e.g. many OpenShift repos expect UPSTREAM: <upstream-pr-or-carry>: <subject>:
git -C "${REPO_DIR}" log --oneline -20
If the recent history shows the UPSTREAM: convention and a dependency bump with a known upstream fix PR number (from the Phase 4 remediation plan):
UPSTREAM: <upstream-pr>: Bump <module> to <new> for <CVE_ID>
If a dependency bump that is downstream-only / fork / carry (no tracked upstream PR, but repo uses UPSTREAM: convention):
UPSTREAM: <carry>: Bump <module> to <new> for <CVE_ID>
If the repo does not use the UPSTREAM: convention, use a plain subject. Dependency bump:
Bump <module> to <new> for <CVE_ID>
If the fix is not a version bump (code, config, workaround), regardless of convention:
Fix <CVE_ID>: <short description of the change>
Body: one or two sentences describing what changed and why. Include Fixes: <SOURCE_TICKET> in Jira mode; omit that line in direct CVE mode. For a bump, include old → new versions. Do not claim a module bump if Phase 5 did not bump a module.
git -C "${REPO_DIR}" commit --signoff -m "${COMMIT_SUBJECT}" -m "${COMMIT_BODY}"
Sign off (DCO) by default — most upstream/downstream OpenShift-style repos require it and a missing sign-off is a common, avoidable PR-check failure. Never use --no-verify or skip hooks unless the user explicitly asks.
3c. Push
git -C "${REPO_DIR}" push -u origin "${BRANCH_NAME}"
Default is a normal push. Amending an existing commit and force-pushing is never authorized by AUTO_APPROVE; it always requires an interactive user (moot in practice, since AUTO_APPROVE=yes never selects stack — see Step 2).
Step 4: Create or Update the GitHub PR
Title
Dependency bump:
<CVE_ID>: bump <module-short> to <new> [<SOURCE_TICKET>]
Omit [<SOURCE_TICKET>] in direct CVE mode. Example: CVE-2026-33186: bump google.golang.org/grpc to v1.79.3 [OCPBUGS-80452]
Non-bump fix:
<CVE_ID>: <short description> [<SOURCE_TICKET>]
Body
Read the repo's PR template if one exists (cat "${REPO_DIR}/.github/PULL_REQUEST_TEMPLATE.md" 2>/dev/null) and structure the body around it. Otherwise use:
Jira mode — every Jira key must be a markdown link. Use a Fixes: line (do not use a bare key):
## Summary
Fixes: [<SOURCE_TICKET>](<JIRA_BASE_URL>/browse/<SOURCE_TICKET>)
<What Phase 5 changed and why — e.g. bump `<module>` from `<old>` to `<new>`, or a code/config workaround.>
<2–3 sentence CVE description from Phase 1>
## Changes
- <file- or behavior-level bullets from the Phase 5 diff>
## Verification
- `make verify` / `go mod verify` (if modules changed)
- `make build` / `go build ./...`
- `govulncheck ./...`
---
Always review AI generated responses prior to use.
AI-assisted change via compliance plugin (`/compliance:analyze-cve`)
Direct CVE mode — same body without the Fixes: line and without Jira URLs.
Do not include hostnames, cluster names, routes, usernames, passwords, or tokens in the title, body, or comments.
Create vs update
New PR (default mode — no FORK_ORG):
gh pr create \
--repo "${ORG}/${REPO}" \
--base "${BASE_BRANCH}" \
--head "${BRANCH_NAME}" \
--title "${PR_TITLE}" \
--body "${PR_BODY}"
New PR (fork mode — FORK_ORG set): use the Fork Mode Step 4 variant (gh api repos/.../pulls -f head_repo=...) instead of the gh pr create call above.
Stacked on existing PR: push is enough (to origin by default, or fork in Fork Mode). Optionally:
gh pr comment "${EXISTING_PR}" --repo "${ORG}/${REPO}" \
--body "Added <CVE_ID> fix: <what Phase 5 changed>."
And gh pr edit to append the CVE / Jira key to title and the Fixes: line if missing.
Capture PR_URL from gh pr create output or gh pr view --json url (default mode), or from the gh api response (Fork Mode).
IF create fails (permissions, fork needed) → show the exact gh error (no secrets). If the error indicates missing write access and FORK_ORG is not set, suggest re-running with FORK_ORG configured (see Fork Mode) rather than guessing at a fork target. Otherwise give the user the title/body to paste, return status: failed (pr_create_failed). Do not retry more than once.
Step 5: Post PR URL to Jira (Jira mode only)
Skip this step if SOURCE_TICKET is unset (direct CVE mode) → still status: success for the GitHub PR.
Use the report-to-jira skill's Follow-up: PR URL comment section. Do not edit or replace the Phase 4 analysis comment. Do not add/remove labels here.
IF posting fails → display the comment in session for manual paste. The GitHub PR is still a success (jira_followup: failed).
Return Value
Success:
{
"skill": "create-fix-pr",
"status": "success",
"action": "created | updated",
"pr_url": "https://github.com/<org>/<repo>/pull/<n>",
"pr_number": 123,
"branch": "fix/cve-yyyy-nnnnn-ocpbugs-12345",
"base_branch": "release-4.17",
"cve_id": "CVE-YYYY-NNNNN",
"source_ticket": "OCPBUGS-12345 or null",
"jira_followup": "posted | skipped | failed"
}
Skipped:
{
"skill": "create-fix-pr",
"status": "skipped",
"reason": "user_declined | no_local_changes | phase5_incomplete | user_wait_for_pr | user_wait_for_pr_auto | embargo"
}
Failed:
{
"skill": "create-fix-pr",
"status": "failed",
"reason": "git_missing | gh_missing | gh_unauthenticated | pr_create_failed | commit_failed | phase5_files_missing | phase5_files_mismatch | fork_wrong_lineage | fork_create_failed",
"error": "<message without secrets>"
}
Integration with analyze-cve
Called from Phase 6 of the analyze-cve skill after Phase 5 verification succeeds. Runs after the Repo Guard has confirmed REPO_DIR still exists.
Guardrails
- Never commit, push, or open a PR without explicit approval — interactive, or
AUTO_APPROVE=yesrecorded once upfront - Never force-push to
BASE_BRANCH/main/master/release-* - Never skip git hooks unless the user asks
- Never stage paths outside
PHASE5_FILES; nevergit add -Aorgit add . - Never commit/push/PR without validating the staged (and, for
stack, the branch) path set againstPHASE5_FILESand rejecting extras - Never run vendor sync in Phase 6 — it happens in Phase 5, before
PHASE5_FILESis written - Never push to, or open a PR from, a
FORK_ORGrepo without first verifying its fork lineage (isFork+parent.fullNamematch) — never reuse a same-named repo that isn't actually a fork of the target - Never let
AUTO_APPROVE=yesauto-selectstackorindependenton a PR-title conflict — alwayswaitunattended - Never let
AUTO_APPROVE=yesskip a hard-fail case (missing/mismatchedPHASE5_FILES, ambiguous conflict resolution) — those always require a human, flag or not - Never include secrets in commit messages, PR text, or Jira comments
- Stop immediately on embargo
- Direct CVE mode must still produce a PR
CVE Intelligence Gathering
Systematically collects CVE vulnerability details from multiple authoritative sources, handles search failures, and compiles a comprehensive vulnerability profile for analysis.
When to Use This Skill
Use this skill when:
- Starting CVE analysis and need complete vulnerability information
- Web searches are returning limited or no results
- CVE is very new and not yet in all databases
- Need to distinguish between authoritative and user-provided information
- Building evidence for security compliance reports
Prerequisites
Required
- Valid CVE identifier (format: CVE-YYYY-NNNNN)
- Internet connectivity (recommended but not required)
web_searchtool access
Optional
- User-provided CVE details (fallback when internet unavailable)
- Links to security advisories
Implementation Steps
Step 1: Validate CVE Format
# Regex pattern for CVE ID
CVE_PATTERN="^CVE-[0-9]{4}-[0-9]{4,}$"
# Validate format
if [[ "$CVE_ID" =~ $CVE_PATTERN ]]; then
echo "Valid CVE format"
else
echo "ERROR: Invalid CVE format. Expected: CVE-YYYY-NNNNN"
exit 1
fi
Extract components:
- Year:
YYYYfromCVE-YYYY-NNNNN - Number:
NNNNNfromCVE-YYYY-NNNNN
Decision Point:
- IF invalid format → Return error to parent command
- IF valid → Continue to Step 1.5
Step 1.5: Seed Profile from Jira Context (if available)
If a jira_context object was passed in from the jira-cve-extraction skill (i.e. the parent command was invoked with --jira= or --jql=), pre-populate the vulnerability profile before any web searches. This reduces redundant lookups and surfaces internal context that is not available in public databases.
Fields to extract and pre-populate:
| Jira field | Profile field | Notes |
|---|---|---|
cvss_score + cvss_vector | severity.cvss_score, severity.cvss_vector | Prefer Jira value; verify against NVD in Step 2 |
cwe_id | cwe_id | Cross-check with NVD; flag if they differ |
summary (parsed description) | description (supplement) | Internal phrasing may be more specific |
affects_versions | Analysis scope (which project/release versions are affected) | |
target_versions | Fix target / release window | |
release_note_text | remediation.recommended_action (supplement) | May already describe the fix or upgrade path |
components, labels | Context only | |
| Description body (workaround scan) | remediation.workarounds | Already extracted by jira-cve-extraction |
| Internal notes from description | internal_context field in profile | Capture any previous analysis, conclusions, or decisions noted in the ticket body |
Mark each pre-populated field as source: jira in the profile.
Conflict resolution: If Jira and a public source (NVD, GHSA) disagree on CVSS score or CWE:
- Note both values in the profile
- Prefer the higher CVSS score for risk assessment (conservative)
- Flag the discrepancy as a gap
Decision Point:
- IF
jira_contextis null or absent (direct<CVE-ID>mode) → Skip this step entirely, proceed to Step 2 as normal - IF
jira_contextis present → Pre-populate, then continue to Step 2 to fill remaining gaps and verify
Step 2: Search Primary Sources (NVD and MITRE)
National Vulnerability Database (NVD)
Search query: "CVE-{ID} site:nvd.nist.gov"
Example: "CVE-YYYY-NNNNN site:nvd.nist.gov"
Extract from results:
- CVSS Score (v3.1, v3.0, or v2.0)
- Severity rating (CRITICAL/HIGH/MEDIUM/LOW)
- Base score and vector string
- Affected product/versions
- CWE (Common Weakness Enumeration) ID
- Published date and last modified date
MITRE CVE Database
Search query: "CVE-{ID} site:cve.mitre.org"
Example: "CVE-YYYY-NNNNN site:cve.mitre.org"
Extract from results:
- CVE description (official)
- References (links to advisories, patches, exploits)
- CWE classification
- Assigning CNA (CVE Numbering Authority)
Error Handling:
- IF no results from NVD → Try MITRE
- IF no results from MITRE → Try NVD alternative URL pattern
- IF both fail → Continue to Step 3 (Go-specific sources)
Step 3: Search Go-Specific Sources
Go Vulnerability Database
Search queries:
1. "CVE-{ID} golang vulnerability"
2. "CVE-{ID} site:github.com/golang/vulndb"
3. "CVE-{ID} site:go.dev/security"
Extract from results:
- Affected Go package/module (e.g.,
<package-path>) - Vulnerable version ranges (e.g.,
< <version>) - Fixed version (e.g.,
<version>) - Vulnerable functions/symbols
- Import paths
GitHub Security Advisories (GHSA)
Search queries:
1. "CVE-{ID} golang GHSA"
2. "CVE-{ID} site:github.com/advisories"
Look for:
- GHSA identifier (e.g.,
GHSA-xxxx-xxxx-xxxx) - Severity from GitHub
- Affected versions
- Patched versions
- Workarounds if available
Decision Point:
- IF Go-specific info found → High confidence this is Go-related
- IF only general CVE info found → May not be Go-specific, note this
- IF nothing found → Proceed to Step 4
Step 4: Search for Remediation Intelligence
Security Advisories
Search queries:
1. "CVE-{ID} security advisory"
2. "CVE-{ID} golang fix"
3. "CVE-{ID} patch"
Look for:
- Official vendor security bulletins
- Fix commits on GitHub
- Release notes mentioning the CVE
- Migration guides for breaking changes
Community Discussions
Search queries:
1. "CVE-{ID} golang github issue"
2. "CVE-{ID} golang discussion"
Check for:
- GitHub issues discussing the vulnerability
- Pull requests with fixes
- Community workarounds
- Discussion on golang-nuts or Reddit
Proof of Concept / Exploits (for context only)
Search query: "CVE-{ID} exploit poc"
Note: Only use for understanding attack vectors, not for testing
Step 5: Handle Search Failures and Limited Results
If CVE is Very New (e.g., published recently)
Search alternative queries:
1. "CVE-{ID} disclosure"
2. "CVE-{ID} advisory {YEAR}"
3. "{PACKAGE_NAME} vulnerability {YEAR}"
- It may not be listed in the NVD yet (this can take weeks)
- Check vendor security pages directly
- Look for embargo lift dates
- Note: govulncheck may have it via GHSA before NVD
If Web Searches Return No Results
Try alternative strategies:
-
Search by package name (if known from context):
Search: "{package-name} vulnerability {year}" Example: "<package-name> vulnerability <year>" -
Search for GHSA aliases:
Search: "GHSA-{pattern} golang" -
Check package repository directly:
Search: "site:github.com/{org}/{repo} security"
Decision Point:
- IF still no results → Proceed to Step 6 (User Input)
- IF partial results → Continue with available data, mark gaps
Step 6: Request User Input (Fallback)
If automated searches fail: IF AUTO_APPROVE=yes → there is no one to prompt; skip straight to "User Response Handling: no" below (return an error to the parent command). This step is never gated to proceed automatically — fabricating CVE details is not a safe default, regardless of how much unattended automation the caller wants. IF AUTO_APPROVE=no (or unset — the default) → prompt user:
❌ Unable to fetch details for {CVE-ID} from online sources.
Attempted searches:
- NVD: No results
- MITRE: No results
- Go vulnerability database: No results
- GitHub Security Advisories: No results
Please provide any information you have about this CVE:
1. CVE Description:
[What vulnerability does this CVE describe?]
2. Affected Go Packages/Modules:
[e.g., <package-path>, github.com/<org>/<repo>]
3. Vulnerable Version Range:
[e.g., all versions before <version>, or versions <version-range>]
4. Fixed Version (if known):
[e.g., <version> or later]
5. Severity (if known):
[CRITICAL/HIGH/MEDIUM/LOW or CVSS score]
6. References (if any):
[Links to security advisories, GitHub issues, etc.]
You can provide partial information. Analysis will proceed with whatever details are available.
Would you like to provide CVE details? (yes/no)
User Response Handling:
- IF yes → Collect information, mark as "User-provided"
- IF no → Return error to parent command (insufficient data to proceed)
Step 7: Compile Merged Vulnerability Profile
Merge all gathered information — Jira context (Step 1.5, if present) and public sources (Steps 2–6) — into a single profile. Every field records which source(s) populated it.
{
"cve_id": "CVE-YYYY-NNNNN",
"aliases": ["GHSA-xxxx-xxxx-xxxx"],
"severity": {
"rating": "<CRITICAL|HIGH|MEDIUM|LOW>",
"cvss_score": "<score>",
"cvss_vector": "<CVSS vector string>",
"cvss_source": "<jira|nvd|ghsa — which source this came from>"
},
"affected_packages": [
{
"name": "<package-name>",
"vulnerable_versions": "<version-range>",
"fixed_version": "<fixed-version>",
"vulnerable_functions": ["<function1>", "<function2>"]
}
],
"vulnerability_type": "<vulnerability-type>",
"cwe_id": "CWE-<number>",
"attack_vector": "<attack-vector>",
"description": "<vulnerability description>",
"impact": {
"confidentiality": "<NONE|LOW|HIGH>",
"integrity": "<NONE|LOW|HIGH>",
"availability": "<NONE|LOW|HIGH>"
},
"remediation": {
"fix_available": true,
"recommended_action": "<remediation guidance>",
"workarounds": ["<workaround from Jira description or public advisory>"],
"fix_target_versions": ["<target versions from Jira target_versions, if any>"],
"release_note": "<from Jira release_note_text if present>"
},
"internal_context": {
"jira_ticket": "<PROJ-NNNNN or null>",
"affects_versions": ["<affected versions from Jira>"],
"previous_analysis_notes": "<any conclusions or analysis captured in Jira description>",
"priority": "<Jira priority>",
"status": "<Jira status>"
},
"information_sources": [
{
"type": "Jira",
"verified": true,
"url": "https://redhat.atlassian.net/browse/<PROJ-NNNNN>"
},
{
"type": "NVD",
"verified": true,
"url": "https://nvd.nist.gov/vuln/detail/CVE-YYYY-NNNNN"
},
{
"type": "GitHub Security Advisory",
"verified": true,
"url": "https://github.com/advisories/GHSA-xxxx-xxxx-xxxx"
}
],
"information_completeness": "COMPLETE",
"data_quality": "HIGH",
"conflicts": [],
"gaps": []
}
internal_context and the Jira entry in information_sources are only populated when a jira_context was passed in (Step 1.5); omit them entirely in direct <CVE-ID> mode.
Mark Information Sources:
- ✓ "Verified from Jira ticket (internal)"
- ✓ "Verified from NVD"
- ✓ "Verified from MITRE"
- ✓ "Verified from Go vulndb"
- ✓ "Verified from GitHub Security Advisory"
- ⚠️ "Based on user-provided information"
- ⚠️ "Inferred from package repository"
- ⚠️ "Partial information - some fields missing"
Record conflicts when Jira and public sources disagree:
"conflicts": [
{
"field": "cvss_score",
"jira_value": "7.5",
"public_value": "6.5",
"resolution": "Used higher value (7.5) for conservative risk assessment"
}
]
Assess Information Completeness:
- COMPLETE: All critical fields populated from authoritative sources
- MOSTLY_COMPLETE: Core info available, some details missing
- PARTIAL: Only basic info (CVE ID, description, rough severity)
- MINIMAL: User-provided or very limited data
Identify Gaps:
"gaps": [
"CVSS score not available",
"Fixed version not confirmed",
"Vulnerable functions not identified"
]
Step 8: Determine Go Relevance
Assess if CVE is Go-related:
Strong Indicators (HIGH confidence):
- Found in Go vulnerability database
- GHSA entry mentions Go/Golang
- Affected package is a Go module
- NVD lists Go as affected product
Weak Indicators (MEDIUM confidence):
- Generic web framework CVE that might affect Go
- Library with Go bindings
- Transitive dependency through C libraries
Not Go-related (Exit early):
- CVE explicitly for other languages (Python, Node.js, etc.)
- OS/kernel vulnerabilities (unless Go runtime affected)
- Hardware vulnerabilities
Decision Point:
- IF clearly NOT Go-related → Return "NOT_APPLICABLE" verdict
- IF Go-related → Continue analysis
- IF unclear → Note uncertainty, continue with caution
Return Value
Return structured data to parent command:
{
"skill": "cve-intelligence-gathering",
"status": "success",
"cve_profile": {
"cve_id": "CVE-YYYY-NNNNN",
"severity": "<CRITICAL|HIGH|MEDIUM|LOW>",
"cvss_score": "<score>",
"affected_packages": [...],
"fixed_versions": [...],
"description": "...",
"references": [...]
},
"information_quality": {
"completeness": "<COMPLETE|MOSTLY_COMPLETE|PARTIAL|MINIMAL>",
"sources": ["<source1>", "<source2>", ...],
"user_provided": "<true|false>",
"gaps": []
},
"go_relevance": {
"is_go_related": "<true|false>",
"confidence": "<HIGH|MEDIUM|LOW>",
"reasoning": "<explanation>"
}
}
Error Handling
Invalid CVE Format
Error: Invalid CVE identifier format
Expected: CVE-YYYY-NNNNN
Received: {user-input}
Action: Return error, do not proceed
Network/Search Failures
- Try multiple search strategies
- Fall back to alternative sources
- Request user input as last resort
- Document what was attempted
CVE Not Found Anywhere
Warning: CVE-{ID} not found in any database
Possible reasons:
- CVE is very new (not yet published)
- CVE ID is incorrect
- CVE was disputed/rejected
- Private disclosure not yet public
Action: Request user input or exit
Non-Go CVE
Info: CVE-{ID} does not appear to affect Go
Affected platforms: {list}
Action: Return NOT_APPLICABLE verdict early
Example: Complete Workflow
Step 1: Validate
✓ CVE-YYYY-NNNNN - Valid format
Step 2: Primary Sources
✓ NVD: Found - CVSS <score>, Severity: <severity>
✓ MITRE: Found - CWE-<number>, References available
Step 3: Go-Specific Sources
✓ Go vulndb: Found - <package-name>
✓ GHSA: Found - GHSA-xxxx-xxxx-xxxx
- Affected: <package-name> <version-range>
- Fixed: <fixed-version>
- Vulnerable functions: <function1>, <function2>
Step 4: Remediation Intelligence
✓ GitHub Advisory: Update to <fixed-version>
✓ Release notes: <release-notes-url>
✓ Fix commit: <commit-url>
Step 5: Not needed - sufficient data
Step 6: Not needed - sufficient data
Step 7: Compile Profile
✓ All fields populated
✓ Information completeness: COMPLETE
✓ Data quality: HIGH
✓ No gaps identified
Step 8: Go Relevance
✓ Is Go-related: YES
✓ Confidence: HIGH
✓ Package: <package-name>
Result: Complete vulnerability profile ready for Phase 2 analysis
Integration with analyze-cve
This skill is called from Phase 1 of the analyze-cve skill.
Input from parent:
- CVE identifier (from the
<CVE-ID>argument, or extracted byjira-cve-extractionwhen--jira=/--jql=was used) jira_contextobject from thejira-cve-extractionskill (optional — only present when--jira=or--jql=was provided)AUTO_APPROVE(yes/no, defaultno) — governs the Step 6 fallback-prompt gating
Output to parent:
cve_profile— merged vulnerability profile (Jira internal context + public sources when Jira mode was used; public sources only otherwise)information_quality— completeness assessment (noting which fields came from which source)conflict_log— where Jira and public sources disagreed (empty when no Jira context)go_relevance— Go applicability determination- Decision on whether to proceed to Phase 2
Decision Flow:
IF status = "error" → Exit command
IF go_relevance.is_go_related = false → Generate "Not Applicable" report, exit
IF information_quality.completeness = "MINIMAL" AND user_declined → Exit command
OTHERWISE → Proceed to Phase 2 with profile
Image to Repository Mapping
Translates a container image name into the GitHub repository URL to clone for analysis. Image names appear in the ticket summary, pscomponent: labels, and the Downstream Component Name custom field.
When to Use This Skill
Use this skill when:
- An image name has been extracted from a Jira ticket (summary, label, or custom field)
- The user passes
--repo=<image-name>using a short image name rather than a full GitHub URL - Phase 0.7 needs to determine which repository to clone
Resolution Order
Apply these in order and stop at the first match:
- Full GitHub URL supplied (
--repo=https://github.com/...) → use directly, skip this skill. - Exact image name match — look the image name up in the table below.
- Prefix match — strip version suffixes (e.g.
-1-0,-1-12-4,-rhel9,-rhel8) and re-match. - Keyword match — check the per-section keyword rules at the bottom of each group.
- NOT FOUND → Exit immediately with the error message below. Do not guess. Do not proceed with analysis.
Tip: Strip
pkg:oci/prefix before matching (e.g.pkg:oci/ose-ansible-operator→ose-ansible-operator).
Not-Found Exit
If no match is found after all steps above, stop immediately and output:
❌ Repository mapping not found for image: <image_name>
The image "<image_name>" is not in the known mapping table and could not
be resolved automatically.
To proceed, re-run with an explicit repository URL:
--repo=https://github.com/org/repo
Or add the mapping to:
plugins/compliance/skills/image-repo-mapping/SKILL.md
Do NOT continue analysis without a confirmed source repository.
Do NOT fall back to guessing, fuzzy matching, or prompting the user inline. Exit the command at this point.
Two Repository Patterns
Components fall into one of two patterns. The resolution output is different for each.
Pattern A — Direct repo
Clone the mapped repo directly at the mapped branch. Used by: Operator SDK, Ansible Operator, must-gather, Secrets Store CSI.
image → repo URL + branch
Pattern B — Release repo with git submodules
Some components use a dedicated -release repo that aggregates all component repos as git submodules. The release repo branch pins each submodule to the exact commit/tag used for that release. Used by: cert-manager, ZTWIM, ESO.
Resolution steps for Pattern B:
- Clone the release repo at the mapped release branch
- Read
.gitmodulesfrom that branch to find the submodule entry matching the target image - Read the pinned commit from the release repo tree (
git ls-tree HEAD <submodule-path>) — do not clone from the.gitmodulesbranch field alone - Clone the component repo and check out that pinned commit for analysis
# Step 1: Clone release repo at correct branch (per-run path under REPOS_BASE)
RELEASE_CLONE_DIR="${REPOS_BASE}/.release-clones/$(echo "${RELEASE_REPO_URL}" | sed -E 's#^[a-zA-Z]+://github\.com/##; s#\.git$##; s#/$##' | tr '/' '-')-${RELEASE_BRANCH}"
rm -rf "${RELEASE_CLONE_DIR}"
mkdir -p "$(dirname "${RELEASE_CLONE_DIR}")"
git clone --depth=1 -b "${RELEASE_BRANCH}" "${RELEASE_REPO_URL}" "${RELEASE_CLONE_DIR}"
# Step 2: Read .gitmodules
cat "${RELEASE_CLONE_DIR}/.gitmodules"
# Step 3: Extract submodule path + url from .gitmodules
# Step 4: Read pinned commit from release repo tree
PINNED_COMMIT=$(git -C "${RELEASE_CLONE_DIR}" ls-tree HEAD "${SUBMODULE_PATH}" | awk '{print $3}')
if [ -z "${PINNED_COMMIT}" ]; then
echo "ERROR: no pinned commit found for ${SUBMODULE_PATH}"
exit 1
fi
# Step 5: Clone component repo and checkout pinned commit (fetch SHA explicitly — shallow clone alone may miss it)
git clone "${COMPONENT_URL}" "${REPO_DIR}"
git -C "${REPO_DIR}" fetch origin "${PINNED_COMMIT}"
git -C "${REPO_DIR}" checkout "${PINNED_COMMIT}"
Jira branch → release branch naming for Pattern B:
Jira BRANCH value | Release branch |
|---|---|
cert-manager-X-Y | release-X.Y in cert-manager-operator-release |
external-secrets-X-Y | release-X.Y in external-secrets-operator-release |
ztwim-1.0 | release-1.0.0 in zero-trust-workload-identity-manager-release (one-time exception — team confirmed this was a branching mistake; future releases use release-X.Y) |
ztwim-X.Y (any other) | release-X.Y in zero-trust-workload-identity-manager-release |
Note: Jira branch values use hyphens for separators (e.g.
external-secrets-1-0) while release branches use dots (e.g.release-1.0). Strip the component prefix and convert the remaining hyphen-separated version to dot notation.
Image → Repository Map
Every image name here has appeared in real ticket summaries or labels. This table is intentionally scoped to the components this command has been validated against — extend it as new components come up (see the not-found exit message above).
cert-manager / jetstack — Pattern B (release repo + submodules)
Release repo: https://github.com/openshift/cert-manager-operator-release
Submodules: cert-manager-operator, cert-manager, cert-manager-istio-csr
Branch mapping: Jira cert-manager-X-Y → release-X.Y in the release repo
Clone the release repo at the correct branch, read .gitmodules to find the submodule URL and pinned ref for the target image, then clone that component at the pinned ref.
| Image Name / Prefix | Submodule in .gitmodules |
|---|---|
cert-manager/cert-manager-operator-rhel9, cert-manager/cert-manager-operator-bundle, cert-manager-operator-* | cert-manager-operator |
cert-manager/cert-manager-istio-csr-rhel9 | cert-manager-istio-csr |
cert-manager/jetstack-cert-manager-*, jetstack-cert-manager-*, redhat-user-workloads/jetstack-cert-manager-* | cert-manager |
cert-manager-operator (operator + bundle only)
| Image Name / Prefix | GitHub Repository |
|---|---|
cert-manager-operator-container | https://github.com/openshift/cert-manager-operator |
cert-manager-operator-rhel9 | https://github.com/openshift/cert-manager-operator |
cert-manager/cert-manager-operator-rhel9 | https://github.com/openshift/cert-manager-operator |
cert-manager/cert-manager-operator-bundle | https://github.com/openshift/cert-manager-operator |
cert-manager-istio-csr
| Image Name / Prefix | GitHub Repository |
|---|---|
cert-manager/cert-manager-istio-csr-rhel9 | https://github.com/openshift/cert-manager-istio-csr |
jetstack-cert-manager
| Image Name / Prefix | GitHub Repository |
|---|---|
cert-manager/jetstack-cert-manager-rhel9 | https://github.com/openshift/jetstack-cert-manager |
cert-manager/jetstack-cert-manager-acmesolver-rhel9 | https://github.com/openshift/jetstack-cert-manager |
jetstack-cert-manager-rhel9 | https://github.com/openshift/jetstack-cert-manager |
jetstack-cert-manager-container | https://github.com/openshift/jetstack-cert-manager |
jetstack-cert-manager-acmesolver-rhel9 | https://github.com/openshift/jetstack-cert-manager |
jetstack-cert-manager-acmesolver-container | https://github.com/openshift/jetstack-cert-manager |
redhat-user-workloads/jetstack-cert-manager-* | https://github.com/openshift/jetstack-cert-manager |
Namespace prefix match: cert-manager → requires full image name lookup above (multiple repos in this namespace).
Keyword match: cert-manager-operator / cert-manager-operator-bundle → cert-manager-operator; cert-manager-istio-csr → cert-manager-istio-csr; jetstack-cert-manager → jetstack-cert-manager.
Operator SDK / Helm Operator (non-ansible images)
| Image Name / Prefix | GitHub Repository |
|---|---|
operator-sdk | https://github.com/openshift/ocp-release-operator-sdk |
openshift4/ose-operator-sdk-rhel8 | https://github.com/openshift/ocp-release-operator-sdk |
openshift4/ose-operator-sdk-rhel9 | https://github.com/openshift/ocp-release-operator-sdk |
openshift-enterprise-operator-sdk-container | https://github.com/openshift/ocp-release-operator-sdk |
openshift4/ose-helm-operator | https://github.com/openshift/ocp-release-operator-sdk |
openshift4/ose-helm-rhel9-operator | https://github.com/openshift/ocp-release-operator-sdk |
openshift-enterprise-helm-operator-container | https://github.com/openshift/ocp-release-operator-sdk |
pkg:oci/ose-operator-sdk-rhel8 | https://github.com/openshift/ocp-release-operator-sdk |
pkg:oci/ose-operator-sdk-rhel9 | https://github.com/openshift/ocp-release-operator-sdk |
pkg:oci/ose-helm-operator | https://github.com/openshift/ocp-release-operator-sdk |
pkg:oci/openshift-enterprise-helm-operator | https://github.com/openshift/ocp-release-operator-sdk |
Ansible Operator
| Image Name / Prefix | GitHub Repository |
|---|---|
ansible-operator-plugins | https://github.com/openshift/ansible-operator-plugins |
openshift4/ose-ansible-operator | https://github.com/openshift/ansible-operator-plugins |
openshift4/ose-ansible-rhel9-operator | https://github.com/openshift/ansible-operator-plugins |
openshift-enterprise-ansible-operator-container | https://github.com/openshift/ansible-operator-plugins |
pkg:oci/ose-ansible-operator | https://github.com/openshift/ansible-operator-plugins |
pkg:oci/ose-ansible-rhel9-operator | https://github.com/openshift/ansible-operator-plugins |
Keyword match: any image containing ansible-operator → https://github.com/openshift/ansible-operator-plugins
External Secrets Operator — Pattern B (release repo + submodules)
Release repo: https://github.com/openshift/external-secrets-operator-release
Submodules: external-secrets-operator, external-secrets, bitwarden-sdk-server
Branch mapping: Jira external-secrets-X-Y → release-X.Y in the release repo
Clone the release repo at the correct branch, read .gitmodules to find the submodule URL and pinned ref for the target image, then clone that component at the pinned ref.
| Image Name / Prefix | Submodule in .gitmodules |
|---|---|
external-secrets-operator/external-secrets-operator-rhel9, external-secrets-operator/external-secrets-operator-bundle, redhat-user-workloads/external-secrets-operator-* | external-secrets-operator |
external-secrets-operator/external-secrets-rhel9, redhat-user-workloads/external-secrets-1-0 | external-secrets |
external-secrets-operator/bitwarden-sdk-server-rhel9, redhat-user-workloads/bitwarden-sdk-server-* | bitwarden-sdk-server |
Keyword match: external-secrets-operator / external-secrets-operator-bundle → submodule external-secrets-operator; bitwarden-sdk-server → submodule bitwarden-sdk-server; external-secrets-rhel9 / external-secrets-1-0 → submodule external-secrets.
Zero Trust / SPIFFE / SPIRE — Pattern B (release repo + submodules)
Release repo: https://github.com/openshift/zero-trust-workload-identity-manager-release
Submodules: zero-trust-workload-identity-manager (spire-operator), spiffe-spire, spiffe-spire-controller-manager, spiffe-spiffe-csi
Branch mapping: Jira ztwim-X.Y → release-X.Y in the release repo
Clone the release repo at the correct branch (--recurse-submodules is NOT needed — read .gitmodules manually and clone only the relevant submodule), then clone that component at the pinned ref.
| Image Name / Prefix | Submodule in .gitmodules |
|---|---|
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-rhel9, *-operator-bundle | zero-trust-workload-identity-manager |
zero-trust-workload-identity-manager/spiffe-spire-agent-rhel9, *spiffe-spire-server*, *spire-oidc*, redhat-user-workloads/spiffe-spire-* | spiffe-spire |
zero-trust-workload-identity-manager/spiffe-spire-controller-manager-rhel9 | spiffe-spire-controller-manager |
zero-trust-workload-identity-manager/spiffe-csi-driver-rhel9, redhat-user-workloads/spiffe-csi-driver-* | spiffe-spiffe-csi |
zero-trust-workload-identity-manager/spiffe-helper-rhel9 | spiffe-spiffe-helper |
The zero-trust-workload-identity-manager namespace spans four repositories — match on the full image name, not just the namespace prefix.
spire-operator (operator + bundle only)
| Image Name / Prefix | GitHub Repository |
|---|---|
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-rhel9 | https://github.com/openshift/spire-operator |
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-operator-bundle | https://github.com/openshift/spire-operator |
spiffe-spire (agent, server, OIDC discovery provider)
| Image Name / Prefix | GitHub Repository |
|---|---|
zero-trust-workload-identity-manager/spiffe-spire-agent-rhel9 | https://github.com/openshift/spiffe-spire |
zero-trust-workload-identity-manager/spiffe-spire-server-rhel9 | https://github.com/openshift/spiffe-spire |
zero-trust-workload-identity-manager/spiffe-spire-oidc-discovery-provider-rhel9 | https://github.com/openshift/spiffe-spire |
redhat-user-workloads/spiffe-spire-agent-* | https://github.com/openshift/spiffe-spire |
redhat-user-workloads/spiffe-spire-server-* | https://github.com/openshift/spiffe-spire |
redhat-user-workloads/spiffe-spire-oidc-discovery-provider-* | https://github.com/openshift/spiffe-spire |
spiffe-spire-controller-manager
| Image Name / Prefix | GitHub Repository |
|---|---|
zero-trust-workload-identity-manager/spiffe-spire-controller-manager-rhel9 | https://github.com/openshift/spiffe-spire-controller-manager |
spiffe-spiffe-csi (CSI driver)
| Image Name / Prefix | GitHub Repository |
|---|---|
zero-trust-workload-identity-manager/spiffe-csi-driver-rhel9 | https://github.com/openshift/spiffe-spiffe-csi |
redhat-user-workloads/spiffe-csi-driver-* | https://github.com/openshift/spiffe-spiffe-csi |
spiffe-spiffe-helper
| Image Name / Prefix | GitHub Repository |
|---|---|
zero-trust-workload-identity-manager/spiffe-helper-rhel9 | https://github.com/openshift/spiffe-spiffe-helper |
Namespace prefix match: zero-trust-workload-identity-manager → requires full image name lookup above (multiple repos in this namespace).
Keyword match: spire-agent / spire-server / spire-oidc → https://github.com/openshift/spiffe-spire; spire-controller-manager → https://github.com/openshift/spiffe-spire-controller-manager; spiffe-csi-driver → https://github.com/openshift/spiffe-spiffe-csi; spiffe-helper → https://github.com/openshift/spiffe-spiffe-helper; zero-trust-workload-identity-manager (manager/bundle) → https://github.com/openshift/spire-operator.
must-gather
| Image Name / Prefix | GitHub Repository |
|---|---|
openshift4/ose-must-gather-rhel9 | https://github.com/openshift/must-gather |
openshift4/ose-support-log-gather-rhel9-operator | https://github.com/openshift/must-gather-operator |
Secrets Store CSI
The namespace spans two repositories. The mustgather image is built from the operator repo.
secrets-store-csi-driver-operator (operator, bundle, mustgather)
| Image Name / Prefix | GitHub Repository |
|---|---|
openshift4/ose-secrets-store-csi-driver-rhel9-operator | https://github.com/openshift/secrets-store-csi-driver-operator |
openshift4/ose-secrets-store-csi-driver-operator-bundle | https://github.com/openshift/secrets-store-csi-driver-operator |
ose-secrets-store-csi-driver-operator-container | https://github.com/openshift/secrets-store-csi-driver-operator |
openshift4/ose-secrets-store-csi-mustgather-rhel9 | https://github.com/openshift/secrets-store-csi-driver-operator |
ose-secrets-store-csi-mustgather-container | https://github.com/openshift/secrets-store-csi-driver-operator |
secrets-store-csi-driver (driver only)
| Image Name / Prefix | GitHub Repository |
|---|---|
openshift4/ose-secrets-store-csi-driver-rhel9 | https://github.com/openshift/secrets-store-csi-driver |
ose-secrets-store-csi-driver-container | https://github.com/openshift/secrets-store-csi-driver |
Keyword match: secrets-store-csi-mustgather / secrets-store-csi-driver-operator / secrets-store-csi-driver-operator-bundle → secrets-store-csi-driver-operator; secrets-store-csi-driver-rhel9 (driver image, not operator) → secrets-store-csi-driver.
Return Value
Success:
{
"skill": "image-repo-mapping",
"status": "success",
"resolved_repos": [
{
"image_name": "openshift4/ose-ansible-rhel9-operator",
"repo_url": "https://github.com/openshift/ansible-operator-plugins",
"clone_path": ".work/compliance/analyze-cve/repos/ansible-operator-plugins",
"confidence": "exact_match",
"match_method": "exact"
}
],
"unresolved": [],
"resolution_method": "summary_image_name"
}
Not found (exit):
{
"skill": "image-repo-mapping",
"status": "not_found",
"image_name": "<image_name>",
"error": "No repository mapping found. Re-run with --repo=https://github.com/org/repo or add the mapping to image-repo-mapping/SKILL.md."
}
confidence: exact_match, prefix_match, keyword_match, user_provided
Integration with analyze-cve
Called from Phase 0.7 of the analyze-cve skill.
Input: image name extracted by jira-cve-extraction skill (from summary, pscomponent: label, or Downstream Component Name field), or the short name passed via --repo=<name>
Output: (image_name, repo_url, clone_path) tuple passed to Phase 0.7 for cloning
Jira CVE Extraction
Fetches a Jira ticket and extracts three things:
- CVE ID — passed to Phase 1 (
cve-intelligence-gathering) - Image name — passed to Phase 0.7 via the
image-repo-mappingskill to resolve which repo to clone - Enriched context — CVSS, CWE, priority, target versions, workarounds — embedded in the Phase 3 report and used to seed the CVE profile
Key insight: Security tracking tickets (e.g.
OCPBUGSCVE trackers) follow a consistent summary format:CVE-YYYY-NNNNN <component>: <description> [<version>]. Parsing the summary is the most reliable single extraction path and should always be tried first — it typically yields the CVE ID, image name, and branch in one step.
When to Use This Skill
Use this skill when the user invokes /compliance:analyze-cve with --jira=PROJ-NNN or --jql="...".
Prerequisites
Preferred: Atlassian MCP
Use the Atlassian Rovo MCP tools bundled with the jira plugin (or an equivalent Atlassian MCP server configured for this Claude Code instance):
getJiraIssue— fetch a single ticketsearchJiraIssuesUsingJql— fetch a batch of tickets (Phase 0.3 / idempotency lookups)editJiraIssue— update labels (idempotency marker)
Fallback: jira-cli
If the MCP server is unavailable: jira issue get <TICKET> and jira issue edit <TICKET> --label ... (from go-jira). Requires ~/.jira.d/config.yml configured for the target Jira instance.
Credential rule: Never print, echo, or log any token, password, or key value — not in shell commands, not in model responses, not in debug output. Reference credentials only via environment variable names (e.g.
$JIRA_API_TOKEN).
Implementation Steps
Step 1: Validate Ticket Format
PROJECT-NNNNN e.g. OCPBUGS-12345, CNTRLPLANE-678
Pattern: ^[A-Z]+-[0-9]+$
- IF invalid → Return error: "Invalid Jira ticket format. Expected PROJECT-NNNNN."
- IF valid → Continue
Step 2: Fetch the Ticket
issue = getJiraIssue(issue_key="PROJ-12345")
Fallback (jira-cli):
jira issue get PROJ-12345
Error Handling:
- 404 / not found → "Ticket not found. Verify the key and your access."
- Auth failure → IF
AUTO_APPROVE=no, prompt user to authenticate and retry. IFAUTO_APPROVE=yes, exit with error — there is no credential to fix automatically. - Network down → IF
AUTO_APPROVE=no, ask the user to supply the CVE ID manually and skip the enrichment. IFAUTO_APPROVE=yes, exit with error (never gated — cannot fabricate ticket data).
Step 2.5: Idempotency Check — Already Processed?
Inspect the ticket's labels list from the response above. Check whether ai-cve-analyzed is present (case-sensitive exact match). This check always runs here regardless of entry point (--jira= direct or --jql= batch mode) — it is the authoritative guard against re-processing.
labels = issue["fields"]["labels"] # list of strings
if "ai-cve-analyzed" in labels:
# Already processed — exit immediately
IF label is present → Stop immediately and output:
⚠️ Skipping analysis — this ticket has already been processed by /compliance:analyze-cve.
Ticket: <JIRA_KEY>
Label: ai-cve-analyzed
To force a re-analysis, remove the label from the ticket and re-run.
Return status: skipped and exit. Do not proceed with analysis.
IF label is absent → Continue to Step 3.
Step 3: Extract CVE ID and Image Name from Summary
The ticket summary follows this common format:
CVE-YYYY-NNNNN <image-name>: <vulnerability description> [<branch-or-version>]
Example:
CVE-2024-45338 openshift4/ose-operator-sdk-rhel9: some-lib: vulnerability description [openshift-4.17]
Parse with:
^(CVE-\d{4}-\d{4,})\s+([\w/:\-\.@]+)\s*:.*\[([\w\.\-]+)\]
group 1 = CVE ID
group 2 = image name
group 3 = branch/version
This is the primary and most reliable extraction path. If this succeeds, groups 1 and 2 are immediately available — no further searching needed for CVE ID or image name.
- IF summary matches → set
CVE_ID,IMAGE_NAME,BRANCH→ skip to Step 5 - IF summary does not match → continue to Step 4
Step 4: Fallback Extraction (when summary doesn't match)
Try in order until both CVE_ID and IMAGE_NAME are found:
CVE ID fallbacks:
- A dedicated
CVE IDcustom field, if the project has one — always accurate when present - Labels — look for a label matching
CVE-\d{4}-\d{4,}exactly - Description body — scan for
CVE-\d{4}-\d{4,}pattern
Image name fallbacks:
pscomponent:label — parsepscomponent:<image-name>from the labels list; strip thepscomponent:prefixDownstream Component Namecustom field, if the project has one — dedicated field mapping directly to the affected image- Description body — scan for known image name prefixes (
openshift4/,cert-manager/,external-secrets-operator/,zero-trust-workload-identity-manager/,redhat-user-workloads/)
Multiple CVE IDs found: List all found. IF AUTO_APPROVE=no → ask the user which to analyze (or analyze all with confirmation). IF AUTO_APPROVE=yes → always exit with error listing the candidates and asking the caller to re-run with a direct <CVE-ID> argument (or a ticket/JQL that resolves to a single CVE). This case is never gated by AUTO_APPROVE — guessing which CVE to analyze is a correctness risk.
Decision Point:
- IF no CVE ID found anywhere → IF
AUTO_APPROVE=no, ask the user to supply it manually; if declined → Exit. IFAUTO_APPROVE=yes, there is no one to ask → Exit immediately with error (never gated byAUTO_APPROVE). - IF no image name found → leave
IMAGE_NAMEblank; Phase 0.7 will prompt the user for--repo=(or hard-fail ifAUTO_APPROVE=yes, per its own rules) — this is never guessed.
Step 5: Extract Additional Context Fields
Read the following fields from the ticket response. Field names vary by Jira instance/project — look them up by display name if the custom field ID is unknown (e.g. via issue-type field metadata), rather than hardcoding an ID that may not match this instance.
| Field | Typical location | Notes |
|---|---|---|
| Status | fields.status.name | |
| Priority | fields.priority.name | Blocker/Critical → urgency escalation |
| Assignee | fields.assignee.displayName | |
| Components | fields.components[].name | |
| Labels | fields.labels[] | Full label list — needed intact for Step 4.5 of report-to-jira |
| Affects versions | fields.versions[].name | |
| Fix versions | fields.fixVersions[].name | |
| Target version | project-specific custom field (e.g. "Target Version") | |
| CVSS Score | custom field named "CVSS Score" | Format often 7.5 CVSS:3.1/AV:N/... — extract score and vector separately |
| CWE ID | custom field named "CWE ID" | e.g. CWE-409 |
| Embargo Status | custom field named "Embargo Status" | True/False — security-critical, see Step 5.5 |
| Downstream Component Name | custom field named "Downstream Component Name", if the project has one | Redundant image name source — cross-check against the summary/label extraction |
| Release Note Text | custom field named "Release Note Text" | May already describe the fix |
| Description | fields.description | Scan for workaround/mitigation keywords |
Scan description for workarounds: look for sections or sentences containing "workaround", "mitigation", "disable", "restrict" — extract the first ~300 chars of any such passage.
Linked issues:
issue["fields"]["issuelinks"] # each has inwardIssue/outwardIssue + type.name
Step 5.5: Embargo Check — MUST run before returning
Read the Embargo Status custom field from the ticket (if the project defines one).
- IF value is
True(case-insensitive) → immediately stop all processing and return:
Do NOT output any CVE details, CVSS scores, image names, or other ticket data.❌ Embargoed CVE — cannot proceed. This ticket is marked as embargoed. Embargoed CVEs must not be analysed, disclosed, or shared outside authorised channels. Exit. - IF value is
False, empty, or the field does not exist on this project → Continue to Step 6.
Branch Resolution
The BRANCH value extracted in Step 3/4 (e.g. openshift-4.17, release-4.15.z, ztwim-1.0) uses a different naming convention from actual git branches. Resolve it before Phase 0.7 clones anything — do not pass the raw Jira value straight to git clone -b.
.z-stream suffix — strip it first. OpenShift versioning uses a trailing.z(case-insensitive:.z/.Z) to mean "any z-stream of this minor release" (e.g.4.16.z,openshift-4.16.z,release-4.15.z). This is a Jira/versioning convention only — no git branch is ever named with a.zsuffix; the real branch is always theX.Yform. Before doing anything else, strip a trailing.zfromBRANCHif present (openshift-4.16.z→openshift-4.16;release-4.15.z→release-4.15), then apply the table below to the stripped value.
Pattern A components (direct repo — Operator SDK, Ansible Operator, must-gather, Secrets Store CSI):
Jira BRANCH value (after stripping .z) | git_branch to use |
|---|---|
openshift-X.Y | release-X.Y (e.g. openshift-4.17 → release-4.17; openshift-4.16.z → strip to openshift-4.16 → release-4.16) |
release-X.Y | Already a real git branch name — use verbatim (e.g. release-4.15.z → strip to release-4.15) |
Anything else (e.g. ztwim-1.0, main) | Use verbatim — Pattern B components resolve their own release-repo branch inside image-repo-mapping |
Set git_branch to the resolved value and git_branch_source to jira_summary. Phase 0.7 uses git_branch directly for the -b flag when cloning a Pattern A repo. For a Pattern B component (cert-manager, ESO, ZTWIM), strip the .z suffix per the rule above, then pass the result through unchanged — image-repo-mapping's own branch table (e.g. cert-manager-X-Y → release-X.Y in the release repo) is what actually resolves it, and applying the Pattern A table first would corrupt it.
If BRANCH was not extracted (no Jira ticket, or the ticket didn't have a parseable version/branch token): leave git_branch unset — Phase 0.7 clones the repository's default branch and notes this in the report.
Step 6: Compile and Return
{
"skill": "jira-cve-extraction",
"status": "success",
"cve_id": "CVE-YYYY-NNNNN",
"image_name": "openshift4/ose-operator-sdk-rhel9",
"branch": "openshift-4.17",
"jira_context": {
"ticket_key": "PROJ-NNNNN",
"ticket_url": "https://<jira-host>/browse/PROJ-NNNNN",
"summary": "CVE-YYYY-NNNNN openshift4/ose-operator-sdk-rhel9: <lib>: <description> [openshift-4.17]",
"status": "New",
"priority": "Major",
"assignee": "<assignee-display-name>",
"components": ["<component>"],
"labels": ["CVE-YYYY-NNNNN", "SecurityTracking", "pscomponent:openshift4/ose-operator-sdk-rhel9"],
"affects_versions": ["4.17"],
"fix_versions": [],
"target_versions": [],
"cvss_score": "7.5",
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
"cwe_id": "CWE-NNN",
"embargo_status": "False",
"downstream_component_name": "openshift4/ose-operator-sdk-rhel9",
"internal_notes": "",
"release_note_text": "",
"linked_issues": []
},
"analysis_hints": {
"urgency_override": null,
"workaround_present": false,
"cve_extraction_source": "summary",
"image_extraction_source": "summary",
"git_branch": "release-4.17",
"git_branch_source": "jira_summary"
}
}
cve_extraction_source values: summary, custom_field, label, description, user_provided
image_extraction_source values: summary, pscomponent_label, downstream_component_field, description, user_provided
Error Handling
| Situation | Action |
|---|---|
| Ticket not found (404) | Exit with error: "Ticket not found or access denied" |
| Auth failure | Prompt to authenticate and retry (or exit if AUTO_APPROVE=yes) |
| No CVE ID in ticket | AUTO_APPROVE=no: ask user to supply manually. AUTO_APPROVE=yes: exit with error (never gated). |
| No image name in ticket | Leave blank; Phase 0.7 will prompt for --repo= (or hard-fail if AUTO_APPROVE=yes) |
| Multiple CVEs | List all. AUTO_APPROVE=no: ask user which to analyze. AUTO_APPROVE=yes: exit with error (never gated). |
Embargo True | Stop immediately. Return error: "This ticket is under embargo. Embargoed CVEs must not be analysed or disclosed outside authorised channels. Exiting." |
Label ai-cve-analyzed present | Stop immediately. Return status: skipped — ticket already processed. |
Integration with Parent Command
Called from Phase 0.5 of the analyze-cve skill, only when --jira= or --jql= was provided.
Output is used as:
cve_id→ Phase 1 (cve-intelligence-gathering)image_name→ Phase 0.7 via theimage-repo-mappingskill to resolve the clone URLanalysis_hints.git_branch→ Phase 0.7 Step 3 — the-bflag forgit clone(Pattern A) or the release-branch lookup (Pattern B)jira_context→ Phase 1 (merged into vulnerability profile) + Phase 3 report "Jira Context" sectionjira_context.cvss_score+cvss_vector→ seeds Phase 1 before NVD lookupanalysis_hints.urgency_override→ can escalate the final risk levelanalysis_hints.workaround_present→ noted in Phase 4 remediation planjira_context.ticket_key→ becomesSOURCE_TICKETforreport-to-jira(Phase 4) andcreate-fix-pr(Phase 6)
Remediation Planning
Creates actionable remediation plans for vulnerable Go codebases based on analysis results from previous phases.
Supported Remediation Types
- Dependency Update - Update Go package to fixed version
- Go Runtime Update - Update Go itself (for stdlib vulnerabilities)
- Configuration Change - Disable features, change settings, adjust security controls
- Code Refactoring - Replace vulnerable patterns, add validation, refactor code
- Security Patch - Apply vendor-provided patch files
- Workarounds - Temporary mitigations (timeouts, rate limiting, input validation)
- Infrastructure - Network policies, firewall rules, WAF configuration
- Combination - Multiple remediation types together
The skill automatically determines the appropriate remediation strategy based on CVE details and impact analysis.
When to Use This Skill
Use this skill when:
- Codebase is confirmed or likely affected by a CVE
- Need specific remediation steps beyond "update the package"
- Fixed version exists but need to assess compatibility
- No fixed version available and need workarounds
- Project uses custom build/test commands via Makefile
Implementation Steps
Step 1: Analyze Inputs and Determine Strategy
Required Inputs from Previous Phases:
From Phase 1 (cve-intelligence-gathering):
- CVE ID, severity, CVSS score
- Affected package/module and vulnerable version range
- Fixed version (if available)
- Vulnerability type and remediation guidance
From Phase 2 (codebase-impact-analysis):
- Risk level (HIGH / MEDIUM / LOW / NEEDS REVIEW)
- Current package version and dependency type
- Usage locations and functions being called
From Call Graph Analysis (optional):
- Reachability risk level and call chain
- Entry points
From govulncheck (optional):
- Detection result and vulnerable symbols
Decision Tree:
IF risk_level = "LOW":
→ Document findings, recommend monitoring and manual review
IF risk_level = "HIGH" or "MEDIUM":
IF fixed_version EXISTS:
IF affected_package is in go.mod → Dependency Update (Step 2)
ELSE IF affected_package is Go stdlib → Go Runtime Update (Step 2A)
IF fixed_version = null:
IF remediation_guidance has "configuration" → Configuration Change (Step 2B)
IF remediation_guidance has "code change" OR pattern vulnerability → Code Refactoring (Step 2C)
IF remediation_guidance has "patch" → Apply Patch (Step 2D)
ELSE → Workarounds (Step 3)
IF risk_level = "NEEDS_REVIEW":
→ Manual review + defensive workarounds (Step 3)
Step 2: Plan Dependency Update (If Applicable)
Analyze the dependency situation:
-
Understand the dependency relationship:
- Is this a direct or indirect (transitive) dependency?
- If indirect, which direct dependency pulls it in?
- Are there multiple dependency paths to this package?
- What version is currently in use?
-
Assess the update strategy:
For direct dependencies:
- Can we directly update to the fixed version?
- What's the version jump? (major/minor/patch)
- Are there intermediate versions we should consider?
For indirect dependencies:
- Should we update the parent package instead?
- Will updating the parent also fix this issue?
- Is the parent package actively maintained?
- Do we need to explicitly override the version?
- Is a
replacedirective necessary (avoid unless no other update path exists)?
-
Research breaking changes:
- Search for changelog and release notes
- Look for BREAKING CHANGE markers
- Check GitHub issues for migration problems
- Assess semantic versioning signals:
- Major version bump → Expect breaking changes
- v0.x minor bump → May have breaking changes
- Patch version → Should be safe
- Identify specific API changes that affect your code
-
Evaluate compatibility risks:
- Does the fixed version require a newer Go version?
- Are there conflicts with other dependencies?
- What's the blast radius if something breaks?
- Is there test coverage for affected code paths?
-
Plan the update approach:
- Decide on exact version to target
- Determine the update commands to use
- Plan for testing and validation
- Consider gradual rollout strategy
- Prepare rollback plan
Document the chosen approach with specific commands and rationale for the decision.
Step 2A: Plan Go Runtime Update (If Applicable)
Analyze Go runtime update requirements:
-
Determine version requirements:
- What Go version fixes the vulnerability?
- What's the current Go version in use?
- What's the minimum version bump needed?
- Are there multiple affected Go versions with different fixes?
-
Assess project constraints:
- What's the project's minimum supported Go version (from go.mod)?
- Are there compatibility requirements (OS distributions, cloud providers)?
- What Go versions are used in CI/CD pipelines?
- What about developer environments?
- Are there dependencies that constrain Go version?
-
Evaluate upgrade path:
- Can we upgrade directly to the fixed version?
- Should we target a newer Go version for future-proofing?
- Are there intermediate versions to consider?
- What's the official support status of target version?
-
Research breaking changes:
- Review Go release notes for the target version
- Check for deprecated features being removed
- Look for behavior changes in standard library
- Identify new language features that might affect build
- Search for migration guides
-
Plan the migration:
- Decide on target Go version
- Update go.mod minimum version
- Plan testing strategy
- Update build systems and Docker base images
- Update developer documentation
-
Consider alternatives:
- If Go update is too disruptive, can we backport the fix?
- Are there workarounds while planning the upgrade?
- What's the risk of delaying the Go update?
Document the chosen Go version, migration plan, and timeline.
Step 2B: Plan Configuration Changes (If Applicable)
Analyze if configuration-based mitigation is possible:
-
Understand what the vulnerability requires to trigger:
- Does it require a specific feature to be enabled?
- Does it depend on insecure default settings?
- Is it protocol/algorithm-related?
- Does it require network exposure?
-
Evaluate configuration options:
- Review application/library configuration documentation
- Check if security features can be enabled
- Determine if vulnerable features can be disabled
- Consider network-level controls
-
Design configuration changes:
- If vulnerable feature is optional: Disable it
- If secure alternatives exist: Switch to them (e.g., stronger crypto)
- If security controls are available: Enable them
- If network exposure is unnecessary: Restrict access
-
Assess impact:
- Will disabling the feature break functionality?
- Are there dependencies on the current configuration?
- What's the performance/UX impact?
- Is the change reversible?
Configuration types to consider:
- Application config files (YAML, JSON, properties)
- Environment variables
- Command-line flags
- Runtime feature flags
- Web server configuration (nginx, apache)
- Network policies (firewalls, Kubernetes NetworkPolicy)
- Infrastructure as Code (Terraform, CloudFormation)
Document specific configuration changes needed with rationale.
Step 2C: Plan Code Refactoring (If Applicable)
Analyze the vulnerability to determine code changes needed:
Step 2C.1: Identify Vulnerable Code Patterns
-
Review the CVE description:
- What specific code pattern or API usage is vulnerable?
- Is it about how a function is called or what's passed to it?
- Are there examples of vulnerable vs. safe usage?
-
Locate vulnerable code in the codebase:
- Search for the vulnerable function/method calls
- Identify all files and locations where it's used
- Understand the context of each usage
-
Categorize the refactoring type:
- API migration: Old API → new safe API
- Pattern replacement: Unsafe pattern → safe pattern
- Input handling: Add validation/sanitization
- Error handling: Add proper error checks
- Resource management: Add limits/cleanup
- Security controls: Add authentication/authorization checks
Step 2C.2: Design the Refactoring
Based on the vulnerability type, determine the approach:
For unsafe API usage:
- Replace with secure alternative API
- Add security parameters/options to existing calls
- Wrap calls with safety checks
For missing input validation:
- Add validation before vulnerable operations
- Sanitize/escape untrusted data
- Use type-safe APIs when the language and framework provide them
For resource management issues:
- Add resource limits (size, time, count)
- Implement proper cleanup (defer, finally)
- Use safer resource handling patterns
For logic flaws:
- Fix incorrect conditionals/checks
- Add missing security validations
- Correct state management
Step 2C.3: Plan Migration Strategy
-
Find all usage locations:
grep -r "<function-name>" --include="*.go" . # Or use codebase_search for semantic search -
Assess each usage:
- Is this usage vulnerable or safe?
- What's the correct replacement?
- Are there edge cases to handle?
-
Create migration examples:
- Document "before" and "after" for each pattern
- Explain why the change is necessary
- Note any behavior changes
-
Estimate scope:
- Number of files affected
- Complexity of changes (simple replace vs. logic rewrite)
- Test coverage available
-
Plan testing:
- Which tests need updates?
- Are new tests needed?
- How to verify the fix works?
Document specific code changes with file paths, line numbers, and refactoring rationale.
Step 2D: Apply Security Patches (If Applicable)
When vendor provides patch files:
-
Obtain the patch:
- Download from vendor security advisory
- Verify patch authenticity and source
- Check patch format (unified diff, git patch, etc.)
-
Review the patch carefully:
- Understand what changes it makes
- Verify it targets the correct vulnerability
- Check for any side effects or breaking changes
- Ensure it's appropriate for your version
-
Apply the patch:
- Test in non-production environment first
- Use appropriate tool (
patch,git apply) - Handle conflicts if any
- Document what was patched
-
Verify the patch:
- Confirm all changes applied without conflicts or missing hunks
- Run tests to ensure no breakage
- Test the vulnerability is actually fixed
- Document patch source and date
For Go module patches:
- Consider forking the repository
- Apply patch to your fork
- Use
replacedirective in go.mod to use patched version - Document this is temporary until official fix
Alternative: If patch is complex or risky, consider workarounds (Step 3) while waiting for official release.
Step 3: Plan Workarounds (If No Fix Available)
Analyze the vulnerability to design appropriate mitigations:
Step 3.1: Understand the Vulnerability
Ask these questions about the CVE:
-
What type of vulnerability is it?
- DoS, RCE, injection, authentication bypass, information disclosure, etc.
-
What triggers the vulnerability?
- User input, specific API calls, network requests, file operations, etc.
-
What is the attack vector?
- Remote/network-based, local, requires authentication, etc.
-
What resource/capability is affected?
- CPU, memory, network, data confidentiality, system integrity, etc.
-
What conditions must exist for exploitation?
- Specific input patterns, race conditions, particular configurations, etc.
Step 3.2: Identify Mitigation Strategies
Based on vulnerability characteristics, consider appropriate defenses:
For Input-Related Vulnerabilities:
- Validate input size, format, and content before vulnerable code
- Sanitize/escape untrusted input
- Reject known malicious patterns
- Use allowlists instead of denylists when the set of valid inputs is known
For Algorithmic Complexity / DoS:
- Impose timeouts on operations
- Limit resource consumption (CPU time, memory)
- Add circuit breakers to prevent cascading failures
- Cache results when possible
- Consider simpler/safer algorithms for untrusted input
For Resource Exhaustion:
- Rate limit requests (per user, per IP, globally)
- Set quotas on operations
- Implement backpressure mechanisms
- Monitor and alert on unusual patterns
For Authentication/Authorization Issues:
- Add additional authentication checks
- Restrict network access (firewalls, NetworkPolicies)
- Require multi-factor authentication
- Log and monitor access attempts
For Information Disclosure:
- Redact sensitive data in responses
- Restrict access to affected endpoints
- Add encryption in transit/at rest
- Audit and minimize data exposure
For Code Execution Vulnerabilities:
- Run vulnerable code in sandboxes
- Reduce privileges (principle of least privilege)
- Disable dynamic code execution when the application does not require it
- Add integrity checks
Step 3.3: Design Layered Defense
Apply defense-in-depth principles:
- Layer multiple controls - Don't rely on a single mitigation
- Fail securely - If mitigation fails, fail closed not open
- Monitor for exploitation - Add logging/alerting for attack attempts
- Consider degraded functionality - Can you disable features temporarily?
Step 3.4: Evaluate Trade-offs
For each mitigation:
- Effectiveness: How well does it address the vulnerability?
- Impact: Will it break legitimate use cases?
- Performance: What's the overhead?
- Complexity: How difficult to implement and maintain?
- Risk: Could the workaround introduce new issues?
Step 3.5: Document Mitigation Plan
For each workaround, specify:
- What it protects against
- How it works
- Where to implement it (code location, config file, infrastructure)
- Expected impact on functionality/performance
- Monitoring/logging to detect bypass attempts
- When it can be removed (after patching)
Note: Workarounds are temporary defenses, not permanent solutions. Always prioritize updating to a fixed version when available.
Step 4: Create Verification Plan
Design a comprehensive verification strategy:
-
Understand project testing infrastructure:
- Does the project have a Makefile with standard targets?
- What build and test commands does the project use?
- Are there CI/CD pipelines that should be considered?
- What testing levels exist? (unit, integration, e2e)
- Are there performance or security-specific tests?
-
Plan verification layers:
Dependency Verification:
- Confirm the updated version is actually in use
- Verify go.mod and go.sum reflect the target version with no unexpected changes
- Check for unexpected transitive dependency changes
- Ensure no conflicts were introduced
Build Verification:
- Confirm the project builds successfully
- Check for new compiler warnings
- Verify all target platforms still build
- Test with different Go versions if applicable
Functional Verification:
- Run existing test suites (unit, integration, e2e)
- Focus on code paths that use the updated dependency
- Test edge cases related to the vulnerability
- Add regression tests for this CVE
Security Verification:
- Re-run vulnerability scanners (govulncheck, etc.)
- Confirm the specific CVE no longer appears in scan results
- Check for new vulnerabilities introduced by the update
- Validate security assumptions haven't changed
Regression Verification:
- Test critical user journeys
- Check performance hasn't degraded
- Verify logging and monitoring still work
- Test error handling and edge cases
-
Sequence the verification steps:
- Start with fast, cheap checks (dependency verification)
- Progress to more expensive tests (full test suite)
- End with manual/exploratory testing if needed
- Run independent verification steps in parallel when CI infrastructure supports it
-
Define success criteria:
- What must pass before considering the fix complete?
- What level of test coverage is acceptable?
- How to handle test failures (existing vs. new)?
- What monitoring should be in place post-deployment?
-
Plan for different environments:
- Local development verification
- CI/CD pipeline checks
- Staging environment validation
- Production canary/gradual rollout
Document specific verification commands, expected outcomes, and decision points for handling failures.
Step 5: Generate Remediation Plan Document
Create a comprehensive, context-specific remediation document:
Structure the document based on the remediation type:
-
Executive Summary Section:
- State the CVE and its severity clearly
- Summarize the vulnerability impact on THIS project
- Present the recommended remediation approach
- Highlight urgency and risk levels
- Note any critical dependencies or blockers
-
Detailed Remediation Steps:
Tailor to the remediation type selected:
- For dependency updates: Explain the version change, why this version, compatibility considerations
- For Go runtime updates: Explain version requirements, migration path, compatibility impacts
- For configuration changes: Specify exact changes, why they work, impact on functionality
- For code refactoring: Detail the code changes, locations, before/after comparisons
- For workarounds: Explain each mitigation, why it's effective, limitations
Include:
- Step-by-step instructions (not just commands)
- Rationale for each decision made
- Project-specific context and considerations
- Estimated time and effort
- Prerequisites and dependencies
-
Verification Plan:
- Specific commands appropriate to the project
- Success criteria for each verification step
- What to look for (not just "run tests")
- How to interpret results
- What to do if verification fails
-
Risk Assessment:
Update Risk:
- What could go wrong with this remediation?
- Breaking changes identified
- Dependencies on other changes
- Performance implications
- Rollback difficulty
Not Updating Risk:
- Exploitability in THIS environment
- Actual exposure (reachability, network access)
- Potential impact (data, availability, reputation)
- Likelihood of exploitation
- Compliance implications
-
Implementation Strategy:
- Environment progression (dev → staging → prod)
- Rollout approach (big bang, canary, gradual)
- Monitoring and validation checkpoints
- Rollback triggers and procedures
- Communication plan for stakeholders
-
Timeline and Effort:
- Estimated time for each phase
- Resource requirements
- Critical path items
- Recommended deadline based on risk
-
Supporting Information:
- Links to relevant documentation
- References to CVE advisories
- Related issues or PRs
- Contact information for escalation
Adapt the document structure and depth to:
- Remediation complexity
- Organizational needs
- Audience (technical team, management, security)
- Risk level and urgency
The document should enable someone to execute the remediation plan without additional context.
Return Value
Return structured plan to parent command:
{
"skill": "remediation-planning",
"status": "success",
"input_summary": {
"cve_id": "<from Phase 1>",
"risk_level": "<from Phase 2>",
"reachable": "<from call-graph-analysis or unknown>",
"fixed_version_available": "<true|false from Phase 1>"
},
"remediation_decision": {
"strategy_selected": "<dependency_update|go_runtime_update|configuration|code_refactoring|workaround|combination>",
"reasoning": "<why this strategy based on inputs>",
"priority": "<CRITICAL|HIGH|MEDIUM|LOW based on severity+confidence+reachability>",
"driven_by": {
"primary_factor": "<main decision factor from analysis>",
"confidence_factor": "<confidence level justification>",
"availability_factor": "<fix availability>"
}
},
"remediation_plan": {
"remediation_type": "<type>",
"complexity": "<LOW|MEDIUM|HIGH>",
"fix_available": true,
"requires_code_changes": false,
"requires_go_update": false,
"requires_config_changes": false,
"update_commands": ["go get ...", "go mod tidy"],
"config_changes": [],
"code_changes_summary": "",
"verification_commands": {
"verify": "make verify || go mod verify",
"build": "make build || go build ./...",
"test": "make test || go test ./...",
"vuln_check": "govulncheck ./..."
},
"breaking_changes": [],
"estimated_effort": "15 minutes",
"risk_level": "LOW"
},
"project_context": {
"has_makefile": true,
"available_commands": ["verify", "build", "test"],
"go_version": "1.21",
"dependency_type": "indirect"
}
}
Priority Determination:
Priority should be calculated based on multiple factors:
- CVE severity (CRITICAL/HIGH/MEDIUM/LOW)
- Confidence level of impact assessment
- Reachability of vulnerable code
- Availability of fixes
- Exploitability in the specific environment
- Business criticality of affected systems
Higher priority when: severe + high confidence + reachable + fix available Lower priority when: low severity + uncertain + not reachable + no immediate fix
Automated Fix Eligibility - Decision Framework:
Evaluate whether to offer automated fix application by considering:
-
Confidence Level:
- HIGH confidence → Automation is safer
- MEDIUM/LOW confidence → Manual review required
-
Remediation Complexity:
- Simple dependency update with no breaking changes → Good candidate
- Multiple steps or code changes → Manual application safer
- Configuration changes with unclear impact → Needs review
-
Risk Assessment:
- Well-tested fix from trusted source → Lower risk
- Affects critical code paths → Manual verification needed
- Breaking changes possible → Requires careful review
-
Project Maturity:
- Strong test coverage → Automation safer
- Limited testing → Manual application with thorough testing
- Active development → Consider coordination
-
Blast Radius:
- Small, localized change → Automation acceptable
- Wide-ranging impact → Manual control preferred
- Affects production systems → Needs careful planning
General principles:
- Only offer automation for high-confidence, low-risk scenarios
- Always provide clear rationale for the decision
- When in doubt, recommend manual application with monitoring
- Automation should never bypass testing and verification
Integration with analyze-cve
This skill is called from Phase 4 of the analyze-cve skill.
Input Pipeline:
Phase 1 (CVE Intelligence) → CVE profile, severity, affected package, fixed version
Phase 2 (Impact Analysis) → Risk level, current version, usage locations
↓ Optional: Call Graph Analysis Skill → Reachability risk level, call chain
↓ Optional: govulncheck → Detection result, vulnerable symbols
Phase 3 (Report Generation) → Consolidated impact assessment report
Phase 4 (THIS SKILL) → Complete remediation plan based on all inputs
Phase 5 (Fix Application) → Execute remediation using plan from this skill
Output: Complete remediation plan tailored to the specific CVE and project context, including verification strategy, risk assessment, priority determination, and automated fix eligibility decision based on thorough analysis.
Report to Jira
Posts the completed CVE analysis report as a comment on the source Jira ticket — the same ticket the CVE details were read from (SOURCE_TICKET, set in Phase 0.5 from --jira=/--jql=). Always called as the last step of Phase 4, after the report has been generated. Also reused by create-fix-pr (Phase 6) for a short follow-up comment containing the PR URL.
If no Jira ticket was involved (direct <CVE-ID> mode), this skill is skipped entirely — there is nothing to post to.
Step 1: Confirm Report is Ready
Before posting, verify the following are available from the parent command:
- Final report content (full markdown from Phase 3)
- CVE ID (e.g.
CVE-2024-45338) SOURCE_TICKET— the Jira ticket key from--jira=/--jql=(e.g.OCPBUGS-12345). This is the only ticket this skill writes to.jira_context— label snapshot from Phase 0.5 (jira_context["labels"]); used as a hint only — Step 4.5 re-fetches current labels before writing- Risk level (
HIGH/MEDIUM/LOW/NEEDS_REVIEW) AUTO_APPROVE(yes/no, defaultno) — governs the Step 3b visibility-downgrade fallback prompt
If SOURCE_TICKET is not available (direct CVE mode): return status: skipped with reason "no_source_ticket".
If the report is incomplete or Phase 3 did not finish, return status: skipped with reason.
Step 2: Build the Comment Body
Read ${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}/report.md from Phase 3 and post it in full. The Jira comment is the report — do not pre-emptively shorten it or write a separate jira-comment.md.
Write standard Markdown — Jira Cloud renders Markdown natively when posted with contentFormat: "markdown" (see markdown-for-jira reference if that plugin is installed; the syntax is standard CommonMark either way). No wiki-markup conversion is needed.
Default body = attribution header + entire report.md. If Phase 4 produced a remediation plan not already under ## Remediation in the report, append it as ## Remediation Plan (Phase 4).
Prepend the following attribution header before the report:
> ⚠️ **This analysis was performed automatically by `/compliance:analyze-cve`.**
> Results should be reviewed by a human before acting on remediation steps.
---
Size limit handling
Jira comment bodies are capped at 32,767 characters. Apply these steps in order — only move to the next step if the comment is still over 32,000 chars:
- Post in full (≤ 32,000 chars) — no changes.
- Trim raw tool dumps only (> 32,000 chars) — inside fenced code blocks, replace full
govulncheckscrollback, call-graph DOT, or megabyte grep output with a one-line pointer:
Keep executive summary, CVE context, evidence interpretations, call-graph results table, risk assessment, and remediation in full. Re-measure._(Full output truncated — see `${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/<CVE_ID>/govulncheck-source.txt`)_ - Shortened summary (last resort only) — if still > 32,000 chars after step 2, replace the body with a condensed summary derived from
report.md. Retain: risk level, repository/branch/commit, dependency versions, govulncheck conclusion, four-algorithm call-graph table, manual verification findings, recommendation, and artifact paths. Omit repeated narrative and any remaining large code blocks. Note at the top:
Do not use a shortened summary unless steps 1–2 are insufficient._(Full report exceeded Jira comment limit — summary below. See `${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/<CVE_ID>/report.md`.)_
Stripping rules (apply regardless of size)
- Remove internal email addresses — replace with the display name only.
- Do not include embargoed content — if somehow reached here with
embargo_status: True, abort immediately.
Step 3: Post the Comment
Credential rule: Never print, echo, or log any token, key, or password value. Reference credentials only via environment variable names. Never interpolate a credential value into a logged string.
CVE analysis reports contain security-sensitive findings. Prefer restricted (internal-only) visibility when the Jira instance supports it.
Step 3a: Direct REST API with restricted visibility (attempt first, if credentials are configured)
If a token is available in the environment, try the REST API directly so the comment can carry a visibility restriction the MCP tool does not support. Try both auth schemes and let the HTTP response decide which one worked — credentials may be exposed differently depending on the runtime (a local shell with a bare token vs. a CI/RWS runner with a mounted service-account email+token pair):
- Basic auth (email + API token) — the scheme most Jira Cloud instances actually expect for API tokens. Used when both
JIRA_EMAILand a token are available. - Bearer token only — fallback for runtimes that expose only a bare token env var with no associated email.
JIRA_API_TOKEN="${JIRA_API_TOKEN:-${JIRA_TOKEN:-${ATLASSIAN_API_TOKEN:-}}}"
JIRA_BASE_URL="${JIRA_URL:-}"
JIRA_EMAIL="${JIRA_EMAIL:-}"
if [ -n "${JIRA_API_TOKEN}" ] && [ -n "${JIRA_BASE_URL}" ]; then
case "${JIRA_BASE_URL}" in
https://*) ;;
*) echo "ERROR: JIRA_BASE_URL must use HTTPS (got: ${JIRA_BASE_URL})"; exit 1 ;;
esac
cat > /tmp/cve-report-comment.txt << 'COMMENT_EOF'
<constructed comment from Step 2>
COMMENT_EOF
COMMENT_BODY=$(cat /tmp/cve-report-comment.txt)
COMMENT_JSON_BODY=$(echo "${COMMENT_BODY}" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))")
post_comment() {
# $1 = auth mode: "basic" (email+token) or "bearer" (token only)
# Build the Authorization header inside this function after set +x so
# credentials never appear in traced argv when post_comment is invoked.
local auth_mode="$1" curl_cfg http_code auth_header
curl_cfg=$(mktemp)
chmod 600 "${curl_cfg}"
trap 'rm -f "${curl_cfg}"' RETURN EXIT INT TERM
[[ $- == *x* ]] && local _was_tracing=true || local _was_tracing=false
set +x
if [ "${auth_mode}" = "basic" ]; then
auth_header="Basic $(printf '%s:%s' "${JIRA_EMAIL}" "${JIRA_API_TOKEN}" | base64 | tr -d '\n')"
else
auth_header="Bearer ${JIRA_API_TOKEN}"
fi
printf 'header = "Authorization: %s"\n' "${auth_header}" > "${curl_cfg}"
unset auth_header
$_was_tracing && set -x || true
http_code=$(curl -s -o /tmp/jira-post-response.txt -w "%{http_code}" \
--connect-timeout 15 \
--max-time 60 \
-X POST \
-K "${curl_cfg}" \
"${JIRA_BASE_URL}/rest/api/2/issue/${SOURCE_TICKET}/comment" \
-H "Content-Type: application/json" \
--data-binary @- << EOF
{
"body": ${COMMENT_JSON_BODY},
"visibility": {
"type": "group",
"value": "Red Hat Employee"
}
}
EOF
)
echo "${http_code}"
}
HTTP_STATUS=""
if [ -n "${JIRA_EMAIL}" ] && [ -n "${JIRA_API_TOKEN}" ]; then
echo "Attempting REST post with Basic auth (email + token)..."
HTTP_STATUS=$(post_comment basic)
fi
# Only retry with the other auth scheme when Basic wasn't attempted at all
# (no JIRA_EMAIL) or came back with an actual auth failure (401/403). This
# POST is not idempotent: retrying it for every other status (400, 429,
# 5xx, or curl's own "000") risks creating a duplicate comment if the first
# request was actually accepted server-side but the response was lost or
# malformed. Any other failure goes straight to Step 3b instead of retrying.
if { [ -z "${HTTP_STATUS}" ] || [ "${HTTP_STATUS}" = "401" ] || [ "${HTTP_STATUS}" = "403" ]; } && [ -n "${JIRA_API_TOKEN}" ]; then
echo "Attempting REST post with Bearer auth..."
HTTP_STATUS=$(post_comment bearer)
fi
echo "Jira API HTTP status: ${HTTP_STATUS:-none attempted}"
if [ "${HTTP_STATUS}" = "201" ]; then
echo "✓ Comment posted with restricted visibility"
else
echo "✗ REST API failed (HTTP ${HTTP_STATUS:-n/a}) — will fall back to MCP tool"
cat /tmp/jira-post-response.txt 2>/dev/null || true
fi
fi
The
visibilityobject above targetsredhat.atlassian.net. On other Jira Cloud instances, adjusttype/valueto match an equivalent internal-only group, or omitvisibilityentirely if none exists.
- IF HTTP 201 (either scheme) → done. Skip Step 3b.
- IF credentials are not configured → continue to Step 3b.
- IF HTTP 401/403 on both schemes (or Basic wasn't attempted and Bearer also fails) → credentials not available or insufficient permissions; continue to Step 3b.
- IF Basic auth returns any other status (400, 429, 5xx, curl error
000) → do not retry with Bearer (the POST is not idempotent) — go directly to Step 3b. - Never print
JIRA_API_TOKEN,JIRA_EMAIL, the computedBASIC_AUTHvalue, or the contents of${curl_cfg}— only the HTTP status code and response body (which contains no credentials).
Step 3b: MCP tool (default / fallback)
addCommentToJiraIssue(
issue_key=SOURCE_TICKET,
comment_body="<constructed comment from Step 2>",
contentFormat="markdown"
)
⚠️ The MCP tool does not expose a
visibilityparameter — the comment will be visible to everyone with access to the ticket, not restricted to an internal group.
This visibility downgrade is gated by AUTO_APPROVE when it happens after Step 3a was actually attempted and failed (i.e. restricted posting was possible in principle but didn't work):
- IF
AUTO_APPROVE=noand Step 3a was attempted and failed → ask the user:
IF user says no → display the full comment body in the session for manual posting instead.⚠️ Restricted-visibility posting is unavailable (no REST credentials, or the request failed). The MCP fallback will post this comment visible to everyone with ticket access. Proceed? - IF
AUTO_APPROVE=yesand Step 3a was attempted and failed → proceed automatically via the MCP fallback. Clearly log that this comment was posted without the internal-only restriction. - IF Step 3a was never attempted (no REST credentials configured at all) → just post via MCP; this is the normal/expected path for most setups and does not need a prompt.
Fallback — jira-cli (if MCP is also unavailable):
jira issue comment add "${SOURCE_TICKET}" \
--body "$(cat /tmp/cve-report-comment.txt)" \
--no-input
Step 4: Confirm and Report
After posting, output to the session:
✅ Report posted to <SOURCE_TICKET>
<JIRA_BASE_URL>/browse/<SOURCE_TICKET>
CVE: <CVE_ID>
Risk level: <level>
If the post fails:
❌ Failed to post report to <SOURCE_TICKET>
Error: <error message>
The full report has been displayed above. Please copy and paste it
into <SOURCE_TICKET> manually.
Do not retry more than once. On failure, display the comment body in the session so the user can post it manually.
Step 4.5: Mark Source Ticket as Processed
Add the label ai-cve-analyzed to SOURCE_TICKET to prevent redundant re-processing on future runs.
Only run this step if Step 3 succeeded. If Step 3 failed for any reason, skip this step entirely — do not add the label to a ticket that did not receive the comment.
⚠️ CRITICAL: Existing labels MUST be preserved
Jira's update API replaces the entire label list — it does not append. Sending only ["ai-cve-analyzed"] will delete all existing labels on the ticket. This is a destructive operation and must never happen.
Before writing, always:
- Re-fetch the ticket's current labels (do not trust the Phase 0.5 snapshot alone — labels may have changed while analysis ran):
Usefresh = getJiraIssue(issue_key=SOURCE_TICKET) current_labels = fresh["fields"]["labels"] # never start from an empty listjira_context["labels"]only as a fallback if the re-fetch fails. - Append
ai-cve-analyzedtocurrent_labels - Write the combined list back
# current_labels comes from the mandatory re-fetch above (Step 4.5)
if "ai-cve-analyzed" not in current_labels:
new_labels = current_labels + ["ai-cve-analyzed"]
else:
new_labels = current_labels # already marked — nothing to write
editJiraIssue(
issue_key=SOURCE_TICKET,
fields={"labels": new_labels}
)
Fallback — jira-cli (appends without replacing — safe to use directly):
jira issue edit "${SOURCE_TICKET}" --label "ai-cve-analyzed" --no-input
Verification (mandatory when using the MCP/REST label-replace path)
After the update call, re-fetch the ticket labels and confirm:
updated = getJiraIssue(issue_key=SOURCE_TICKET)
updated_labels = updated["fields"]["labels"]
assert "ai-cve-analyzed" in updated_labels, "New label missing"
for label in current_labels:
assert label in updated_labels, f"LABEL LOST: {label}"
If the new label is missing: log a non-fatal warning — the report is already posted:
⚠️ Could not add 'ai-cve-analyzed' label to <SOURCE_TICKET>. Add it manually to prevent re-processing.
If an existing label was lost: this is a data integrity error — log it and output the original label list so the user can restore it:
❌ LABEL INTEGRITY ERROR on <SOURCE_TICKET>
The following labels were present before the update but are now missing:
<list of lost labels>
Original full label list (restore manually):
<current_labels>
If both checks pass:
✅ Label 'ai-cve-analyzed' added to <SOURCE_TICKET>. Labels verified intact.
Return Value
Success:
{
"skill": "report-to-jira",
"status": "success",
"source_ticket": "<SOURCE_TICKET>",
"cve_id": "<CVE_ID>",
"risk_level": "<HIGH|MEDIUM|LOW|NEEDS_REVIEW>",
"method": "rest | mcp | jira-cli"
}
Skipped:
{
"skill": "report-to-jira",
"status": "skipped",
"reason": "<no_source_ticket | report incomplete | phase 3 did not finish>"
}
Failed:
{
"skill": "report-to-jira",
"status": "failed",
"source_ticket": "<SOURCE_TICKET>",
"error": "<error message>",
"fallback": "comment body displayed in session for manual posting"
}
Integration with analyze-cve
Called from Phase 4 of the analyze-cve skill as the final step, after the report has been fully generated.
Input: complete report content, CVE ID, risk level, SOURCE_TICKET (from Phase 0.5), AUTO_APPROVE
Output: confirmation of comment and label posted to SOURCE_TICKET, or status: skipped/failed per above
Also called from Phase 6 (create-fix-pr) for a short follow-up comment containing only the GitHub PR URL. That path uses the section below and must not replace this analysis comment or change labels.
Follow-up: PR URL comment (Phase 6)
Post a new comment on SOURCE_TICKET after a remediation PR is opened. Invoked by create-fix-pr.
Do not run this path unless SOURCE_TICKET is set, Phase 6 produced a PR_URL, and the user approved opening the PR.
Do not:
- Edit or delete the Phase 4 analysis comment
- Add or remove labels (
ai-cve-analyzedstays as Phase 4 left it) - Re-post the full analysis report
- Mention embargoed content (if
embargo_status = True, abort)
Comment body
### Remediation PR opened
A pull request is open for this CVE.
- **PR:** [<PR_URL>](<PR_URL>)
- **CVE:** <CVE_ID>
- **Change:** <what Phase 5 changed — `<module>` <old> → <new> only for a dependency bump; otherwise a short source/config summary>
- **Base branch:** <BASE_BRANCH>
Posting
Use the same procedure as Step 3 (REST with restricted visibility first if configured, MCP/jira-cli fallback otherwise).
On failure, print the comment in the session for manual paste. Do not treat a Jira follow-up failure as a GitHub PR failure — the PR itself is still a success.
Return:
{
"skill": "report-to-jira",
"status": "success | skipped | failed",
"mode": "pr_followup",
"source_ticket": "<SOURCE_TICKET>",
"pr_url": "<PR_URL>"
}
Sponsors
Details
- Marketplace
- openshift-eng/ai-helpers
- Source
- plugins/compliance
- Category
- Security
- Keywords
- cve, vulnerabilities, compliance, go
More from openshift-eng/ai-helpers
All 56- consolev0.1.0
- container-imagev0.0.2
- docv0.0.2
- etcdv0.0.2
- gitv0.0.7
- githubv0.3.0
- golangv0.7.0
- gopls-lspv1.0.0
- gwapiv0.0.1
- hcpv0.0.3
- hello-worldv1.0.3
- jirav0.9.8
- lvmsv0.1.1
- marketplace-opsv0.1.2
- metricsv0.3.0
- must-gatherv0.0.3
- native-notificationsv0.0.2
- nid-teamv0.2.2
- nodev0.0.3
- node-bugv0.0.3
- node-cvev0.0.8
- node-onboardingv0.0.3
- node-rpmv0.0.3
- node-teamv1.0.1