diff --git a/.claude/skills/README.md b/.claude/skills/README.md new file mode 100644 index 000000000000..9b21f704989e --- /dev/null +++ b/.claude/skills/README.md @@ -0,0 +1,36 @@ +# Claude Skills Directory + +This directory contains Claude Code skills for OpenSearch Dashboards development. + +**Multi-Platform Support**: Skills are available for both Claude Code and Kiro users through corresponding prompt formats. + +## Available Skills + +### `resolve-cve` ([resolve_cve.md](resolve_cve.md)) +Automatically identify and resolve security vulnerabilities (CVEs) in project dependencies. + +- **Documentation**: [resolve_cve_readme.md](resolve_cve_readme.md) +- **Claude Usage**: `/resolve-cve [--cve_id CVE-2024-12345]` +- **Kiro Usage**: Also available as Kiro prompt at [.kiro/prompts/resolve_cve.md](../../.kiro/prompts/resolve_cve.md) +- **Purpose**: Scans GitHub issues for CVEs, verifies presence in codebase, attempts automated fixes + +## Adding New Skills + +When adding new skills to this directory: + +1. **Claude skill file**: `skill-name.md` (the actual skill definition) +2. **Kiro prompt file**: `../../.kiro/prompts/skill-name.md` (Kiro-format prompt that delegates to Claude skill) +3. **Documentation**: `skill_name_readme.md` (comprehensive user guide) +4. **Update this README**: Add entry to "Available Skills" section with both usage formats + +## Skill Development Guidelines + +- Follow the existing skill template format with frontmatter +- Include clear usage examples and error handling +- Document all parameters and expected outputs +- Test thoroughly before committing +- Keep skills focused on specific, well-defined tasks + +--- + +For general Claude Code documentation, see [CLAUDE.md](../../CLAUDE.md) in the project root. \ No newline at end of file diff --git a/.claude/skills/resolve_cve.md b/.claude/skills/resolve_cve.md new file mode 100644 index 000000000000..c695d14cc1ba --- /dev/null +++ b/.claude/skills/resolve_cve.md @@ -0,0 +1,207 @@ +--- +name: resolve-cve +description: Automatically resolve CVEs by checking GitHub issues, verifying presence in codebase, and attempting various remediation strategies while documenting the process. +arguments: + - name: cve_id + description: Specific CVE identifier to resolve (e.g., CVE-2024-12345). If not provided, will search for all open CVE issues. + required: false +--- + +# CVE Resolution Skill + +Automatically resolve CVEs by checking GitHub issues, verifying presence in codebase, and attempting various remediation strategies while documenting the process. + +## Usage + +``` +/resolve-cve [--cve_id CVE-2024-12345] +``` + +If no CVE ID is provided, will search for all open CVE issues. + +## Process + +You are a CVE resolution specialist for OpenSearch Dashboards. Your goal is to automatically identify and resolve security vulnerabilities in the project's dependencies. + +**Important**: +- Always create reports in `tmp/` directory (gitignored) to avoid committing temporary files +- Clean existing tmp files at start of each run to prevent stale data in PR descriptions + +### Step 1: Identify CVEs + +1. **Search GitHub Issues**: Look for open CVE issues in https://github.com/opensearch-project/OpenSearch-Dashboards/issues + + - Use GitHub API or web search to find issues with "CVE" in title + - Filter for open issues only + - Extract CVE numbers and affected package information + +2. **Parse CVE Details**: For each CVE found, extract: + - CVE identifier (e.g., CVE-2024-12345) + - Affected package name and vulnerable version range + - Recommended safe version + - Severity level + +### Step 2: Verify Presence in Codebase + +1. **Check package.json**: Search for the vulnerable package in package.json files +2. **Check yarn.lock**: Verify if vulnerable versions are actually installed +3. **Analyze dependency tree**: Use `yarn why ` to understand why the package is included + +### Step 3: Remediation Strategies + +Try the following strategies in order until successful: + +#### Strategy A: Direct Package Update (if in package.json) + +1. If vulnerable package is explicitly declared in package.json: + - Update version to safe version with caret (^) + - Run `yarn osd bootstrap` to update lock file and verify build + +#### Strategy B: Lock File Manipulation (if transitive dependency) + +1. If package is NOT in package.json (transitive dependency): + - Delete vulnerable package entries from yarn.lock + - Run `yarn osd bootstrap` to regenerate with latest versions + - Check if vulnerability is resolved + +#### Strategy C: Peer Dependency Resolution + +1. If Strategy B fails due to peer dependency constraints: + - Identify which dependency requires the vulnerable version + - Delete that dependency's yarn.lock entries too + - Run `yarn osd bootstrap` again + - May need to update parent dependency version + +#### Strategy D: Resolutions (last resort) + +1. If other strategies fail: + - Add yarn resolutions to package.json to force safe version + - Use the least invasive resolution path possible + - Example: If package "a" has a CVE and the vulnerable version comes from dependency "b", use a targeted resolution like `"**/b/a": "^3.5.3"` instead of a global `"a": "^3.5.3"` + - Document why the resolution was needed and which dependency path required it + +### Step 4: Verification + +After each remediation attempt: + +1. Run `yarn osd bootstrap` to ensure build succeeds +2. Run `yarn audit` to check if vulnerability is resolved +3. Run basic smoke tests if available +4. Verify no new vulnerabilities were introduced + +### Step 5: Documentation + +Create a PR-ready description in `tmp/cve-pr-description.md` by **dynamically using the current GitHub PR template**: + +1. **Read the current PR template**: Load `.github/pull_request_template.md` to get the latest format +2. **Parse template structure**: Identify sections like Description, Issues Resolved, Testing, Changelog, etc. +3. **Fill in CVE-specific content**: Replace template placeholders with actual CVE resolution details +4. **Auto-extract GitHub Issue Numbers**: Parse CVE issue URLs and add `closes #[number]` entries + +**Content Mapping Strategy**: + +- **Description section**: Fill with CVE summary, affected packages, resolution strategy +- **Issues Resolved section**: Auto-populate with `closes #[issue-number]` from found CVE issues +- **Testing section**: Add CVE-specific verification commands +- **Changelog section**: Generate appropriate changelog entry for security fixes +- **Checklist section**: Mark relevant items as completed based on resolution results + +**Dynamic Template Approach**: + +```bash +# Always use current template as base +cp .github/pull_request_template.md tmp/cve-pr-description.md + +# Then programmatically fill in sections with CVE data: +# - Replace "" with CVE details +# - Replace "" with closes #123 +# - Fill testing section with CVE verification steps +# - Add appropriate changelog entry +``` + +This ensures the skill **always respects the current PR template format**, even if it changes in the future - no manual skill updates required! + +### Step 6: Setup and Failure Documentation + +**Setup tmp/ directory and generate PR description**: + +```bash +mkdir -p tmp +echo "tmp/" >> .gitignore # if not already present + +# IMPORTANT: Clean any existing tmp files to avoid stale data +rm -f tmp/cve-pr-description.md tmp/cve-failure-report.md + +# Use current GitHub PR template as base (future-proof!) +cp .github/pull_request_template.md tmp/cve-pr-description.md +``` + +**Why we clean tmp files first**: +- **Prevents stale data**: Ensures fresh reports with current CVE status +- **Accurate issue refs**: Avoids outdated "closes #123" references +- **No confusion**: Eliminates mixing data from multiple CVE runs +- **Current state**: Always reflects the actual dependency versions being fixed + +**Template Content Replacement Guide**: + +1. **Description section**: Replace `` with: + + ``` + Resolves security vulnerabilities in project dependencies: + - **CVE-[ID]** ([Severity]): [Brief description] + - **Package**: [affected-package@version] → [safe-version] + - **Resolution Strategy**: [Strategy used] + ``` + +2. **Issues Resolved section**: Replace `` with: + + ``` + - closes #[issue-number] (auto-extracted from GitHub CVE issues) + ``` + +3. **Testing section**: Replace `` with CVE-specific validation steps + +4. **Changelog section**: Add appropriate security fix entry following existing format + +This approach ensures the skill **automatically adapts** to any future PR template changes without requiring skill updates. + +If CVE cannot be automatically resolved, document in `tmp/cve-failure-report.md`: + +- Which strategies were attempted +- Specific error messages encountered +- Dependency conflicts preventing resolution +- Recommended manual intervention steps +- Upstream dependency update requirements +- GitHub issue numbers for tracking + +## Error Handling + +- Always backup original package.json and yarn.lock before making changes +- If any step fails, restore backups and document the failure +- Never leave the project in a broken state +- Provide clear next steps for manual resolution + +## Constraints + +- Only modify dependency versions, never remove required dependencies +- Maintain compatibility with Node.js version requirements +- Preserve existing functionality +- Follow semver best practices for version updates +- Document all changes for PR review + +## Success Criteria + +A CVE is considered resolved when: + +1. Vulnerable package version is no longer present +2. Project builds successfully (`yarn osd bootstrap` passes) +3. All tests pass (`yarn test:jest` passes) +4. No new vulnerabilities introduced (`yarn audit` clean for resolved CVE) +5. PR-ready documentation created in `tmp/cve-pr-description.md` +6. GitHub issue numbers auto-extracted and added as `closes #123` references + +## Output Files + +- `tmp/cve-pr-description.md` - PR description ready to copy/paste, **dynamically generated from current `.github/pull_request_template.md`** +- `tmp/cve-failure-report.md` - Failure analysis (if resolution fails), using same template approach +- Both files automatically adapt to future PR template changes - no skill maintenance required! diff --git a/.claude/skills/resolve_cve_readme.md b/.claude/skills/resolve_cve_readme.md new file mode 100644 index 000000000000..08da1d00581f --- /dev/null +++ b/.claude/skills/resolve_cve_readme.md @@ -0,0 +1,230 @@ +# resolve-cve Skill Documentation + +Comprehensive guide for the **`resolve-cve`** skill (`resolve_cve.md`). + +Automated tool for identifying and resolving security vulnerabilities (CVEs) in OpenSearch Dashboards dependencies. + +## 🔧 What it does + +The CVE resolution skill automatically: +- 🔍 **Finds open CVE issues** from GitHub +- 🔎 **Verifies which affect your code** by analyzing package.json and yarn.lock +- 🛠️ **Attempts multiple fix strategies** (direct updates, lock manipulation, resolutions) +- ✅ **Validates the fixes work** by running builds and audits +- 📋 **Documents everything** in a comprehensive report for your PR + +## 🚀 Usage + +### Basic Commands + +```bash +# Scan and fix ALL open CVEs +/resolve-cve + +# Target a specific CVE +/resolve-cve --cve_id CVE-2025-54798 + +# Get help on available options +/resolve-cve --help +``` + +### Example Workflow + +1. **Run the skill:** + ```bash + /resolve-cve --cve_id CVE-2025-54798 + ``` + +2. **Review the generated `tmp/cve-pr-description.md`** for PR-ready content + +3. **Test your changes:** + ```bash + yarn osd bootstrap + yarn test:jest # optional + ``` + +4. **Copy `tmp/cve-pr-description.md` content to your PR** - it's formatted and ready! + +## 📂 Output Files + +After running the skill, look in the `tmp/` directory for: + +- **`tmp/cve-pr-description.md`** 📋 - **Main output**: Copy this content into your PR description +- **`tmp/cve-failure-report.md`** ⚠️ - **If resolution fails**: Manual steps and error analysis + +> **💡 Tip**: The PR description follows GitHub's template format and includes auto-generated "closes #123" references! + +## 📋 Prerequisites + +Make sure you have: +- ✅ **Clean working directory** (commit any pending changes) +- ✅ **Yarn installed** (the skill uses `yarn osd bootstrap`) +- ✅ **GitHub access** (for searching CVE issues) +- ✅ **Node.js 20+** (required by OpenSearch Dashboards) + +## 📂 File Management + +**Important**: The skill automatically cleans `tmp/` files at the start of each run to prevent stale data: + +```bash +# These files are removed before generating new reports +rm -f tmp/cve-pr-description.md tmp/cve-failure-report.md +``` + +**Why this matters**: +- 🚫 **Prevents outdated PR content** - No risk of copying old CVE info +- ✅ **Ensures current data** - Reports always reflect actual dependency state +- 🎯 **Accurate issue references** - Correct "closes #123" GitHub issue numbers +- 🔄 **Clean slate each run** - No confusion from previous CVE resolution attempts + +If you need to preserve previous reports, copy them elsewhere before running the skill again. + +## 🔍 How it works + +### Step 1: CVE Discovery +- Searches https://github.com/opensearch-project/OpenSearch-Dashboards/issues +- Filters for open issues containing "CVE" +- Extracts vulnerability details (package, versions, severity) + +### Step 2: Impact Analysis +- Checks if vulnerable packages exist in your `package.json` +- Analyzes `yarn.lock` for vulnerable transitive dependencies +- Uses `yarn why ` to understand dependency chains + +### Step 3: Smart Remediation +The skill tries multiple strategies in order: + +**Strategy A: Direct Updates** +- For packages explicitly in `package.json` +- Updates to safe versions with caret ranges + +**Strategy B: Lock File Manipulation** +- For transitive dependencies +- Removes vulnerable entries, lets yarn regenerate with latest + +**Strategy C: Parent Dependency Updates** +- When Strategy B fails due to constraints +- Updates parent dependencies that pull in vulnerable packages + +**Strategy D: Yarn Resolutions** ⭐ +- Last resort for stubborn vulnerabilities +- Forces specific safe versions using targeted resolutions +- Example: `"**/selenium-webdriver/tmp": "^0.2.4"` + +### Step 4: Validation +- ✅ Runs `yarn osd bootstrap` to ensure build works +- ✅ Checks `yarn audit` to confirm CVE is resolved +- ✅ Verifies no new vulnerabilities introduced +- ✅ Creates backup files for easy rollback + +## 📄 Generated Documentation + +The skill creates comprehensive documentation in the `tmp/` directory: + +**Primary Output: `tmp/cve-pr-description.md`** - Ready-to-copy PR description following GitHub template format + +**Content includes:** + +```markdown +### Description + +Resolves security vulnerability in project dependencies: +- **CVE-2025-54798** (Low): Vulnerability in tmp package +- **Package**: tmp@0.0.30 → tmp@0.2.5 + +### Issues Resolved +- closes #10376 + +## Testing the changes +[CVE-specific verification commands] + +## Changelog +- fix: Resolve CVE-2025-54798 in tmp dependency +``` + +**Failure Reports: `tmp/cve-failure-report.md`** - Detailed analysis if resolution fails + +## 🛡️ Safety Features + +- **🔙 Automatic backups**: Creates `*.bak` files before any changes +- **🚫 Never breaks builds**: Validates changes before proceeding +- **📝 Complete audit trail**: Documents every action taken +- **🔄 Easy rollback**: Restore from backups if needed +- **🎯 Targeted fixes**: Uses least invasive resolution strategies + +## 🐛 Troubleshooting + +### "Unknown skill: resolve-cve" +The skill needs to be in your global skills directory: +```bash +# Check if skill exists +ls ~/.claude/skills/resolve-cve/ + +# If not, skills may be project-local only +ls .claude/skills/resolve-cve.md +``` + +### "Build fails after CVE fix" +1. **Restore backups:** + ```bash + mv package.json.bak package.json + mv yarn.lock.bak yarn.lock + yarn osd bootstrap + ``` + +2. **Check `tmp/cve-failure-report.md`** for manual steps required + +3. **Try a different strategy** - some CVEs need manual intervention + +### "CVE still shows in audit" +- Check if multiple packages have the same vulnerability +- Some audit tools cache results - try `yarn audit --force` +- Verify you're checking the right CVE ID + +### "Skill doesn't find CVE issues" +- Ensure you have internet access for GitHub API calls +- Check if the CVE issue still exists and is open +- Try searching GitHub manually: "repo:opensearch-project/OpenSearch-Dashboards CVE" + +## 💡 Pro Tips + +1. **Run regularly**: Use `/resolve-cve` weekly to catch new vulnerabilities early + +2. **Test thoroughly**: Always run the full test suite after CVE fixes: + ```bash + yarn test:jest + yarn test:jest_integration + ``` + +3. **Review yarn resolutions**: If Strategy D was used, periodically check if resolutions can be removed after dependency updates + +4. **Batch related CVEs**: If multiple CVEs affect the same package, fix them together + +5. **Keep backups**: The `*.bak` files are your safety net - don't delete them until your PR is merged + +## 🔗 Related Commands + +```bash +# Check current vulnerabilities +yarn audit --level moderate + +# Find why a package is installed +yarn why + +# Update all dependencies (careful!) +yarn upgrade-interactive --latest + +# Clean build after fixes +yarn osd clean && yarn osd bootstrap +``` + +## 📞 Getting Help + +- **Skill issues**: Check the skill file at `.claude/skills/resolve-cve.md` +- **CVE questions**: Review files in `tmp/` directory (cve-pr-description.md, cve-failure-report.md) +- **Build problems**: See OpenSearch Dashboards troubleshooting in `CLAUDE.md` +- **Security concerns**: Consult with security team before merging CVE fixes + +--- + +**Happy CVE hunting! 🛡️** \ No newline at end of file diff --git a/.gitignore b/.gitignore index 8cf39608517c..473d4c70174d 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,13 @@ /.opensearch /.chromium /package.json.bak +*.bak .claude/ +!.claude/skills/ + +# Temporary files and directories +tmp/ +.claude/settings.local.json CLAUDE.local.md .DS_Store .node_binaries @@ -50,7 +56,8 @@ selenium package-lock.json .yo-rc.json .vscode -.kiro +.kiro/ +!.kiro/prompts/ *.sublime-* npm-debug.log* .tern-project diff --git a/.kiro/prompts/resolve_cve.md b/.kiro/prompts/resolve_cve.md new file mode 100644 index 000000000000..5dba00c924ea --- /dev/null +++ b/.kiro/prompts/resolve_cve.md @@ -0,0 +1,64 @@ +--- +name: resolve-cve +description: Automatically resolve CVEs by checking GitHub issues, verifying presence in codebase, and attempting various remediation strategies while documenting the process. +parameters: + - name: cve_id + description: Specific CVE identifier to resolve (e.g., CVE-2024-12345). If not provided, will search for all open CVE issues. + required: false + type: string +--- + +# CVE Resolution (Kiro) + +You are a CVE resolution specialist for OpenSearch Dashboards. Your task is to automatically identify and resolve security vulnerabilities in the project's dependencies. + +## Instructions + +**IMPORTANT**: Read and follow the comprehensive CVE resolution process defined in `.claude/skills/resolve_cve.md`. That file contains the complete, detailed instructions for: + +1. **CVE Discovery**: How to search GitHub issues and parse CVE details +2. **Impact Analysis**: Verifying presence in codebase via package.json and yarn.lock +3. **Remediation Strategies**: Four different approaches (A-D) to try in order +4. **Verification**: Build validation and audit confirmation +5. **Documentation**: Creating PR-ready descriptions in `tmp/` directory + +## Key Requirements + +- **Follow the exact process** outlined in `.claude/skills/resolve_cve.md` +- **Use the `tmp/` directory** for all generated reports to avoid git conflicts +- **Clean existing tmp files** at start of each run to prevent stale data +- **Generate PR descriptions** using the dynamic GitHub template approach +- **Auto-extract issue numbers** and add appropriate "closes #123" references + +## Parameters + +- `cve_id` (optional): Specific CVE to target (e.g., CVE-2024-12345) +- If no CVE ID provided, process all open CVE issues + +## Output + +Generate these files in `tmp/` directory: +- `tmp/cve-pr-description.md` - Ready-to-copy PR description +- `tmp/cve-failure-report.md` - Analysis if resolution fails + +## Process Overview + +Refer to `.claude/skills/resolve_cve.md` for the complete step-by-step process, including: + +- **Strategy A**: Direct package updates (if in package.json) +- **Strategy B**: Lock file manipulation (transitive dependencies) +- **Strategy C**: Parent dependency updates (when constraints prevent B) +- **Strategy D**: Yarn resolutions (last resort, most reliable) + +## Success Criteria + +A CVE is resolved when: +1. Vulnerable package version no longer present +2. Project builds successfully (`yarn osd bootstrap`) +3. Tests pass (`yarn test:jest`) +4. Audit clean for the target CVE +5. PR-ready documentation generated in `tmp/` + +--- + +**Execute the CVE resolution process exactly as specified in `.claude/skills/resolve_cve.md`** \ No newline at end of file diff --git a/changelogs/fragments/11650.yml b/changelogs/fragments/11650.yml new file mode 100644 index 000000000000..f1ba9e4d9f46 --- /dev/null +++ b/changelogs/fragments/11650.yml @@ -0,0 +1,2 @@ +feat: +- Add automated CVE resolution skill with multi-platform support ([#11650](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/11650)) \ No newline at end of file