pypi-version-bisect

Binary-search a PyPI package's release history to pin down exactly which versions a vulnerability affects — the first-affected release, the last-affected release, and the version that fixed it — using O(log n) tests instead of installing every version.

You supply an oracle (check_fn(version) -> bool) that decides whether a given release is vulnerable. This library handles fetching the release timeline from PyPI (in chronological upload order) and driving an efficient bisection over it.

Install

pip install pypi-version-bisect

Library usage

from pypi_version_bisect import find_affected_range, format_version_range

def check_fn(version: str) -> bool:
    # Install the version in a sandbox and probe for the vulnerability.
    # Return True if vulnerable, False if clean.
    ...

result = find_affected_range("pyyaml", check_fn)
print(result["first_affected"])   # e.g. "3.1"
print(result["last_affected"])    # e.g. "5.3.1"
print(result["fixed_in"])         # e.g. "5.4"
print(format_version_range(result))  # ">=3.1,<5.4"

find_affected_range returns a dict with package, all_versions, first_affected, last_affected, fixed_in, and checked_count. If nothing could be determined it also includes an error key.

Tuning knobs:

• delay (default 0.5) — seconds between oracle calls, to be kind to install infrastructure.
• max_checks (default 40) — hard cap on oracle calls. Binary search is logarithmic, so 40 covers thousands of releases.

CLI

List releases in upload order:

pypi-version-bisect list requests

Bisect using an external command as the oracle (exit code 0 = vulnerable):

pypi-version-bisect range examplepkg \
  --check-cmd "python probe.py examplepkg=={version}" \
  --delay 1.0

Notes

• Only depends on requests.
• Network failures are non-fatal: fetching returns an empty list and the run reports a clear error rather than raising.
• Versions are ordered by earliest file upload time, which matches release chronology better than string sorting for pre-releases and hotfixes.

License

MIT