honey_badger_mcp

world 1st black hat hacker mcp that think studies plans and select optimal attack vector and move forward

<p align="center"> <pre> ╔══════════════════════════════════════════════════════════╗ ║ ║ ║ ██╗ ██╗ ██████╗ ███╗ ██╗███████╗██╗ ██╗ ║ ║ ██║ ██║██╔═══██╗████╗ ██║██╔════╝╚██╗ ██╔╝ ║ ║ ███████║██║ ██║██╔██╗ ██║█████╗ ╚████╔╝ ║ ║ ██╔══██║██║ ██║██║╚██╗██║██╔══╝ ╚██╔╝ ║ ║ ██║ ██║╚██████╔╝██║ ╚████║███████╗ ██║ ║ ║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝ ╚═╝ ║ ║ ║ ║ ██████╗ █████╗ ██████╗ ██████╗ ███████╗██████╗ ║ ║ ██╔══██╗██╔══██╗██╔══██╗██╔════╝ ██╔════╝██╔══██╗ ║ ║ ██████╔╝███████║██║ ██║██║ ███╗█████╗ ██████╔╝ ║ ║ ██╔══██╗██╔══██║██║ ██║██║ ██║██╔══╝ ██╔══██╗ ║ ║ ██████╔╝██║ ██║██████╔╝╚██████╔╝███████╗██║ ██║ ║ ║ ╚═════╝ ╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝ ║ ║ ║ ║ HONEY_BADGER_MCP v3.1 — WARFARE ENGINE ║ ║ "Honey Badger don't care. Honey Badger PWNS." ║ ╚══════════════════════════════════════════════════════════╝ </pre> </p> <div align="center"> <img src="banner.svg" alt="Honey Badger Architecture Outline Banner"> </div> <p align="center"> <br/> <strong>Elite offensive security MCP server: 15-tool parallel warfare, real-time target learning, adaptive attack intelligence, and AI-driven exploit chain automation.</strong> </p>

What Makes v3.0 Different
Features
Architecture Flow
Complete MCP Tool Reference (28 Tools)
Quick Start & Setup
AI IDE Setup Guide
Project Structure
Real-Time Learning Engine
Framework Comparison
Configuration
Security Considerations
Troubleshooting
License

What Makes v3.1 Different

Capability	v3.0	v3.1
Parallel Output	Waits for slowest	Streaming results as each tool finishes (`parallel_stream`)
Auto-routing	Manual decision	`smart_parallel` auto-selects strategy by tool speed
File I/O	Fragile `cat EOF` shell	Native API: 12 ops unified into `file_manager`
Command Length	4,096 bytes cap	Large payload support (32,768+ bytes)
Server Visuals	Basic standard output	Premium UI: Grid tables, inline findings, color pills
Data Extraction	Manual regex by AI	Auto port/URL findings extracted per streaming tool

Features

⚡ Streaming Parallel Warfare Engine — Launch up to 50 concurrent commands. With smart_parallel and SSE endpoints, receive test results the moment each tool finishes — you no longer wait 60 seconds just because one tool is slow.
📁 Unified Native File Management — Safely read, write, update, delete, and copy exploit files without touching a shell container. 12 file operations consolidated perfectly into one MCP file_manager tool to optimize LLM performance limit load.
🧬 Real-Time Target Learning — After every scan wave, the engine analyzes findings, builds a structured target profile (OS, web server, CMS, database, frameworks), maps detected versions to known CVEs, identifies knowledge gaps, and recommends the optimal next 10-15 tools.
🧠 Deep Decision Engine — CVE-aware attack recommendations with priority-weighted scoring. Maps 25+ services to specific attack tool chains. Flags critical vulnerabilities instantly.
🕸️ Smart Conditional Graphs — Model complex multi-stage attack workflows as conditional directed acyclic graphs. Tools only run when their conditions are met (port open, string found, previous success).
🗄️ Persistent Findings Memory — Thread-safe SQLite storage for ports, URLs, IPs, vulnerabilities, and execution audit logs. Deduplication prevents redundant entries.
📊 Premium Battle Dashboard (CLI) — High-fidelity CLI interface displaying executing pipelines in beautiful progress bars, inline open ports alongside running status pills, discovering schemas through organized column-grid UI, and clean dashboard endpoints.

Architecture Flow

How Honey Badger Works

