From ff15285f1836009e428feee57d0103220af6e711 Mon Sep 17 00:00:00 2001 From: unknown Date: Fri, 7 Aug 2026 12:19:34 +0530 Subject: [PATCH 1/2] Add corrected integration guide The prior draft (received as a PDF) described a CLI surface (claude code --task/--workflow/--plugin install) that doesn't exist. This replaces it with a guide grounded in the actual mechanics: slash-command install, natural-language usage via the pentest skill, and the real ht_preflight.py / ht_search.py / ht_run.py pipeline, verified with live runs (nmap against scanme.nmap.org, httpx) in this session. Co-Authored-By: Claude Sonnet 5 --- docs/INTEGRATION_GUIDE.md | 311 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100644 docs/INTEGRATION_GUIDE.md diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md new file mode 100644 index 0000000..30b6fee --- /dev/null +++ b/docs/INTEGRATION_GUIDE.md @@ -0,0 +1,311 @@ +# HackingTool Plugin Integration Guide for Claude Code + +**Plugin:** `hackingtool` (marketplace: `hackingtool-marketplace`, repo `AKCODEZ/hackingtool-plugin`) +**Wraps:** [Z4nzu/hackingtool](https://github.com/Z4nzu/hackingtool) — 183 pentesting/OSINT tools (MIT) +**Plugin version:** 0.2.0 +**This guide replaces an earlier draft that described a CLI surface (`claude code --task`, `--workflow`, `--plugin install`) that does not exist. Everything below was verified against the actual scripts and a live run.** + +## Table of Contents + +1. Quick Start +2. Prerequisites +3. Installation +4. How It Actually Works +5. Basic Usage +6. Common Workflows +7. Best Practices +8. Security Considerations +9. Troubleshooting +10. Examples (real, validated runs) + +--- + +## 1. Quick Start + +There is no special `claude code --task "..."` command. You install the plugin once, then just talk to Claude normally. + +``` +# 1. Install Claude Code, if you haven't already +npm install -g @anthropic-ai/claude-code + +# 2. Inside a Claude Code session, add the marketplace and install the plugin +/plugin marketplace add AKCODEZ/hackingtool-plugin +/plugin install hackingtool@hackingtool-marketplace + +# 3. Just ask, in plain language +"recon example.com" +"hunt the username johndoe" +"scan my repo for leaked secrets" +``` + +The first pentest-shaped ask in a session triggers a preflight check automatically — Claude will tell you which backend it picked (native / WSL / Docker) before running anything. + +--- + +## 2. Prerequisites + +### System Requirements + +- **OS:** Linux, macOS, or Windows. +- **Python 3.10+** on the machine running Claude Code — the plugin's scripts (`ht_preflight.py`, `ht_search.py`, `ht_run.py`) are plain Python, executed via Claude Code's Bash tool. (Verified working on Python 3.14.) +- **Claude Code** with plugin support. +- **Disk space:** 5GB+ free recommended. `ht_preflight.py` checks free space and warns below that threshold, since pentest Docker images add up. + +### Windows specifically + +You need **one** of: + +- a real WSL distro (Ubuntu, Kali, etc.), or +- Docker Desktop running. + +The detector (`ht_env.py`) explicitly filters out Docker Desktop's internal housekeeping distros (`docker-desktop`, `docker-desktop-data`, etc.) — those don't count as a usable WSL backend. If neither a real distro nor Docker is present, the environment reports `preferred_backend: fallback` and the skill says so rather than pretending it can run tools. + +### Network + +Outbound internet is required for Docker Hub image pulls and some tools' own lookups (e.g. `nuclei` templates, `subfinder` sources). Preflight actively checks connectivity (`1.1.1.1:443`) and flags it if unreachable. + +### Authorization + +Unchanged from good general practice: never point this at a system you don't own or don't have explicit written permission to test. See [Security Considerations](#8-security-considerations). + +### No built-in credential vault + +There is no `~/.hackingtool/credentials.env` mechanism. If a tool needs an API key (e.g. a Shodan-backed lookup), export it as a normal environment variable in the shell Claude Code is running in, or pass it inline when the tool is invoked via `--command`. + +--- + +## 3. Installation + +**Step 1 — Install Claude Code.** Standard install, nothing hackingtool-specific. + +**Step 2 — Add the marketplace and install the plugin**, from inside a Claude Code chat (slash commands, not shell flags): + +``` +/plugin marketplace add AKCODEZ/hackingtool-plugin +/plugin install hackingtool@hackingtool-marketplace +``` + +**Step 3 — Confirm it's active.** Ask something pentest-shaped, e.g. `"recon example.com"`. If the `pentest` skill's description matches your ask, Claude invokes it and runs preflight automatically. There's no shell-level `claude code --plugin list` to check from outside a session — installed plugins are managed from inside Claude Code. + +**Step 4 (Windows, one-time, if needed)** — set up a backend before your first real task: + +``` +wsl --install -d Ubuntu +``` + +or install Docker Desktop and leave it running. + +There is **no `HACKINGTOOL_BACKEND` environment variable**. Backend selection is automatic (`ht_env.py`), and can be overridden per-invocation with `--backend native|wsl|docker` when a tool actually runs. + +--- + +## 4. How It Actually Works + +``` +Claude Code chat (natural language) + │ + ▼ +`pentest` skill (SKILL.md) — auto-triggered when the ask is pentest/OSINT-shaped + │ + ├─ Step 0: ht_preflight.py → verdict: ready | partial | blocked + ├─ ht_search.py → look up a tool id in data/tools.json (183 tools) + └─ ht_run.py → picks a backend and runs it + │ + ├─ native (Linux/macOS): bash -lc "" + ├─ wsl (Windows + a real distro): wsl -d -- bash -lc "" + └─ docker (anywhere Docker runs): docker run --rm + │ + └─ ~25 tools map to a purpose-built image + (instrumentisto/nmap, projectdiscovery/nuclei, + caffix/amass, paoloo/sqlmap, ...); everything + else falls back to kalilinux/kali-rolling + │ + ▼ +structured JSON: {status, backend, returncode, stdout, stderr, command, tool, title, ...} + │ + ▼ +Claude reads the JSON and summarizes it in chat +``` + +What's different from the fictional version of this doc: + +- There's no separate "Claude Code API" layer sitting behind the chat — the skill runs as part of the same session, executing the bundled Python scripts through the ordinary Bash tool. You can read and run every one of those scripts yourself. +- Tool invocation isn't hidden behind an opaque marshaling layer — it's three scripts: `ht_preflight.py` (capability check), `ht_search.py` (query the 183-tool index), `ht_run.py` (execute with backend/retry logic). +- Backend selection on Windows specifically distinguishes a *real* WSL distro from Docker Desktop's internal pseudo-distros, and prefers WSL over Docker when both are available (falls back to Docker only if no real distro exists). +- Only one thing is ever pre-blocked: tools flagged `interactive` (they read from stdin mid-run, which a captured pipe can't answer). Everything else is tried first, and only falls back to a "do this yourself" message if the real attempt actually fails. + +--- + +## 5. Basic Usage + +No CLI syntax like `claude code --task "..."` exists — you talk to Claude directly. Two runs from this session, verified end-to-end: + +**"scan scanme.nmap.org for open ports"** *(scanme.nmap.org is the Nmap project's own public host, explicitly offered for testing — see nmap.org/legal — so it's a genuinely safe target to demo against)* + +1. Skill runs `ht_preflight.py` → `verdict: ready`, backend `wsl` (Docker also available). +2. `ht_search.py --q nmap` → resolves to `information_gathering.NMAP`. +3. NMAP has no default `run_commands` in the index (`runnable: false` upstream), so the skill supplies `--command` directly: `ht_run.py information_gathering.NMAP --command "nmap -F scanme.nmap.org"`. +4. First attempt on WSL fails (`nmap` not installed in that distro) → automatically retried on the Docker backend with the `instrumentisto/nmap` override image. +5. Real result: ports 22 (ssh) and 80 (http) open, others closed/filtered — returned as JSON and summarized in chat. + +**"run httpx -h"** + +Resolves to `information_gathering.Httpx`. WSL attempt fails (`command not found`) → falls back to Docker with `projectdiscovery/httpx`, image is pulled on first use, full `--help` output returned with `status: ok`. + +--- + +## 6. Common Workflows + +These are the real named playbooks (`skills/pentest/reference/workflows.md`) — you ask for the outcome in one sentence and Claude walks the chain, tool by tool, narrating results as it goes. There is no single flag that packages a multi-step workflow into one shell invocation like the old `--workflow pentest --output report.html` — that doesn't exist. + +| # | Workflow | Input | Tool chain (ids) | +|---|---|---|---| +| 1 | Domain recon | root domain | `Subfinder`/`Amass` → `Httpx` → `Nuclei` → `Ffuf`/`Gobuster` | +| 2 | Username investigation | username | `Sherlock` → `Maigret` → manual pivot | +| 3 | Email investigation | email address | `Holehe` → `Infoga` → pivot to #2 if a name surfaces | +| 4 | Leaked-secrets scan | git repo (URL or local) | `TruffleHog` → `Gitleaks` (cross-reference both) | +| 5 | Web app recon | target URL | `Wafw00f` → `Katana` → `Arjun` → `Ffuf` → `Nuclei` → `TestSSL` → `Sqlmap --batch` | +| 6 | Active Directory enumeration | DC + credentials | `NetExec` → `Impacket` → `Kerbrute` → `Certipy` → `BloodHound` | +| 7 | Cloud misconfig recon | cloud creds/asset | `Prowler` → `ScoutSuite` → `Pacu` | +| 8 | Mobile app static analysis | APK/IPA | `MobSF` → `Frida` → `Objection` | +| 9 | Wifi recon | monitor-mode adapter required | `Airgeddon` / `Wifite` / `Fluxion` / `pixiewps` | +| 10 | Reverse-engineer a binary | binary path | `Radare2` → `Ghidra` → `Binwalk` | +| 11 | Forensic image triage | disk image / memory dump | `Autopsy` → `BulkExtractor` → `Pspy` | + +For chaining, intermediate output is conventionally written to `./ht-/-.txt` so a multi-tool session stays reproducible. + +--- + +## 7. Best Practices + +**Authorization first.** Same rule as always — get written permission, define scope, stay inside it. This has nothing to do with the CLI and doesn't change. + +**Incremental scanning.** Ask for the narrow version first (`nmap -F` — top 100 ports) before the wide one. There's no separate "pass 1 / pass 2" flag; you just phrase the ask that way. + +**Output handling.** `ht_run.py` always prints JSON to stdout — there's no `--output` or `--preserve-raw` flag. Redirect it yourself, or ask Claude to write/summarize results to a file. The workflow convention above (`./ht-/...`) is the closest thing to a built-in output scheme. + +**Tool selection** — driven by the real capability flags in `data/tools.json`, not an invented table: + +| Capability flag | Meaning | +|---|---| +| `requires_sudo` | needs elevated privileges (native/WSL auto-retries once with `sudo -n`) | +| `interactive` | reads stdin mid-run — pre-blocked unless you pass `--force` + `--command` | +| `requires_hardware` | needs physical hardware (wifi adapter in monitor mode, etc.) | +| `long_running` | expect to raise `--timeout` | +| `runnable_by_claude` | whether the index ships a ready-to-run command (56 of 183 do) | + +**Resource management.** The real lever is `--timeout ` on `ht_run.py` (default 180). There's no thread-count flag on some outer CLI — pass tool-native flags (e.g. `nuclei -c 50`) as part of the command itself. + +**Error handling.** Read `skills/pentest/reference/runtime-fallbacks.md` — every failure mode `ht_run.py` can hit is documented there with the exact JSON shape to expect. There's no `--dry-run` flag; `ht_search.py` (which shows the command without executing it) is the closest equivalent. + +--- + +## 8. Security Considerations + +The substance of the original guidance was sound and isn't tied to any fictional CLI — authorization docs, legal review, scope definition, and restricting sensitive tools all still apply as written. What changes is the *mechanics*: + +**Secrets management.** There's no `~/.hackingtool/credentials.env` support. Export API keys as environment variables in the shell Claude Code runs in, or reference them explicitly when a tool is invoked via `ht_run.py ... --command`. + +**Audit logging.** Not built in. There's no `~/.hackingtool/audit.log` today. If your org needs an audit trail of every tool invocation, that has to be layered on yourself — e.g. by reviewing Claude Code's own session transcripts, or wrapping `ht_run.py` with your own logging before deploying it to a team. + +**Sensitive tool restrictions.** Build any allow/deny policy on the real capability flags (`requires_sudo`, `interactive`, `requires_hardware`, `long_running`) and real tool ids — e.g. `sql_injection.Sqlmap`, `active_directory.Impacket`, `wordlist_generator.Hashcat`, `wordlist_generator.JohnTheRipper` — rather than a generic "some tools need more approval" list. + +**Docker runs as root inside the container.** Unlike a native/WSL `sudo` retry (which needs a real password unless passwordless sudo is configured), the Docker backend always executes as the container's default user — usually root. Treat Docker-backed invocations of any exploitation-class tool with the same scrutiny you'd give root shell access. + +--- + +## 9. Troubleshooting + +Real diagnostics, all plain Python — run from `plugins/hackingtool/`: + +```bash +python scripts/ht_preflight.py +python scripts/ht_search.py --q "" +python scripts/ht_run.py --backend docker --command "..." --timeout 300 +python scripts/ht_index.py --hackingtool-path # regenerate tools.json from upstream +python scripts/build_readme_table.py # regenerate the README tool table +``` + +There is no `claude code --diagnostic`, `--show-backends`, `--test-tool`, or `--plugin verify` — those don't exist. + +### Preflight verdicts + +- **`ready`** — proceed; the summary states which backend was picked. +- **`partial`** — some core tools missing and no Docker fallback; recommendations list what to install. +- **`blocked`** — `preferred_backend: fallback` (no WSL, no Docker, on Windows) or critical recommendation unmet. Fix that first. + +### `ht_run.py` fallback reasons (`status: "fallback"`, `reason: ...`) + +| Reason | Means | Fix | +|---|---|---| +| `no_backend` | No usable Linux runtime | `wsl --install -d Ubuntu`, or start Docker Desktop | +| `not_installed` | Binary missing on the chosen backend | `ht_run.py --install`, or `--docker-image ` | +| `no_device` | Tool needs hardware not visible to the backend (e.g. wifi monitor mode) | Passthrough hardware via `usbipd-win`, or run on a machine that has it | +| `sudo_password_needed` | `sudo -n` retry failed — needs an interactive password | Run manually, or configure passwordless sudo for that command | +| `interactive` / `interactive_detected` | Tool reads stdin mid-run | Supply a non-interactive form via `--command` (e.g. `sqlmap --batch`), or run it yourself | +| `no_command` | Index has no `run_commands` for this tool (e.g. NMAP, Masscan) | Supply `--command ""` yourself | +| `timeout` | Ran past `--timeout` (default 180s) | Raise `--timeout`, or narrow the scan | + +--- + +## 10. Examples (real, validated runs) + +**Port scan (Docker backend, real target — authorized public test host):** + +``` +$ python scripts/ht_run.py information_gathering.NMAP --backend docker \ + --command "nmap -F scanme.nmap.org" --timeout 90 +``` +```json +{ + "status": "ok", + "backend": "docker", + "returncode": 0, + "stdout": "Nmap scan report for scanme.nmap.org (45.33.32.156)\nHost is up (0.055s latency).\n...\n22/tcp open ssh\n80/tcp open http\n...", + "command": "nmap -F scanme.nmap.org", + "image": "instrumentisto/nmap", + "tool": "information_gathering.NMAP", + "title": "Network Map (nmap)" +} +``` + +**HTTP probing tool, help output (Docker backend):** + +``` +$ python scripts/ht_run.py information_gathering.Httpx --backend docker --timeout 60 +``` +Result: `status: "ok"`, image `projectdiscovery/httpx`, full `httpx -h` usage text returned. + +**Same tool, WSL backend, binary missing:** + +``` +$ python scripts/ht_run.py information_gathering.Httpx --timeout 30 +``` +```json +{ + "status": "fallback", + "reason": "not_installed", + "command": "httpx -h", + "message": "Runtime fell back (not_installed). Manual run needed:\n\n httpx -h\n\nTool binary not found. Try: `python ht_run.py information_gathering.Httpx --install`...", + "diagnostic": {"backend": "wsl", "returncode": 127, "stderr": "bash: line 1: httpx: command not found\n"} +} +``` + +Note the difference from a hypothetical `claude code --task` command: these are plain scripts you (or Claude, via Bash) invoke directly. Nothing about them requires Claude in the loop — you can script `ht_run.py` yourself outside of Claude Code if you want a repeatable, non-interactive pipeline. + +--- + +## Summary Checklist + +Before conducting security tests with this plugin: + +- [ ] Written authorization from the system owner +- [ ] Defined scope (targets, timing, intensity) +- [ ] Legal review completed +- [ ] Secure handling worked out for anything the tools output +- [ ] Preflight run and verdict is `ready` (or `partial` with accepted limitations) +- [ ] Team knows there's no built-in audit log or credential vault — plan for those separately if needed + +--- + +**Sources:** `README.md`, `plugins/hackingtool/.claude-plugin/plugin.json`, `plugins/hackingtool/skills/pentest/SKILL.md`, `plugins/hackingtool/skills/pentest/reference/workflows.md`, `plugins/hackingtool/skills/pentest/reference/runtime-fallbacks.md`, and live script runs (`ht_preflight.py`, `ht_search.py`, `ht_run.py`) in this session. From 877ee8eae080fa80aad1fd29bab462ee1227b941 Mon Sep 17 00:00:00 2001 From: unknown Date: Fri, 7 Aug 2026 12:51:49 +0530 Subject: [PATCH 2/2] Add docs/ to README directory layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to the previous commit — the layout tree was missing the new docs/INTEGRATION_GUIDE.md entry. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f080e76..9026905 100644 --- a/README.md +++ b/README.md @@ -447,6 +447,8 @@ If hackingtool is a sibling directory of this repo, `--hackingtool-path` isn't n hackingtool-plugin/ ├── .claude-plugin/ │ └── marketplace.json # marketplace entry +├── docs/ +│ └── INTEGRATION_GUIDE.md # usage guide (install, workflows, troubleshooting) ├── images/ # screenshots + logo ├── README.md # this file └── plugins/hackingtool/