Skip to content

README.md

Latest commit

 

History

History
123 lines (94 loc) · 4.94 KB

README.md

File metadata and controls

123 lines (94 loc) · 4.94 KB
Raw

VulnHunter-Fix

Automated security remediation skill for Claude Code. This is the companion to VulnHunter: VulnHunter finds the vulnerabilities, VulnHunter-Fix remediates them via test-driven development. For each finding it writes an exploit demo, writes a failing security test (RED), implements the fix (GREEN), verifies the exploit is blocked and nothing regressed, then delivers a PR.

Install

This skill ships as part of the VulnHunter repository. From the repository root, run the shared installer to copy all skills (including this one) into ~/.claude/skills/:

./install.sh      # installs vulnhunt, vulnhunt-fix-verify, and vulnhunter-fix
./uninstall.sh    # removes them

Restart Claude Code afterward, then invoke it with /vulnhunter-fix. Re-run ./install.sh from the repo root any time you change this skill's files to sync the installed copy.

Run on Opus. The reasoning load (clustering, fix synthesis, the collaboration loop) is calibrated for Opus; the skill stops and asks you to switch if it detects Sonnet or Haiku.

Requirements

  • The Claude Code CLI, authenticated, running on an Opus model.
  • git and the GitHub CLI (gh), authenticated for the repos you target.
  • Python 3.11+ with the skill's helper package installed: python -m pip install -e ".[dev]" (from this directory) — pulls in jsonschema.

Modes

Mode Entry point Orchestration Use case
In-place (default) cd into the target repo, run /vulnhunter-fix with no args Harvests vulnhunter-labeled GitHub issues on origin; fixes on per-finding git worktrees under <repo>/.vulnhunter-fix/; opens PRs back to the same repo Remediation against your own checkout
Fork (cross-org) /vulnhunter-fix <TARGET_REPO> <RESULTS_PATH> Forks the target into your configured fork_org, clones the fork into ./work/, delivers PRs to the fork Delivering fixes without touching the upstream target

Mode is auto-detected by scripts/detect_mode.sh (in-place when you are inside a GitHub checkout with no args; fork when you pass a target + results path).

Quick start (in-place)

cd ~/code/my-project          # a repo where VulnHunter has posted findings as issues
claude --model opus --add-dir ~/.claude/skills/vulnhunter-fix
# then in Claude Code:
/vulnhunter-fix

Quick start (fork)

claude --model opus --add-dir ~/.claude/skills/vulnhunter-fix
# then in Claude Code:
/vulnhunter-fix https://github.com/your-org/my-service /path/to/RepoName_VULNHUNT_RESULTS_*/

Workflow

The skill runs unattended within a phase but pauses at every phase boundary for an operator Approve/Pause decision.

  1. Parse — extract findings (from vulnhunter-labeled issues, or a results directory in fork mode) and cluster them.
  2. Plan — decide fix order and approach per cluster.
  3. Implement (TDD gate) — for each finding: exploit demo → failing security test (RED) → fix (GREEN) → confirm the exploit is blocked → regression check → commit. No source file is edited until RED evidence exists on disk.
  4. Verify — re-run the full RED→GREEN matrix per cluster.
  5. Deliver — six mechanical gates (severity mask, body completeness, scope, idempotency, anti-merge, verification table) run before any gh pr create.

Key principles

  • TDD-driven — no fix is "done" until a test proves it works.
  • Evidence-based PRs — every PR shows the exploit, the test, and the fix.
  • One PR per unit of delivery — a cluster (in-place) or a single finding (fork).
  • Operator-gated — phase-boundary checkpoints; no fast-path or skip options.
  • Never modifies untargeted code — fixes are scoped to the finding.

Configuration

Settings live in config.json. The org fields ship as neutral placeholders — set them to your own org names before running fork mode:

{
  "github": {
    "default_target_org": "your-org",
    "fork_org": "your-fork-org",
    "fork_prefix": "vulnhunter-fix",
    "pr_draft": true
  }
}
Key Default Meaning
github.host github.com Target GitHub host
github.default_target_org your-org Default org when resolving bare target repo names
github.fork_org your-fork-org Org where forks are created (fork mode)
github.fork_prefix vulnhunter-fix Prefix for created fork repo names
github.pr_draft true Open PRs as drafts
behavior.fork_visibility private Visibility for created forks

Override the GitHub host at runtime via VULNFIX_GH_HOST / GH_HOST.

Tests

python -m pip install -e ".[dev]"
python -m pytest -q

License

Part of the VulnHunter project; licensed under the Apache License, Version 2.0. See the repository-root LICENSE.