PwnBridge

<div align="center">

⚠️ 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:

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:

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>