Pwnbridge— agent skill

<div align="center">

PwnBridge

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

Tools

Reconnaissance & Scanning

Web Application Testing

Exploitation & Auth Testing

Security Analysis

Utility

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:

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

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

Tool Requirements on Kali

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>