gh-openshift-eng-ai-helpers-plugins-compliance/commands/analyze-cve.md

description, argument-hint

description	argument-hint
Analyze Go codebase for CVE vulnerabilities and suggest fixes	<CVE-ID>

Name

compliance:analyze-cve

Synopsis

/compliance:analyze-cve <CVE-ID>

Description

The compliance:analyze-cve command performs comprehensive security vulnerability analysis for Go projects. Given a CVE identifier, it fetches complete vulnerability details from authoritative sources, analyzes the codebase for potential impact, and provides actionable remediation guidance.

This command helps developers:

• Understand the full scope of a CVE vulnerability
• Determine if their Go codebase is affected
• Get specific fix recommendations
• Optionally apply fixes automatically

Implementation

Phase 1: CVE Intelligence Gathering

1. Validate CVE Format

   • Verify CVE ID follows standard format (e.g., CVE-2024-1234)
   • Extract year and number components

2. Fetch CVE Details from Multiple Sources

   Use web_search tool to gather information from these sources:

   • Primary Sources:

     • NVD: Search for "CVE-{ID} site:nvd.nist.gov"

       • URL pattern: https://nvd.nist.gov/vuln/detail/{CVE-ID}
       • Extract: CVSS score, severity, affected versions, vulnerability type

     • MITRE: Search for "CVE-{ID} site:cve.mitre.org"

       • URL pattern: https://cve.mitre.org/cgi-bin/cvename.cgi?name={CVE-ID}
       • Extract: Description, references, CWE classification

   • Go-Specific Sources:

     • Go Vulnerability Database: Search for "CVE-{ID} golang vulnerability"

       • Check: https://go.dev/security/vuln/
       • Search GitHub: "CVE-{ID} site:github.com/golang/vulndb"
       • Extract: Affected Go packages, versions, fix versions

     • GitHub Security Advisories: Search for "CVE-{ID} golang GHSA"

       • May have GHSA-* aliases
       • Often contains detailed remediation steps

   • General Go Security:

     • Search: "CVE-{ID} golang fix" or "CVE-{ID} go security"
     • Look for blog posts, security advisories, and discussions

3. Handle Search Issues and Limited Results

   • If CVE details cannot be fetched (network error, search failure, insufficient results):

     • Inform user about the lookup issue
     • Try alternative search strategies:
       • Search for package name + "vulnerability" + year
       • Search for GHSA (GitHub Security Advisory) aliases
       • Check if govulncheck finds it (most reliable for Go CVEs)
     • If still unsuccessful, ask user to provide available information:
       • CVE description and severity
       • Affected Go packages/modules
       • Vulnerable version ranges
       • Fixed versions (if known)
       • Any relevant links or references
     • Document the source as "User-provided information"
     • Note limitations in final report

   • If CVE is very new (e.g., CVE-2025-xxxxx):

     • May not be in NVD or Go vulndb yet
     • Search for: "CVE-{ID} disclosure" or "CVE-{ID} advisory"
     • Check vendor security pages directly
     • Run govulncheck anyway - it may know about it via GHSA

   • If suggested fixes cannot be found:

     • Check the package's GitHub releases for recent security fixes
     • Look for security-related commits in the repository
     • Ask user if they have:
       • Official security advisories
       • Patch information
       • Workaround documentation
       • Any relevant fix details
     • Proceed with available information
     • Clearly mark sections as "Based on user input" vs "Verified online"

4. Gather Remediation Intelligence

   • Search for:
     • Official security advisories
     • GitHub Security Advisories (GHSA)
     • Vendor patches and updates
     • Community discussions on GitHub, Go forums
   • Follow hyperlinks to:
     • Pull requests with fixes
     • Security mailing list threads
     • Blog posts with analysis
     • Proof-of-concept exploits (for context)
   • If searches fail or return insufficient results:
     • Request user input for any known fixes or workarounds
     • Accept partial information and document gaps

5. Compile Vulnerability Profile

   • Create structured summary with:
     • CVE ID and aliases (GHSA-*, etc.)
     • Severity and CVSS metrics
     • Affected packages/modules
     • Vulnerable version ranges
     • Fixed versions
     • Attack vectors and prerequisites
     • Impact assessment (confidentiality, integrity, availability)
     • Recommended mitigations
   • Clearly distinguish:
     • Information from authoritative sources (NVD, MITRE, etc.)
     • Information from web searches
     • Information provided by user
     • Information gaps or uncertainties

Phase 2: Codebase Impact Analysis

