diff --git a/WSL_SETUP.md b/WSL_SETUP.md new file mode 100644 index 000000000..2f436e24b --- /dev/null +++ b/WSL_SETUP.md @@ -0,0 +1,179 @@ +# HexStrike AI MCP Setup for WSL + +This guide covers setting up the HexStrike AI MCP client in **WSL2** to connect to a **HexStrike server running in a Kali Linux VM** on the same Windows machine. + +**Typical Setup:** You have Claude Code running in WSL on Windows, and HexStrike server running in a Kali VM (VMware/VirtualBox/Hyper-V) also on the same Windows machine. This guide bridges that connection. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Windows Host Machine │ +│ │ +│ ┌────────────────────────┐ │ +│ │ Kali Linux VM │ │ +│ │ (VMware/VBox/Hyper-V) │ │ +│ │ │ ┌──────────────────────────┐ │ +│ │ hexstrike_server │────►│ VM Port Forward to │ │ +│ │ listening on :8888 │ │ Windows 127.0.0.1:8888 │ │ +│ └────────────────────────┘ └──────────────────────────┘ │ +│ │ │ +│ │ netsh portproxy │ +│ ▼ │ +│ ┌──────────────────────────────┐ │ +│ │ WSL Gateway: 172.x.x.1:8888 │ │ +│ └──────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────────────────────┼───────────────┐ │ +│ │ WSL2 (Ubuntu/Debian) ▼ │ │ +│ │ ┌─────────────────────────────────────────────────────┐ │ │ +│ │ │ Claude Code CLI │ │ │ +│ │ │ └── hexstrike_mcp.py → http://172.x.x.1:8888 │ │ │ +│ │ └─────────────────────────────────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +**The Problem:** WSL2 can't reach `localhost` on Windows directly, and definitely can't reach your Kali VM. We solve this by port-forwarding through Windows as a bridge. + +## Prerequisites + +- WSL2 installed and running (Ubuntu, Debian, etc.) +- Claude Code CLI installed in WSL +- **Kali Linux VM** running with HexStrike server started +- VM port forwarding configured (VM's port 8888 → Windows 127.0.0.1:8888) +- Python 3.8+ in WSL + +## Quick Setup + +Run the setup script: + +```bash +cd /path/to/hexstrike-ai +./wsl-setup.sh +``` + +## Manual Setup + +### Step 1: Install Python Dependencies (WSL) + +```bash +# Install required packages to system Python +pip3 install requests fastmcp flask psutil beautifulsoup4 aiohttp +``` + +### Step 2: Get Windows Host IP from WSL + +WSL's `localhost` doesn't route to Windows. You need the Windows host IP: + +```bash +# Get the Windows host IP (usually the default gateway) +ip route show default | awk '{print $3}' +``` + +This typically returns something like `172.17.224.1` or `172.x.x.1`. + +### Step 3: Configure Windows Networking (PowerShell as Admin) + +Run these commands in PowerShell with Administrator privileges: + +```powershell +# Get the WSL gateway IP (run this first to find your specific IP) +wsl -e ip route show default + +# Add firewall rule to allow WSL traffic +New-NetFirewallRule -DisplayName "WSL to HexStrike" -Direction Inbound -LocalPort 8888 -Protocol TCP -Action Allow + +# Create port proxy from WSL interface to localhost +# Replace 172.17.224.1 with YOUR gateway IP from the command above +netsh interface portproxy add v4tov4 listenport=8888 listenaddress=172.17.224.1 connectport=8888 connectaddress=127.0.0.1 +``` + +To verify the port proxy: +```powershell +netsh interface portproxy show all +``` + +To remove later if needed: +```powershell +netsh interface portproxy delete v4tov4 listenport=8888 listenaddress=172.17.224.1 +``` + +### Step 4: Test Connectivity (WSL) + +```bash +# Replace with your Windows host IP +curl http://172.17.224.1:8888/health +``` + +You should see a JSON response with server status. + +### Step 5: Add MCP to Claude Code + +```bash +# Replace IP with your Windows host IP +claude mcp add hexstrike-ai -s user -- python3 /path/to/hexstrike-ai/hexstrike_mcp.py --server http://172.17.224.1:8888 +``` + +Or manually edit `~/.claude.json` and add to `mcpServers`: + +```json +{ + "mcpServers": { + "hexstrike-ai": { + "type": "stdio", + "command": "python3", + "args": [ + "/path/to/hexstrike-ai/hexstrike_mcp.py", + "--server", + "http://172.17.224.1:8888" + ], + "env": {} + } + } +} +``` + +### Step 6: Restart Claude Code + +Exit and restart Claude Code. Check `/mcp` to verify hexstrike-ai is connected. + +## Troubleshooting + +### Connection Refused (exit code 7) +- Windows Firewall is blocking the connection +- Run the firewall rule command in Step 3 + +### Connection Reset (exit code 56) +- Port proxy not configured +- Run the netsh portproxy command in Step 3 + +### Module Not Found Errors +- Missing Python dependencies +- Run `pip3 install requests fastmcp` in WSL + +### MCP Not Showing in Claude Code +- Config syntax error in ~/.claude.json +- Restart Claude Code after config changes + +### Finding Your WSL Gateway IP +The gateway IP can change after WSL restarts. To make it persistent, consider: + +1. **Check on each session:** + ```bash + ip route show default | awk '{print $3}' + ``` + +2. **Or use mirrored networking (WSL 2.0+):** + Add to `%USERPROFILE%\.wslconfig`: + ```ini + [wsl2] + networkingMode=mirrored + ``` + Then `wsl --shutdown` and restart. With mirrored mode, `localhost` works directly. + +## Verification + +Once set up, you should see hexstrike-ai tools available in Claude Code: +- Run `/mcp` to see server status +- Tools will be prefixed with `mcp__hexstrike-ai__` diff --git a/wsl-setup.sh b/wsl-setup.sh new file mode 100755 index 000000000..4202172a9 --- /dev/null +++ b/wsl-setup.sh @@ -0,0 +1,143 @@ +#!/bin/bash +# HexStrike AI MCP Setup Script for WSL +# Configures Claude Code in WSL to connect to HexStrike server running in a Kali VM +# See WSL_SETUP.md for full documentation + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +MCP_SCRIPT="$SCRIPT_DIR/hexstrike_mcp.py" + +echo "==========================================" +echo " HexStrike AI MCP - WSL Setup Script" +echo "==========================================" +echo "" + +# Step 1: Check if MCP script exists +if [[ ! -f "$MCP_SCRIPT" ]]; then + echo "ERROR: hexstrike_mcp.py not found at $MCP_SCRIPT" + exit 1 +fi +echo "[OK] Found hexstrike_mcp.py" + +# Step 2: Install Python dependencies +echo "" +echo "[*] Installing Python dependencies..." +pip3 install --quiet requests fastmcp flask psutil beautifulsoup4 aiohttp 2>/dev/null || { + echo "[!] pip3 install failed, trying with --user flag..." + pip3 install --user requests fastmcp flask psutil beautifulsoup4 aiohttp +} +echo "[OK] Python dependencies installed" + +# Step 3: Test imports +echo "" +echo "[*] Testing Python imports..." +python3 -c "import requests; from mcp.server.fastmcp import FastMCP; print('[OK] All imports successful')" || { + echo "ERROR: Python imports failed. Check installation." + exit 1 +} + +# Step 4: Detect Windows host IP +echo "" +echo "[*] Detecting Windows host IP..." +WINDOWS_HOST_IP=$(ip route show default | awk '{print $3}') + +if [[ -z "$WINDOWS_HOST_IP" ]]; then + echo "ERROR: Could not detect Windows host IP" + exit 1 +fi +echo "[OK] Windows host IP: $WINDOWS_HOST_IP" + +# Step 5: Test connectivity +echo "" +echo "[*] Testing connection to HexStrike server at $WINDOWS_HOST_IP:8888..." +if curl -s --connect-timeout 5 "http://$WINDOWS_HOST_IP:8888/health" > /dev/null 2>&1; then + echo "[OK] HexStrike server is reachable!" +else + echo "" + echo "==========================================" + echo " WINDOWS CONFIGURATION REQUIRED" + echo "==========================================" + echo "" + echo "The HexStrike server is not reachable from WSL." + echo "Run these commands in PowerShell (as Administrator):" + echo "" + echo " # Add firewall rule" + echo " New-NetFirewallRule -DisplayName 'WSL to HexStrike' -Direction Inbound -LocalPort 8888 -Protocol TCP -Action Allow" + echo "" + echo " # Create port proxy" + echo " netsh interface portproxy add v4tov4 listenport=8888 listenaddress=$WINDOWS_HOST_IP connectport=8888 connectaddress=127.0.0.1" + echo "" + echo "After running those commands, re-run this script." + echo "" + + read -p "Press Enter to continue anyway, or Ctrl+C to exit..." +fi + +# Step 6: Configure Claude Code MCP +echo "" +echo "[*] Configuring Claude Code MCP..." + +CLAUDE_CONFIG="$HOME/.claude.json" + +if [[ ! -f "$CLAUDE_CONFIG" ]]; then + echo "ERROR: Claude Code config not found at $CLAUDE_CONFIG" + echo "Make sure Claude Code is installed and has been run at least once." + exit 1 +fi + +# Check if hexstrike-ai already configured +if grep -q "hexstrike-ai" "$CLAUDE_CONFIG" 2>/dev/null; then + echo "[!] hexstrike-ai already exists in config" + echo "[*] Updating server URL to use $WINDOWS_HOST_IP..." + + # Use sed to update the URL (handles both localhost and any IP) + sed -i "s|http://[^\"]*:8888|http://$WINDOWS_HOST_IP:8888|g" "$CLAUDE_CONFIG" + echo "[OK] Updated MCP config" +else + echo "[*] Adding hexstrike-ai to Claude Code..." + + # Use claude mcp add command + claude mcp add hexstrike-ai -s user -- python3 "$MCP_SCRIPT" --server "http://$WINDOWS_HOST_IP:8888" 2>/dev/null || { + echo "[!] Could not use 'claude mcp add' command" + echo "" + echo "Please manually add to ~/.claude.json mcpServers:" + echo "" + echo ' "hexstrike-ai": {' + echo ' "type": "stdio",' + echo ' "command": "python3",' + echo ' "args": [' + echo " \"$MCP_SCRIPT\"," + echo ' "--server",' + echo " \"http://$WINDOWS_HOST_IP:8888\"" + echo ' ],' + echo ' "env": {}' + echo ' }' + echo "" + } +fi + +# Step 7: Final verification +echo "" +echo "==========================================" +echo " Setup Complete!" +echo "==========================================" +echo "" +echo "Configuration:" +echo " - MCP Script: $MCP_SCRIPT" +echo " - Server URL: http://$WINDOWS_HOST_IP:8888" +echo "" +echo "Next steps:" +echo " 1. Restart Claude Code" +echo " 2. Run /mcp to verify hexstrike-ai is connected" +echo " 3. HexStrike tools will be available as mcp__hexstrike-ai__*" +echo "" + +# Optional: Test the MCP script directly +read -p "Test MCP script now? (y/N) " -n 1 -r +echo +if [[ $REPLY =~ ^[Yy]$ ]]; then + echo "" + echo "[*] Testing MCP script (Ctrl+C to stop)..." + python3 "$MCP_SCRIPT" --server "http://$WINDOWS_HOST_IP:8888" --help +fi