regression-hunter

Finds candidate locations where a project's own previously-published security fix may not have been applied to a structurally similar ("sibling") piece of code elsewhere in the same codebase — a pattern security researchers call variant analysis.

This tool does not find vulnerabilities. It produces a short, ranked list of files worth a human researcher's attention, drawn from a project's own security advisory history. See METHODOLOGY.md for the technique, its grounding in published research, and its honest limitations.

Why this exists

Two problems, both documented in the bug bounty / open-source security community:

1. Target and lead selection is hard, especially for researchers without years of experience in a specific codebase — a lot of time goes into reading code that turns out to be fine.
2. Triage capacity is now a bigger bottleneck than researcher supply, and AI-assisted tools that flood programs with unverified, low-quality submissions make this worse, not better.

This tool is built to help with the first problem without contributing to the second: it narrows a large codebase down to a short list grounded in something concrete (the project's own prior fixes), and it stops there — verification, judgment, and the actual report stay a human's job.

Install

pip install -r requirements.txt

Optional: set GITHUB_TOKEN to raise the GitHub API rate limit from 60/hour to 5000/hour — matters for repositories with dozens of advisories.

Usage

# You choose what to clone and where — this tool never clones for you.
git clone https://github.com/<owner>/<repo>.git /path/to/clone

python3 -m regression_hunter <owner>/<repo> --clone-path /path/to/clone

Options:

--min-severity {critical,high,medium,low}   only consider advisories at or above this severity
--limit N                                    process at most N advisories (default 20, most severe/recent first)
--out FILE                                   write the Markdown report to FILE instead of stdout

Worked example

Run against portainer/portainer's own real advisory history:

python3 -m regression_hunter portainer/portainer --clone-path ./portainer

Advisory GHSA-cqpq-2fgr-8mvc (CVE-2026-44884) fixed a missing authorization check in customtemplate_file.go. This tool independently flags its sibling file in the same directory, customtemplate_git_fetch.go, as a high-confidence candidate — correctly, and without being told in advance: this file was later confirmed, by hand, to have the exact same missing-authorization bug, live-verified against a real running build of the project. See this project's companion vulnerability research for the full writeup.

That result is what this tool is for: it would have gotten a researcher to the right file directly, instead of by manually reading the advisory and every sibling in that directory.

Scope and responsible use

Only use this against repositories you are authorized to test, per their own security policy. This tool only reads a local clone and calls the public GitHub API for advisory metadata — it never scans, exploits, or contacts any running instance of the target software. Always follow the target project's documented disclosure process for anything you decide, after manual verification, is real.