PwnBridge

<div align="center">

!PwnBridge

!TypeScript !MCP SDK !Node.js !License !Status

⚠️ AUTHORIZED USE ONLY — Only test systems you own or have explicit written permission to test. Unauthorized access to computer systems is illegal.

</div>

---

What is PwnBridge?

PwnBridge is a Model Context Protocol (MCP) server that bridges AI assistants to a Kali Linux machine over SSH. Ask Claude, ChatGPT, or Gemini to run a port scan, test for SQL injection, or perform a full SAST/DAST security assessment — the AI translates intent into commands, executes them on your Kali box, streams back results, and keeps a full audit trail.

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│   Claude Desktop ──── stdio ────┐                                       │
│                                 │                                       │
│   ChatGPT ──────── HTTP/SSE ───►│  PwnBridge ──── SSH ────► Kali Linux │
│                                 │  (11 tools)                           │
│   Gemini CLI ───── HTTP/SSE ───►│                                       │
│                                 │                                       │
└─────────────────────────────────────────────────────────────────────────┘

Dual Transport

| Transport | Clients | Protocol | |-----------|---------|----------| | stdio | Claude Desktop | MCP native (spawned process) | | HTTP / SSE | ChatGPT, Gemini CLI, any MCP client | Streamable HTTP + legacy SSE |

---

Tools

Reconnaissance & Scanning

| Tool | Description | |------|-------------| | nmap_scan | Port scanning — quick, service, OS, full, stealth, UDP profiles | | nikto_scan | Web server vulnerability and misconfiguration detection | | whatweb_fingerprint | CMS, framework, and technology fingerprinting |

Web Application Testing

| Tool | Description | |------|-------------| | sqlmap_scan | SQL injection detection and exploitation | | gobuster_scan | Directory, file, subdomain, and vhost enumeration | | ffuf_fuzz | Web fuzzing with FUZZ keyword — params, paths, headers |

Exploitation & Auth Testing

| Tool | Description | |------|-------------| | hydra_attack | Password brute-force — SSH, FTP, HTTP, SMB, RDP, and more | | metasploit_exec | Non-interactive Metasploit module execution |

Security Analysis

| Tool | Description | |------|-------------| | sast_scan | Static analysis — Semgrep + Bandit + Gitleaks + Graudit in parallel, versioned reports | | dast_scan | Dynamic analysis — OWASP ZAP + Nuclei, 5 auth modes, versioned reports |

Utility

| Tool | Description | |------|-------------| | shell_exec | Raw shell command passthrough (escape hatch for advanced scenarios) |

---

Quick Start

Prerequisites

• Kali Linux machine accessible over SSH (VM, VPS, or bare metal)
• Node.js 22+ on your local machine

1. Clone & Install

git clone https://github.com/1mr0-tech/simple-kali-mcp.git pwnbridge
cd pwnbridge
npm install

2. Configure

cp .env.example .env

Edit .env — minimum required:

SSH_HOST=192.168.1.100     # Your Kali machine IP
SSH_USER=kali
SSH_PRIVATE_KEY_PATH=~/.ssh/id_rsa   # Recommended over password

3. Build

npm run build

4. Connect Your AI Assistant

---

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pwnbridge": {
      "command": "node",
      "args": ["/absolute/path/to/pwnbridge/dist/index.js", "--stdio"]
    }
  }
}

Restart Claude Desktop. All 11 tools appear automatically.

---

ChatGPT

Option A — MCP Connector (ChatGPT Plus / Team / Enterprise):

node dist/index.js --http    # starts on port 3000

In ChatGPT → Settings → Connected Apps → Add MCP Server → http://your-server:3000/mcp

Option B — Custom GPT Actions (legacy):

Import the auto-generated schema: http://your-server:3000/openapi.yaml

