dragonked2 / tool-doctor

TOOL DOCTOR

Check your tools before you need them. Missing tools mid-engagement = lost time.

0. CROSS-PLATFORM AND NON-FATAL RULES (READ FIRST)

Supported install targets: Windows native, Debian/Ubuntu/Kali, RHEL/CentOS/Rocky/Alma/Fedora, Alpine, Arch, openSUSE, macOS, and WSL (only when installed + Running).

The big readiness script in section 1 is Linux/bash-only (command -v,
bash arrays, &>/dev/null, ((missing++))). It FAILS on Windows
(PowerShell) and on minimal shells. Rules:

1. Check ONE tool at a time, never the whole script at once.
   A single failed check must never abort the engagement.
   `bash
   # Linux / macOS / Git Bash
   command -v subfinder && subfinder -version 2>&1 | head -1
   `
   `powershell
   # Windows PowerShell
   Get-Command subfinder -ErrorAction SilentlyContinue
   `

2. A missing tool is routine, not an error. Record it
   (subfinder: MISSING → fallback: assetfinder, crt.sh via httpflow)
   and switch to section 4 alternatives immediately. Never retry a
   failed install more than twice.

3. Prefer tools already inside this agent: the httpflow tool
   replaces curl | jq chains (crt.sh, header fetches), bash
   replaces ad-hoc scripting. External binaries are accelerators,
   not prerequisites.

4. On Windows without Go/Python toolchains, use Docker images
   (docker run projectdiscovery/subfinder) or the httpflow/curl
   fallbacks — do not burn the engagement on toolchain setup.

5. WSL only when ready. Never assume WSL. Use it only if
   wsl -l -v shows a distro with State: Running (installer
   prints WSL: ready). Prefer native winget/scoop/choco installs.

1. TOOL READINESS CHECK

Run alphacode bugbounty doctor first. It is cross-platform, read-only,
and resolves the Go bin directory and Windows PATHEXT correctly. Use the bash
script below only when that command is unavailable or when you need the
extended tool list it covers.

Run this to see what's available on the current machine:

#!/bin/bash
echo "╔══════════════════════════════════════════════════════════╗"
echo "║              🔧 TOOL DOCTOR — READINESS CHECK           ║"
echo "╚══════════════════════════════════════════════════════════╝"
echo ""

# Tool categories
RECON_TOOLS=(subfinder amass assetfinder dnsx massdns)
HTTP_TOOLS=(httpx curl wget)
SCANNER_TOOLS=(nuclei nikto nmap masscan)
FUZZ_TOOLS=(ffuf gobuster dirsearch feroxbuster)
EXPLOIT_TOOLS=(sqlmap dalfox xsstrike commix)
JS_TOOLS=(katana gau waybackurls linkfinder secretfinder)
SECRET_TOOLS=(trufflehog gitleaks)
API_TOOLS=(arjun paramspider kiterunner)
MISC_TOOLS=(checksec searchsploit whatweb wafw00f)

check_tool() {
    local tool=$1
    if command -v "$tool" &>/dev/null; then
        version=$("$tool" --version 2>&1 | head -1)
        echo "  ✅ $tool — $version"
        return 0
    else
        echo "  ❌ $tool — NOT FOUND"
        return 1
    fi
}

echo "📡 RECONNAISSANCE TOOLS"
echo "────────────────────────"
missing=0
for tool in "${RECON_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "🌐 HTTP PROBING TOOLS"
echo "────────────────────────"
for tool in "${HTTP_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "🔍 SCANNER TOOLS"
echo "────────────────────────"
for tool in "${SCANNER_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "📁 FUZZING TOOLS"
echo "────────────────────────"
for tool in "${FUZZ_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "💉 EXPLOITATION TOOLS"
echo "────────────────────────"
for tool in "${EXPLOIT_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "📜 JAVASCRIPT ANALYSIS TOOLS"
echo "────────────────────────"
for tool in "${JS_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "🔑 SECRET SCANNING TOOLS"
echo "────────────────────────"
for tool in "${SECRET_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "🔌 API DISCOVERY TOOLS"
echo "────────────────────────"
for tool in "${API_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

echo "🧰 MISC TOOLS"
echo "────────────────────────"
for tool in "${MISC_TOOLS[@]}"; do
    check_tool "$tool" || ((missing++))
done
echo ""