<pre> [ AI Client ] (Antigravity / Cursor / Windsurf / Claude Desktop) │ │ (JSON-RPC over Stdio) ▼ ╔════════════════════════════════════════════════════════╗ ║ HONEY BADGER MCP v3.1 WARFARE ENGINE ║ ║ ║ ║ ┌──────────────────────────────────────────────┐ ║ ║ │ client.py — MCP Protocol Bridge │ ║ ║ │ • 28 FastMCP tools │ ║ ║ │ • Opt-in MCP File I/O Management │ ║ ║ │ • HTTP adapter to server │ ║ ║ └────────────────────┬─────────────────────────┘ ║ ║ │ HTTP (localhost or network) ║ ║ ┌────────────────────▼─────────────────────────┐ ║ ║ │ server.py — Execution Engine │ ║ ║ │ • Parallel warfare (15-50 threads) │ ║ ║ │ • Target intelligence analyzer │ ║ ║ │ • CVE detection (18+ patterns) │ ║ ║ │ • Smart conditional graphs │ ║ ║ │ • Workflow engine │ ║ ║ │ • SQLite persistent memory │ ║ ║ │ • Tool auto-discovery (35+) │ ║ ║ └────────────────────┬─────────────────────────┘ ║ ╚═══════════════════════│════════════════════════════════╝ │ (Spawns 15+ parallel processes) │ ┌────────┬───────┴───────┬────────┐ ▼ ▼ ▼ ▼ ┌────────┐┌────────┐ ┌────────┐┌────────┐ │ nmap ││ nikto │ │gobuster││ hydra │ │ scan ││ scan │ │ scan ││ attack │ └───┬────┘└───┬────┘ └───┬────┘└───┬────┘ └────┐ │ ┌───────┘ ┌────┘ ▼ ▼ ▼ ▼ 🎯 TARGET ATTACK SURFACE 🎯 </pre>

Complete MCP Tool Reference (28 Tools)

🔧 Security Tool Wrappers (10 tools)

Tool	Function	Description
`nmap_scan`	Port/service scanning	Target, scan_type, ports, additional_args
`gobuster_scan`	Directory/DNS bruteforce	URL, mode (dir/dns/fuzz/vhost), wordlist
`dirb_scan`	Directory bruteforce	URL, wordlist, additional_args
`nikto_scan`	Web vulnerability scanner	Target, additional_args
`sqlmap_scan`	SQL injection testing	URL, data, additional_args
`metasploit_run`	Metasploit module execution	Module path, options dict
`hydra_attack`	Credential brute force	Target, service, username/file, password/file
`john_crack`	Password hash cracking	Hash file, wordlist, format
`wpscan_analyze`	WordPress scanner	URL, additional_args
`enum4linux_scan`	SMB/NetBIOS enumeration	Target, additional_args

⚡ Parallel Execution Engine

Tool	Function	Description
`smart_parallel`	Auto-Routing Parallel Execution	Intelligently delegates list of commands based on tool length
`parallel_stream`	Streaming Fast Returns	Waitless synchronous streaming, fastest tools output returned instantly
`parallel_execute`	Synchronous block	Runs everything, waits for slowest
`parallel_execute_async`	Fire-and-forget background	Commands list, timeout. Returns job_id
`parallel_watch`	Live push feed SSE	Consume instant results as they land in real-time server streams

🧠 Intelligence & Planning (4 tools)

Tool	Function	Description
`analyze_and_plan`	Real-time target analysis	Target profile, CVE detection, next 15 tools
`get_next_steps`	Decision engine suggestions	Priority-scored attack recommendations
`get_findings`	Query findings database	Filter by type, limit
`add_finding`	Store manual finding	Type, value, source

🕸️ Orchestration Engine (4 tools)

Tool	Function	Description
`smart_graph_execute`	Conditional task graph	Nodes with port_open/stdout_contains conditions
`execute_task_graph`	DAG task execution	Dependency-aware parallel execution
`execute_command`	Raw shell command	⚠️ Requires user confirmation
`discover_tools`	System tool scanner	Finds 35+ security tools on PATH

📋 Workflow Engine (4 tools)

Tool	Function	Description
`run_workflow`	Execute attack recipe	recon / web / smb / full + custom
`get_workflow`	Preview workflow steps	See before executing
`list_workflows`	Available workflows	Built-in + custom listing
`list_workflow_runs`	Execution history	Recent runs with status

📊 Operations

Tool	Function	Description
`dashboard`	Live battle overview	Running jobs, findings, recent commands
`server_health`	Server status check	Tool availability, DB status, version
`get_workflow_run`	Past run details	Full results of a workflow execution
`get_command_log`	Audit trail	Command history with stdout/stderr

📁 Unified File I/O