1. Identify Go Module Dependencies

   • Read go.mod file from workspace root
   • Parse direct and indirect dependencies
   • Extract module versions using go list -m all
   • Build dependency tree if needed

2. Cross-Reference Vulnerable Packages

   • 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

   • Method 2: Go Vulnerability Scanner

     • Run govulncheck if available in the environment
     • Command: govulncheck ./...
     • Parse output for CVE matches
     • Alternative: Use go list -json -m all and cross-reference

   • Method 3: Direct Dependency Check

     • Use go list to verify package presence
     • Command: go list -mod=mod <vulnerable-package>
     • Example: go list -mod=mod golang.org/x/net/html
     • Confirms package is included (directly or transitively)
     • Note: This alone doesn't prove vulnerable functions are called

   • Method 4: Call Graph Reachability Analysis (Highest Confidence)

     • Build complete program call graph using callgraph tool
     • Search for vulnerable function signatures in the graph
     • Commands:

       # Check if vulnerable function exists in call graph
       callgraph -format=digraph . | digraph nodes | grep "<vulnerable-function-signature>"
       
       # Find execution path from main to vulnerable function
       callgraph -format=digraph . | digraph somepath command-line-arguments.main <vulnerable-function> | digraph to dot
       

     • Example (for CVE-2024-45338 affecting golang.org/x/net/html.Parse):

       # Step 1: Check if Parse is called anywhere
       callgraph -format=digraph . | digraph nodes | grep "golang.org/x/net/html.Parse$"
       
       # Step 2: Find path from main() to Parse()
       callgraph -format=digraph . | digraph somepath command-line-arguments.main golang.org/x/net/html.Parse
       

     • Interpretation:
       • If path exists: Code is DEFINITELY vulnerable (reachable code path)
       • If no path: Function may be dead code or only called conditionally
       • Generates DOT graph showing exact call chain
     • Visualization (optional):

       callgraph -format=digraph . | digraph somepath <entrypoint> <vulnerable-func> | digraph to dot | sfdp -Tsvg -o callgraph.svg
       

     • Prerequisites: Install tools if missing

       go install golang.org/x/tools/cmd/callgraph@latest
       go install golang.org/x/tools/cmd/digraph@latest
       

   • Method 5: Source Code Analysis

     • Search for import statements of vulnerable packages
     • Use grep/codebase_search to find package usage
     • Identify actual code paths that use vulnerable functions
     • Check if vulnerable functions are called in reachable code

3. Verify Impact with Multiple Methods & Confidence Levels

   Use multiple verification layers, with each providing increasing confidence:

   • Level 1: Basic Presence (Low Confidence)

     • Check go.mod for vulnerable package
     • Run: go list -mod=mod <vulnerable-package>
     • Result: Confirms package is a dependency (direct or transitive)
     • ⚠️ Limitation: Doesn't prove the vulnerable code is actually used

   • Level 2: Import & Version Analysis (Medium Confidence)

     • Verify package is imported in source code (grep/codebase_search)
     • Check version is in vulnerable range
     • Search for vulnerable function/method names in codebase
     • ⚠️ Limitation: Function may exist but not be in reachable code paths

   • Level 3: Vulnerability Scanner (Medium-High Confidence)

     • Run govulncheck ./... (official Go vulnerability checker)
     • Performs reachability analysis automatically
     • Reports if vulnerable functions are actually called
     • ✓ Advantage: Maintained by Go team, knows about CVEs

   • Level 4: Call Graph Reachability (Highest Confidence)

     • Use callgraph + digraph to prove execution path exists
     • Trace from main() (or test entry points) to vulnerable function
     • Generate visual call graph showing exact path
     • ✓ Advantage: Provides definitive proof with traceable evidence
     • Example output shows complete call chain:

       main → MyHandler → ParseHTML → html.Parse (VULNERABLE)
       

   • Level 5: Configuration & 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)

   Recommended Approach: Use multiple methods and assign confidence:

   • High Confidence (DEFINITELY AFFECTED):
     • Call graph shows reachable path AND version is vulnerable
     • OR govulncheck explicitly reports the CVE
   • Medium Confidence (LIKELY AFFECTED):
     • Package present + vulnerable version + function calls found
     • But no call graph or reachability proof
   • Low Confidence (POSSIBLY AFFECTED):
     • Vulnerable package present but no direct usage evidence
   • Not Affected:
     • Package not present OR version not vulnerable OR dead code