if [ "$missing" -gt 0 ]; then
    echo "⚠‹VARIATION SELECTOR U+FE0F›  $missing tools missing. Install them for full coverage."
    echo ""
    echo "BUNDLED INSTALLER (preferred — auto-detects OS):"
    echo "  bash scripts/install_bugbounty_tools.sh --platform"
    echo "  bash scripts/install_bugbounty_tools.sh all"
    echo "  bash scripts/install_bugbounty_tools.sh --verify"
    echo ""
    echo "WINDOWS NATIVE (no WSL):"
    echo "  powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1"
    echo ""
    echo "DEBIAN/KALI/UBUNTU:"
    echo "  sudo apt install nmap sqlmap ffuf gobuster nikto jq"
    echo ""
    echo "RHEL/CENTOS/FEDORA:"
    echo "  sudo dnf install nmap sqlmap jq    # or: sudo yum install nmap sqlmap jq"
    echo ""
    echo "ALPINE/ARCH/SUSE/macOS:"
    echo "  sudo apk add nmap sqlmap jq"
    echo "  sudo pacman -S nmap sqlmap jq"
    echo "  sudo zypper install nmap sqlmap jq"
    echo "  brew install nmap sqlmap jq"
    echo ""
    echo "GO TOOLS (all platforms):"
    echo "  go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest"
    echo "  go install github.com/projectdiscovery/httpx/cmd/httpx@latest"
    echo "  go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest"
    echo "  go install github.com/projectdiscovery/katana/cmd/katana@latest"
    echo "  go install github.com/projectdiscovery/dnsx/cmd/dnsx@latest"
    echo "  go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest"
    echo "  go install github.com/hahwul/dalfox/v2@latest"
    echo "  go install github.com/ffuf/ffuf/v2@latest"
    echo ""
    echo "WSL: only if wsl -l -v shows State: Running; otherwise install natively."
else
    echo "✅ All tools ready! You're fully equipped."
fi

2. TOOL STATUS MATRIX

Track tool status for your engagement:

## Tool Readiness — example.com Pentest

| Category | Tool | Status | Version | Notes |
|----------|------|--------|---------|-------|
| Recon | subfinder | ✅ Ready | v2.6.3 | |
| Recon | amass | ✅ Ready | v4.2.0 | |
| HTTP | httpx | ✅ Ready | v1.3.7 | |
| HTTP | curl | ✅ Ready | 8.4.0 | |
| Scanner | nuclei | ✅ Ready | v3.1.0 | Templates updated: 2026-01-15 |
| Scanner | nmap | ✅ Ready | 7.94 | |
| Fuzz | ffuf | ✅ Ready | v2.1.0 | |
| Exploit | sqlmap | ✅ Ready | v1.7.12 | |
| JS | katana | ❌ Missing | - | Need for JS crawling |
| Secret | trufflehog | ✅ Ready | v3.60.0 | |

### Missing Tools Impact
- **katana**: Use `gau` + `waybackurls` as alternative for JS crawling
- **dalfox**: Use manual XSS testing with curl

3. TOOL INSTALLATION

PREFERRED: built-in alphacode bugbounty (no shell script required)

This is the fastest and most reliable path. It resolves install commands per
platform, verifies the package manager it needs, reports exactly which tool
ended up on PATH, and handles the Go bin-directory problem that makes
go install look like it failed when it succeeded.

# What is present / missing, with the install command for each
alphacode bugbounty doctor

# JSON for scripting
alphacode bugbounty doctor --json

# What can be installed automatically
alphacode bugbounty list

# Preview without changing anything
alphacode bugbounty install subfinder httpx --dry-run

# Install the default pipeline
# (subfinder httpx dnsx katana gau waybackurls ffuf nuclei)
alphacode bugbounty install

# Install specific tools
alphacode bugbounty install subfinder httpx katana

# Verify an install landed
alphacode bugbounty doctor

Go is the one hard prerequisite. Most of the toolkit is Go-built. If it is
missing, the doctor says so explicitly — install it first:

# Windows
winget install GoLang.Go
# macOS
brew install go
# Debian/Ubuntu/Kali
sudo apt install golang-go

Then reopen your terminal so PATH picks up the new Go, and note that
go install writes to ~/go/bin (%USERPROFILE%\go\bin on Windows), which
is frequently not on PATH. The doctor and installer both check that directory
and print the exact export PATH=... line if it is missing.

Installation is always explicit. The agent never installs a binary on its
own initiative during an engagement — it reports the missing tool and the
command. Installing third-party binaries is an external-state change, and
silently doing it mid-scan is not something to do without a human saying yes.

The shell installers below remain valid and cover tools the built-in command
does not automate (nikto, dirb, dalfox, trufflehog, nuclei templates,
wordlists).

One-shot installer (bundled) — all OSes

# Detect platform + WSL policy
bash scripts/install_bugbounty_tools.sh --platform

# Full toolkit: Go tools + OS packages + pip + nuclei templates + wordlists
bash scripts/install_bugbounty_tools.sh all

# Preview only
bash scripts/install_bugbounty_tools.sh --dry-run all

# Single family (auto-detect uses `os`)
bash scripts/install_bugbounty_tools.sh go
bash scripts/install_bugbounty_tools.sh os
bash scripts/install_bugbounty_tools.sh pip
bash scripts/install_bugbounty_tools.sh nuclei
bash scripts/install_bugbounty_tools.sh wordlists

