# VA Pentest MCP - Vulnerability Assessment & Penetration Testing MCP Server

🔒 **Model Context Protocol (MCP) Server for Security Vulnerability Assessment and Penetration Testing**

A comprehensive Python-based MCP server that provides automated security scanning capabilities for projects. Combines OWASP Dependency-Check for dependency scanning with custom code vulnerability detection.

## Features

### 🔍 Security Scanning
- **Dependency Scanning**: Uses OWASP Dependency-Check to identify known vulnerabilities in project dependencies
- **Code Security Scanning**: Custom regex-based vulnerability detection for:
  - 🔐 Hardcoded Secrets (API keys, passwords, private keys, JWT tokens, database URLs, AWS credentials)
  - 💉 SQL Injection patterns
  - 🎯 Command Injection vulnerabilities
  - ⚠️ Unsafe Operations (eval, pickle, dangerous imports, file permissions)
  - 🌐 Cross-Site Scripting (XSS) vulnerabilities
  - 🚶 Path Traversal vulnerabilities

### 📊 Report Generation
- **HTML Reports**: Beautiful, interactive HTML reports with vulnerability details and recommendations
- **JSON Reports**: Machine-readable JSON format for integration with other systems
- **Comprehensive Summary**: Risk assessment and vulnerability statistics

### 🛠️ MCP Protocol Support
- Full Model Context Protocol implementation
- Tool registration and management
- Resource handling
- Standardized request/response format

## Installation

### Prerequisites
- Python 3.8 or higher
- pip (Python package manager)
- OWASP Dependency-Check (optional - will attempt auto-install)

### Setup

1. **Clone the repository**
```bash
git clone https://github.com/banhongit7/va-pentest-mcp.git
cd va-pentest-mcp
```

2. **Create virtual environment**
```bash
python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate
```

3. **Install dependencies**
```bash
pip install -r requirements.txt
```

4. **Install package**
```bash
pip install -e .
```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# MCP Server Configuration
LOG_LEVEL=INFO
LOG_FILE=./logs/va-pentest-mcp.log

# Dependency Check Configuration
DEPENDENCY_CHECK_ENABLED=true
DEPENDENCY_CHECK_PATH=/path/to/dependency-check/bin/dependency-check
DEPENDENCY_CHECK_DB_DIR=./tools/dependency-check-db

# Code Scanner Configuration
CODE_SCANNER_ENABLED=true
SCAN_FOR_SECRETS=true
SCAN_FOR_SQL_INJECTION=true
SCAN_FOR_COMMAND_INJECTION=true
SCAN_FOR_UNSAFE_OPERATIONS=true

# Report Generation
GENERATE_HTML_REPORT=true
GENERATE_JSON_REPORT=true

# Python Path (for Windows)
PYTHONPATH=D:\mcp\va-pentest-mcp\src
```

### MCP Configuration (config.json)

For OpenCode AI integration:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "va-pentest-mcp": {
      "type": "local",
      "command": ["python", "-m", "va_pentest_mcp.server"],
      "enabled": true,
      "env": {
        "PYTHONPATH": "D:\\mcp\\va-pentest-mcp\\src",
        "PATH": "D:\\mcp\\va-pentest-mcp\\tools;{env:PATH}"
      }
    }
  }
}
```

## Usage

### Starting the Server

```bash
python -m va_pentest_mcp.server
```

Or using the console script:

```bash
va-pentest-mcp
```

### Available Tools

#### 1. **scan_dependencies**
Scans project dependencies for known vulnerabilities using OWASP Dependency-Check.

```python
{
  "project_path": "/path/to/project"
}
```

#### 2. **scan_code**
Scans source code for security vulnerabilities.

```python
{
  "project_path": "/path/to/project",
  "file_extensions": [".py", ".js", ".java"]  # Optional
}
```

#### 3. **scan_full**
Runs complete security scan and generates reports.

```python
{
  "project_path": "/path/to/project",
  "generate_reports": true
}
```