Tool	Function	Description
`file_manager`	Native Python File Ops	Supports: `write`, `read`, `update`, `delete`, `move`, `copy`, `list`, `info`, `mkdir`, `chmod`, `grep`, `find`. Replaces previous shell scripts format limit and fragilities.

Quick Start & Setup

Prerequisites

Python 3.10+
Kali Linux (or any Linux with security tools installed)
Dependencies: pip install flask mcp requests

Step 1: Clone & Install

git clone https://github.com/kishwordulal1234/honey-badger-mcp.git
cd honey-badger-mcp
pip install flask mcp requests

Step 2: Start the Server (on Kali VM or target machine)

# Local only
python3 server.py --port 5253

# Network accessible (for remote AI IDE connection)
python3 server.py --port 5253 --ip 0.0.0.0

Step 3: Configure Your AI IDE (see next section)

AI IDE Setup Guide

Honey Badger MCP works with any AI IDE that supports the Model Context Protocol. Below are setup instructions ranked by recommendation.

🥇 #1 Recommended: Antigravity (Google DeepMind)

The best experience — native MCP support with deep tool integration.

Config file: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "honey_badger_mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/honey_badger_mcp/client.py",
        "--server",
        "http://KALI_IP:5253"
      ],
      "description": "Honey Badger MCP v3.1 — Elite Offensive Security Warfare Engine",
      "timeout": 300,
      "alwaysAllow": []
    }
  }
}

Example with actual paths:

{
  "mcpServers": {
    "honey_badger_mcp": {
      "command": "python3",
      "args": [
        "/home/unknonehartr/Desktop/honey_badger_mcp/client.py",
        "--server",
        "http://192.168.1.8:5253"
      ],
      "description": "Honey Badger MCP v3.1 — Elite Offensive Security Warfare Engine",
      "timeout": 300,
      "alwaysAllow": []
    }
  }
}

Why #1: Antigravity has the deepest MCP integration, handles 28 tools seamlessly, and supports the parallel execution patterns Honey Badger relies on. The timeout configuration ensures long-running scans (nikto, sqlmap) don't get killed prematurely.

🥈 #2 Recommended: Codeium (Windsurf)

Excellent MCP support with Cascade agent mode.

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "honey_badger_mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/honey_badger_mcp/client.py",
        "--server",
        "http://KALI_IP:5253"
      ]
    }
  }
}

Why #2: Windsurf's Cascade mode handles multi-step tool chains well, making it great for the adaptive learning loop (scan → analyze → plan → execute).

🥉 #3 Recommended: Cursor

Strong MCP support with agentic capabilities.

Config file: .cursor/mcp.json (in your project root)

{
  "mcpServers": {
    "honey_badger_mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/honey_badger_mcp/client.py",
        "--server",
        "http://KALI_IP:5253"
      ]
    }
  }
}

Note: Cursor uses project-level MCP config. Create .cursor/mcp.json in whichever project directory you're working from.

#4: Claude Desktop (Anthropic)

Works well for interactive security analysis.

Config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "honey_badger_mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/honey_badger_mcp/client.py",
        "--server",
        "http://KALI_IP:5253"
      ]
    }
  }
}

⚙️ Setup Checklist (All IDEs)

✅ Server running on Kali: python3 server.py --port 5253 --ip 0.0.0.0
✅ Health check passes: curl http://KALI_IP:5253/health
✅ Absolute paths in config — NO relative paths
✅ Python3 accessible from your IDE's environment
✅ Dependencies installed: pip install flask mcp requests
✅ Network accessible — Kali VM IP reachable from your desktop
✅ Restart your IDE after adding/changing MCP config

🔌 Connection Architecture

