Security MCP Server

## 🛡️ **Project Overview & Purpose** ### **What It Is** The Security-MCP-Server is an **enterprise-grade, production-ready framework** for secure execution and orchestration of security tools. It's designed as a **Model Context Protocol (MCP) server** that integrates with Large Language Models (LLMs) like Claude Desktop to provide natural language security assessment capabilities. ### **What It's For** - **Security Tool Orchestration**: Unified management of multiple security tools through a single interface - **Safe Tool Execution**: Enterprise-grade safety controls for running potentially dangerous security tools - **LLM Integration**: Natural language security assessments where users can describe security goals in plain English - **Automation**: Automated security workflows, incident response, and continuous monitoring ### **How It Works** The system operates as a **command orchestration platform** with multiple layers of safety and control: 1. **Client Layer**: LLMs, CLI clients, HTTP clients 2. **Transport Layer**: stdio for CLI, HTTP/REST for services 3. **Server Core**: Main orchestration with tool registry, health monitoring, metrics collection 4. **Tool Framework**: Base classes with circuit breakers, validation, and resource limits 5. **Tools**: Specific security tool implementations (Nmap, Masscan, Gobuster, Sqlmap, Hydra) 6. **Infrastructure**: Configuration, logging, Prometheus metrics ## 🏗️ **Architecture & Technical Design** ### **Core Components** - **server.py**: Main server orchestration with `EnhancedMCPServer` and `ToolRegistry` - **base_tool.py**: Abstract framework for all tools with input validation and resource limits - **config.py**: Centralized configuration with hot-reload capabilities - **health.py**: Real-time health monitoring with priority-based checks - **metrics.py**: Prometheus-compatible metrics collection - **circuit_breaker.py**: Automatic failure detection and recovery ### **Safety-First Design Principles** 1. **Multiple Validation Points**: Input validation, target validation, argument validation 2. **Circuit Breaker Pattern**: Prevents cascading failures and system overload 3. **Resource Limits**: CPU, memory, output size, and concurrency limits 4. **Network Restrictions**: RFC1918 private networks only (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) 5. **Process Isolation**: Subprocess execution with clean environments ### **Available Security Tools** | Tool | Purpose | Security Level | Safety Features | |------|---------|----------------|-----------------| | **NmapTool** | Network scanning & service discovery | Medium | Rate limiting, max 1024 hosts, safe scripts only | | **MasscanTool** | High-speed port scanning | Medium | Rate limited to 1000 pps, max /16 networks | | **GobusterTool** | Web content discovery | Low-Medium | Thread limits, wordlist validation | | **SqlmapTool** | SQL injection testing | High | Risk level 1-2 only, test level 1-3 only | | **HydraTool** | Password security testing | High | Service validation, password list restrictions | ## 🔒 **Security & Compliance Features** ### **Enterprise Security Controls** - **Input Validation**: Comprehensive validation of all tool inputs - **Rate Limiting**: Prevents resource exhaustion and network flooding - **Audit Logging**: Complete audit trail of all tool executions - **No Shell Execution**: Direct process execution only (no shell interpretation) - **Authentication Ready**: Easy integration with external auth systems ### **Resilience & Reliability** - **Circuit Breaker Pattern**: Automatic failure detection and recovery - **Adaptive Timeouts**: Exponential backoff with jitter - **Graceful Degradation**: System continues operating during component failures - **Health Monitoring**: Real-time system and tool health checks - **Automatic Recovery**: Self-healing capabilities for transient failures ### **Observability** - **Prometheus Metrics**: Comprehensive metrics with percentile calculations - **Grafana Dashboards**: Pre-built visualization dashboards - **Structured Logging**: JSON-formatted logs for easy parsing - **Real-time Events**: Server-Sent Events for live updates - **Distributed Tracing**: Request correlation across components ## 🚀 **Usage & Integration** ### **Target Users** - **Security Operations Center (SOC)** teams - **DevSecOps** engineers - **Penetration Testers** - **Security Researchers & Developers** ### **Key Use Cases** 1. **SOC Automation**: Automated security scanning workflows, incident response tool orchestration 2. **DevSecOps Pipeline**: CI/CD security scanning, pre-deployment checks, container security 3. **Penetration Testing**: Reconnaissance automation, controlled vulnerability scanning 4. **Research & Development**: Tool comparison, performance benchmarking, custom tool development ### **LLM Integration Examples** The system is designed for natural language interaction: ``` "Please scan the network 192.168.1.0/24 to discover all active hosts and identify their open ports and services. Use Nmap with service version detection enabled." ``` ``` "Conduct a security-focused port scan of 192.168.1.15. Use Nmap to scan the top 1000 most common ports, detect service versions, and identify potential vulnerabilities." ``` ## 📊 **Deployment & Operations** ### **Deployment Options** - **Docker (Recommended)**: Full stack with docker-compose - **Local Installation**: Python-based with virtual environment - **Configuration**: Environment variables and YAML files ### **Monitoring Stack** - **Prometheus**: Metrics collection and alerting - **Grafana**: Visualization and dashboards - **Health Checks**: HTTP endpoint for system status - **Metrics Endpoint**: Prometheus-formatted metrics ### **Configuration Management** - **Hot-Reload**: Change settings without restart - **Multiple Sources**: Environment variables, YAML/JSON files, defaults - **Validation**: Automatic configuration validation - **Security**: Sensitive data redaction ## ⚠️ **Safety & Legal Considerations** ### **Responsible Usage** - **Authorization Required**: Strong warnings about legal authorization - **Network Restrictions**: Limited to private networks and lab domains - **Tool Safety**: Each tool has specific safety limits and restrictions - **Audit Trail**: Complete logging for compliance and accountability ### **Risk Mitigation** - **Defense in Depth**: Multiple layers of security controls - **Fail-Safe Design**: System defaults to safe state - **Resource Protection**: Prevents system overload and resource exhaustion - **Circuit Breakers**: Automatic protection against tool failures ## 🎯 **Key Differentiators** 1. **LLM-Native Design**: Built specifically for seamless LLM integration 2. **Enterprise-Grade Reliability**: Production-ready with comprehensive monitoring 3. **Security-First Architecture**: Multiple layers of safety controls 4. **Extensible Framework**: Easy addition of new security tools 5. **Comprehensive Observability**: Full monitoring and metrics capabilities This project represents a sophisticated bridge between powerful security tools and safe, controlled access through modern LLM interfaces, making enterprise security operations more accessible while maintaining strict security boundaries and compliance requirements. https://chat.z.ai/s/95fb3345-0c5c-481c-b103-8d9ff337136f Debug: https://copilot.microsoft.com/shares/EEknMPSokMtsoGXoVEbUa Review: https://chat.deepseek.com/share/x6m1hl6168lvuvxkxs