---

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "pwnbridge": {
      "httpUrl": "http://your-server:3000/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

---

SAST Scanning

Run static analysis on a local codebase. Code is synced to Kali via SFTP, scanned in parallel, then deleted — only the report is kept.

AI: "Run a SAST scan on /Users/me/projects/backend, project name backend-api"

What runs on Kali:

┌─────────────────────────────────────────────────────────────────┐
│  SFTP Upload (8 concurrent streams)                             │
│  /Users/me/projects/backend  →  /tmp/kali-sast-abc123/src/     │
└───────────────────────┬─────────────────────────────────────────┘
                        │ parallel
        ┌───────────────┼───────────────┬──────────────┐
        ▼               ▼               ▼              ▼
   Semgrep          Bandit          Gitleaks        Graudit
 (multi-lang)     (Python*)       (secrets)      (lang-aware)
        │               │               │              │
        └───────────────┴───────────────┴──────────────┘
                        │ consolidated report
                        ▼
   ~/kali-mcp-reports/sast/backend-api/v002_20240120_091500_sast_all.md

Bandit is automatically skipped if no .py files are found. Graudit uses language auto-detection to target the right rule databases (e.g. python,js,code).

Report Naming

~/kali-mcp-reports/
  sast/
    {project}/
      v001_20240115_103000_sast_all.md
      v002_20240120_091500_sast_semgrep+bandit.md
      v003_20240125_140000_sast_all.md

---

DAST Scanning

Run dynamic analysis against a live web application.

AI: "Run a full authenticated DAST scan on http://192.168.1.50, form login at /login"

Authentication modes:

| auth_type | How it works | |-------------|--------------| | none | Standard unauthenticated crawl | | basic | Injects Authorization: Basic <b64> via ZAP Replacer | | bearer | Injects Authorization: Bearer <token> via ZAP Replacer | | cookie | Injects Cookie: <value> via ZAP Replacer | | form | Generates ZAP Automation Framework YAML — full login flow |

What runs on Kali (parallel):

  ZAP (spider → passive scan → active scan)
     +
  Nuclei (CVE + template detection)
     │
     ▼
  ~/kali-mcp-reports/dast/192.168.1.50/v001_20240115_103000_dast_full_form-auth.md

Report Naming

~/kali-mcp-reports/
  dast/
    {host}/
      v001_20240115_103000_dast_baseline_unauth.md
      v002_20240116_090000_dast_full_form-auth.md
      v003_20240118_143000_dast_full_bearer-auth.md

---

Configuration Reference

| Variable | Default | Description | |----------|---------|-------------| | SSH_HOST | — | Required. Kali machine IP or hostname | | SSH_PORT | 22 | SSH port | | SSH_USER | — | Required. SSH username | | SSH_PASSWORD | — | SSH password (prefer key auth) | | SSH_PRIVATE_KEY_PATH | — | Path to private key — ~ is expanded | | SSH_PASSPHRASE | — | Passphrase for encrypted private key | | HTTP_PORT | 3000 | HTTP server port | | HTTP_HOST | 0.0.0.0 | HTTP bind address | | HTTP_API_KEY | — | API key to protect the HTTP endpoint | | DEFAULT_TIMEOUT_MS | 300000 | Default command timeout (5 min) | | NMAP_TIMEOUT_MS | 600000 | nmap timeout (10 min) | | SQLMAP_TIMEOUT_MS | 900000 | sqlmap timeout (15 min) | | SAST_TIMEOUT_MS | 900000 | SAST scan timeout (15 min) | | DAST_TIMEOUT_MS | 1800000 | DAST scan timeout (30 min) | | AUDIT_LOG_PATH | ./logs/audit.log | Local audit log file | | KALI_REPORT_DIR | ~/kali-mcp-reports | Report directory on Kali |

---

Audit Logging

Every command is logged with a full timestamp:

{"timestamp":"2024-01-15 10:30:00","level":"info","message":"COMMAND_EXECUTED",
 "tool":"nmap_scan","command":"nmap -T4 -F 192.168.1.1","target":"192.168.1.1"}

Log: ./logs/audit.log — rotates at 50MB, keeps 5 files.

---

Server Commands

# HTTP mode — ChatGPT / Gemini
npm run start:http

# stdio mode — Claude Desktop (usually auto-launched)
npm run start:stdio

# Health check
curl http://localhost:3000/health

---

Security Considerations

| Concern | Mitigation | |---------|------------| | Unauthorized access | Set HTTP_API_KEY before exposing port 3000 | | Credential theft | Use SSH key auth over password | | Command injection | Tool schemas use enums and typed params — only shell_exec accepts raw strings | | Audit trail | All commands logged with timestamp, tool, target, and full command string | | Source code exposure | SAST uploads code temporarily — deleted immediately after scan | | Network exposure | Restrict port 3000 at firewall level; bind to 127.0.0.1 for local-only use |

---

Tool Requirements on Kali

| Tool | Install | |------|---------| | nmap | Pre-installed | | nikto | apt install nikto | | sqlmap | Pre-installed | | gobuster | apt install gobuster | | ffuf | apt install ffuf | | whatweb | Pre-installed | | hydra | Pre-installed | | metasploit | Pre-installed | | semgrep | pip install semgrep | | bandit | pip install bandit | | gitleaks | apt install gitleaks | | graudit | apt install graudit | | zaproxy | apt install zaproxy | | nuclei | apt install nuclei |

---

Troubleshooting

SSH connection fails: ``bash ssh -i ~/.ssh/id_rsa kali@<host> ``

Tool not appearing in Claude Desktop:

• Verify absolute path in claude_desktop_config.json
• Restart Claude Desktop after config changes
• Check logs: ~/Library/Logs/Claude/ (macOS)

ZAP / Nuclei / Semgrep not found: ``bash apt install zaproxy nuclei gitleaks graudit pip install semgrep bandit ``

---

License

MIT — see LICENSE for details.

---

<div align="center">

Built for authorized security professionals. Assess responsibly.

</div>