DX hardening, cbh packaging, and Claude-OSINT integration (#43)

* fix(dx): harden install, package cbh as pipx-installable, fix broken commands

Addresses 6 P1 defects from a DX review (solo bug-bounty hunter persona):

- install: .gitattributes (eol=lf) + CRLF self-heal in install.sh; INSTALL uses bash form
- cli: package cbh as a real pip/pipx console-script (pyproject.toml + cbh/ package +
  bundled cbh/data/skill_index.json fallback + scripts/gen_skill_index.py); scripts/cbh.py
  kept as a clone shim; recon writes to ./recon when installed
- commands: add /scope backed by a new deterministic engine/scope.py CLI (was called
  mandatory in /hunt but missing); reframe /token-scan, /intel, /surface so the skill
  path is primary and missing helper scripts are clearly optional
- docs: install capability matrix (plugin vs clone vs pipx); reconcile the authorization
  story in /hunt (don't ingest the SOW document != skip scope verification)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(skills): consolidate recon skills as canonical (integration Phase 1)

BugHunter becomes the source of truth for the two recon skills shared with
Claude-OSINT (which now re-exports them).

- offensive-osint: port h1_reference.py (HackerOne hacktivity agent) + dashboard.py
  (local recon console) + assets/ font from Claude-OSINT (CRLF->LF); documented in
  references/helpers-and-automation.md sec 49-50 + SKILL.md router. references/ split kept;
  OSINT's recent change was dashboard-only so no SKILL.md content delta.
- osint-methodology: keep BugHunter's expanded version (1703 vs 455 lines, supersedes
  OSINT's); bump version 2.1 -> 2.3 to pass OSINT's 2.2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(dx): correct CRLF docs + scope.py footguns (post-verification)

A 20-agent adversarial verification found the install.sh CRLF self-heal was
non-functional (bash parse-aborts on the CRLF case statement before the guard
runs) and the docs over-promised it; plus two fail-safe scope.py footguns.

- install.sh: remove the dead self-heal block (.gitattributes is the real fix);
  INSTALL.md now tells the truth (renormalize an existing CRLF checkout manually)
- engine/scope.py: keep bullets under nested ### sub-headings (was dropping in-scope
  assets under default-deny); --in-scope/--out-of-scope are now repeatable flags so a
  target placed after them is no longer swallowed
- commands/scope.md: inline example uses repeated --in-scope flags
- .gitignore: anchor scope.md -> /scope.md so it no longer shadows commands/scope.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(skills): add triggers frontmatter to offensive-osint

offensive-osint lacked the `triggers:` field that osint-methodology already has
and that the sibling Claude-OSINT repo's frontmatter lint requires (>=5). Added the
127-entry recon trigger list so the skill is internally consistent and Claude-OSINT
can re-export it without CI failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(install): install manifest + safe --uninstall + skip-identical (Phase 3)

Coexistence with the sister bundle Claude-OSINT: each install now records a manifest
of its footprint so uninstall removes only its own files and keeps any skill the other
bundle still owns (the two shared recon skills).

- install.sh: write ~/.claude/.skill-manifests/claude-bughunter.txt; --uninstall removes
  tracked skills/commands/hunt.sh + rc line but keeps shared-owned skills; skip re-copying
  a skill/command already present and identical (no last-installer-wins clobber)
- INSTALL.md: replace the unsafe rm -rf ~/.claude/skills advice with --uninstall
- README: document safe coexistence with Claude-OSINT

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(cbh): recon->hunt manifest contract (integration Phase 4)

The data handoff between recon and hunt: cbh recon emits recon/<target>/manifest.json,
which cbh surface and the hunt scaffold consume. Turns the conceptual 'OSINT recons,
BugHunter hunts' into a real, tested contract.

- cbh recon: emit manifest.json (schema 1.0) -- assets + ranked_surface (P1/P2/Kill via
  host heuristic + classify) + counts; secrets[]/identity_fabric{} left for the
  offensive-osint skill's deeper probes to append (shared-container design)
- cbh surface <target>: new subcommand -- read the manifest, print the ranked surface
- hunt.sh: ingest a manifest (2nd arg / $HUNT_MANIFEST / ./recon/<target>/) to seed
  scope.md (live hosts) + notes.md (ranked surface)
- docs/recon-manifest.md + recon-manifest.schema.json: the contract spec
- docs/cbh-cli.md, commands/surface.md: document the surface subcommand + manifest

Round-trip verified end-to-end (synthetic + a real 'cbh recon example.com').

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(dx): P2 backlog — --no-shell flag, supply-chain trust section, feedback template

- install.sh: add --no-shell (don't touch shell rc; print the source line to add);
  the default path now also echoes the exact line it appended (T2)
- SECURITY.md: 'Verifying what you install' supply-chain trust section — leans on the
  existing skill-lint CI, with an explicit 'what this does NOT prove' disclaimer and
  pin-to-reviewed-commit guidance, no malware-scanner theater (T13)
- add .github/ISSUE_TEMPLATE/dx_feedback.yml — low-friction 'skill didn't trigger /
  first-hunt' DX feedback form (T14)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Brian Richter <richter83.star@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitattributes

@@ -0,0 +1,20 @@
+# Normalize line endings so shell/Python entrypoints stay LF on every platform.
+# Without this, a Windows checkout (incl. WSL on a Windows-mounted drive) can
+# land CRLF in the scripts and break the installer with `env: 'bash\r': ...`.
+* text=auto eol=lf
+
+# Executable text MUST be LF regardless of platform.
+*.sh   text eol=lf
+*.py   text eol=lf
+*.bash text eol=lf
+
+# Treat known binary assets as binary (no eol munging).
+*.svg  binary
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.cast binary
+*.woff2 binary
+*.woff  binary

.github/ISSUE_TEMPLATE/dx_feedback.yml

@@ -0,0 +1,41 @@
+name: 💬 DX feedback (skill didn't trigger / first-hunt experience)
+description: A skill didn't load when you expected it, install/onboarding tripped you up, or you want to share how your first hunt went.
+title: "[dx] <short summary>"
+labels: ["dx-feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Quick, low-friction feedback on the developer experience — onboarding, install, or skill triggering. Helps us tune description keywords and the getting-started flow. **Anonymize all target data.**
+  - type: dropdown
+    id: area
+    attributes:
+      label: What's this about?
+      options:
+        - A skill didn't trigger when I expected it to
+        - Install / onboarding friction
+        - First-hunt experience (good or bad)
+        - cbh CLI behavior
+        - Other DX feedback
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: For a non-triggering skill, paste the prompt you used and which skill you expected to load. For install/onboarding, what step and what you saw.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect instead?
+    validations:
+      required: false
+  - type: input
+    id: env
+    attributes:
+      label: Environment (optional)
+      description: Harness (Claude Code / OpenCode / Codex / Hermes), OS, install path (plugin vs clone), cbh version.
+    validations:
+      required: false

.gitignore

@@ -28,7 +28,7 @@ evidence/
 findings/
 submissions.txt
 notes.md
-scope.md
+/scope.md
 CLAUDE.md.local
 targets/
 
@@ -48,6 +48,10 @@ __pycache__/
 *.pyc
 .venv/
 venv/
+# packaging build output (cbh is pip/pipx installable)
+build/
+dist/
+*.egg-info/
 
 # Node (if anyone adds tooling later)
 node_modules/

INSTALL.md

@@ -37,10 +37,15 @@ cd Claude-BugHunter
 ## Step 2 — Run the installer
 
 ```bash
-chmod +x scripts/install.sh
-./scripts/install.sh
+bash scripts/install.sh
 ```
 
+> On Windows/WSL, the repo ships a `.gitattributes` that forces LF line endings, so a
+> **fresh clone installs cleanly**. If you have an **existing** checkout that already
+> picked up CRLF (cloned before this `.gitattributes`), normalize it once with
+> `git add --renormalize . && git checkout .` (or just re-clone) — a CRLF-corrupted
+> shell script aborts with a `syntax error` and cannot fix itself.
+
 This copies:
 - All 71 skills → `~/.claude/skills/`
 - All 15 slash commands → `~/.claude/commands/`
@@ -192,24 +197,21 @@ Then go find a real program and put it to work. See [USAGE.md](USAGE.md) for the
 
 ## Uninstall
 
-To remove everything this repo installed:
+The installer writes a manifest of exactly what it placed (under
+`~/.claude/.skill-manifests/claude-bughunter.txt`). Remove that footprint — and
+**only** that footprint — with:
 
 ```bash
-# Remove all bundled skills (this removes EVERY skill in ~/.claude/skills,
-# including any you added manually — be selective if needed)
-# rm -rf ~/.claude/skills
-
-# Or remove only the originals contributed by this repo:
-rm -rf ~/.claude/skills/bugcrowd-reporting
-rm -rf ~/.claude/skills/evidence-hygiene
+bash scripts/install.sh --uninstall
+```
 
-# Remove all bundled commands
-# rm -rf ~/.claude/commands
+This removes the bundle's skills, slash commands, the `hunt.sh` script, and its
+shell-rc source line. Skills you also installed from the **sister bundle**
+[Claude-OSINT](https://github.com/elementalsouls/Claude-OSINT) — `offensive-osint`
+and `osint-methodology` — are **kept** if Claude-OSINT's manifest still claims them,
+so uninstalling one bundle never breaks the other. (Install backups under
+`~/.claude/install-backups/` are left in place; delete them manually if you want.)
 
-# Remove the hunt shell command
-rm -f ~/.claude/scripts/hunt.sh
-sed -i.bak '/claude\/scripts\/hunt.sh/d' ~/.zshrc
+If you installed via the **plugin** instead of the script: `/plugin uninstall claude-bughunter@elementalsouls`.
 
-# Remove Burp MCP entry
-claude mcp remove burp
-```
+Burp MCP, if you wired it, is removed separately: `claude mcp remove burp`.

README.md

@@ -53,6 +53,18 @@ cd Claude-BugHunter
 bash scripts/install.sh        # copies skills + commands into ~/.claude/
 ```
 
+**What each install path gives you:**
+
+| Path | 71 skills + 15 slash commands | `cbh` CLI | `hunt` scaffolder |
+|---|---|---|---|
+| **A — plugin** | ✅ namespaced under `claude-bughunter:` | ➕ separate `pipx install` | ❌ clone-only |
+| **B — copy install** | ✅ copied into `~/.claude/` | ✅ from the clone | ✅ from the clone |
+
+The plugin is the fastest path to the skills + slash commands. The terminal-native
+`cbh` runner installs standalone — `pipx install git+https://github.com/elementalsouls/Claude-BugHunter`
+— so plugin users can add it without a full clone (see [`cbh` CLI](docs/cbh-cli.md)).
+The `hunt` engagement scaffolder ships with the clone (Option B).
+
 That's it. Open Claude Code and describe what you're testing in plain English — the right skill loads automatically, no invocation by name:
 
 ```text
@@ -249,7 +261,7 @@ Operational tradecraft accumulated across bug-bounty engagements and authorized
 
 **Author:** [ElementalSoul](https://github.com/elementalsouls) · GenAI Security Research
 
-**Sister project:** [Claude-OSINT](https://github.com/elementalsouls/Claude-OSINT) — paired skills for the recon phase that this bundle picks up after.
+**Sister project:** [Claude-OSINT](https://github.com/elementalsouls/Claude-OSINT) — paired skills for the recon phase that this bundle picks up after. Its two recon skills (`offensive-osint`, `osint-methodology`) are **canonically maintained here** and re-exported there, so the two are byte-identical. **Installing both is safe:** each bundle's `install.sh` records a manifest, the script skips re-copying an identical skill, and `--uninstall` keeps any skill the other bundle still owns — uninstalling one never breaks the other.
 
 **Vendored foundation:** [shuvonsec/claude-bug-bounty](https://github.com/shuvonsec/claude-bug-bounty) — methodology, validation, reporting, payload library (8 of 71 skills + 15 slash commands)
 

SECURITY.md

@@ -48,6 +48,24 @@ The reasoning: internal-AD attacks against monitored corporate networks have a f
 
 If you reach domain-admin-class objectives during an engagement, the bundle's external-perimeter chain ends at "credential discovered + access verified" — handoff to specialist internal-RT tooling (Impacket, NetExec, CrackMapExec, Rubeus, Certify, BloodHound) is intentionally outside the bundle's scope.
 
+## Verifying what you install (supply-chain trust)
+
+You are installing 71 `SKILL.md` files plus shell and Python helpers into your AI agent's context. Agent Skills are third-party code — treat them like any dependency you run. Independent research (Snyk "ToxicSkills", 2026) found prompt injection in a meaningful fraction of public skills, so verification matters.
+
+**What we do on our side:**
+
+- **CI gate on every skill change** — [`.github/workflows/skill-lint.yml`](.github/workflows/skill-lint.yml) runs `scripts/lint_skills.py` on each PR: it validates `SKILL.md` structure against `CONTRIBUTING.md` and scans for leaked secrets and client/engagement identifiers.
+- **Pinned, reviewable provenance** — installing via the **plugin marketplace** pins each release to a specific commit SHA and runs Anthropic's automated screening. From a clone you can pin yourself: `git checkout <tag-or-commit>` before `bash scripts/install.sh`.
+- **No network calls at install time** — `install.sh` only copies local files and (unless `--no-shell`) appends one `source` line to your shell rc, which it prints back to you.
+
+**What this does NOT prove — read this:**
+
+- The lint is a **structural + secrets/identifier** check. It is **not** a malware or prompt-injection detector and makes no claim to catch a malicious skill. A clean lint means "well-formed, no obvious leaked secret" — nothing more.
+- **Review before you trust.** The `SKILL.md` files and bundled scripts (`skills/*/scripts/`, `scripts/`) are plain text — skim them before installing, paying attention to anything that fetches from the network or executes shell.
+- **Pin to a reviewed tag/commit** rather than tracking `main`, so an upstream change can't alter what runs in your agent without your say-so.
+
+If you find a skill or script in this repo that could be abused, see **Reporting a security issue** below.
+
 ## Reporting a security issue in this repo
 
 If you discover a security issue in **this repository itself** (not in a target you're hunting):

cbh/__init__.py

@@ -0,0 +1,2 @@
+"""claude-bughunter CLI package."""
+__version__ = "2.1.0"