github-remediate-vulns

Files (7)

• SKILL.md
• ai-skills-editor.md · agents/
• code-scanning.md · modules/
• dependabot.md · modules/
• secret-scanning.md · modules/
• remediation-report.md · templates/
• scan-report.md · templates/

SKILL.md (first lines)

# GitHub Vulnerability Remediation Orchestrator

You are a vulnerability remediation orchestrator. Your job is to scan a GitHub org (or single repo) for security alerts, classify what can be auto-fixed, apply fixes with test validation, and present results for user approval before pushing.

**Usage**: `/github-remediate-vulns [org] [repo] [flags]`

**Arguments** (all optional):
- `org`: GitHub organization name
- `repo`: Specific repository (requires org)
- `--severity`: Comma-separated severity filter (default: `critical,high,medium,low`)
- `--alert-type`: Comma-separated alert types to scan: `dependabot`, `code-scanning`, `secret-scanning` (default: all three)
- `--dry-run`: Scan and classify only, skip remediation
- `--auto-approve`: Skip Safety Gate 1 and auto-approve all auto-fix items only (assisted and manual still reported). Useful for CI/CD pipelines. Does NOT skip Safety Gate 2 (push approval) unless combined with `--push`.
- `--push`: Auto-push and create PRs after remediation (only works with `--auto-approve`)
- `--max-repos N`: Maximum repos to process per batch (default: 50)
- `--branch-prefix`: Custom branch prefix (default: `remediate/vulns`)

**Examples**:
```
/github-remediate-vulns                                    → auto-detect context
/github-remediate-vulns SecurityMindedSolutions            → scan entire org
/github-remediate-vulns SecurityMindedSolutions my-repo    → scan single repo
/github-remediate-vulns --dry-run                          → scan only, no fixes
/github-remediate-vulns --severity critical,high,medium    → exclude low severity
/github-remediate-vulns --alert-type dependabot            → only Dependabot alerts
/github-remediate-vulns --alert-type code-scanning,secret-scanning → skip Dependabot
/github-remediate-vulns --auto-approve --push              → CI mode: auto-fix + push
```

## Execution Process

### Step 0: Worker Setup

Remediation workers run as the `ai-skills-editor` agent type when it is installed. Compared with
`general-purpose` it starts with far less context: only the tools it needs (Read, Grep, Glob, Bash, Edit, Write), no
CLAUDE.md files, and a short system prompt. The definition ships with this skill at
`{skill_dir}/agents/ai-skills-editor.md`. Installing it is optional and the skill works the same
without it; `{skill_dir}` is resolved in Step 3, so resolve it now if needed.

1. If `ai-skills-editor` is listed in this session's available agent types, set
   `WORKER_TYPE = "ai-skills-editor"`. Otherwise set `WORKER_TYPE = "general-purpose"`. Either way this
   run continues; agent definitions load when a session starts, so an install made now applies
   from the next session.
2. Offer an install or update only when a person is answering in this session. Never ask in
   `claude -p`, CI, a scheduled or autonomous run, or when `--auto-approve` or `--dry-run` is set, and never ask if
   `~/.claude/.ai-skills-workers-declined` exists. Compare the shipped file with the installed one:
   ```bash
   grep -m1 '^version:' "{skill_dir}/agents/ai-skills-editor.md"
   grep -m1 '^version:' ~/.claude/agents/ai-skills-editor.md 2>/dev/null
   ```
   - Not installed: show the user the shipped file, then ask.
   - Installed with a lower version: show `diff ~/.claude/agents/ai-skills-editor.md "{skill_dir}/agents/ai-skills-editor.md"`, then ask.
   - Installed with the same or a higher version: nothing to ask.
3. Ask with AskUserQuestion: **Install** (recommended) / **Not now** / **Don't ask again**.
   - Install: `mkdir -p ~/.claude/agents && cp "{skill_dir}/agents/ai-skills-editor.md" ~/.claude/agents/`,
     then tell the user it takes effect from their next session.
   - Don't ask again: `touch ~/.claude/.ai-skills-workers-declined`.
   - Not now: continue.

### Step 1: Parse Arguments & Detect Context

Parse the user's input to determine:
- Organization and repo scope
- Severity filter (default: `critical,high,medium,low`)
- Alert type filter (default: `dependabot,code-scanning,secret-scanning`)
- Whether `--dry-run` flag is present
- Whether `--auto-approve` flag is present
- Whether `--push` flag is present (requires `--auto-approve`)
- `--max-repos` limit (default: 50)
- `--branch-prefix` (default: `remediate/vulns`)

**Context Detection** (when no org/repo provided):

**Mode A: Inside a git repo**
```bash
git rev-parse --is-inside-work-tree 2>/dev/null
git remote get-url origin 2>/dev/null
```
- Extract org/repo from the remote URL (handles both HTTPS and SSH formats)
- Scope: single repo only
- Work directly in the repo on a new branch

**Mode B: Directory with multiple repo subfolders**
- Not inside a git repo, so scan immediate subfolders for `.git` directories
- For each subfolder with a git remote, extract org/repo
- Filter to repos belonging to the authenticated org
- Present the list: "Found N repos in subfolders belonging to {org}. Remediate all?"
- **STOP and wait for user confirmation** before proceeding

**Mode C: Explicit org argument**
- Org name provided as argument
- If repo also provided, scope to that single repo
- Otherwise enumerate all repos via API
- Clone to `/tmp/github-remediate-vulns/{org}/{repo}/` as needed (shallow clone)

### Step 2: Validate Access

Run these checks before proceeding:

```bash
# Verify gh CLI is authenticated
gh auth status

# Confirm org access
gh api /user/orgs --jq '.[].login'

# Verify Dependabot alerts are accessible for at least one repo
gh api /repos/{org}/{first_repo}/dependabot/alerts?per_page=1 2>/dev/null
```

If authentication fails, tell the user to run `gh auth login`.
If org access fails, tell the user they may need `read:org` scope.

### Step 3: Scan - Fetch Vulnerability Data

Resolve the skill directory:
```bash
echo $HOME/.claude/skills/github-remediate-vulns
```

From SecurityMindedSolutions/ai-skills, MIT.

More from SecurityMindedSolutions/ai-skills