Security MCP Server

# Codebase Review and Understanding: Security MCP Server ## 1. Project Purpose and Core Concept This project is a **production-ready, security-hardened server** that implements the Model Context Protocol (MCP). Its primary function is to act as a safe intermediary between an AI agent (like a large language model) and a suite of powerful, potentially dangerous network security command-line tools (e.g., `nmap`, `masscan`, `gobuster`). The core problem it solves is **safely delegating** network operations to an AI. Instead of letting an AI generate and execute arbitrary shell commands, this server exposes a structured, API-like interface for each tool. It enforces a strict, non-negotiable set of security policies to prevent misuse, whether accidental or malicious. The design philosophy is **"defense in depth"** and **"secure by default."** ## 2. Architecture and Key Components The system is built on a modular, decoupled architecture where each component has a clear responsibility. - **`mcp_server/server.py` (The Core Engine):** This is the main entry point. It handles both `stdio` transport (for direct integration with clients like Claude Desktop) and `http` transport (via FastAPI, for standard API access). Its primary roles are: - Initializing the environment. - Discovering and loading all available tools from the `mcp_server/tools/` directory. - Managing a `ToolRegistry` to keep track of enabled/disabled tools. - Setting up and exposing monitoring endpoints (`/health`, `/metrics`). - Handling incoming requests and dispatching them to the correct tool. - **`mcp_server/base_tool.py` (The Foundation):** This is the most critical file for understanding the security model. Every tool *must* inherit from `MCPBaseTool`. It provides a secure-by-default foundation that includes: - **Input Validation (`ToolInput`):** A Pydantic model that strictly validates all inputs. It ensures targets are within private RFC1918 networks or approved internal domains (`.lab.internal`) and blocks shell metacharacters (`;`, `|`, `&`, etc.) in arguments. - **Secure Command Execution (`_spawn`):** A hardened subprocess execution method that sets resource limits (CPU, memory, file descriptors) and runs commands in an isolated environment with a minimal `PATH`. - **Concurrency Control:** A thread-safe semaphore system (`_ensure_semaphore`) limits the number of concurrent executions for each tool class, preventing resource exhaustion. - **Circuit Breaker Integration:** Each tool instance is wrapped in a `CircuitBreaker` to prevent cascading failures. If a tool fails repeatedly, the breaker trips, and subsequent calls fail fast without executing the tool. - **Metrics Integration:** Automatically records execution time, success/failure status, and error types for each tool run. - **The Tools (`mcp_server/tools/*.py`):** Each file in this directory defines a specific tool by subclassing `MCPBaseTool`. They extend the base functionality by: - Defining the `command_name` (e.g., `nmap`). - Specifying a `allowed_flags` whitelist, which is the primary mechanism for preventing arbitrary command execution. - Implementing tool-specific validation logic (e.g., `masscan_tool.py` checks for `CAP_NET_RAW` privileges and enforces strict rate limits; `nmap_tool.py` filters dangerous scripts). - **`mcp_server/config.py` (Configuration Management):** A robust system for managing configuration from multiple sources (defaults, YAML file, environment variables) with a clear priority order. It includes validation, type casting, and clamping of values to safe ranges (e.g., ensuring `max_rate` for a tool doesn't exceed a hardcoded safety limit). It also supports hot-reloading of the configuration file. - **`mcp_server/health.py` (Health Monitoring):** A sophisticated, priority-based health check system. - Checks are categorized as `CRITICAL` (e.g., system resources), `IMPORTANT` (e.g., process health), and `INFORMATIONAL` (e.g., tool availability). - The overall system status (`HEALTHY`, `DEGRADED`, `UNHEALTHY`) is determined by the outcome of these checks, with failures in higher-priority checks having a greater impact. - It runs checks periodically in the background and includes staleness detection. - **`mcp_server/metrics.py` (Observability):** A comprehensive metrics collection system. - It tracks detailed statistics for each tool (execution count, success/failure rates, latency percentiles). - It integrates with Prometheus (`PrometheusRegistry`) to expose these metrics in a standard format for monitoring and alerting. - It is designed as a thread-safe singleton to ensure consistent metric collection across the application. - **`mcp_server/circuit_breaker.py` (Resilience):** A standalone, production-ready circuit breaker implementation. It protects the system from failures in downstream tools by monitoring their success/failure rates and "opening the circuit" (blocking further calls) when a failure threshold is exceeded. It supports automatic recovery (`HALF_OPEN` state) and adaptive backoff. ## 3. Deployment and Operations (Docker & Scripts) The project is designed for modern, container-based deployments. - **`Dockerfile`:** A multi-stage build that creates a minimal, secure runtime image. It correctly installs system dependencies (like `nmap`), sets up a non-root user, and copies only the necessary application code and virtual environment. - **`docker-compose.yml`:** Defines a full-stack, production-like environment that includes not just the MCP server but also a complete observability stack: `Prometheus` for metrics collection, `Grafana` for visualization, `node-exporter` for host metrics, and `cadvisor` for container metrics. This demonstrates a commitment to operational excellence. - **`scripts/mcp_server_launcher.sh`:** A well-written helper script for managing the server outside of Docker. It handles process lifecycle (start, stop, status) and includes a crucial `validate` command to ensure the environment is set up correctly. ## 4. Overall Impression This is a well-architected, security-focused application. The code is clean, modular, and demonstrates a deep understanding of building resilient, production-ready systems. The separation of concerns is excellent, with security logic centralized in the `MCPBaseTool`, making it easy and safe to extend the system with new tools. The inclusion of a comprehensive observability stack out-of-the-box is a standout feature that makes it suitable for serious operational use.