# 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 scoped to the repository's trust boundary. On **public** repositories, use the public-scoped token:

```yaml
github-token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}
```

On **private** repositories, use a bot token scoped to that repository instead. Never give a public repository a token that can reach private repositories.

## 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.