<div align="center">

![PwnBridge](./assets/banner.svg)

![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)
![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.x-blueviolet)
![Node.js](https://img.shields.io/badge/Node.js-22.x-339933?logo=node.js&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-active-brightgreen)

> **⚠️ 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)](https://modelcontextprotocol.io) 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

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

### 2. Configure

```bash
cp .env.example .env
```

Edit `.env` — minimum required:

```bash
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

```bash
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):

```json
{
  "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):

```bash
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`:

```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:

```json
{"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

```bash
# 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](LICENSE) for details.

---

<div align="center">

*Built for authorized security professionals. Assess responsibly.*

</div>