@openhands/extensions 0.1.0 → 0.2.0

package/plugins/vulnerability-remediation/README.md

@@ -0,0 +1,217 @@
+# Vulnerability Remediation Plugin
+
+Automated security vulnerability scanning and AI-powered remediation using OpenHands agents. This plugin scans repositories for vulnerabilities, skips the agent when no issues are found, and automatically creates PRs with fixes.
+
+## Quick Start (2 Steps)
+
+### 1. Add the Workflow
+
+```bash
+mkdir -p .github/workflows
+curl -o .github/workflows/vulnerability-scan.yml \
+  https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/vulnerability-remediation/workflows/vulnerability-scan.yml
+```
+
+### 2. Add Your Secret
+
+Go to **Settings → Secrets → Actions** and add:
+
+| Secret | Description |
+|--------|-------------|
+| `LLM_API_KEY` | API key for your LLM provider (Anthropic, OpenAI, etc.) |
+
+That's it! The workflow will:
+- Run weekly scans (configurable)
+- **Skip the AI agent if no vulnerabilities are found** (saves costs)
+- Auto-update when the plugin is improved
+
+## Features
+
+- **Smart Scanning** — Only starts the AI agent when vulnerabilities are found
+- **Auto-Updates** — Uses `@main` so you always get the latest improvements
+- **Scheduled Scanning** — Weekly by default, configurable via cron
+- **Severity Filtering** — Only fix CRITICAL/HIGH by default
+- **Trivy Integration** — Comprehensive vulnerability detection
+- **AI-Powered Fixes** — OpenHands agents analyze and fix vulnerabilities
+- **Automatic PRs** — Creates PRs with detailed CVE references
+
+## Plugin Contents
+
+```
+plugins/vulnerability-remediation/
+├── README.md                    # This file
+├── action.yml                   # Composite GitHub Action
+├── scripts/                     # Python scripts for scan and remediation
+│   └── scan_and_remediate.py   # Main remediation agent script
+├── workflows/                   # Example GitHub workflow files
+│   └── vulnerability-scan.yml  # Thin wrapper workflow (copy this)
+└── skills/                      # Symbolic links to related skills
+    ├── security -> ../../../skills/security
+    └── github -> ../../../skills/github
+```
+
+## How It Works
+
+The action runs in two phases:
+
+1. **Scan Phase** — Runs Trivy to detect vulnerabilities (fast, no AI costs)
+2. **Remediation Phase** — Only runs if vulnerabilities are found
+
+This means:
+- ✅ No AI costs when your repo is clean
+- ✅ Fast feedback on scan results
+- ✅ AI only runs when needed
+
+## Configuration
+
+### Optional: Customize Settings
+
+Edit your workflow to adjust defaults:
+
+```yaml
+- name: Run Vulnerability Remediation
+  uses: OpenHands/extensions/plugins/vulnerability-remediation@main
+  with:
+    severity-threshold: HIGH      # CRITICAL, HIGH, MEDIUM, or LOW
+    max-vulnerabilities: '5'      # Limit PRs per run (0 = unlimited)
+    llm-api-key: ${{ secrets.LLM_API_KEY }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Optional: Change Schedule
+
+```yaml
+on:
+  schedule:
+    - cron: '0 0 * * *'    # Daily at midnight
+    - cron: '0 9 * * 1'    # Weekly Monday 9am UTC (default)
+    - cron: '0 6 1 * *'    # Monthly on the 1st
+```
+
+### Optional: Use a Bot Account
+
+For better PR attribution, use a bot PAT:
+
+```yaml
+github-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT || secrets.GITHUB_TOKEN }}
+```
+
+## Usage
+
+### Automatic Scheduled Scans
+
+Once configured, the workflow runs automatically on the specified schedule. It will:
+
+1. Run a Trivy security scan on your repository
+2. Filter vulnerabilities by severity threshold
+3. For each vulnerability with an available fix:
+   - Create a fix branch (`fix/<cve-id>`)
+   - Update the vulnerable dependency
+   - Create a pull request with the fix
+
+### Manual Trigger
+
+You can also trigger scans manually:
+
+1. Go to **Actions** in your repository
+2. Select **Vulnerability Scan and Remediation**
+3. Click **Run workflow**
+4. Configure options:
+   - Severity threshold
+   - Maximum vulnerabilities to fix
+   - LLM model
+
+## Action Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `llm-model` | No | `anthropic/claude-sonnet-4-5-20250929` | LLM model for remediation |
+| `llm-base-url` | No | `''` | Custom LLM endpoint URL |
+| `severity-threshold` | No | `HIGH` | Minimum severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` |
+| `max-vulnerabilities` | No | `5` | Max vulnerabilities per run (0 = unlimited) |
+| `extensions-repo` | No | `OpenHands/extensions` | Extensions repository |
+| `extensions-version` | No | `main` | Git ref (tag, branch, or SHA) |
+| `llm-api-key` | Yes | - | LLM API key |
+| `github-token` | Yes | - | GitHub token for API access |
+
+## Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `vulnerabilities-found` | Number of vulnerabilities found matching severity threshold |
+| `scan-only` | `true` if no vulnerabilities were found (agent skipped) |
+
+## Remediation Workflow
+
+When remediating a vulnerability, the agent:
+
+1. **Analyzes** the vulnerability details (CVE ID, affected package, versions)
+2. **Locates** the dependency file (package.json, requirements.txt, pom.xml, etc.)
+3. **Updates** the package to the fixed version
+4. **Verifies** the change doesn't break the build
+5. **Creates a branch** named `fix/<cve-id>`
+6. **Commits** changes with a descriptive message
+7. **Creates a PR** with:
+   - Vulnerability details
+   - What was changed
+   - Links to CVE references
+
+## Supported Package Ecosystems
+
+Trivy scans and the remediation agent support:
+
+- **Node.js**: package.json, package-lock.json, yarn.lock
+- **Python**: requirements.txt, Pipfile, pyproject.toml
+- **Java**: pom.xml, build.gradle
+- **Go**: go.mod, go.sum
+- **Ruby**: Gemfile, Gemfile.lock
+- **Rust**: Cargo.toml, Cargo.lock
+- **PHP**: composer.json, composer.lock
+- **Docker**: Dockerfile, container images
+
+## Troubleshooting
+
+### Scan Not Running
+
+1. Check that the workflow file is in `.github/workflows/`
+2. Verify the cron syntax is correct
+3. Ensure secrets are configured correctly
+
+### No Vulnerabilities Fixed
+
+1. Check if vulnerabilities have available fixes (`FixedVersion` in Trivy)
+2. Verify the severity threshold isn't too strict
+3. Review the scan results artifact for details
+
+### PR Not Created
+
+1. Ensure GitHub token has write permissions for pull requests
+2. Check if a fix branch already exists
+3. Review workflow logs for agent errors
+
+### Rate Limiting
+
+If you see rate limit errors:
+1. Reduce `max-vulnerabilities` to limit PRs per run
+2. Use a dedicated bot token for high-volume repositories
+
+## Security
+
+- Uses checkout with `persist-credentials: true` for PR creation
+- Trivy runs locally within the GitHub runner
+- LLM API key and GitHub token are passed as secrets
+- Scan results are uploaded as artifacts for review
+
+## Related Resources
+
+- **Web Application**: https://openhands-vulnerability-fixer.vercel.app/
+- **Source Repository**: https://github.com/OpenHands/vulnerability-fixer
+- **Trivy Documentation**: https://aquasecurity.github.io/trivy/
+
+## Contributing
+
+See the main [extensions repository](https://github.com/OpenHands/extensions) for contribution guidelines.
+
+## License
+
+This plugin is part of the OpenHands extensions repository. See [LICENSE](../../LICENSE) for details.

package/plugins/vulnerability-remediation/action.yml

@@ -0,0 +1,187 @@
+---
+name: OpenHands Vulnerability Remediation
+description: Scan repositories for vulnerabilities and create PRs with fixes using OpenHands agents
+author: OpenHands
+
+branding:
+    icon: shield
+    color: red
+
+inputs:
+    llm-model:
+        description: >
+            LLM model to use for remediation.
+            Example: 'anthropic/claude-sonnet-4-5-20250929' or 'openai/gpt-4o'
+        required: false
+        default: anthropic/claude-sonnet-4-5-20250929
+    llm-base-url:
+        description: LLM base URL (optional, for custom LLM endpoints)
+        required: false
+        default: ''
+    max-vulnerabilities:
+        description: Maximum number of vulnerabilities to remediate per run (0 = unlimited)
+        required: false
+        default: '5'
+    severity-threshold:
+        description: "Minimum severity to remediate: 'CRITICAL', 'HIGH', 'MEDIUM', or 'LOW'"
+        required: false
+        default: HIGH
+    extensions-repo:
+        description: GitHub repository for extensions (owner/repo)
+        required: false
+        default: OpenHands/extensions
+    extensions-version:
+        description: Git ref to use for extensions (tag, branch, or commit SHA)
+        required: false
+        default: main
+    llm-api-key:
+        description: LLM API key (required)
+        required: true
+    github-token:
+        description: GitHub token for API access and creating PRs (required)
+        required: true
+
+outputs:
+    vulnerabilities-found:
+        description: Number of vulnerabilities found that match the severity threshold
+        value: ${{ steps.scan.outputs.vulnerabilities-found }}
+    scan-only:
+        description: Whether this was a scan-only run (no vulnerabilities to remediate)
+        value: ${{ steps.scan.outputs.scan-only }}
+
+runs:
+    using: composite
+    steps:
+        - name: Checkout extensions repository
+          uses: actions/checkout@v4
+          with:
+              repository: ${{ inputs.extensions-repo }}
+              ref: ${{ inputs.extensions-version }}
+              path: extensions
+
+        - name: Checkout target repository
+          uses: actions/checkout@v4
+          with:
+              fetch-depth: 0
+              persist-credentials: true
+              path: target-repo
+
+        - name: Set up Python
+          uses: actions/setup-python@v5
+          with:
+              python-version: '3.12'
+
+        - name: Install uv
+          uses: astral-sh/setup-uv@v6
+          with:
+              enable-cache: true
+
+        - name: Install Trivy
+          shell: bash
+          run: |
+              TRIVY_VERSION=$(curl -sL "https://api.github.com/repos/aquasecurity/trivy/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
+              curl -sL "https://github.com/aquasecurity/trivy/releases/download/${TRIVY_VERSION}/trivy_${TRIVY_VERSION#v}_Linux-64bit.tar.gz" | tar xzf - -C /usr/local/bin trivy
+              trivy --version
+
+        - name: Install GitHub CLI
+          shell: bash
+          run: |
+              if ! command -v gh &> /dev/null; then
+                sudo apt-get update
+                sudo apt-get install -y gh
+              fi
+
+        - name: Check required configuration
+          shell: bash
+          env:
+              LLM_API_KEY: ${{ inputs.llm-api-key }}
+              GITHUB_TOKEN: ${{ inputs.github-token }}
+          run: |
+              if [ -z "$LLM_API_KEY" ]; then
+                echo "Error: llm-api-key is required."
+                exit 1
+              fi
+
+              if [ -z "$GITHUB_TOKEN" ]; then
+                echo "Error: github-token is required."
+                exit 1
+              fi
+
+              echo "Repository: ${{ github.repository }}"
+              echo "Extensions Version: ${{ inputs.extensions-version }}"
+              echo "LLM Model: ${{ inputs.llm-model }}"
+              echo "Severity Threshold: ${{ inputs.severity-threshold }}"
+              echo "Max Vulnerabilities: ${{ inputs.max-vulnerabilities }}"
+
+        - name: Run vulnerability scan
+          id: scan
+          shell: bash
+          env:
+              SEVERITY_THRESHOLD: ${{ inputs.severity-threshold }}
+              MAX_VULNERABILITIES: ${{ inputs.max-vulnerabilities }}
+          run: |
+              cd target-repo
+              uv run python ../extensions/plugins/vulnerability-remediation/scripts/scan_and_remediate.py --scan-only
+              
+              # Read the vulnerability count from the scan results with error handling
+              if [ -f "scan-results.json" ]; then
+                VULN_COUNT=$(python3 -c "
+              import sys, json
+              try:
+                  with open('scan-results.json') as f:
+                      data = json.load(f)
+                  print(data.get('vulnerabilities_to_fix', 0))
+              except (json.JSONDecodeError, KeyError, FileNotFoundError) as e:
+                  print(f'Error parsing scan results: {e}', file=sys.stderr)
+                  print(0)
+              " 2>&1) || VULN_COUNT=0
+                
+                # Ensure VULN_COUNT is a valid number
+                if ! [[ "$VULN_COUNT" =~ ^[0-9]+$ ]]; then
+                  echo "⚠️ Failed to parse vulnerability count, defaulting to 0"
+                  VULN_COUNT=0
+                fi
+                
+                echo "vulnerabilities-found=$VULN_COUNT" >> $GITHUB_OUTPUT
+                
+                if [ "$VULN_COUNT" -eq 0 ]; then
+                  echo "scan-only=true" >> $GITHUB_OUTPUT
+                  echo "✅ No vulnerabilities found that match criteria. Skipping remediation."
+                else
+                  echo "scan-only=false" >> $GITHUB_OUTPUT
+                  echo "🔍 Found $VULN_COUNT vulnerabilities to remediate."
+                fi
+              else
+                echo "vulnerabilities-found=0" >> $GITHUB_OUTPUT
+                echo "scan-only=true" >> $GITHUB_OUTPUT
+                echo "✅ No scan results found. Skipping remediation."
+              fi
+
+        - name: Run remediation agent
+          if: steps.scan.outputs.vulnerabilities-found != '0'
+          shell: bash
+          env:
+              LLM_MODEL: ${{ inputs.llm-model }}
+              LLM_BASE_URL: ${{ inputs.llm-base-url }}
+              LLM_API_KEY: ${{ inputs.llm-api-key }}
+              GITHUB_TOKEN: ${{ inputs.github-token }}
+              REPO_NAME: ${{ github.repository }}
+              SEVERITY_THRESHOLD: ${{ inputs.severity-threshold }}
+              MAX_VULNERABILITIES: ${{ inputs.max-vulnerabilities }}
+          run: |
+              cd target-repo
+              echo "🤖 Starting OpenHands agent for vulnerability remediation..."
+              uv run --with openhands-sdk --with openhands-tools \
+                python ../extensions/plugins/vulnerability-remediation/scripts/scan_and_remediate.py --remediate
+
+        - name: Upload scan results
+          uses: actions/upload-artifact@v4
+          if: always()
+          with:
+              name: vulnerability-scan-results
+              path: |
+                  target-repo/trivy-results.json
+                  target-repo/scan-results.json
+                  target-repo/remediation-report.json
+              retention-days: 30
+              if-no-files-found: ignore