🛡️ MCPPentestBOT

AI-Powered Security Testing Toolkit Built on Model Context Protocol (MCP)

An intelligent penetration testing assistant that seamlessly integrates professional security tools with AI language models through the Model Context Protocol standard.

---

📖 What is MCPPentestBOT?

MCPPentestBOT brings enterprise-grade security testing capabilities to AI assistants like AZURE , Claude and GPT-4. Built on the Model Context Protocol (MCP), it provides a standardized, universal interface for AI-powered penetration testing and security assessments.

Instead of manually running security tools and interpreting results, security professionals can now have natural conversations with AI assistants that directly execute scans, analyze vulnerabilities, and provide actionable insights.

---

🎯 Why MCP?

The Model Context Protocol (MCP) is an open standard that enables secure, structured communication between AI applications and external tools. Here's why it matters for security testing:

Benefit	Description
🔌 Universal Compatibility	Works seamlessly with any MCP-enabled AI platform - no custom integrations needed
🔒 Secure & Structured	Type-safe, validated communication between AI and security tools
🚀 Zero Setup	Standardized tool definitions mean instant recognition by AI assistants
🔧 Easy Extension	Add new security tools using MCP's plugin architecture without code changes
🌐 Ecosystem Ready	Part of the growing MCP ecosystem with thousands of compatible tools

---

✨ Key Features

Security Testing Tools

• 🔐 SSL/TLS Certificate Analysis
  Complete certificate validation, expiration checks, cipher strength analysis, and protocol security assessment

• 📋 HTTP Security Headers Audit
  Comprehensive analysis of security headers including HSTS, CSP, X-Frame-Options, and security recommendations

• 🔍 Port Scanning & Service Detection
  Advanced network reconnaissance using industry-standard Nmap with service version detection

• 🕸️ Web Vulnerability Scanning
  Deep web application security testing with Nikto for common vulnerabilities and misconfigurations

• 📡 Network Discovery
  Efficient host discovery across networks using ICMP ping sweeps and network mapping

• ⚡ Connectivity Testing
  Quick port accessibility checks for service availability and firewall verification

Technical Advantages

• ✅ AI-Native Design - Purpose-built for seamless LLM integration
• ✅ Async Architecture - High-performance concurrent scanning capabilities
• ✅ Direct Integration - No subprocess overhead or JSON-RPC complexity
• ✅ Structured Output - Clean JSON responses optimized for AI processing
• ✅ Type Safety - Full type hints and validated inputs/outputs
• ✅ Extensible - Easy to add custom security tools and workflows

---

🚀 Getting Started

Prerequisites

System Requirements:

• Python 3.8 or higher
• Operating System: Linux, macOS, or Windows (WSL recommended)

Required Security Tools:

# Ubuntu/Debian
sudo apt-get install nmap nikto openssl

# macOS
brew install nmap nikto openssl

Installation

1. Clone the Repository

   git clone https://github.com/kannanprabu/MCPPentestBOT.git
   cd MCPPentestBOT
   

2. Install Python Dependencies

   pip install -r requirements.txt
   

3. Verify Installation

   python llm_client.py --version
   

Configuration

For Claude Desktop Users:

Add to your configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pentestbot": {
      "command": "python",
      "args": ["/absolute/path/to/MCPPentestBOT/llm_client.py"]
    }
  }
}

For Direct Python Integration:

Configure your environment variables in .env:

LOG_LEVEL=INFO
NMAP_TIMEOUT=300
NIKTO_TIMEOUT=600

---

💡 Usage Examples

Using with AI Assistants

Once configured, simply ask your AI assistant natural language questions:

• "Check the SSL certificate for github.com"
• "Scan ports 80 and 443 on example.com"
• "Analyze HTTP security headers for my website"
• "Perform a comprehensive security assessment on 192.168.1.1"

The AI will automatically select and execute the appropriate security tools, interpret results, and provide actionable recommendations.

Direct Python Usage

from pentestgpt.tools import ssl_check
import asyncio

# Run a security check
result = asyncio.run(ssl_check(target="example.com"))
print(result)

---

🔧 Available Security Tools

