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

Clone the Repository

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

Install Python Dependencies
```
pip install -r requirements.txt
```
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-tool)
Commit your changes (git commit -m 'Add amazing security tool')
Push to the branch (git push origin feature/amazing-tool)
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:

Fork the repository
Create a feature branch for your enhancement
Test thoroughly with various target types
Submit a pull request with detailed descriptions
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