# After install
bash scripts/install_bugbounty_tools.sh --verify

os dispatches automatically:

Windows native PowerShell installer (no WSL):

powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1
powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1 -DryRun
powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1 -VerifyOnly

WSL: used only when status is ready (wsl.exe present + distro Running). Never required.

Script location (reference): scripts/install_bugbounty_tools.sh and scripts/install_bugbounty_tools.ps1 under the bugbounty skill.

Quick Install by OS

# ═══════════════════════════════════════════════════════════
# DEBIAN / KALI / UBUNTU
# ═══════════════════════════════════════════════════════════
apt update && apt install -y nmap sqlmap ffuf gobuster nikto jq

# ═══════════════════════════════════════════════════════════
# RHEL / CENTOS / ROCKY / ALMA / FEDORA
# ═══════════════════════════════════════════════════════════
sudo dnf install -y nmap sqlmap jq          # CentOS/RHEL 8+, Fedora
sudo yum install -y nmap sqlmap jq          # CentOS/RHEL 7, Amazon Linux
# ffuf/gobuster often missing from repos → install via Go (below)

# ═══════════════════════════════════════════════════════════
# ALPINE / ARCH / OPENSUSE
# ═══════════════════════════════════════════════════════════
sudo apk add nmap sqlmap jq
sudo pacman -S nmap sqlmap jq
sudo zypper install nmap sqlmap jq

# ═══════════════════════════════════════════════════════════
# macOS
# ═══════════════════════════════════════════════════════════
brew install nmap sqlmap jq

# ═══════════════════════════════════════════════════════════
# WINDOWS NATIVE (no WSL)
# ═══════════════════════════════════════════════════════════
winget install GoLang.Go
winget install Python.Python.3.12
winget install Insecure.Nmap
winget install Microsoft jq
# or: powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1

# ═══════════════════════════════════════════════════════════
# GO TOOLS (all platforms — preferred for ProjectDiscovery)
# ═══════════════════════════════════════════════════════════
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install github.com/projectdiscovery/katana/cmd/katana@latest
go install github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install github.com/hahwul/dalfox/v2@latest
go install github.com/ffuf/ffuf/v2@latest
go install github.com/OJ/gobuster/v3@latest
nuclei -update-templates

# ═══════════════════════════════════════════════════════════
# WSL (ONLY if installed AND Running)
# ═══════════════════════════════════════════════════════════
wsl -l -v    # must show State: Running
# then inside: use apt/dnf as appropriate for that distro

# ═══════════════════════════════════════════════════════════
# DOCKER (all platforms)
# ═══════════════════════════════════════════════════════════
docker pull projectdiscovery/subfinder:latest
docker pull projectdiscovery/httpx:latest
docker pull projectdiscovery/nuclei:latest
docker pull projectdiscovery/katana:latest
docker pull paoloo/sqlmap

4. TOOL ALTERNATIVES

When a tool is missing, use alternatives:

MISSING TOOL     → ALTERNATIVE
═══════════════════════════════════════════════════════════
subfinder        → amass, assetfinder, crt.sh + curl
httpx            → curl -s -o /dev/null -w "%{http_code}"
nuclei           → nikto, manual testing
ffuf             → gobuster, dirsearch, feroxbuster
sqlmap           → manual SQLi testing with curl
dalfox           → manual XSS testing with curl
katana           → gau + waybackurls + manual crawling
dnsx             → dig, nslookup
naabu            → nmap
nmap             → masscan (fast) + manual port check
trufflehog       → gitleaks
arjun            → manual parameter discovery
searchsploit     → exploit-db.com manual search

5. TOOL HEALTH CHECKS

# Check nuclei templates are up to date
nuclei -update-templates 2>&1 | tail -5

# Check nmap scripts
ls /usr/share/nmap/scripts/ | wc -l

# Check wordlists
ls /usr/share/wordlists/dirb/common.txt 2>/dev/null && echo "✅ wordlists ready" || echo "❌ wordlists missing"

# Check Go path
go version && echo "✅ Go installed" || echo "❌ Go not installed"

# Check Python (for sqlmap, etc.)
python3 --version && echo "✅ Python3 installed" || echo "❌ Python3 not installed"

# Check disk space for evidence collection
df -h . | tail -1 | awk '{print "Disk: " $4 " available"}'

6. QUICK COMMANDS

# Platform + WSL policy
bash scripts/install_bugbounty_tools.sh --platform

# Run tool doctor
/doctor

# Check specific tool
/doctor check nuclei

# Install missing tools (bundled installer — all OSes)
bash scripts/install_bugbounty_tools.sh all
bash scripts/install_bugbounty_tools.sh --verify

# Windows native (no WSL)
powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1
powershell -ExecutionPolicy Bypass -File scripts/install_bugbounty_tools.ps1 -VerifyOnly

# Show tool alternatives
/doctor alternatives sqlmap