4. Build Evidence Package

   Collect comprehensive evidence for the report:

   • Dependency Evidence:

     • go.mod entries showing vulnerable package
     • go list output confirming presence
     • Version information from go list -m <package>

   • Static Code Evidence:

     • File paths where vulnerable packages are imported
     • Line numbers where vulnerable functions are called
     • Code snippets showing usage context

   • Reachability Evidence (if call graph analysis performed):

     • Call graph output showing vulnerable function in nodes
     • Execution path from entry points to vulnerable code
     • DOT graph visualization (saved to .work/compliance/analyze-cve/{CVE-ID}/callgraph.svg)
     • Complete call chain as text (e.g., "main → handler → parse → VULN")

   • Scanner Evidence:

     • govulncheck output (full text)
     • Vulnerability findings with line numbers

   • Mitigation Factors:

     • Input validation or sanitization in place
     • Vulnerable features disabled by configuration
     • Code behind feature flags or conditional execution
     • Security controls limiting exposure

   • Confidence Assessment:

     • List which verification methods were used
     • Assign overall confidence level based on evidence
     • Note any gaps in analysis or areas needing manual review

Phase 3: Report Generation

1. Create Analysis Report

   • Location: .work/compliance/analyze-cve/{CVE-ID}/report.md

   • Additional artifacts:

     • callgraph.svg (if generated)
     • govulncheck-output.txt (if run)
     • evidence.json (structured evidence data)

   • Include sections:

     • Executive Summary:

       • Impact verdict (AFFECTED/NOT AFFECTED/UNKNOWN)
       • Confidence level badge (HIGH/MEDIUM/LOW)
       • Quick summary of findings

     • CVE Details:

       • Full vulnerability information
       • Tag information sources (e.g., "Source: NVD", "Source: User-provided")
       • Affected package/function signatures
       • Vulnerability type and attack vector

     • Analysis Methodology:

       • List all verification methods used
       • Note which tools were available (callgraph, govulncheck, etc.)
       • Explain confidence level determination
       • Example:

         ✓ Method 1: Dependency check (go list) - POSITIVE
         ✓ Method 2: Version analysis - VULNERABLE VERSION FOUND
         ✓ Method 3: govulncheck scan - CVE REPORTED
         ✓ Method 4: Call graph analysis - REACHABLE PATH FOUND
         → Confidence: HIGH
         

     • Dependency Analysis:

       • Package versions from go.mod
       • Direct vs. transitive dependencies
       • Vulnerable package version range

     • Impact Assessment:

       • Specific findings in codebase
       • File paths and line numbers
       • Code snippets showing vulnerable usage
       • Reachability Analysis (if performed):
         • Call chain from entry points to vulnerable functions
         • Visual call graph (link to SVG)
         • Interpretation of findings

     • Risk Level:

       • Based on exploitability, exposure, and reachability
       • Consider CVSS score + actual codebase context

     • Evidence:

       • All collected evidence organized by type
       • Terminal output from tools
       • Screenshots or links to visualizations

     • Confidence Assessment:

       • Final confidence: High/Medium/Low
       • Justification based on methods used
       • Gaps or limitations noted
       • Recommendations for additional verification if needed

     • Remediation Steps:

       • Specific fixes needed (version updates, code changes)
       • Verification commands (prefer make targets, fallback to go commands)
       • Note which make targets are available in the project
       • Priority based on confidence level and risk

     • References:

       • All sources consulted (automated + user-provided)
       • Tool versions used
       • Timestamp of analysis

2. Format Report

   • Use clear markdown formatting
   • Include severity badges
   • Add code blocks for examples
   • Link to external references
   • Provide actionable recommendations
   • Clearly mark user-provided information with labels like:
     • "⚠️ Based on user-provided information"
     • "✓ Verified from authoritative sources"
     • "⚠️ Partial information - manual verification recommended"

Phase 4: Remediation Guidance

1. If Codebase is NOT Affected

   • Explain why (version not vulnerable, package not used, etc.)
   • Suggest preventive measures
   • Recommend ongoing monitoring

2. If Codebase IS Affected

   • Provide specific remediation steps:

     1. Update Dependencies

        • Exact go get commands to upgrade packages
        • Target version that fixes the CVE
        • Consider semantic versioning compatibility
        • Note: Use go mod tidy after updates

     2. Code Changes (if needed)

        • Identify functions that need modification
        • Provide before/after code examples
        • Explain breaking changes if any

     3. Workarounds (if no fix available)

        • Suggest temporary mitigations
        • Configuration changes to reduce risk
        • Input validation or sanitization

     4. Verification Commands

        • Check for project's Makefile first
        • Prefer project-specific make targets: make verify, make build, make test
        • Fall back to standard Go commands if no Makefile
        • Command to check for make targets: make -qp | grep "^[a-zA-Z]" | head -20

     5. Testing Recommendations

        • Suggest tests to verify the fix
        • Security test cases to add
        • Regression testing guidance
        • Re-run govulncheck to confirm vulnerability is resolved

