Skip to content

docs: Add WSL setup guide and automation script for Claude Code #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeffaf wants to merge 1 commit into
base: master
Choose a base branch
from
+322 −0
Open

docs: Add WSL setup guide and automation script for Claude Code #121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 179 additions & 0 deletions WSL_SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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__`
143 changes: 143 additions & 0 deletions wsl-setup.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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