Bounty Program Finder

bounty-program-finder is a discovery-only Agent Skill and CLI for finding, filtering, ranking, and explaining bug bounty programs that may be useful for later security research.

It focuses on programs with clear scope data, useful bounty/response signals, and GitHub repository candidates. It does not scan, fuzz, exploit, clone repositories automatically, run target code, or submit reports.

What It Does

• Loads bug bounty program seed data from public bounty target datasets.
• Normalizes HackerOne, Bugcrowd, Intigriti, and YesWeHack records into one schema.
• Enriches candidates with GitHub repository metadata when possible.
• Checks official program page reachability as a source signal.
• Ranks programs with explainable profiles such as oss_audit, max_payout, and fast_response.
• Produces Markdown plus stable JSON for use in a later audit workflow.
• Keeps strict scope safety: seed or inferred data is never treated as authorization.

Safety Model

This project is for target discovery and triage only.

• Do not treat a repository or asset as authorized unless the official program scope confirms it.
• Do not test, scan, fuzz, exploit, or contact production systems based only on this tool's output.
• Preserve and review all out-of-scope and exclusion text before any audit work.
• The default authorization status for seed-derived candidates is candidate_verification_required.

Quick Start

No third-party Python dependencies are required.

python3 skills/bounty-program-finder/scripts/bounty_program_finder.py \
  --query "List popular bounty programs with in-scope open-source GitHub repositories" \
  --profile auto \
  --limit 10 \
  --format both

Install or update the Codex skill locally:

python3 tools/install_codex_skill.py --force

Repeatable JSON-filtered run:

python3 skills/bounty-program-finder/scripts/bounty_program_finder.py \
  --filters-json '{"require_github": true, "bounty_only": true}' \
  --profile oss_audit \
  --limit 10 \
  --format json

CLI Options

python3 skills/bounty-program-finder/scripts/bounty_program_finder.py --help

Common flags:

• --query: natural-language discovery request.
• --filters-json: exact filter object; explicit filters override inferred query filters.
• --profile: auto, balanced, oss_audit, max_payout, fast_response, popular, or low_noise.
• --limit: number of rich records to return.
• --format: markdown, json, or both.
• --refresh: bypass cache.
• --require-github: require at least one GitHub repository candidate.
• --include-private: include private/invite-only records if accessible in the data.

Optional Environment Variables

Credentials are optional and are only read from environment variables:

• GITHUB_TOKEN
• HACKERONE_USERNAME
• HACKERONE_TOKEN
• BUGCROWD_TOKEN_ID
• BUGCROWD_TOKEN_SECRET
• INTIGRITI_TOKEN
• YESWEHACK_ACCESS_TOKEN

Token values are not written to output, tests, generated packages, or committed files.

Skill Layout

skills/bounty-program-finder/
├── SKILL.md
├── agents/openai.yaml
├── references/
└── scripts/bounty_program_finder.py

Planning documents live under planning/ and are intentionally outside the skill package.

Tests

Run the test suite:

python3 -m unittest discover -s tests

Run syntax checks:

python3 -m py_compile \
  skills/bounty-program-finder/scripts/bounty_program_finder.py \
  tools/package_claude_skill.py \
  tools/install_codex_skill.py

Package a Claude-compatible zip:

python3 tools/package_claude_skill.py

Install or update the local Codex skill:

python3 tools/install_codex_skill.py --force

Current Status

v1 is usable for discovery with:

• public seed data,
• GitHub metadata enrichment,
• official page reachability checks,
• explainable ranking,
• Markdown and JSON output,
• generic audit handoff fields.

Deep official API adapters are planned next. See planning/06-next-steps-roadmap.md.

Public Release Notes

• .cache/, dist/, .env*, generated bytecode, zip files, and private prompt folders are ignored.
• Do not commit local cache data or private program output.
• The project is released under the MIT License.