pentest

Pentest / OSINT Skill

Claude Code runs on the user's machine. You have real Bash, real filesystem, real process execution. Run tools immediately; the runtime wrapper handles environment details for you.

The execution model

Every tool runs through ht_run.py, which:

1. Reads ht_env.py to pick a backend — native on Linux/macOS, WSL on Windows with a real distro, Docker anywhere with Docker Desktop.
2. Looks up a purpose-built Docker image for the tool if one exists (instrumentisto/nmap, projectdiscovery/nuclei, caffix/amass, 20+ more). Falls back to kalilinux/kali-rolling for anything not mapped.
3. Executes the command. If permission-denied on native/WSL, auto-retries with sudo -n. If an error is classifiable as recoverable, handles it.
4. Returns structured JSON with status, stdout, stderr, returncode, and the command that ran.

Only one pre-block exists: tools flagged interactive (they read stdin mid-run). Bypass with --force + --command if you have non-interactive args.

Bundled scripts

All scripts live at ${CLAUDE_PLUGIN_ROOT}/scripts/. Call them with python ${CLAUDE_PLUGIN_ROOT}/scripts/<script>.py .... They emit JSON on stdout.

Script	Purpose
ht_search.py	Query the tool index. Filter by --q, --category, --tag, --capability runnable_by_claude, --os linux.
ht_env.py	Report host OS, WSL distros, Docker availability, and preferred_backend.
ht_run.py	Execute a tool. --command "..." for a full-command override. --args "..." for append-args. --network-host for LAN scans via docker. --privileged for raw sockets / hardware. --force to bypass the interactive pre-block.

Golden path

1. Read the ask. Map to a workflow if possible — see reference/workflows.md.
2. Check the environment once. python ${CLAUDE_PLUGIN_ROOT}/scripts/ht_env.py tells you which backend will run. If Windows + no WSL + Docker stopped, ask the user to start Docker before Linux-only work.
3. Find candidate tools. ht_search.py --q "<keyword>" to discover tool ids. Don't assume ids.
4. Execute them.
   • If RUN_COMMANDS is populated → ht_run.py <tool_id> --args "..."
   • If RUN_COMMANDS is empty (many upstream tools have runnable=False) → use --command "<full command>". The wrapper still picks the backend and image for you.
   • For LAN / gateway scans via Docker → add --network-host so the container sees your LAN.
   • For raw sockets / hardware → add --privileged.
5. Parse the JSON result:
   • status: ok → summarize the interesting parts of stdout; don't paste the whole output if it's long.
   • status: error with returncode != 0 → tool ran but failed. Report stderr and decide whether to retry with different args.
   • status: fallback → see reference/runtime-fallbacks.md. Pick the template matching the reason field.
   • status: timeout → raise --timeout <N> or break the scan into smaller chunks.
6. Compose, don't just call once. OSINT chains: subfinder → httpx → nuclei. holehe → sherlock → maigret. Feed outputs into the next step.

Docker image overrides

ht_run.py maps common tools to purpose-built images. These pull faster than Kali and have proper ENTRYPOINTs, so you just pass args:

Tool	Image
NMAP	instrumentisto/nmap
Nuclei	projectdiscovery/nuclei
Subfinder / Httpx / Katana	projectdiscovery/*
Amass	caffix/amass
TheHarvester	secsi/theharvester
Holehe / Maigret / SpiderFoot	official images
TruffleHog / Gitleaks	official images
Sqlmap	paoloo/sqlmap
Impacket / NetExec	rflathers/impacket, byt3bl33d3r/netexec

Override with --docker-image my/image for one-off swaps.

Ad-hoc commands (no wrapper)

For one-off invocations that don't map to a hackingtool tool id — e.g. curl -I https://target, arp -a, dig @8.8.8.8 example.com — just use Bash directly. Use ht_run.py when:

• The tool is in the index and you want automatic image/backend selection
• You want permission-error auto-retry
• You're chaining multiple tools and want uniform JSON output

References

• ${CLAUDE_PLUGIN_ROOT}/skills/pentest/reference/workflows.md — named playbooks
• ${CLAUDE_PLUGIN_ROOT}/skills/pentest/reference/runtime-fallbacks.md — templates for each fallback reason