HexStrike AI Logo # HexStrike AI MCP Agents v5.0 ### AI-Powered Cybersecurity Tool Integration via Model Context Protocol [![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Security](https://img.shields.io/badge/Security-Penetration%20Testing-red.svg)](https://github.com/0x4m4/hexstrike-ai) [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://github.com/0x4m4/hexstrike-ai) [![Version](https://img.shields.io/badge/Version-5.0.0-orange.svg)](https://github.com/0x4m4/hexstrike-ai/releases) [![Tools](https://img.shields.io/badge/Security%20Tools-70%2B-brightgreen.svg)](https://github.com/0x4m4/hexstrike-ai) **MCP Server that enables AI agents to perform autonomous cybersecurity testing and penetration testing through 70+ integrated security tools** [๐Ÿ—๏ธ Architecture](#๏ธ-architecture-overview) โ€ข [๐Ÿš€ Installation](#quick-installation) โ€ข [๐Ÿ› ๏ธ Features](#comprehensive-feature-set) โ€ข [๐Ÿค– AI Usage](#ai-agent-usage-examples) โ€ข [๐Ÿ“ก API Reference](#api-reference) โ€ข [โญ Star Us](https://github.com/0x4m4/hexstrike-ai)
--- ## ๐Ÿ—๏ธ **Architecture Overview** HexStrike AI MCP Agents is a **Model Context Protocol (MCP) server** that bridges AI agents with cybersecurity tools. This project serves as the foundation for HexStrike AI - a separate automated AI pentesting platform. ```mermaid graph TD A[AI Agent - Claude/GPT/Copilot] -->|MCP Protocol| B[HexStrike MCP Server] B -->|Tool Execution| C[Security Tools - nmap/nuclei/etc] B -->|File Operations| D[Payload Generation] B -->|Process Control| E[Real-time Monitoring] C -->|Results| B D -->|Payloads| B E -->|Status| B B -->|Analysis & Results| A style A fill:#ff6b6b,stroke:#d63031,stroke-width:3px,color:#fff style B fill:#a29bfe,stroke:#6c5ce7,stroke-width:3px,color:#fff style C fill:#fd79a8,stroke:#e84393,stroke-width:3px,color:#fff style D fill:#fdcb6e,stroke:#e17055,stroke-width:3px,color:#fff style E fill:#55a3ff,stroke:#0984e3,stroke-width:3px,color:#fff ``` ### **How It Works:** 1. **AI Agent Connection**: Claude, GPT, or other MCP-compatible AI agents connect to this server 2. **Intelligent Tool Usage**: AI agents autonomously select and execute appropriate security tools 3. **Real-time Results**: Agents receive live feedback and adapt their testing strategies 4. **Autonomous Pentesting**: AI performs comprehensive security assessments without human intervention *Note: Some components of this project are integrated into the main HexStrike AI automated pentesting platform.* --- ## **Why Choose HexStrike AI MCP Agents?** Enable your AI agents to become autonomous cybersecurity experts with access to professional-grade security tools and intelligent automation capabilities. ### ๐ŸŽฏ **Perfect For:** - ๐Ÿค– **AI Agent Developers** - Provide your agents with cybersecurity capabilities - ๐Ÿ” **Automated Penetration Testing** - Let AI agents perform comprehensive security assessments - ๐Ÿ’ฐ **Bug Bounty Automation** - AI-driven target analysis and vulnerability discovery - ๐Ÿ† **CTF Automation** - AI agents that can solve security challenges - ๐Ÿ”ฌ **Security Research** - Automated tool orchestration and payload generation - ๐Ÿ“š **Security Training** - AI tutors with practical security tool access --- ## **Key Highlights**
| ๐Ÿค– **AI Agent Integration** | ๐Ÿ› ๏ธ **70+ Security Tools** | โšก **Real-time Control** | |:---:|:---:|:---:| | MCP protocol for seamless AI connection | Complete penetration testing toolkit | Command termination & progress tracking | | ๐Ÿ”ง **Intelligent Automation** | ๐ŸŒ **Modern API Testing** | ๐Ÿ“Š **Advanced Monitoring** | |:---:|:---:|:---:| | AI-driven tool selection & usage | GraphQL, JWT, REST API security | Live dashboards & system metrics |
### โœจ **What Makes Us Special:** - ๐Ÿ”ฅ **Zero Human Intervention** - AI agents handle complete security assessments - ๐ŸŽจ **Beautiful Real-time Output** - Progress bars, ETA calculations, visual status - ๐Ÿง  **Intelligent Tool Selection** - AI chooses the right tools for each scenario - ๐Ÿ“Š **Live Dashboard** - Monitor all AI agent activities with system metrics - ๐Ÿ”„ **Smart Caching** - Optimized performance for repeated operations - ๐Ÿ›ก๏ธ **Comprehensive Coverage** - Network, web, binary, cloud, CTF tools --- ## **Comprehensive Feature Set** ### ๐ŸŽฏ **Core Security Tools (70+)**
๐Ÿ” Network Reconnaissance & Scanning - **Nmap** - Advanced port scanning with custom NSE scripts - **Amass** - Comprehensive subdomain enumeration and OSINT - **Subfinder** - Fast passive subdomain discovery - **Nuclei** - Fast vulnerability scanner with 4000+ templates - **AutoRecon** - Automated reconnaissance with 35+ parameters - **Fierce** - DNS reconnaissance and zone transfer testing - **Masscan** - High-speed Internet-scale port scanner
๐ŸŒ Web Application Security Testing - **Gobuster** - Directory, file, and DNS enumeration - **FFuf** - Fast web fuzzer with advanced filtering capabilities - **Dirb** - Comprehensive web content scanner - **Nikto** - Web server vulnerability scanner - **SQLMap** - Advanced automatic SQL injection testing - **WPScan** - WordPress security scanner with vulnerability database - **Burp Suite** - Professional web security testing platform - **OWASP ZAP** - Web application security scanner - **Arjun** - HTTP parameter discovery tool - **Wafw00f** - Web application firewall fingerprinting - **Feroxbuster** - Fast content discovery tool - **Dotdotpwn** - Directory traversal fuzzer - **XSSer** - Cross-site scripting detection and exploitation - **Wfuzz** - Web application fuzzer
๐Ÿ” Authentication & Password Security - **Hydra** - Network login cracker supporting 50+ protocols - **John the Ripper** - Advanced password hash cracking - **Hashcat** - World's fastest password recovery tool - **Medusa** - Speedy, parallel, modular login brute-forcer - **Patator** - Multi-purpose brute-forcer - **CrackMapExec** - Swiss army knife for pentesting networks - **Evil-WinRM** - Windows Remote Management shell
๐Ÿ”ฌ Binary Analysis & Reverse Engineering - **GDB** - GNU Debugger with Python scripting - **Radare2** - Advanced reverse engineering framework - **Binwalk** - Firmware analysis and extraction tool - **ROPgadget** - ROP/JOP gadget finder - **Checksec** - Binary security property checker - **Strings** - Extract printable strings from binaries - **Objdump** - Display object file information - **Ghidra** - NSA's software reverse engineering suite - **XXD** - Hex dump utility
๐Ÿ† Advanced CTF & Forensics Tools - **Volatility3** - Advanced memory forensics framework - **Foremost** - File carving and data recovery - **Steghide** - Steganography detection and extraction - **ExifTool** - Metadata reader/writer for various file formats - **HashPump** - Hash length extension attack tool - **Binwalk** - Firmware analysis and reverse engineering - **Autopsy** - Digital forensics platform - **Sleuth Kit** - Collection of command-line digital forensics tools
โ˜๏ธ Cloud & Container Security - **Prowler** - AWS/Azure/GCP security assessment tool - **Trivy** - Comprehensive vulnerability scanner for containers - **Scout Suite** - Multi-cloud security auditing tool - **Kube-Hunter** - Kubernetes penetration testing tool - **Kube-Bench** - CIS Kubernetes benchmark checker - **CloudSploit** - Cloud security scanning and monitoring
๐Ÿ”ฅ Bug Bounty & Reconnaissance Arsenal - **Hakrawler** - Fast web endpoint discovery and crawling - **HTTPx** - Fast and multi-purpose HTTP toolkit - **ParamSpider** - Mining parameters from dark corners of web archives - **Aquatone** - Visual inspection of websites across hosts - **Subjack** - Subdomain takeover vulnerability checker - **DNSENUM** - DNS enumeration script - **Fierce** - Domain scanner for locating targets
### ๐Ÿค– **AI-Powered Automation Features**
๐ŸŽฏ Intelligent Payload Generation **Smart Attack Vector Creation:** - **XSS Payloads** - Basic, advanced, filter bypass techniques - **SQL Injection** - Database-specific, blind, time-based attacks - **Command Injection** - OS-specific, blind execution techniques - **LFI/RFI** - Local/remote file inclusion with wrapper techniques - **SSTI** - Server-side template injection for various engines - **XXE** - XML external entity attacks with data exfiltration - **CSRF** - Cross-site request forgery payload generation **Features:** - ๐Ÿง  **Context Awareness** - AI adapts payloads to target technology - ๐ŸŽฏ **Risk Assessment** - Automatic payload severity rating - ๐Ÿ”„ **Encoding Variations** - URL, HTML, Unicode encoding - ๐Ÿ“Š **Success Probability** - AI-calculated effectiveness scores
๐Ÿงช Automated Vulnerability Testing - **Intelligent Test Cases** - AI-guided vulnerability assessment - **Response Analysis** - Automated vulnerability confirmation - **False Positive Reduction** - Smart filtering and validation - **Comprehensive Reports** - Detailed security assessments - **Attack Chaining** - Multi-stage exploit development
๐ŸŒ Advanced API Security Testing - **GraphQL Security** - Introspection, depth limiting, batch query testing - **JWT Analysis** - Algorithm confusion, signature bypass, token manipulation - **REST API Testing** - Endpoint discovery, parameter fuzzing, authentication bypass - **API Schema Analysis** - OpenAPI/Swagger security assessment - **Comprehensive Audits** - Multi-technique API penetration testing
### โšก **Performance & Control Features**
๐ŸŽฎ Real-time Process Management **Advanced Command Control:** - **Live Termination** - Stop scans without server restart - **Progress Tracking** - Real-time progress bars with ETA calculations - **Process Dashboard** - Monitor all active scans simultaneously - **Resource Management** - CPU and memory optimization - **Pause/Resume** - Full control over long-running operations **Visual Progress Display:** ```bash โšก PROGRESS โฃท [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 60.5% | 12.3s | ETA: 8s | PID: 87369 ๐Ÿ“Š FINAL RESULTS โœ… โ”œโ”€ Command: nmap -sV -sC example.com โ”œโ”€ Duration: 15.2s โ”œโ”€ Output Size: 2847 bytes โ”œโ”€ Exit Code: 0 โ””โ”€ Status: SUCCESS | Cached: Yes ```
๐Ÿš€ Intelligent Caching System - **Performance Optimization** - Smart result caching with LRU eviction - **Context-Aware TTL** - Dynamic cache expiration based on command type - **Hit Rate Optimization** - Statistical analysis and cache tuning - **Memory Management** - Configurable cache size and cleanup - **Cache Analytics** - Detailed performance metrics
--- ## **Quick Installation** ### ๐Ÿ“‹ **System Requirements** ```bash # Recommended Environment OS: Kali Linux 2023.1+ / Ubuntu 20.04+ / Debian 11+ Python: 3.8+ with pip RAM: 4GB+ (8GB recommended) Storage: 20GB+ free space Network: High-speed internet for tool updates ``` ### ๐Ÿ› ๏ธ **Installation Steps** #### **Step 1: Install Server Dependencies** ```bash # 1. Clone the repository git clone https://github.com/0x4m4/hexstrike-ai.git cd hexstrike-ai # 2. Install Python dependencies pip3 install -r requirements.txt ``` #### **Step 2: Install Security Tools** **Required Tools** (install separately from their respective sources): - **Network Tools**: nmap, amass, subfinder, nuclei, autorecon, fierce, masscan - **Web Tools**: gobuster, ffuf, dirb, nikto, sqlmap, wpscan, burpsuite, zaproxy - **Password Tools**: hydra, john, hashcat, medusa, patator, crackmapexec - **Binary Tools**: gdb, radare2, binwalk, ropgadget, checksec, ghidra - **Forensics Tools**: volatility3, foremost, steghide, exiftool, hashpump - **Cloud Tools**: prowler, trivy, scout-suite, kube-hunter, kube-bench - **Recon Tools**: hakrawler, httpx, paramspider, aquatone, subjack, dnsenum *Note: Each tool should be installed according to its official documentation. Even if not all tools are installed it will work fine and will ignore that tool.* #### **Step 3: Start HexStrike Server** ```bash # Start the MCP server python3 hexstrike_server.py # Verify server is running curl http://localhost:5000/health ``` #### **Step 4: Configure AI Agent** Use the provided MCP configuration file [`hexstrike-ai-mcp.json`](hexstrike-ai-mcp.json) with your AI agent. --- ## **AI Integration Setup** ### **Claude Desktop Integration**
Claude MCP Configuration **Configure Claude Desktop:** Edit `~/.config/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "hexstrike-ai": { "command": "python3", "args": [ "/path/to/hexstrike-ai/hexstrike_mcp.py", "--server", "http://localhost:5000" ], "env": { "HEXSTRIKE_SERVER": "http://localhost:5000" } } } } ```
### **VS Code Copilot Integration**
VS Code MCP Configuration **Configure VS Code settings** in `.vscode/settings.json`: ```json { "mcp.servers": { "hexstrike-ai": { "command": "python3", "args": [ "/path/to/hexstrike-ai/hexstrike_mcp.py", "--server", "http://localhost:5000" ], "description": "HexStrike AI MCP Agents v5.0" } } } ```
### **Cursor AI Integration**
Cursor MCP Setup Guide **Configure Cursor settings** in `~/.cursor/mcp_settings.json`: ```json { "mcpServers": { "hexstrike-ai": { "command": "python3", "args": [ "/path/to/hexstrike-ai/hexstrike_mcp.py", "--server", "http://localhost:5000" ], "description": "HexStrike AI MCP Agents v5.0" } } } ```
--- ## **AI Agent Usage Examples** ### ๐ŸŽฏ **Example AI Conversations** #### **Autonomous Penetration Testing** ``` User: "Perform a comprehensive security assessment of example.com" AI Agent: "I'll conduct a multi-phase security assessment: 1. Starting with network reconnaissance using nmap... 2. Performing subdomain enumeration with amass... 3. Running web application scans with nuclei... 4. Testing for common vulnerabilities... [Real-time results and analysis follow]" ``` #### **Intelligent Vulnerability Discovery** ``` User: "Find XSS vulnerabilities in this web application" AI Agent: "I'll test for XSS vulnerabilities: 1. Crawling the application with hakrawler... 2. Discovering parameters with paramspider... 3. Generating contextual XSS payloads... 4. Testing each injection point... [Detailed vulnerability report with proof-of-concepts]" ``` #### **Advanced API Security Testing** ``` User: "Audit this GraphQL API for security issues" AI Agent: "I'll perform a comprehensive GraphQL security audit: 1. Testing introspection queries... 2. Analyzing query depth limitations... 3. Checking for batch query vulnerabilities... 4. Examining authentication bypass techniques... [Complete API security assessment with recommendations]" ``` *Video demonstrations and screenshots showing AI agents in action will be added here.* --- ## **API Reference** ### ๐Ÿ”ง **Core System Endpoints** | Endpoint | Method | Description | Parameters | |----------|--------|-------------|------------| | `/health` | GET | Server health check | None | | `/api/command` | POST | Execute arbitrary commands | `command`, `use_cache` | | `/api/telemetry` | GET | System performance metrics | None | | `/api/cache/stats` | GET | Cache performance statistics | None | ### ๐Ÿ›ก๏ธ **Security Tools API**
Network Security Tools | Tool | Endpoint | Key Parameters | |------|----------|---------------| | **Nmap** | `/api/tools/nmap` | `target`, `scan_type`, `ports`, `additional_args` | | **Amass** | `/api/tools/amass` | `domain`, `mode`, `additional_args` | | **Subfinder** | `/api/tools/subfinder` | `domain`, `silent`, `additional_args` | | **Nuclei** | `/api/tools/nuclei` | `target`, `severity`, `additional_args` |
### ๐Ÿค– **AI-Powered Features**
Intelligent Security Testing | Feature | Endpoint | Key Parameters | |---------|----------|---------------| | **Payload Generation** | `/api/ai/generate_payload` | `attack_type`, `complexity`, `technology` | | **Payload Testing** | `/api/ai/test_payload` | `payload`, `target_url`, `method` | | **Attack Suite** | `/api/ai/generate_attack_suite` | `target_url`, `attack_types` |
### ๐ŸŽฎ **Process Management**
Real-time Command Control | Action | Endpoint | Description | |--------|----------|-------------| | **List Processes** | `GET /api/processes/list` | List all active processes | | **Process Status** | `GET /api/processes/status/` | Get detailed process information | | **Terminate** | `POST /api/processes/terminate/` | Stop specific process | | **Dashboard** | `GET /api/processes/dashboard` | Live monitoring dashboard |
--- ## **Troubleshooting** ### Common Issues 1. **MCP Connection Failed**: ```bash # Check if server is running netstat -tlnp | grep 5000 # Restart server python3 hexstrike_server.py ``` 2. **Security Tools Not Found**: ```bash # Check tool availability which nmap gobuster nuclei # Install missing tools from their official sources ``` 3. **AI Agent Cannot Connect**: ```bash # Verify MCP configuration paths # Check server logs for connection attempts python3 hexstrike_mcp.py --debug ``` ### Debug Mode Enable debug mode for detailed logging: ```bash python3 hexstrike_server.py --debug python3 hexstrike_mcp.py --debug ``` --- ## **Performance Features** - **โšก Result Caching**: Optimized performance for repeated operations - **๐Ÿ”„ Concurrent Execution**: Multiple tools can run simultaneously - **๐Ÿ“Š Real-time Progress**: Live command output and progress tracking - **๐Ÿ’พ Memory Optimization**: Efficient handling of large outputs - **๐Ÿ”ง Automatic Cleanup**: Temporary files and processes are managed --- ## **What's New in v5.0** ### ๐Ÿ”ฅ Major Enhancements - **MCP Integration**: Full Model Context Protocol support for AI agents - **Advanced Process Control**: Real-time command termination and monitoring - **Enhanced Caching**: LRU cache with intelligent TTL management - **Cloud Security**: Comprehensive cloud and container security tools - **AI Automation**: Intelligent payload generation and testing capabilities - **File Operations**: Complete file management system for AI agents ### ๐Ÿ†• New Features - Real-time command output streaming - Progress indicators for long-running operations - Contextual payload generation system - Advanced API security testing (GraphQL, JWT) - Comprehensive process dashboard - Enhanced error handling with detailed logging --- ## ๐Ÿ”’ Security Considerations โš ๏ธ **Important Security Notes**: - This tool provides AI agents with powerful system access - Run in isolated environments or dedicated security testing VMs - AI agents can execute arbitrary security tools - ensure proper oversight - Monitor AI agent activities through the real-time dashboard - Consider implementing authentication for production deployments --- ## ๐Ÿ“ Contributing We welcome contributions from the cybersecurity and AI community! ### ๐Ÿ”ง **Development Environment Setup** ```bash # 1. Fork and clone the repository git clone https://github.com/0x4m4/hexstrike-ai.git cd hexstrike-ai # 2. Create development environment python3 -m venv hexstrike-dev source hexstrike-dev/bin/activate # 3. Install development dependencies pip install -r requirements.txt # 4. Start development server python3 hexstrike_server.py --port 5000 --debug ``` ### ๐ŸŽฏ **Priority Areas for Contribution** - **๐Ÿค– AI Agent Integrations** - Support for new AI platforms and agents - **๐Ÿ› ๏ธ Security Tool Additions** - Integration of additional security tools - **โšก Performance Optimizations** - Caching improvements and scalability enhancements - **๐Ÿ“– Documentation** - AI usage examples and integration guides - **๐Ÿงช Testing Frameworks** - Automated testing for AI agent interactions --- ## ๐Ÿ“„ License MIT License - see LICENSE file for details. --- ## ๐Ÿ‘จโ€๐Ÿ’ป Author **m0x4m4** - [www.0x4m4.com](https://www.0x4m4.com) | [HexStrike](https://www.hexstrike.com) --- **HexStrike AI MCP Agents v5.0 - Empowering AI agents with autonomous cybersecurity capabilities!**