<pre> ┌──────────────────────────────────────────┐ │ YOUR DESKTOP (Windows/macOS/Linux) │ │ │ │ ┌────────────────────────────────────┐ │ │ │ AI IDE (Antigravity/Cursor/etc.) │ │ │ │ ↕ Stdio pipe │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ client.py (MCP Bridge) │ │ │ │ │ │ 28 tools via FastMCP │ │ │ │ │ └──────────┬───────────────────┘ │ │ │ └─────────────│──────────────────────┘ │ └────────────────│─────────────────────────┘ │ HTTP (http://192.168.x.x:5253) ┌────────────────│─────────────────────────┐ │ KALI LINUX VM │ │ │ ┌─────────────▼───────────────────────┐ │ │ │ server.py (Execution Engine) │ │ │ │ Port 5253 — Flask threaded │ │ │ │ • 50 parallel execution threads │ │ │ │ • SQLite persistent memory │ │ │ │ • 35+ auto-discovered tools │ │ │ └─────────────┬───────────────────────┘ │ │ │ │ │ ┌────────┼────────┐ │ │ ▼ ▼ ▼ │ │ [nmap] [nikto] [sqlmap] ... │ │ ↕ Target │ └──────────────────────────────────────────┘ </pre>

Project Structure

honey_badger_mcp/
│
├── server.py                 # 🏗️ Flask API Execution Engine
│                             #    ├── Parallel Warfare Engine (50 concurrent threads)
│                             #    ├── Smart Conditional Graph Executor
│                             #    ├── Workflow Engine (recon/web/smb/full)
│                             #    ├── Target Intelligence Analyzer (OS/CMS/DB/CVE)
│                             #    ├── Deep Decision Engine (25+ service→attack maps)
│                             #    ├── SQLite Persistent Memory Store
│                             #    ├── Tool Auto-Discovery (35+ tools)
│                             #    ├── DAG-Based Task Orchestration
│                             #    └── REST API (20+ endpoints)
│
├── client.py                 # 🔗 MCP Client Bridge (FastMCP Protocol)
│                             #    ├── 28 MCP Tools Exposed
│                             #    ├── Elite System Prompt
│                             #    │   ├── Bug Bounty Hunter (15yr)
│                             #    │   ├── Exploit Developer (20yr)
│                             #    │   ├── CTF Champion (10yr)
│                             #    │   ├── Systems Hacker (40yr)
│                             #    │   └── Red Team Operator (25yr)
│                             #    ├── KaliToolsClient HTTP Adapter
│                             #    ├── Real-Time Learning Tools
│                             #    └── Health Check & Diagnostics
│
├── mcp.json                  # ⚙️ MCP Configuration Template
│                             #    └── Ready-to-use config for all AI IDEs
│
├── banner.svg                # 🎨 Project Banner Graphic
├── architecture.svg          # 📐 Architecture Diagram
│
├── honey_badger.db           # 🗄️ SQLite Database (auto-created at runtime)
│                             #    ├── findings      — ports, URLs, IPs, vulns
│                             #    ├── command_log    — full execution audit trail
│                             #    ├── tasks          — DAG task state
│                             #    ├── parallel_jobs  — background job tracking
│                             #    ├── workflow_runs  — workflow execution history
│                             #    └── smart_graph_runs — conditional graph logs
│
└── workflows/                # 📋 Custom Workflow Definitions (auto-created)
                              #    └── Drop .json or .md workflow files here

Real-Time Learning Engine

After every scan wave, analyze_and_plan() performs deep target analysis:

<pre> SCAN WAVE COMPLETES ↓ ┌─────────────────────────────────────────────┐ │ 1. EXTRACT INTELLIGENCE │ │ Pull all findings from SQLite │ │ Categorize: ports, URLs, IPs, vulns │ │ │ │ 2. BUILD TARGET PROFILE │ │ OS: Linux/Windows/FreeBSD │ │ Web: Apache/Nginx/IIS + version │ │ CMS: WordPress/Drupal/Joomla │ │ DB: MySQL/PostgreSQL/MongoDB │ │ Tech: PHP/Python/Java/Node.js │ │ Frameworks: React/Angular/jQuery │ │ │ │ 3. CVE DETECTION │ │ 18+ version→CVE patterns checked │ │ Apache 2.4.49 → CVE-2021-41773 (RCE!) │ │ vsftpd 2.3.4 → CVE-2011-2523 (Backdoor!)│ │ Drupal 7 → CVE-2018-7600 (Drupalgeddon!) │ │ │ │ 4. KNOWLEDGE GAP ANALYSIS │ │ Which ports haven't been deep-scanned? │ │ Which services lack vuln assessment? │ │ What attack vectors are unexplored? │ │ │ │ 5. PRIORITIZED RECOMMENDATIONS │ │ 🔴 CRITICAL exploits first │ │ 🟠 HIGH-value enumeration second │ │ 🟡 MEDIUM credential attacks third │ │ 🟢 LOW passive intel last │ │ → Top 15 tools for next parallel burst │ └─────────────────────────────────────────────┘ ↓ LAUNCH NEXT 15-TOOL PARALLEL WAVE </pre>

Service → Attack Chain Mapping (25+ services)

Port	Service	Auto-launched Tools
21	FTP	nmap ftp-scripts, hydra anonymous check
22	SSH	nmap ssh-auth-methods, hydra brute force
25	SMTP	nmap smtp-enum-users, smtp-vuln scripts
53	DNS	nmap dns-zone-transfer, dig axfr
80	HTTP	nikto, dirb, gobuster, whatweb
443	HTTPS	nikto-ssl, sslscan, gobuster-https
445	SMB	enum4linux, smb-vuln scripts, smbclient
1433	MSSQL	nmap ms-sql scripts, hydra mssql
3306	MySQL	nmap mysql scripts, hydra mysql
3389	RDP	rdp-vuln-ms12-020, hydra rdp
5432	PostgreSQL	nmap pgsql-brute
5900	VNC	nmap vnc-info, vnc-brute
6379	Redis	nmap redis-info
8080	Alt HTTP	nikto, gobuster
27017	MongoDB	nmap mongodb-databases

Framework Comparison

Why Honey Badger > Everything Else

Feature	HexStrike	MCP Kali Server	Honey Badger v3.1
Parallel Execution	❌ Sequential	❌ Sequential	✅ 15-50 simultaneous
Target Learning	❌ None	❌ None	✅ Real-time adaptive
CVE Detection	❌ None	❌ None	✅ 18+ version→CVE maps
Attack Planning	❌ Manual	❌ Manual	✅ Auto 15-tool recommendations
Safety Controls	⚠️ Basic	❌ None (raw bash)	✅ Input validation + injection detection
Plugin System	⚠️ Complex	❌ None	✅ Simple Python plugins
Persistent Memory	⚠️ Partial	❌ None	✅ Full SQLite with dedup
MCP Integration	⚠️ Custom	✅ Basic	✅ 28 typed tools via FastMCP
Setup Complexity	🔴 Heavy	🟡 Medium	🟢 2 files, pip install

Configuration

Environment Variables

Variable	Default	Description
`API_PORT`	`5000`	Server bind port
`COMMAND_TIMEOUT`	`180`	Per-command timeout (seconds)
`HB_DB_PATH`	`./honey_badger.db`	SQLite database path
`HB_WORKFLOW_DIR`	`./workflows`	Custom workflow directory
`DEBUG_MODE`	`0`	Enable debug logging (1/true)

Server Command Line

python3 server.py [OPTIONS]

  --port PORT          Server port (default: 5000)
  --ip IP              Bind address (default: 127.0.0.1, use 0.0.0.0 for network)
  --db PATH            Override database path
  --debug              Enable debug logging
  --no-discovery       Skip tool auto-discovery on startup

Client Command Line

python3 client.py [OPTIONS]

  --server URL         Server URL (default: http://localhost:5000)
  --timeout SECONDS    Request timeout (default: 300)
  --debug              Enable debug logging
  --no-health-check    Skip initial server health check

Security Considerations

Input Validation — All commands validated for length, injection characters, and safety
Timeout Enforcement — Every command: configurable timeout (default 180s) with process group isolation
Process Isolation — Each parallel command runs in its own process group (setsid)
Output Truncation — Raw output bounded (50KB stdout, 10KB stderr per command)
WAL Mode Database — SQLite Write-Ahead Logging for safe concurrent thread access
Prompt Injection Detection — System prompt instructs AI to detect and reject injected instructions
Authorization Required — AI persona requires explicit user authorization before engaging targets

Troubleshooting

Server won't start

python3 --version              # Must be 3.10+
pip install flask mcp requests # Install deps
ss -tlnp | grep 5253           # Check port in use

Database permission errors

sudo chown $USER honey_badger.db        # Fix ownership
# OR
export HB_DB_PATH=./my_hb.db && python3 server.py  # Custom path

Tool discovery finds no tools

which nmap gobuster dirb nikto sqlmap    # Verify in PATH
sudo apt install nmap nikto dirb gobuster sqlmap hydra john enum4linux  # Install (Kali)

MCP client can't connect

curl http://KALI_IP:5253/health          # Verify server reachable
# Use ABSOLUTE paths in mcp.json
# Restart your IDE after config changes

IDE shows "timeout" errors

# Increase timeout in mcp_config.json:
"timeout": 300    # 5 minutes — enough for heavy scans
# OR use async mode for long scans (nikto, sqlmap, full nmap)

License

This project is provided as-is for authorized security testing purposes only. Ensure you have proper, documented authorization before scanning any targets. The authors hold no responsibility for misuse.

"Honey Badger don't care. Honey Badger PWNS." 🦡

Repository

kishwordulal1234

kishwordulal1234/honey_badger_mcp

Created

April 3, 2026

Updated

April 13, 2026

Language

Python