Security compliance and vulnerability analysis tools for Go projects

version
0.4.1
GitHub stars
123

Install

/plugin install compliance@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 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 labeled ai-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/--jql was used), then prompts the user.
  • --algo (default: vta): Call graph construction algorithm.
    • vta — Most precise, fewest false positives (recommended)
    • rta — Good balance of precision and speed
    • cha — Fast, less precise
    • static — 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:

  1. Autonomous Mode — the full AUTO_APPROVE decision table (what's gated vs. what always hard-fails)
  2. Security — Credential Handling — rules that apply to every command this skill runs
  3. Runtime Configuration — AI_HELPERS_WORKSPACE, FORK_ORG
  4. Implementation — Phase 0 (setup) through Phase 6 (PR creation), including the Repo Guard and each sub-skill's input/output contract
  5. Return Value — the report format this skill produces

Examples

  1. Basic CVE analysis against an explicit repo:

    /compliance:analyze-cve CVE-2024-45338 --repo=https://github.com/openshift/cert-manager-operator
    
  2. With specific algorithm:

    /compliance:analyze-cve CVE-2024-45338 --repo=https://github.com/openshift/cert-manager-operator --algo=rta
    
  3. Starting from a Jira ticket (repo/branch resolved automatically from the ticket's image name):

    /compliance:analyze-cve --jira=OCPBUGS-12345
    
  4. 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:

  • graphviz for visual call graph generation (brew install graphviz or sudo apt-get install graphviz)
  • gh (GitHub CLI, authenticated via gh auth login) for Phase 6 pull-request creation. Missing gh does 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 jira plugin's bundled Rovo MCP) or jira-cli for --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 cloned REPO_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
  • govulncheck is 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@latest
  • digraph: go install golang.org/x/tools/cmd/digraph@latest
  • Go workspace with go.mod file

Optional Tools

  • graphviz (for visualization): brew install graphviz (macOS) or sudo apt-get install graphviz (Linux)
  • sfdp or dot command (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 --algo from parent command
  • CVE_ID — used to construct the output directory
  • OUT_DIR (optional, default: ${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/${CVE_ID}) — where artifacts are written; same workspace base as Phase 0.7's REPOS_BASE

Critical Rules

  1. Always use timeout -k 10 — plain timeout sends SIGTERM but callgraph can ignore it when stuck in SSA construction or type resolution. -k 10 sends SIGKILL after 10s grace, guaranteeing termination.
  2. Never run callgraph on ./... 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.
  3. 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 callgraph invocations use timeout -k 10 300 (5 minutes + 10s force-kill) to prevent hanging.
  • Scope: target the specific main package (e.g. ./cmd/controller), not ./.... The callgraph tool 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_PKG graph → Continue to Step 4
  • IF function NOT found in this graph → Try the next candidate from MAIN_PKGS (different TARGET_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.go test 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.main not 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)

  • go toolchain with go.mod in workspace root
  • govulncheck: go install golang.org/x/vuln/cmd/govulncheck@latest
  • callgraph: go install golang.org/x/tools/cmd/callgraph@latest
  • digraph: 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:

  • --algo preference 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.mod from 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.mod dependencies
  • 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:

  1. 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.
  2. 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.
  3. "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.
  4. Always use timeout -k 10 to force-kill if SIGTERM is ignored. Plain timeout sends 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 list succeeds with CGO_ENABLED=0 → continue to Step 2c, then 2d
  • IF go list still fails after Step 2c's CGO probe (with the chosen CGO_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 list still fails after retry → ${OUT_DIR}/govulncheck-source.txt is populated; skip Step 2d and proceed to Method 3
  • IF go list succeeds → 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.txt as 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: --algo preference from user, vulnerable function signature, package path
  • Receive: Risk level, call chain, evidence files

Scope rule: Never invoke callgraph with ./.... 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:

  1. Basic Presence (Low) — Package in go.mod (Method 1, 3)
  2. Import & Version Analysis (Medium) — Package imported, version in vulnerable range, function names found (Method 4)
  3. Vulnerability Scanner (Medium-High) — govulncheck confirms reachable vulnerable symbols (Method 2)
  4. Call Graph Reachability (Definitive) — Proven execution path from entry point to vulnerable function (Method 5)
  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.mod entries, go list output, 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, outside REPO_DIR)
  • Scanner Evidence: govulncheck output, 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 govulncheck confirms 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.mod but 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.mod and 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_DIR and verification passed
  • The user approved creating a GitHub PR
  • embargo_status is not True

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:

InputSourceRequired
REPO_DIRPhase 0.7Yes
GIT_BRANCHPhase 0.7 (mapped release branch, e.g. release-4.17)Yes
REPO_URLPhase 0.7Yes
CVE_IDPhase 0.5 / direct CVE modeYes
SOURCE_TICKET--jira= / --jql=No
AUTO_APPROVEPhase 0 (--auto-approve, default no)Yes
FORK_ORGCaller environment (e.g. CI/RWS runner)No — enables Fork Mode when set
PHASE5_FILESPhase 5 allowlist (incl. untracked)Yes
Module path, old version, new versionPhase 4 / 5Yes if a dependency bump
Short CVE descriptionPhase 1Recommended
Phase 5 change summaryPhase 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 git is missing → print install instructions and return status: failed (git_missing). Stop. Do not commit or push.
  • IF gh is missing → print install instructions (https://cli.github.com/) and return status: failed (gh_missing). Stop. Do not commit or push.
  • IF gh auth status fails → print gh auth login instructions and return status: 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 gh auth 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 (the gh repo view above succeeded) and (IS_FORK is not exactly true or PARENT_FULL_NAME is not exactly ${ORG}/${REPO}) → stop immediately, do not add the fork remote or push anything, and return status: 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_EXIT is non-zero → stop immediately and return status: failed (fork_create_failed). Do not poll, do not add the fork remote, do not push — the create call already reported failure, so there is nothing to wait for.
  • IF FORK_CREATE_EXIT is 0 → 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 to origin — that would silently switch to requiring direct upstream write access, which is exactly what FORK_ORG was 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

  1. IF embargo_status = True → abort immediately. Do not commit, push, create a PR, or mention ticket contents.

  2. IF Phase 5 did not complete successfully → return status: skipped (phase5_incomplete).

  3. 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 outside PHASE5_FILES → always return status: failed (phase5_files_mismatch) immediately. Never gated by AUTO_APPROVE and never prompt.
    • IF working tree is clean and HEAD is still ${GIT_BRANCH} with no Phase 5 commit → return status: skipped (no_local_changes).
  4. 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.


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)
    
    ChoiceAction
    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.mod is in this diff, mention possible module-file conflicts. Strategy = new.
    No answerDo not guess. Ask again.
  • AUTO_APPROVE=yes → always wait, automatically, with no exceptions: return status: skipped (user_wait_for_pr_auto) including the existing PR URL. Never auto-choose stack (that pushes commits onto a branch nobody reviewed for this run) or independent (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=no if 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, and go.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=yes recorded 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; never git add -A or git add .
  • Never commit/push/PR without validating the staged (and, for stack, the branch) path set against PHASE5_FILES and rejecting extras
  • Never run vendor sync in Phase 6 — it happens in Phase 5, before PHASE5_FILES is written
  • Never push to, or open a PR from, a FORK_ORG repo without first verifying its fork lineage (isFork + parent.fullName match) — never reuse a same-named repo that isn't actually a fork of the target
  • Never let AUTO_APPROVE=yes auto-select stack or independent on a PR-title conflict — always wait unattended
  • Never let AUTO_APPROVE=yes skip a hard-fail case (missing/mismatched PHASE5_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_search tool 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: YYYY from CVE-YYYY-NNNNN
  • Number: NNNNN from CVE-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 fieldProfile fieldNotes
cvss_score + cvss_vectorseverity.cvss_score, severity.cvss_vectorPrefer Jira value; verify against NVD in Step 2
cwe_idcwe_idCross-check with NVD; flag if they differ
summary (parsed description)description (supplement)Internal phrasing may be more specific
affects_versionsAnalysis scope (which project/release versions are affected)
target_versionsFix target / release window
release_note_textremediation.recommended_action (supplement)May already describe the fix or upgrade path
components, labelsContext only
Description body (workaround scan)remediation.workaroundsAlready extracted by jira-cve-extraction
Internal notes from descriptioninternal_context field in profileCapture 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_context is null or absent (direct <CVE-ID> mode) → Skip this step entirely, proceed to Step 2 as normal
  • IF jira_context is 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:

  1. Search by package name (if known from context):

    Search: "{package-name} vulnerability {year}"
    Example: "<package-name> vulnerability <year>"
    
  2. Search for GHSA aliases:

    Search: "GHSA-{pattern} golang"
    
  3. 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 by jira-cve-extraction when --jira=/--jql= was used)
  • jira_context object from the jira-cve-extraction skill (optional — only present when --jira= or --jql= was provided)
  • AUTO_APPROVE (yes/no, default no) — 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:

  1. Full GitHub URL supplied (--repo=https://github.com/...) → use directly, skip this skill.
  2. Exact image name match — look the image name up in the table below.
  3. Prefix match — strip version suffixes (e.g. -1-0, -1-12-4, -rhel9, -rhel8) and re-match.
  4. Keyword match — check the per-section keyword rules at the bottom of each group.
  5. 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:

  1. Clone the release repo at the mapped release branch
  2. Read .gitmodules from that branch to find the submodule entry matching the target image
  3. Read the pinned commit from the release repo tree (git ls-tree HEAD <submodule-path>) — do not clone from the .gitmodules branch field alone
  4. 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 valueRelease branch
cert-manager-X-Yrelease-X.Y in cert-manager-operator-release
external-secrets-X-Yrelease-X.Y in external-secrets-operator-release
ztwim-1.0release-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 / PrefixSubmodule 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-rhel9cert-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 / PrefixGitHub Repository
cert-manager-operator-containerhttps://github.com/openshift/cert-manager-operator
cert-manager-operator-rhel9https://github.com/openshift/cert-manager-operator
cert-manager/cert-manager-operator-rhel9https://github.com/openshift/cert-manager-operator
cert-manager/cert-manager-operator-bundlehttps://github.com/openshift/cert-manager-operator
cert-manager-istio-csr
Image Name / PrefixGitHub Repository
cert-manager/cert-manager-istio-csr-rhel9https://github.com/openshift/cert-manager-istio-csr
jetstack-cert-manager
Image Name / PrefixGitHub Repository
cert-manager/jetstack-cert-manager-rhel9https://github.com/openshift/jetstack-cert-manager
cert-manager/jetstack-cert-manager-acmesolver-rhel9https://github.com/openshift/jetstack-cert-manager
jetstack-cert-manager-rhel9https://github.com/openshift/jetstack-cert-manager
jetstack-cert-manager-containerhttps://github.com/openshift/jetstack-cert-manager
jetstack-cert-manager-acmesolver-rhel9https://github.com/openshift/jetstack-cert-manager
jetstack-cert-manager-acmesolver-containerhttps://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 / PrefixGitHub Repository
operator-sdkhttps://github.com/openshift/ocp-release-operator-sdk
openshift4/ose-operator-sdk-rhel8https://github.com/openshift/ocp-release-operator-sdk
openshift4/ose-operator-sdk-rhel9https://github.com/openshift/ocp-release-operator-sdk
openshift-enterprise-operator-sdk-containerhttps://github.com/openshift/ocp-release-operator-sdk
openshift4/ose-helm-operatorhttps://github.com/openshift/ocp-release-operator-sdk
openshift4/ose-helm-rhel9-operatorhttps://github.com/openshift/ocp-release-operator-sdk
openshift-enterprise-helm-operator-containerhttps://github.com/openshift/ocp-release-operator-sdk
pkg:oci/ose-operator-sdk-rhel8https://github.com/openshift/ocp-release-operator-sdk
pkg:oci/ose-operator-sdk-rhel9https://github.com/openshift/ocp-release-operator-sdk
pkg:oci/ose-helm-operatorhttps://github.com/openshift/ocp-release-operator-sdk
pkg:oci/openshift-enterprise-helm-operatorhttps://github.com/openshift/ocp-release-operator-sdk

Ansible Operator

Image Name / PrefixGitHub Repository
ansible-operator-pluginshttps://github.com/openshift/ansible-operator-plugins
openshift4/ose-ansible-operatorhttps://github.com/openshift/ansible-operator-plugins
openshift4/ose-ansible-rhel9-operatorhttps://github.com/openshift/ansible-operator-plugins
openshift-enterprise-ansible-operator-containerhttps://github.com/openshift/ansible-operator-plugins
pkg:oci/ose-ansible-operatorhttps://github.com/openshift/ansible-operator-plugins
pkg:oci/ose-ansible-rhel9-operatorhttps://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 / PrefixSubmodule 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-0external-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 / PrefixSubmodule in .gitmodules
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-rhel9, *-operator-bundlezero-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-rhel9spiffe-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-rhel9spiffe-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 / PrefixGitHub Repository
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-rhel9https://github.com/openshift/spire-operator
zero-trust-workload-identity-manager/zero-trust-workload-identity-manager-operator-bundlehttps://github.com/openshift/spire-operator
spiffe-spire (agent, server, OIDC discovery provider)
Image Name / PrefixGitHub Repository
zero-trust-workload-identity-manager/spiffe-spire-agent-rhel9https://github.com/openshift/spiffe-spire
zero-trust-workload-identity-manager/spiffe-spire-server-rhel9https://github.com/openshift/spiffe-spire
zero-trust-workload-identity-manager/spiffe-spire-oidc-discovery-provider-rhel9https://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 / PrefixGitHub Repository
zero-trust-workload-identity-manager/spiffe-spire-controller-manager-rhel9https://github.com/openshift/spiffe-spire-controller-manager
spiffe-spiffe-csi (CSI driver)
Image Name / PrefixGitHub Repository
zero-trust-workload-identity-manager/spiffe-csi-driver-rhel9https://github.com/openshift/spiffe-spiffe-csi
redhat-user-workloads/spiffe-csi-driver-*https://github.com/openshift/spiffe-spiffe-csi
spiffe-spiffe-helper
Image Name / PrefixGitHub Repository
zero-trust-workload-identity-manager/spiffe-helper-rhel9https://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 / PrefixGitHub Repository
openshift4/ose-must-gather-rhel9https://github.com/openshift/must-gather
openshift4/ose-support-log-gather-rhel9-operatorhttps://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 / PrefixGitHub Repository
openshift4/ose-secrets-store-csi-driver-rhel9-operatorhttps://github.com/openshift/secrets-store-csi-driver-operator
openshift4/ose-secrets-store-csi-driver-operator-bundlehttps://github.com/openshift/secrets-store-csi-driver-operator
ose-secrets-store-csi-driver-operator-containerhttps://github.com/openshift/secrets-store-csi-driver-operator
openshift4/ose-secrets-store-csi-mustgather-rhel9https://github.com/openshift/secrets-store-csi-driver-operator
ose-secrets-store-csi-mustgather-containerhttps://github.com/openshift/secrets-store-csi-driver-operator
secrets-store-csi-driver (driver only)
Image Name / PrefixGitHub Repository
openshift4/ose-secrets-store-csi-driver-rhel9https://github.com/openshift/secrets-store-csi-driver
ose-secrets-store-csi-driver-containerhttps://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:

  1. CVE ID — passed to Phase 1 (cve-intelligence-gathering)
  2. Image name — passed to Phase 0.7 via the image-repo-mapping skill to resolve which repo to clone
  3. 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. OCPBUGS CVE 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 ticket
  • searchJiraIssuesUsingJql — 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. IF AUTO_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. IF AUTO_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:

  1. A dedicated CVE ID custom field, if the project has one — always accurate when present
  2. Labels — look for a label matching CVE-\d{4}-\d{4,} exactly
  3. Description body — scan for CVE-\d{4}-\d{4,} pattern

Image name fallbacks:

  1. pscomponent: label — parse pscomponent:<image-name> from the labels list; strip the pscomponent: prefix
  2. Downstream Component Name custom field, if the project has one — dedicated field mapping directly to the affected image
  3. 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. IF AUTO_APPROVE=yes, there is no one to ask → Exit immediately with error (never gated by AUTO_APPROVE).
  • IF no image name found → leave IMAGE_NAME blank; Phase 0.7 will prompt the user for --repo= (or hard-fail if AUTO_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.

FieldTypical locationNotes
Statusfields.status.name
Priorityfields.priority.nameBlocker/Critical → urgency escalation
Assigneefields.assignee.displayName
Componentsfields.components[].name
Labelsfields.labels[]Full label list — needed intact for Step 4.5 of report-to-jira
Affects versionsfields.versions[].name
Fix versionsfields.fixVersions[].name
Target versionproject-specific custom field (e.g. "Target Version")
CVSS Scorecustom field named "CVSS Score"Format often 7.5 CVSS:3.1/AV:N/... — extract score and vector separately
CWE IDcustom field named "CWE ID"e.g. CWE-409
Embargo Statuscustom field named "Embargo Status"True/False — security-critical, see Step 5.5
Downstream Component Namecustom field named "Downstream Component Name", if the project has oneRedundant image name source — cross-check against the summary/label extraction
Release Note Textcustom field named "Release Note Text"May already describe the fix
Descriptionfields.descriptionScan 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:
    ❌ Embargoed CVE — cannot proceed.
    
    This ticket is marked as embargoed. Embargoed CVEs must not be
    analysed, disclosed, or shared outside authorised channels.
    
    Exit.
    
    Do NOT output any CVE details, CVSS scores, image names, or other ticket data.
  • 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 .z suffix; the real branch is always the X.Y form. Before doing anything else, strip a trailing .z from BRANCH if 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.Yrelease-X.Y (e.g. openshift-4.17 → release-4.17; openshift-4.16.z → strip to openshift-4.16 → release-4.16)
release-X.YAlready 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

SituationAction
Ticket not found (404)Exit with error: "Ticket not found or access denied"
Auth failurePrompt to authenticate and retry (or exit if AUTO_APPROVE=yes)
No CVE ID in ticketAUTO_APPROVE=no: ask user to supply manually. AUTO_APPROVE=yes: exit with error (never gated).
No image name in ticketLeave blank; Phase 0.7 will prompt for --repo= (or hard-fail if AUTO_APPROVE=yes)
Multiple CVEsList all. AUTO_APPROVE=no: ask user which to analyze. AUTO_APPROVE=yes: exit with error (never gated).
Embargo TrueStop immediately. Return error: "This ticket is under embargo. Embargoed CVEs must not be analysed or disclosed outside authorised channels. Exiting."
Label ai-cve-analyzed presentStop 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 the image-repo-mapping skill to resolve the clone URL
  • analysis_hints.git_branch → Phase 0.7 Step 3 — the -b flag for git clone (Pattern A) or the release-branch lookup (Pattern B)
  • jira_context → Phase 1 (merged into vulnerability profile) + Phase 3 report "Jira Context" section
  • jira_context.cvss_score + cvss_vector → seeds Phase 1 before NVD lookup
  • analysis_hints.urgency_override → can escalate the final risk level
  • analysis_hints.workaround_present → noted in Phase 4 remediation plan
  • jira_context.ticket_key → becomes SOURCE_TICKET for report-to-jira (Phase 4) and create-fix-pr (Phase 6)

Remediation Planning

Creates actionable remediation plans for vulnerable Go codebases based on analysis results from previous phases.

Supported Remediation Types

  1. Dependency Update - Update Go package to fixed version
  2. Go Runtime Update - Update Go itself (for stdlib vulnerabilities)
  3. Configuration Change - Disable features, change settings, adjust security controls
  4. Code Refactoring - Replace vulnerable patterns, add validation, refactor code
  5. Security Patch - Apply vendor-provided patch files
  6. Workarounds - Temporary mitigations (timeouts, rate limiting, input validation)
  7. Infrastructure - Network policies, firewall rules, WAF configuration
  8. 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:

  1. 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?
  2. 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 replace directive necessary (avoid unless no other update path exists)?
  3. 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
  4. 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?
  5. 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:

  1. 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?
  2. 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?
  3. 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?
  4. 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
  5. 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
  6. 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:

  1. 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?
  2. 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
  3. 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
  4. 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

  1. 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?
  2. 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
  3. 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

  1. Find all usage locations:

    grep -r "<function-name>" --include="*.go" .
    # Or use codebase_search for semantic search
    
  2. Assess each usage:

    • Is this usage vulnerable or safe?
    • What's the correct replacement?
    • Are there edge cases to handle?
  3. Create migration examples:

    • Document "before" and "after" for each pattern
    • Explain why the change is necessary
    • Note any behavior changes
  4. Estimate scope:

    • Number of files affected
    • Complexity of changes (simple replace vs. logic rewrite)
    • Test coverage available
  5. 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:

  1. Obtain the patch:

    • Download from vendor security advisory
    • Verify patch authenticity and source
    • Check patch format (unified diff, git patch, etc.)
  2. 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
  3. Apply the patch:

    • Test in non-production environment first
    • Use appropriate tool (patch, git apply)
    • Handle conflicts if any
    • Document what was patched
  4. 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 replace directive 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:

  1. What type of vulnerability is it?

    • DoS, RCE, injection, authentication bypass, information disclosure, etc.
  2. What triggers the vulnerability?

    • User input, specific API calls, network requests, file operations, etc.
  3. What is the attack vector?

    • Remote/network-based, local, requires authentication, etc.
  4. What resource/capability is affected?

    • CPU, memory, network, data confidentiality, system integrity, etc.
  5. 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:

  1. Layer multiple controls - Don't rely on a single mitigation
  2. Fail securely - If mitigation fails, fail closed not open
  3. Monitor for exploitation - Add logging/alerting for attack attempts
  4. 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:

  1. 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?
  2. 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
  3. 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
  4. 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?
  5. 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:

  1. 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
  2. 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
  3. 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
  4. 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
  5. 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
  6. Timeline and Effort:

    • Estimated time for each phase
    • Resource requirements
    • Critical path items
    • Recommended deadline based on risk
  7. 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:

  1. Confidence Level:

    • HIGH confidence → Automation is safer
    • MEDIUM/LOW confidence → Manual review required
  2. 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
  3. Risk Assessment:

    • Well-tested fix from trusted source → Lower risk
    • Affects critical code paths → Manual verification needed
    • Breaking changes possible → Requires careful review
  4. Project Maturity:

    • Strong test coverage → Automation safer
    • Limited testing → Manual application with thorough testing
    • Active development → Consider coordination
  5. 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, default no) — 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:

  1. Post in full (≤ 32,000 chars) — no changes.
  2. Trim raw tool dumps only (> 32,000 chars) — inside fenced code blocks, replace full govulncheck scrollback, call-graph DOT, or megabyte grep output with a one-line pointer:
    _(Full output truncated — see `${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/<CVE_ID>/govulncheck-source.txt`)_
    
    Keep executive summary, CVE context, evidence interpretations, call-graph results table, risk assessment, and remediation in full. Re-measure.
  3. 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:
    _(Full report exceeded Jira comment limit — summary below. See `${AI_HELPERS_WORKSPACE:-.}/.work/compliance/analyze-cve/<CVE_ID>/report.md`.)_
    
    Do not use a shortened summary unless steps 1–2 are insufficient.

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):

  1. Basic auth (email + API token) — the scheme most Jira Cloud instances actually expect for API tokens. Used when both JIRA_EMAIL and a token are available.
  2. 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 visibility object above targets redhat.atlassian.net. On other Jira Cloud instances, adjust type/value to match an equivalent internal-only group, or omit visibility entirely 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 computed BASIC_AUTH value, 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 visibility parameter — 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=no and Step 3a was attempted and failed → ask the user:
    ⚠️ 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 user says no → display the full comment body in the session for manual posting instead.
  • IF AUTO_APPROVE=yes and 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:

  1. Re-fetch the ticket's current labels (do not trust the Phase 0.5 snapshot alone — labels may have changed while analysis ran):
    fresh = getJiraIssue(issue_key=SOURCE_TICKET)
    current_labels = fresh["fields"]["labels"]   # never start from an empty list
    
    Use jira_context["labels"] only as a fallback if the re-fetch fails.
  2. Append ai-cve-analyzed to current_labels
  3. 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-analyzed stays 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