## Project Structure

```
va-pentest-mcp/
├── src/
│   └── va_pentest_mcp/
│       ├── __init__.py                 # Package initialization
│       ├── server.py                   # Main MCP Server
│       ├── mcp_protocol.py             # MCP Protocol Handler
│       ├── dependency_scanner.py       # OWASP Dependency-Check Integration
│       ├── code_scanner.py             # Custom Security Vulnerability Detection
│       ├── report_generator.py         # HTML & JSON Report Generation
│       ├── config.py                   # Configuration Management
│       └── utils.py                    # Utility Functions
├── tools/                              # External tools directory
│   ├── dependency-check/               # OWASP Dependency-Check binary
│   └── dependency-check-db/            # Vulnerability database
├── reports/                            # Generated reports
│   ├── scan_report_YYYYMMDD_HHMMSS.html
│   └── scan_report_YYYYMMDD_HHMMSS.json
├── logs/                               # Application logs
├── requirements.txt                    # Python dependencies
├── setup.py                            # Package setup script
├── README.md                           # This file
└── .gitignore                          # Git ignore rules
```

## Vulnerability Detection

### Hardcoded Secrets Detection
Detects:
- API Keys
- Passwords
- Private Keys (RSA, OPENSSH, DSA, EC)
- AWS Access Keys (AKIA...)
- JWT Tokens
- Database Connection Strings

### Code Injection Detection
- SQL Injection via string concatenation, format strings, and direct queries
- Command Injection via os.system, subprocess, shell commands

### Unsafe Operations
- eval() usage
- pickle/marshal usage
- Dangerous imports
- Insecure file permissions

### Web Vulnerabilities
- XSS via innerHTML, dangerouslySetInnerHTML
- Path Traversal patterns

## Report Output

### HTML Report Features
- Executive Summary with Risk Assessment
- Vulnerability Statistics by Severity
- Detailed Vulnerability Listing
- Code Snippets with Line Numbers
- Remediation Recommendations
- Professional Styling

### JSON Report Structure
```json
{
  "scan_info": {
    "timestamp": "2024-01-01T12:00:00",
    "project_path": "/path/to/project",
    "scan_type": "Combined VA Scan"
  },
  "code_scan": {
    "total_vulnerabilities": 5,
    "vulnerabilities": [
      {
        "type": "Hardcoded Secret",
        "severity": "CRITICAL",
        "file": "config.py",
        "line": 42,
        "description": "Hardcoded API Key detected",
        "recommendation": "Use environment variables instead"
      }
    ]
  },
  "summary": {
    "overall_risk": "HIGH",
    "critical": 2,
    "high": 3
  }
}
```

## Advanced Configuration

### Custom File Extensions
```python
file_extensions = ['.py', '.js', '.ts', '.java', '.go', '.rb', '.php', '.cs']
```

### Severity Levels
- **CRITICAL**: Immediate action required
- **HIGH**: Significant security risk
- **MEDIUM**: Moderate risk, should be addressed
- **LOW**: Low risk, consider fixing
- **INFO**: Informational findings

## Troubleshooting

### dependency-check Not Found
```bash
# Try installing via pip
pip install dependency-check

# Or via npm
npm install -g dependency-check

# Or via homebrew (macOS)
brew install dependency-check
```

### Permission Issues
```bash
# Make dependency-check executable
chmod +x /path/to/dependency-check
```

### Windows Python Path
Ensure PYTHONPATH is correctly set in config.json:
```json
"PYTHONPATH": "C:\\Users\\username\\va-pentest-mcp\\src"
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - See LICENSE file for details

## Security Note

This tool is designed for authorized security testing only. Always get proper authorization before testing security vulnerabilities in any system.

## Support

For issues, questions, or suggestions:
- GitHub Issues: https://github.com/banhongit7/va-pentest-mcp/issues
- Email: banhongit7@gmail.com

---

**VA Pentest MCP** - Making security assessment automated and accessible 🚀