Tool	Purpose	Use Case
ssl_check	SSL/TLS certificate and security analysis	Certificate validation, expiration monitoring, cipher assessment
http_headers	HTTP security headers evaluation	Security posture assessment, compliance checking
nmap_scan	Network port scanning and service detection	Infrastructure discovery, attack surface mapping
nikto_scan	Web application vulnerability scanning	Web server security testing, configuration auditing
ping_sweep	Network host discovery	Network mapping, live host identification
port_check	Individual port connectivity testing	Service availability verification, firewall testing

---

⚖️ Legal & Ethical Use

⚠️ Important Legal Notice

MCPPentestBOT is designed for authorized security testing only.

You MUST:

• ✅ Obtain explicit written permission before testing any system
• ✅ Only test systems and networks you own or have authorization to assess
• ✅ Follow responsible disclosure practices for any vulnerabilities found
• ✅ Comply with all applicable laws and regulations in your jurisdiction
• ✅ Respect privacy and handle discovered data responsibly

You MUST NOT:

• ❌ Test systems without proper authorization
• ❌ Use for malicious purposes or unauthorized access
• ❌ Violate terms of service or acceptable use policies
• ❌ Access, modify, or exfiltrate data without permission

Best Practices

• Follow the OWASP Testing Guide
• Adhere to PTES (Penetration Testing Execution Standard)
• Respect Bug Bounty Program Rules

Unauthorized use of this tool may violate computer crime laws. Users are solely responsible for ensuring their use complies with all applicable laws.

---

🛠️ Configuration & Settings

Environment Variables

Create a .env file in the project root:

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=pentestbot.log

# Tool Timeouts (seconds)
NMAP_TIMEOUT=300
NIKTO_TIMEOUT=600
SSL_TIMEOUT=30

# Performance
MAX_CONCURRENT_SCANS=3

Custom Tool Configuration

Advanced users can customize tool behavior by editing config.yaml to adjust timeout values, scan parameters, and output formats.

---

🐛 Troubleshooting

Common Issues

"Command not found: nmap/nikto/openssl"

• Install the required system tools using your package manager
• Verify installation: which nmap nikto openssl

"Permission denied" errors

• Some network operations require elevated privileges
• Run with sudo or add capabilities: sudo setcap cap_net_raw+eip $(which python3)

Module import errors

• Ensure all dependencies are installed: pip install -r requirements.txt
• Verify Python version: python --version (3.8+ required)

Timeout errors

• Increase timeout values in .env configuration
• Check network connectivity to target systems

---

🤝 Contributing

We welcome contributions from the security community!

How to Contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-tool)
3. Commit your changes (git commit -m 'Add amazing security tool')
4. Push to the branch (git push origin feature/amazing-tool)
5. Open a Pull Request

Contribution Ideas:

• Add new security tools and integrations
• Improve documentation and examples
• Report bugs and suggest enhancements
• Share usage patterns and workflows

---

📄 License

This project is licensed under the MIT License.

Copyright (c) 2024 MCPPentestBOT Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software.

See LICENSE file for full details.

---

Educational Test Targets

For learning and practice, use these intentionally vulnerable applications:

• http://testphp.vulnweb.com - Vulnerable PHP application
• scanme.nmap.org - Nmap's official test server
• http://demo.testfire.net - IBM's intentionally vulnerable banking app
• DVWA, WebGoat, Mutillidae - Local vulnerable applications

---

Contributing

We welcome contributions from the security community:

1. Fork the repository
2. Create a feature branch for your enhancement
3. Test thoroughly with various target types
4. Submit a pull request with detailed descriptions
5. Follow responsible disclosure for any security issues

Development Guidelines

• Implement proper error handling and timeouts
• Follow security best practices in code development
• Include comprehensive documentation
• Test across different environments and targets
• Maintain focus on authorized testing scenarios

---

Support and Documentation

• Integration Guide: Detailed Claude Desktop setup instructions
• Tool Documentation: Comprehensive usage examples and workflows
• Security Best Practices: Guidelines for responsible testing
• Troubleshooting: Common issues and solutions
• Community Forums: User discussions and support

---

Contributors

Thanks to all the security professionals who contributed:

• Kannan Prabu Ramamoorthy

---

Disclaimer

This tool is provided "as is" for educational and authorized testing purposes only. Users are solely responsible for compliance with applicable laws, regulations, and organizational policies. The authors assume no liability for misuse or unauthorized activities conducted with this tool.

Always practice responsible disclosure and ethical security testing.

Built with ❤️ by Security Professionals, for Security Professionals

⬆ Back to Top

</div>