vluggy-lite by Osama-Null - MCP Server

Vluggy Lite - CTF-Focused AI Hacking Assistant

A lightweight MCP server that turns Claude Desktop into a CTF-solving machine with:

🧠 CTF Brain: Pattern matching, primitive detection, and solving strategies
🔧 25+ Security Tools: nmap, sqlmap, feroxbuster, hydra, john, hashcat, and more
📚 Knowledge Base: Deep-crawled CTF writeups, HackTricks, PayloadsAllTheThings
🔐 Crypto Decoder: Base64, hex, ROT13, Caesar cipher brute-forcing

Architecture

Claude Desktop
     │
     ▼
┌─────────────┐     ┌─────────────┐
│  mcp-shim   │────▶│  mcp-http   │──┬──▶ kali-mcp (tools)
│  (Python)   │     │  (FastAPI)  │  ├──▶ planner-api
└─────────────┘     └─────────────┘  ├──▶ dcipher
                                     └──▶ CTF Brain
                                          │
                                     ┌────┴────┐
                                     │ Supabase │ (Knowledge Base)
                                     └─────────┘

Quick Start

Prerequisites

Docker Desktop
Python 3.10+
Claude Desktop
(Optional) Supabase account for knowledge base

Installation

Windows:

powershell -ExecutionPolicy Bypass -File setup.ps1

Linux/Mac:

chmod +x setup.sh && ./setup.sh

Start Services

docker-compose up --build -d

Configure Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "vluggy-lite-mcp": {
      "command": "C:\\Users\\YOUR_USER\\vluggy-lite\\mcp-shim\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YOUR_USER\\vluggy-lite\\mcp-shim\\server.py"],
      "env": {
        "VLUGGY_HTTP_URL": "http://localhost:5001",
        "PLANNER_URL": "http://localhost:5101",
        "VLUGGY_API_KEY": "your-api-key-here",
        "VLUGGY_VOLUME_DIR": "C:\\Users\\YOUR_USER\\vluggy-lite\\volumes\\files"
      }
    }
  }
}

MCP Tools

Security Tools

Tool	Description	Example
`exec_tool`	Run any Kali tool	`exec_tool("nmap", "-sV 10.10.10.1")`
`plan_exec`	Auto-plan based on target type	`plan_exec("web", "http://target.com")`
`dcipher`	Decode/encode crypto	`dcipher("brute", "caesar", "Uryyb")`
`tools`	List available tools	`tools()`

CTF Brain Tools

Tool	Description	Example
`ctf_analyze`	Analyze challenge, get strategy	`ctf_analyze("Login form gives MySQL error")`
`ctf_search`	Search knowledge base	`ctf_search("PHP deserialization")`
`ctf_template`	Get exploit code template	`ctf_template("pwn", "buffer_overflow")`

CTF Brain

The CTF Brain embodies the CTF Mindset:

Everything is intentional - If something looks strange, it's a clue
Look for the smallest crack - Find the single weakness
Think like a puzzle solver - Logic beats brute force
Reduce to known primitives - Map to known exploit patterns

Example Usage

User: "The website has a login form. When I enter a single quote, I get a MySQL error."

Claude (via ctf_analyze):
- Category: web (confidence: 0.85)
- Primitives: ["sqli"]
- Tools: ["sqlmap", "burpsuite"]
- Kill chain: ["reconnaissance", "identify_vulnerability", "craft_payload", ...]
- Hints: 
  - "Try ' OR '1'='1' -- "
  - "Check for error messages revealing DB structure"
- Attack vectors:
  - "Run sqlmap with --dbs to enumerate databases"

Knowledge Base Setup (Optional)

To enable semantic search over CTF writeups:

1. Create Supabase Project

Go to supabase.com and create a project
Get your Project URL and anon key

2. Run Schema

In Supabase SQL Editor, run the contents of:

ingestor/app/supabase_schema.sql

3. Configure Environment

Create .env:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
VLUGGY_API_KEY=your-random-api-key
GITHUB_TOKEN=your-github-token  # Optional, for higher API limits

4. Run Ingestor

# Ingest all sources (takes time)
docker-compose --profile ingest up vluggy-lite-ingestor

# Or ingest specific sources
docker-compose run vluggy-lite-ingestor python ingest.py --source gtfobins
docker-compose run vluggy-lite-ingestor python ingest.py --ctftime --max-pages 50
docker-compose run vluggy-lite-ingestor python ingest.py --github swisskyrepo/PayloadsAllTheThings

Available Security Tools

Category	Tools
Scanning	nmap, masscan, whatweb, nikto
Fuzzing	gobuster, ffuf, feroxbuster, dirsearch, wfuzz
Exploitation	sqlmap, hydra, crackmapexec
Password	john, hashcat, hashid
Network	tshark, tcpdump, curl, wget
Crypto	base64, hex, rot13, caesar (via dcipher)

Ports

Service	Port
HTTP Gateway	5001
Planner API	5101
Dcipher	5601
Kali Container	8766

Troubleshooting

Services not starting?

docker-compose logs -f

Claude can't connect?

Ensure Docker services are running: docker ps
Check mcp-shim venv: mcp-shim/.venv/Scripts/pip list
Verify config paths in claude_desktop_config.json

CTF Brain not working?

Check if ingestor/app modules exist
Verify Supabase credentials if using search

Development

# Rebuild specific service
docker-compose build vluggy-lite-http

# View logs
docker-compose logs -f vluggy-lite-http

# Test CTF Brain locally
cd ingestor/app
python ingest.py --test

License

MIT