fix: repoint stale tools/ paths from the bughunter/ restructure (#175)

.github/workflows/tests.yml

@@ -38,3 +38,28 @@ jobs:
 
       - name: Run test suite
         run: pytest -q
+
+  tool-paths:
+    name: tool paths resolve
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Invoked tool paths must exist
+        run: |
+          # Every `bash|python3 <dir>/<file>.{py,sh}` in commands/ and skills/ must
+          # resolve to a real file. Bare filenames (no slash) are external tools and
+          # are skipped. Guards against the bughunter/ restructure leaving stale paths.
+          missing=0
+          while IFS= read -r p; do
+            case "$p" in
+              */*) if [ ! -f "$p" ]; then echo "MISSING: $p"; missing=1; fi ;;
+              *)   : ;;
+            esac
+          done < <(grep -rhoE '(bash|python3?) [A-Za-z0-9/._-]+\.(py|sh)' commands/ skills/ \
+                     | awk '{print $2}' | sort -u)
+          if [ "$missing" -ne 0 ]; then
+            echo "::error::command/skill docs reference tool paths that do not exist (see MISSING lines)"
+            exit 1
+          fi
+          echo "All invoked tool paths resolve."

.gitignore

@@ -50,6 +50,7 @@ nmap-output/
 .forge/
 
 # Runtime lead-board ledgers (per-target, regenerated on each hunt)
-memory/leads/
+# ** matches both the repo-root layout and bughunter/memory/leads/ after the bughunter/ move
+**/memory/leads/
 dist/
 build/

AGENTS.md

@@ -79,15 +79,15 @@ This repo is an agent-portable bug bounty plugin for professional hunting across
 
 ### Tools (Python/shell — in `tools/`)
 
-See **`tools/README.md`** for the full ~50-tool catalogue. Highlights:
-
-- `tools/hunt.py` — master orchestrator (auto lead-board ingest + EOL after recon; `--graphql` / `--cve-hunt` / `--zero-day`)
-- `tools/lead_board.py` — persistent recon→skill lead ledger (`ingest` / `show` / `next` / `touch`)
-- `tools/recon_engine.sh` · `vuln_scanner.sh` · `validate.py` · `scope_checker.py`
-- `tools/graphql_audit.sh` · `cicd_scanner.sh` · `cve_scan.sh` · `eol_check.py`
-- `tools/waf_encoder.py` · `waf_response_analyzer.py` · `multipart_mutator.py` · `bypass_403.sh`
-- `tools/external_arsenal.sh` — installed-tool registry (~50 tools); `_have <tool>` gate
-- `tools/secrets_hunter.sh` · `takeover_scanner.sh` · `cloud_recon.sh` · `param_discovery.sh`
+See **`bughunter/tools/README.md`** for the full ~50-tool catalogue. Highlights:
+
+- `bughunter/tools/hunt.py` — master orchestrator (auto lead-board ingest + EOL after recon; `--graphql` / `--cve-hunt` / `--zero-day`)
+- `bughunter/tools/lead_board.py` — persistent recon→skill lead ledger (`ingest` / `show` / `next` / `touch`)
+- `bughunter/tools/recon_engine.sh` · `vuln_scanner.sh` · `validate.py` · `scope_checker.py`
+- `bughunter/tools/graphql_audit.sh` · `cicd_scanner.sh` · `cve_scan.sh` · `eol_check.py`
+- `bughunter/tools/waf_encoder.py` · `waf_response_analyzer.py` · `multipart_mutator.py` · `bypass_403.sh`
+- `bughunter/tools/external_arsenal.sh` — installed-tool registry (~50 tools); `_have <tool>` gate
+- `bughunter/tools/secrets_hunter.sh` · `takeover_scanner.sh` · `cloud_recon.sh` · `param_discovery.sh`
 - Credential attack (opt-in): `wordlist_engine.sh` · `osint_employees.sh` · `breach_checker.py` · `spray_orchestrator.sh`
 - Web3: `token_scanner.py`
 

CLAUDE.md

@@ -91,42 +91,42 @@ This repo is a Claude Code plugin for professional bug bounty hunting across Hac
 
 ### Tools (Python/shell — in `tools/`)
 
-- `tools/hunt.py` — master orchestrator
-- `tools/recon_engine.sh` — subdomain + URL discovery (now with optional `nuclei` phase)
-- `tools/vuln_scanner.sh` — XSS/SQLi/SSTI/MFA/SAML probe pipeline
-- `tools/validate.py` — 4-gate finding validator
-- `tools/learn.py` — CVE + disclosure intel
-- `tools/intel_engine.py` — on-demand intel with memory context
-- `tools/scope_checker.py` — deterministic scope safety checker
-- `tools/scope_aggregator.sh` — multi-platform scope pull (bbscope + bounty-targets-data)
-- `tools/secrets_hunter.sh` — trufflehog/noseyparker/gitleaks wrapper for FS/git/JS/GH-org
-- `tools/takeover_scanner.sh` — dnsReaper/subjack subdomain-takeover scanner
-- `tools/cloud_recon.sh` — S3Scanner + cloud_enum + CloudFail wrapper
-- `tools/param_discovery.sh` — Arjun/x8 hidden-parameter discovery
-- `tools/bypass_403.sh` — byp4xx + built-in 403/401 bypass matrix
-- `tools/cve_scan.sh` — focused nuclei CVE-tag sweep + optional log4j-scan
-- `tools/external_arsenal.sh` — installed-tool registry (~50 tools); other scripts source this for `_have <tool>`
-- `tools/cicd_scanner.sh` — GitHub Actions workflow scanner (sisakulint wrapper, remote scan)
-- `tools/token_scanner.py` — automated token red flag scanner (EVM + Solana)
-- `tools/wordlist_engine.sh` — company-specific password wordlist generator (cewler + hashcat rules); requires `--with-credential-attack`
-- `tools/osint_employees.sh` — employee names + email patterns for spray prep (theHarvester + username-anarchy, opt-in CrossLinked); requires `--with-credential-attack`
-- `tools/breach_checker.py` — HIBP k-anonymity wordlist enrichment; ranks passwords by breach count (no API key, free)
-- `tools/spray_orchestrator.sh` — password spray with typed-hostname guard + lockout warning + audit log; modes: http-form / oauth / o365 / okta (TREVOR); requires `--with-credential-attack` for TREVOR modes
-- `tools/graphql_audit.sh` — 7-phase GraphQL audit: introspection + schema dump, graphw00f fingerprint, clairvoyance field discovery, batching DoS, alias bomb, gqlmap injection, graphql-cop checklist
-- `tools/lead_board.py` — persistent per-target lead ledger that routes every recon observation to the right `hunt-*` skill and tracks its status so no lead is forgotten (`memory/leads/<target>.jsonl`). `ingest` parses recon output and routes 30+ signal types (IDOR/SSRF/GraphQL/OAuth/SAML/LLM/source-leak/tech-stack/nuclei) to skills; `show` lists untouched-first and flags stale high-priority leads; `next` returns the single top lead; `touch` marks a lead investigating/killed/reported (re-ingest preserves status). See **Critical Rule 6**.
-- `tools/eol_check.py` — EOL / lifecycle intel from endoflife.date (auto-run by `hunt.py` after recon)
-- `tools/waf_encoder.py` · `waf_response_analyzer.py` · `multipart_mutator.py` — WAF bypass + soft-block scoring + upload mutation
-- `tools/cors_scanner.py` — CORS misconfig scanner (origin-reflection / null / credentialed / suffix-prefix regex / scheme-downgrade); pure classifier, no deps
-- `tools/crlf_scanner.py` — CRLF / response-splitting + host-header injection with Set-Cookie canary detection (encoded + UTF-8 bypass variants)
-- `tools/nosqli_scanner.py` — NoSQL injection (operator auth-bypass, bracket-syntax, $where time-based blind) with differential + timing classifier
-- `tools/jwt_scanner.py` — offline JWT toolkit: alg:none forgery, RS256→HS256 confusion, HS256 secret crack, static claim analysis (pure stdlib)
-- `tools/oob_listener.py` — out-of-band orchestrator wrapping interactsh-client; payloads + correlation for blind SSRF/XXE/SQLi/RCE/Log4Shell
-- `tools/llm_redteam.py` — LLM red-team corpus runner (prompt-injection/jailbreak/system-prompt-leak/exfil/indirect/guardrail-bypass) with canary detection
-- `tools/poc_bundler.py` — PoC evidence bundler (`capture` live via SSRF-guarded `safe_http`, or `from-request` offline from a saved/Burp request). Emits `request.http`, `response.http`, `repro.sh` (curl), `evidence.har` (HAR 1.2), optional `screenshot.png`, `evidence.md` (report-ready), and `bundle.json` (manifest + response SHA-256) under `findings/<target>-<class>/evidence/<id>/`. Secrets redacted by default (repro.sh uses `$ENV` placeholders); refuses PUT/DELETE/PATCH without `--confirm-unsafe`. See `/poc`.
-- `tools/hunt_dashboard.py` — local web Hunt Dashboard (`serve`/`export`); reads `memory/leads/`, `recon/`, `findings/`, `reports/`, galleries, and `hunt-memory/` into one live view. Pure stdlib, binds to 127.0.0.1, HTML-escapes all recon-derived data, path-traversal-guarded `/file` endpoint. Distinct from `tools/dashboard.py` (the in-terminal ANSI progress TUI). See `/dashboard`.
-- `tools/verifier.py` — the report gate (prove-or-suppress). Independently re-derives a finding from its `poc_bundler` bundle (re-sends via SSRF-guarded `safe_http` with an initial-host guard, checks a confirmation marker in the fresh response headers+body) and decides reportability: PROVEN only if the marker was in the original response AND is still present now; else REFUTED/UNPROVEN/INCONCLUSIVE → suppressed. Records the re-fetched response's SHA + status. `decide()` is a pure, total policy function; only PROVEN ships. Writes `verification.json`; `check`/`sweep`; `--require-proof` exits non-zero for gating; unsafe methods never re-fired without `--confirm-unsafe`; secrets read from env only. Reuses only merged code (poc_bundler). See `/verify`.
-- `tools/oracle.py` — self-learning lead/finding prioritizer. Trains a smoothed Naive-Bayes log-odds model on `journal.jsonl` outcomes (confirmed/rejected + payout/severity/vuln-class/endpoint/tech features) to score P(lead becomes a real finding), replacing the static regex priority with a data-driven, per-feature-explainable rank. Cold-start prior blends toward the learned model as evidence grows; `eval` runs leave-one-out CV against the prior + majority baselines to prove lift. `train` / `eval` / `rank <target>` (reuses `lead_board`) / `score`. Pure-stdlib, deterministic, read-only. See `/oracle`.
-- Full catalogue: **`tools/README.md`** (~50 tools). `hunt.py` auto-ingests leads after recon (`--graphql` / `--cve-hunt` / `--skip-leads` flags).
+- `bughunter/tools/hunt.py` — master orchestrator
+- `bughunter/tools/recon_engine.sh` — subdomain + URL discovery (now with optional `nuclei` phase)
+- `bughunter/tools/vuln_scanner.sh` — XSS/SQLi/SSTI/MFA/SAML probe pipeline
+- `bughunter/tools/validate.py` — 4-gate finding validator
+- `bughunter/tools/learn.py` — CVE + disclosure intel
+- `bughunter/tools/intel_engine.py` — on-demand intel with memory context
+- `bughunter/tools/scope_checker.py` — deterministic scope safety checker
+- `bughunter/tools/scope_aggregator.sh` — multi-platform scope pull (bbscope + bounty-targets-data)
+- `bughunter/tools/secrets_hunter.sh` — trufflehog/noseyparker/gitleaks wrapper for FS/git/JS/GH-org
+- `bughunter/tools/takeover_scanner.sh` — dnsReaper/subjack subdomain-takeover scanner
+- `bughunter/tools/cloud_recon.sh` — S3Scanner + cloud_enum + CloudFail wrapper
+- `bughunter/tools/param_discovery.sh` — Arjun/x8 hidden-parameter discovery
+- `bughunter/tools/bypass_403.sh` — byp4xx + built-in 403/401 bypass matrix
+- `bughunter/tools/cve_scan.sh` — focused nuclei CVE-tag sweep + optional log4j-scan
+- `bughunter/tools/external_arsenal.sh` — installed-tool registry (~50 tools); other scripts source this for `_have <tool>`
+- `bughunter/tools/cicd_scanner.sh` — GitHub Actions workflow scanner (sisakulint wrapper, remote scan)
+- `bughunter/tools/token_scanner.py` — automated token red flag scanner (EVM + Solana)
+- `bughunter/tools/wordlist_engine.sh` — company-specific password wordlist generator (cewler + hashcat rules); requires `--with-credential-attack`
+- `bughunter/tools/osint_employees.sh` — employee names + email patterns for spray prep (theHarvester + username-anarchy, opt-in CrossLinked); requires `--with-credential-attack`
+- `bughunter/tools/breach_checker.py` — HIBP k-anonymity wordlist enrichment; ranks passwords by breach count (no API key, free)
+- `bughunter/tools/spray_orchestrator.sh` — password spray with typed-hostname guard + lockout warning + audit log; modes: http-form / oauth / o365 / okta (TREVOR); requires `--with-credential-attack` for TREVOR modes
+- `bughunter/tools/graphql_audit.sh` — 7-phase GraphQL audit: introspection + schema dump, graphw00f fingerprint, clairvoyance field discovery, batching DoS, alias bomb, gqlmap injection, graphql-cop checklist
+- `bughunter/tools/lead_board.py` — persistent per-target lead ledger that routes every recon observation to the right `hunt-*` skill and tracks its status so no lead is forgotten (`memory/leads/<target>.jsonl`). `ingest` parses recon output and routes 30+ signal types (IDOR/SSRF/GraphQL/OAuth/SAML/LLM/source-leak/tech-stack/nuclei) to skills; `show` lists untouched-first and flags stale high-priority leads; `next` returns the single top lead; `touch` marks a lead investigating/killed/reported (re-ingest preserves status). See **Critical Rule 6**.
+- `bughunter/tools/eol_check.py` — EOL / lifecycle intel from endoflife.date (auto-run by `hunt.py` after recon)
+- `bughunter/tools/waf_encoder.py` · `waf_response_analyzer.py` · `multipart_mutator.py` — WAF bypass + soft-block scoring + upload mutation
+- `bughunter/tools/cors_scanner.py` — CORS misconfig scanner (origin-reflection / null / credentialed / suffix-prefix regex / scheme-downgrade); pure classifier, no deps
+- `bughunter/tools/crlf_scanner.py` — CRLF / response-splitting + host-header injection with Set-Cookie canary detection (encoded + UTF-8 bypass variants)
+- `bughunter/tools/nosqli_scanner.py` — NoSQL injection (operator auth-bypass, bracket-syntax, $where time-based blind) with differential + timing classifier
+- `bughunter/tools/jwt_scanner.py` — offline JWT toolkit: alg:none forgery, RS256→HS256 confusion, HS256 secret crack, static claim analysis (pure stdlib)
+- `bughunter/tools/oob_listener.py` — out-of-band orchestrator wrapping interactsh-client; payloads + correlation for blind SSRF/XXE/SQLi/RCE/Log4Shell
+- `bughunter/tools/llm_redteam.py` — LLM red-team corpus runner (prompt-injection/jailbreak/system-prompt-leak/exfil/indirect/guardrail-bypass) with canary detection
+- `bughunter/tools/poc_bundler.py` — PoC evidence bundler (`capture` live via SSRF-guarded `safe_http`, or `from-request` offline from a saved/Burp request). Emits `request.http`, `response.http`, `repro.sh` (curl), `evidence.har` (HAR 1.2), optional `screenshot.png`, `evidence.md` (report-ready), and `bundle.json` (manifest + response SHA-256) under `findings/<target>-<class>/evidence/<id>/`. Secrets redacted by default (repro.sh uses `$ENV` placeholders); refuses PUT/DELETE/PATCH without `--confirm-unsafe`. See `/poc`.
+- `bughunter/tools/hunt_dashboard.py` — local web Hunt Dashboard (`serve`/`export`); reads `memory/leads/`, `recon/`, `findings/`, `reports/`, galleries, and `hunt-memory/` into one live view. Pure stdlib, binds to 127.0.0.1, HTML-escapes all recon-derived data, path-traversal-guarded `/file` endpoint. Distinct from `bughunter/tools/dashboard.py` (the in-terminal ANSI progress TUI). See `/dashboard`.
+- `bughunter/tools/verifier.py` — the report gate (prove-or-suppress). Independently re-derives a finding from its `poc_bundler` bundle (re-sends via SSRF-guarded `safe_http` with an initial-host guard, checks a confirmation marker in the fresh response headers+body) and decides reportability: PROVEN only if the marker was in the original response AND is still present now; else REFUTED/UNPROVEN/INCONCLUSIVE → suppressed. Records the re-fetched response's SHA + status. `decide()` is a pure, total policy function; only PROVEN ships. Writes `verification.json`; `check`/`sweep`; `--require-proof` exits non-zero for gating; unsafe methods never re-fired without `--confirm-unsafe`; secrets read from env only. Reuses only merged code (poc_bundler). See `/verify`.
+- `bughunter/tools/oracle.py` — self-learning lead/finding prioritizer. Trains a smoothed Naive-Bayes log-odds model on `journal.jsonl` outcomes (confirmed/rejected + payout/severity/vuln-class/endpoint/tech features) to score P(lead becomes a real finding), replacing the static regex priority with a data-driven, per-feature-explainable rank. Cold-start prior blends toward the learned model as evidence grows; `eval` runs leave-one-out CV against the prior + majority baselines to prove lift. `train` / `eval` / `rank <target>` (reuses `lead_board`) / `score`. Pure-stdlib, deterministic, read-only. See `/oracle`.
+- Full catalogue: **`bughunter/tools/README.md`** (~50 tools). `hunt.py` auto-ingests leads after recon (`--graphql` / `--cve-hunt` / `--skip-leads` flags).
 
 ### External tool references
 

README.md

@@ -502,7 +502,7 @@ Agentic-Bug-Hunter/
 │   ├── recon_engine.sh        # Subdomain + URL discovery
 │   ├── vuln_scanner.sh        # XSS · SQLi · SSRF · SSTI probe pipeline
 │   ├── validate.py            # 4-gate finding validator with identity checks
-│   └── …                      # 30+ more scanners - see tools/README.md
+│   └── …                      # 30+ more scanners - see bughunter/tools/README.md
 │
 ├── memory/                    # Cross-session hunt memory (pattern DB · audit log)
 ├── rules/                     # Always-active hunting + reporting rules

bughunter/agents/credential-hunter.md

@@ -24,7 +24,7 @@ A target domain (e.g., `target.com`) and optional flags:
 
 ## Hard safety rails (NON-NEGOTIABLE)
 
-1. **NEVER invoke `/spray` or `tools/spray_orchestrator.sh` without explicit human approval via AskUserQuestion.** This applies even if the user said "go" or "run the whole pipeline" — spray is its own decision point.
+1. **NEVER invoke `/spray` or `bughunter/tools/spray_orchestrator.sh` without explicit human approval via AskUserQuestion.** This applies even if the user said "go" or "run the whole pipeline" — spray is its own decision point.
 2. **NEVER bypass the spray pre-flight (`--i-understand`) on the user's behalf.** Let the orchestrator's typed-hostname confirmation actually run.
 3. **Stage outputs live under `recon/<target>/`** — DO NOT write anywhere else, DO NOT delete previous runs without permission.
 4. **If `/scope <target>` reports out-of-scope, STOP and surface that to the user before any further work.**
@@ -45,7 +45,7 @@ If unreachable or DNS-fail, STOP and report.
 ### Stage 1 — `/wordlist-gen <target>`
 
 ```bash
-tools/wordlist_engine.sh <target> --filter strict --mode balanced
+bughunter/tools/wordlist_engine.sh <target> --filter strict --mode balanced
 ```
 
 Wait for completion. Capture stats from `recon/<target>/wordlists/`:
@@ -58,7 +58,7 @@ If `cleaned.txt` has <100 entries, the target's website is too thin for a useful
 ### Stage 2 — `/osint-employees <target>`
 
 ```bash
-tools/osint_employees.sh <target> [--with-linkedin] [--with-pydictor-social]
+bughunter/tools/osint_employees.sh <target> [--with-linkedin] [--with-pydictor-social]
 ```
 
 Wait. Capture stats from `recon/<target>/osint/`:
@@ -71,7 +71,7 @@ If `usernames.txt` is empty AND `--with-linkedin` was not enabled, surface: "0 u
 ### Stage 3 — `/breach-check` on the ranked wordlist
 
 ```bash
-tools/breach_checker.py recon/<target>/wordlists/ranked.txt \
+bughunter/tools/breach_checker.py recon/<target>/wordlists/ranked.txt \
     --limit <breach-limit> --shuffle --with-counts
 ```
 
@@ -120,7 +120,7 @@ When user picks option 1, hand them the **exact command** to copy-paste, includi
 
 ```bash
 # AGENT NEVER RUNS THIS — only suggests it for user to run
-tools/spray_orchestrator.sh https://<target>/<login-path> \
+bughunter/tools/spray_orchestrator.sh https://<target>/<login-path> \
     --mode http-form \
     --users recon/<target>/osint/usernames.txt \
     --passes recon/<target>/wordlists/ranked-ranked.txt \
@@ -129,7 +129,7 @@ tools/spray_orchestrator.sh https://<target>/<login-path> \
 
 ## What you DO NOT do
 
-- ❌ DO NOT call `tools/spray_orchestrator.sh` yourself, even with `--dry-run`
+- ❌ DO NOT call `bughunter/tools/spray_orchestrator.sh` yourself, even with `--dry-run`
 - ❌ DO NOT bypass `--i-understand` on the user's behalf
 - ❌ DO NOT auto-pick http-form vs oauth vs o365 — ask the user
 - ❌ DO NOT report bugs / write a report — that's a separate skill (`/validate` + `/report`)

bughunter/agents/report-writer.md

@@ -69,7 +69,7 @@ SSRF → cloud metadata:          AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:L/VA:N/SC:H/S
 Stored XSS → ATO:               AV:N/AC:L/AT:N/PR:N/UI:P/VC:L/VI:L/VA:N/SC:H/SI:H/SA:N = 8.8 High
 ```
 
-Use `python3 tools/validate.py` for interactive CVSS 4.0 scoring, or verify at:
+Use `python3 bughunter/tools/validate.py` for interactive CVSS 4.0 scoring, or verify at:
 https://www.first.org/cvss/calculator/4.0
 
 ## HackerOne Format