From 0ad77c6b56c4d65367b89fc85067b1ba2c08d6f8 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:45:41 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 + README.md | 3 + commands/analyze-cve.md | 525 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 ++++ 4 files changed, 584 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/analyze-cve.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..a6271aa --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "compliance", + "description": "Security compliance and vulnerability analysis tools for Go projects", + "version": "0.0.1", + "author": { + "name": "chiragkyal" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..83f5363 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# compliance + +Security compliance and vulnerability analysis tools for Go projects diff --git a/commands/analyze-cve.md b/commands/analyze-cve.md new file mode 100644 index 0000000..8ce051f --- /dev/null +++ b/commands/analyze-cve.md @@ -0,0 +1,525 @@ +--- +description: Analyze Go codebase for CVE vulnerabilities and suggest fixes +argument-hint: +--- + +## Name +compliance:analyze-cve + +## Synopsis +``` +/compliance:analyze-cve +``` + +## 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 ` + - 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: + ```bash + # Check if vulnerable function exists in call graph + callgraph -format=digraph . | digraph nodes | grep "" + + # Find execution path from main to vulnerable function + callgraph -format=digraph . | digraph somepath command-line-arguments.main | digraph to dot + ``` + - Example (for CVE-2024-45338 affecting `golang.org/x/net/html.Parse`): + ```bash + # 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): + ```bash + callgraph -format=digraph . | digraph somepath | digraph to dot | sfdp -Tsvg -o callgraph.svg + ``` + - Prerequisites: Install tools if missing + ```bash + 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 ` + - 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 ` + + - **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 @` + - 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 + +- ``: 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 + ```bash + go install golang.org/x/vuln/cmd/govulncheck@latest + ``` + - `callgraph` & `digraph` - For reachability analysis (highest confidence) + ```bash + 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) + ```bash + # 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 + diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b64c5ba --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:openshift-eng/ai-helpers:plugins/compliance", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "35e8577e5b1cab879aa29b67fb0278afb51a2cc9", + "treeHash": "9a559d5e5f1958c391137bca677b790af37b1d67d3593e92f000137d371d5290", + "generatedAt": "2025-11-28T10:27:31.365865Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "compliance", + "description": "Security compliance and vulnerability analysis tools for Go projects", + "version": "0.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "9c7655e3ba66461c960fb42047a18e4847e8c3bbdb18ab7914a31768e9e0e2d1" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "ad99b960e4c33405a9b154a337725865c77065b136fe70fc6d48e90ffbb50e68" + }, + { + "path": "commands/analyze-cve.md", + "sha256": "42bddb0ec468238a26b1ba91a88db31f679d81f9be616de966782053c897725a" + } + ], + "dirSha256": "9a559d5e5f1958c391137bca677b790af37b1d67d3593e92f000137d371d5290" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file