# MCP Security Scanner Server v2.0

![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python)
![MCP](https://img.shields.io/badge/MCP-1.28+-orange)
![Kali](https://img.shields.io/badge/Kali-Linux-purple?logo=kalilinux)
![License](https://img.shields.io/badge/License-MIT-green)
![Security](https://img.shields.io/badge/Security-Scanner-red)

> Professional production-grade MCP Server for security assessment. Powered by Model Context Protocol, built for Kali Linux.

## Overview

A professional **Model Context Protocol (MCP) Server** that provides AI agents with standardized security scanning capabilities. Designed for authorized security assessments with strict compliance controls.

### Key Features

- **7-Step Mandatory Flow** — Every tool follows: param validation → security filtering → boundary checks → business logic → result packaging → exception capture → logging
- **Zero Command Injection** — All shell calls use parameter arrays, never string concatenation
- **Mandatory Authorization** — `legal_authorized=true` required for all scan operations
- **8 CVE Verification** — Log4Shell, Spring4Shell, Apache Path Traversal, HTTP/2 Rapid Reset, and more
- **Standardized Output** — Unified JSON response: `code/msg/target/vuln_list/risk_level/cvss_score/suggest`
- **Professional Logging** — Timestamped logs with task IDs, scan trails, and audit records

## Architecture

```
mcp-security-server/
├── server.py              # MCP Server Entry Point
├── core/                  # Business Logic Layer
│   ├── scanner.py         # Scanning Engine (6 tools, 37KB)
│   ├── result.py          # Unified Response Builder
│   ├── analyzer.py        # CVSS 3.1 Scoring & Vulnerability DB
│   └── reporter.py        # Multi-format Report Generator
├── utils/                 # Infrastructure Layer
│   ├── executor.py        # Safe Command Executor (Parameter Arrays)
│   ├── validator.py       # Parameter Validation & Whitelist
│   ├── logger.py          # Professional Logging System
│   └── env.py             # Kali Environment Detection
└── requirements.txt       # Dependencies
```

## Quick Start

### 1. Install Dependencies

```bash
# Python packages
pip3 install mcp pydantic

# System tools (Kali Linux)
sudo apt update && sudo apt install -y nmap curl
```

### 2. Start Server

```bash
cd mcp-security-server
python3 server.py
```

### 3. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop, opencode):

```json
{
  "mcpServers": {
    "mcp-security-scanner": {
      "command": "python3",
      "args": ["/path/to/mcp-security-server/server.py"]
    }
  }
}
```

## Tools

| Tool | Description | Required Params |
|------|-------------|-----------------|
| `host_alive_detect` | Host alive detection (ICMP + TCP SYN) | target, legal_authorized |
| `port_scan` | Port scanning (SYN/Connect) | target, legal_authorized |
| `service_fingerprint` | Service version detection | target, legal_authorized |
| `web_vuln_scan` | Web vulnerability scanning | target, legal_authorized |
| `cve_poc_check` | CVE POC verification | target, legal_authorized, cve_id |
| `report_generate` | Security report generation | target, legal_authorized, scan_data |
| `env_check` | Environment & dependency check | (none) |

## Usage Examples

### Host Alive Detection

```json
{
  "target": "192.168.1.1",
  "legal_authorized": true,
  "timeout": 15
}
```

### Port Scan

```json
{
  "target": "192.168.1.1",
  "legal_authorized": true,
  "ports": "80,443,8080,8443",
  "scan_type": "syn"
}
```

### CVE Verification

```json
{
  "target": "192.168.1.1",
  "legal_authorized": true,
  "cve_id": "CVE-2021-44228",
  "port": 8080
}
```

### Generate Report

```json
{
  "target": "192.168.1.1",
  "legal_authorized": true,
  "scan_data": "{\"vuln_list\":[...],\"suggest\":[...]}",
  "format_type": "html"
}
```

## Supported CVEs

| CVE | Name | CVSS | Verification Method |
|-----|------|------|---------------------|
| CVE-2021-44228 | Log4Shell | 10.0 | Java service detection |
| CVE-2022-22965 | Spring4Shell | 9.8 | Spring/Tomcat detection |
| CVE-2023-22515 | Confluence Privilege | 10.0 | Setup endpoint check |
| CVE-2022-26134 | Confluence OGNL | 9.8 | Confluence detection |
| CVE-2021-41773 | Apache Path Traversal | 7.5 | Path traversal test |
| CVE-2021-42013 | Apache Path Traversal 2 | 7.5 | Path traversal test |
| CVE-2023-44487 | HTTP/2 Rapid Reset | 7.5 | HTTP/2 support check |
| CVE-2021-3449 | OpenSSL NULL deref | 5.9 | Version detection |

## Standardized Output

```json
{
  "code": 0,
  "msg": "success",
  "target": "192.168.1.1",
  "status": "completed",
  "scan_data": { ... },
  "vuln_list": [
    {
      "vuln_id": "CVE-2021-44228",
      "vuln_name": "Log4Shell",
      "cve_id": "CVE-2021-44228",
      "cvss_score": 10.0,
      "risk_level": "Critical",
      "confidence": "Suspected",
      "description": "Apache Log4j2 RCE",
      "evidence": "Java service detected",
      "remediation": "Upgrade Log4j to 2.17.0+"
    }
  ],
  "risk_level": "critical",
  "cvss_score": 10.0,
  "suggest": ["URGENT: Fix critical vulnerability immediately"],
  "task_id": "TASK-20260822100000-a1b2c3d4",
  "timestamp": "2026-08-22T10:00:00",
  "duration": 12.34
}
```

## Logging

Logs are automatically saved to `log/` directory:

| Log File | Purpose |
|----------|---------|
| `main_YYYY-MM-DD.log` | General operations |
| `scan_YYYY-MM-DD.log` | Scan activities |
| `error_YYYY-MM-DD.log` | Errors & exceptions |
| `audit_YYYY-MM-DD.log` | Security audit trail |

## Compliance

This tool is designed for:
- Security assessments with **written authorization**
- Internal security team vulnerability verification
- Security research and education

**PROHIBITED**: Unauthorized scanning, data theft, system damage

## License

MIT License - Authorized security testing only