Phase 5: Interactive Fix Application

1. Present Remediation Plan

   • Show complete analysis report
   • Highlight critical findings
   • List all proposed fixes

2. Ask User for Permission

   • "Would you like me to apply these fixes automatically?"
   • Wait for explicit user confirmation
   • Do NOT proceed without approval

3. If User Approves, Apply Fixes

   • Update go.mod and go.sum

     • Run go get -u <package>@<fixed-version>
     • Run go mod tidy to clean up

   • Modify Source Code (if required)

     • Apply code changes identified in Phase 4
     • Use search_replace or write tools
     • Maintain code style and formatting

   • Verify Changes

     • Check if project has Makefile with common targets
     • For verification:
       • Try make verify first (if target exists)
       • Fallback: go mod verify
     • For building:
       • Try make build first (if target exists)
       • Fallback: go build ./...
     • For testing:
       • Try make test first (if target exists)
       • Fallback: go test ./...
     • Re-check vulnerability:
       • Run govulncheck ./... to confirm fix

4. Document Changes

   • Create summary of changes made
   • List files modified
   • Provide git diff summary
   • Suggest commit message

Return Value

• Format: Markdown report at .work/compliance/analyze-cve/{CVE-ID}/report.md
• Content:
  • Vulnerability details and severity
  • Impact assessment (AFFECTED/NOT AFFECTED/UNCLEAR)
  • Evidence from codebase analysis
  • Specific remediation recommendations
  • Applied fixes (if user approved)

Examples

1. CVE analysis:

   /compliance:analyze-cve CVE-2024-45338
   

   Analyzes the codebase for CVE-2024-45338

Arguments

• <CVE-ID>: The CVE identifier to analyze (e.g., CVE-2024-1234, CVE-2023-45678)
  • Format: CVE-YYYY-NNNNN
  • Case insensitive
  • Required argument

Notes

• The command focuses on Go-specific vulnerabilities
• Flexible Information Sources:
  • Prefers automatic CVE lookup from authoritative sources (NVD, MITRE, Go vulndb)
  • Falls back to user-provided information if internet access fails or CVE data is unavailable
  • Clearly distinguishes between verified and user-provided information in reports
• Analysis may take several minutes for complex codebases
• If govulncheck is not installed, the command will use alternative methods
• The command does NOT make changes without explicit user approval
• Generated reports are saved locally and not committed to git
• When providing manual CVE information, include as much detail as possible:
  • Affected Go package/module names
  • Vulnerable and fixed version numbers
  • Severity and CVSS score (if known)
  • Links to security advisories or patches

Prerequisites

• Required:

  • Go toolchain installed (go version should work)
  • Read access to go.mod and source files in the workspace

• Recommended (for comprehensive analysis):

  • Internet connectivity for automatic CVE data fetching
  • govulncheck - Go's official vulnerability checker

    go install golang.org/x/vuln/cmd/govulncheck@latest
    

  • callgraph & digraph - For reachability analysis (highest confidence)

    go install golang.org/x/tools/cmd/callgraph@latest
    go install golang.org/x/tools/cmd/digraph@latest
    

  • sfdp or graphviz - For call graph visualization (optional)

    # macOS
    brew install graphviz
    # Linux
    sudo apt-get install graphviz
    

• Alternative: If internet access is unavailable, be prepared to provide:

  • CVE description and details
  • Affected package information
  • Specific vulnerable function signatures
  • Remediation guidance from other sources

Tool Availability Check: The command will automatically detect which tools are available and use the most comprehensive methods possible. Missing tools will result in lower confidence levels but analysis will still proceed.

Exit Conditions

• Success: Report generated with clear impact assessment based on complete information
• Success with User Input: Report generated based on user-provided CVE details when internet access fails
• Partial Success: Report generated but impact is unclear (needs manual review)
  • Marked with confidence level: "Low" or "Medium"
  • Includes recommendations for further investigation
• Failure Scenarios:
  • Invalid CVE format (must be CVE-YYYY-NNNNN)
  • User declines to provide information when automatic lookup fails
  • No Go-related information available (CVE is for different technology)
  • Insufficient information to proceed with analysis