Secure Ubuntu MCP Server

Un servidor MCP centrado en la seguridad para realizar operaciones seguras en un sistema Ubuntu, con controles de seguridad robustos y registro de auditoría.

GitHub
40
Prueba este MCPPatrocinado

Documentación

Servidor MCP Seguro de Ubuntu

🔒 Seguridad Primero Servidor de Protocolo de Contexto de Modelo para operaciones seguras del sistema Ubuntu

Un servidor endurecido y listo para producción del Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso seguro y controlado a las operaciones del sistema Ubuntu. Construido con controles de seguridad integrales, registro de auditoría y principios de defensa en profundidad.

License: MIT Python 3.9+ Security Focused MCP Compatible

✨ Características Clave

🛡️ Arquitectura de Seguridad Primero

  • Protección contra recorrido de rutas - Resolución de enlaces simbólicos con controles de lista permitida/denegada
  • Saneamiento de comandos - Prevención de inyección de shell con análisis seguro de argumentos
  • Límites de recursos - Tamaño de archivos, tiempos de espera de ejecución y controles de tamaño de salida
  • Registro de auditoría integral - Todas las operaciones registradas con atribución de usuario
  • Defensa en profundidad - Múltiples capas de seguridad con valores predeterminados a prueba de fallos

🎯 Capacidades Principales

  • Operaciones de archivos - Leer, escribir y listar directorios con validación de permisos
  • Ejecución de comandos - Ejecución segura de comandos de shell con filtrado de lista blanca/negra
  • Información del sistema - Detalles del sistema operativo, memoria y monitoreo de uso de disco
  • Gestión de paquetes - Búsqueda y listado de paquetes APT (la instalación requiere configuración explícita)

🏗️ Listo para Producción

  • Diseño modular con separación clara de responsabilidades
  • Manejo integral de errores con mensajes de error significativos
  • Amplio conjunto de pruebas incluyendo pruebas de validación de seguridad
  • Políticas configurables para diferentes casos de uso y entornos
  • Seguridad sin dependencias - La seguridad principal no depende de paquetes externos

🚀 Inicio Rápido

Requisitos Previos

  • Ubuntu 18.04+ (probado en 20.04, 22.04, 24.04)
  • Python 3.9 o superior
  • Utilidades Unix estándar (ls, cat, echo, etc.)

Instalación

# Clone the repository
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify installation with built-in tests
python main.py --test

Uso Básico

# Start with secure policy (recommended)
python main.py --policy secure

# Start with development policy (more permissive)
python main.py --policy dev

# Test security measures
python main.py --security-test

🔧 Integración

Claude Desktop

Obtener Claude Desktop en Linux

Soporte Oficial: Claude Desktop no soporta oficialmente Linux, ¡pero la comunidad ha creado soluciones!

Método Recomendado: Use el paquete Debian de la comunidad por @aaddrick:

# Download and install Claude Desktop for Linux
wget https://github.com/aaddrick/claude-desktop-debian/releases/latest/download/claude-desktop_latest_amd64.deb
sudo dpkg -i claude-desktop_latest_amd64.deb
sudo apt-get install -f  # Fix any dependency issues

Para otros métodos y solución de problemas, consulte: https://github.com/aaddrick/claude-desktop-debian

Configuración

Una vez instalado Claude Desktop, agregue a su configuración (~/.config/claude-desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "secure-ubuntu": {
      "command": "/path/to/secure-ubuntu-mcp/.venv/bin/python3",
      "args": ["/path/to/secure-ubuntu-mcp/main.py", "--policy", "secure"],
      "env": {
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

⚠️ Importante: Use rutas absolutas y el intérprete de Python del entorno virtual

Verificación: Después de reiniciar Claude Desktop, debería ver "secure-ubuntu" listado como un servidor conectado, y Claude tendrá acceso a las herramientas de control del sistema.

Otros Clientes MCP

El servidor implementa el protocolo MCP estándar y funciona con cualquier cliente compatible con MCP:

# Example with mcp Python client
import asyncio
from mcp.client import ClientSession

async def example():
    # Connect to the server
    # Implementation depends on your MCP client
    pass

🛡️ Políticas de Seguridad

Política Segura (Predeterminada)

Recomendada para entornos de producción y no confiables:

  • Rutas Permitidas: ~/, /tmp, /var/tmp
  • Rutas Prohibidas: /etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
  • Lista Blanca de Comandos: ls, cat, echo, pwd, whoami, date, find, grep, apt (solo búsqueda)
  • Límites de Recursos: Archivos de 1MB, tiempos de espera de 15s, salida de 256KB
  • Sudo: Deshabilitado
  • Ejecución de Shell: Deshabilitada (usa ejecución directa segura)

Política de Desarrollo

Más permisiva para entornos de desarrollo:

  • Rutas Permitidas Adicionales: /opt, /usr/local
  • Menos Restricciones: Acceso a más áreas del sistema
  • Límites Más Amplios: Archivos de 10MB, tiempos de espera de 60s, salida de 1MB
  • Más Comandos: La mayoría de las herramientas de desarrollo permitidas
  • Sudo: Aún deshabilitado por defecto (se puede habilitar)

Políticas Personalizadas

Cree su propia política de seguridad:

from main import SecurityPolicy

custom_policy = SecurityPolicy(
    allowed_paths=["/your/custom/paths"],
    forbidden_paths=["/sensitive/areas"],
    allowed_commands=["safe", "commands"],
    forbidden_commands=["dangerous", "commands"],
    max_command_timeout=30,
    allow_sudo=False,  # Use with extreme caution
    audit_actions=True
)

🔍 Herramientas Disponibles

Operaciones de Archivos

  • list_directory(path) - Listar contenido del directorio con metadatos
  • read_file(file_path) - Leer contenido de archivos con validación de tamaño
  • write_file(file_path, content, create_dirs=False) - Escribir con operaciones atómicas

Operaciones del Sistema

  • execute_command(command, working_dir=None) - Ejecutar comandos de shell de forma segura
  • get_system_info() - Obtener información del sistema operativo, memoria y disco

Gestión de Paquetes

  • search_packages(query) - Buscar en repositorios APT
  • install_package(package_name) - Verificar disponibilidad de paquetes (solo listado)

🔒 Características de Seguridad

Protección Contra Ataques Comunes

Prevención de Recorrido de Rutas:

# These are all blocked:
../../../etc/passwd
/etc/passwd
/tmp/../etc/passwd
symlinks_to_sensitive_files

Prevención de Inyección de Comandos:

# These are all blocked:
echo hello; rm -rf /
echo `cat /etc/passwd`
echo $(whoami)
ls | rm -rf /

Protección Contra Agotamiento de Recursos:

  • Los límites de tamaño de archivos previenen el agotamiento de memoria
  • Los tiempos de espera de ejecución previenen procesos colgados
  • Los límites de tamaño de salida previenen la inundación de registros
  • Los límites de listado de directorios previenen ataques de enumeración

Rastro de Auditoría

Todas las operaciones se registran con:

  • Atribución de usuario
  • Marca de tiempo y tipo de operación
  • Resolución completa de rutas
  • Estado de éxito/fallo
  • Detalles de violaciones de seguridad

🧪 Pruebas

Pruebas de Funcionalidad

# Test core functionality
python main.py --test

Validación de Seguridad

# Run comprehensive security tests
python main.py --security-test

Pruebas Manuales

# Test MCP protocol directly
python test_client.py --simple

📊 Ejemplo de Uso

Una vez integrado con un asistente de IA:

Monitoreo del Sistema:

"Verifica el estado de mi sistema y el espacio en disco"

Gestión de Archivos:

"Lista los archivos en mi directorio de inicio y muéstrame los más grandes"

Tareas de Desarrollo:

"Verifica si Python está instalado y muéstrame la versión"

Análisis de Registros:

"Busca archivos de error en mi directorio de proyecto"

⚙️ Configuración

Variables de Entorno

  • MCP_LOG_LEVEL - Nivel de registro (DEBUG, INFO, WARNING, ERROR)
  • MCP_POLICY - Política de seguridad (secure, dev)
  • MCP_CONFIG_PATH - Ruta al archivo de configuración personalizado

Archivo de Configuración

Cree config.json para configuraciones personalizadas:

{
  "server": {
    "name": "secure-ubuntu-controller",
    "version": "1.0.0",
    "log_level": "INFO"
  },
  "security": {
    "policy_name": "secure",
    "allowed_paths": ["~/", "/tmp"],
    "max_command_timeout": 30,
    "allow_sudo": false,
    "audit_actions": true
  }
}

🛠️ Desarrollo

Agregar Nuevas Herramientas

@mcp.tool("your_tool_name")
async def your_tool(param: str) -> str:
    """Tool description for AI assistant"""
    try:
        # Use controller methods for safe operations
        result = controller.safe_operation(param)
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)}, indent=2)

Extender Seguridad

def create_custom_policy() -> SecurityPolicy:
    """Create a custom security policy"""
    return SecurityPolicy(
        allowed_paths=["/your/paths"],
        forbidden_commands=["dangerous", "commands"],
        # ... other settings
    )

🔧 Solución de Problemas

Problemas Comunes

"El servidor parece colgado"

  • ¡Esto es normal! Los servidores MCP se ejecutan continuamente y se comunican vía stdio
  • El servidor está esperando mensajes del protocolo MCP

"ModuleNotFoundError: No module named 'mcp'"

  • Asegúrese de usar el intérprete de Python del entorno virtual
  • Verifique que su configuración de Claude Desktop use la ruta completa a .venv/bin/python3

Errores de "SecurityViolation"

  • Verifique si la ruta/comando está permitido por su política de seguridad
  • Revise los registros de auditoría en /tmp/ubuntu_mcp_audit.log
  • Considere usar la política de desarrollo para pruebas

Errores de "Permission denied"

  • Verifique que su usuario tenga acceso a las rutas solicitadas
  • Verifique los permisos de archivos/directorios con ls -la

Modo de Depuración

# Enable verbose logging
python main.py --log-level DEBUG --policy secure

# Check audit logs
tail -f /tmp/ubuntu_mcp_audit.log

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulte nuestras Pautas de Contribución para más detalles.

Configuración de Desarrollo

  1. Haga un fork del repositorio
  2. Cree una rama de características: git checkout -b feature/amazing-feature
  3. Haga sus cambios con pruebas
  4. Asegúrese de que todas las pruebas pasen: python main.py --test && python main.py --security-test
  5. Envíe una solicitud de extracción

Estándares de Código

  • Siga las pautas de estilo PEP 8
  • Agregue sugerencias de tipo para todas las funciones públicas
  • Incluya docstrings integrales
  • Escriba pruebas para nuevas funcionalidades
  • Mantenga los principios de seguridad primero

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🔐 Divulgación de Seguridad

Si descubre una vulnerabilidad de seguridad, envíe un correo electrónico a [radjackbartok@proton.me] en lugar de crear un problema público. Nos tomamos la seguridad en serio y responderemos con prontitud.

🙏 Agradecimientos

  • Equipo del Protocolo de Contexto de Modelo por el excelente protocolo
  • Investigadores de seguridad y la comunidad de infosec por las mejores prácticas
  • Comunidad de seguridad de Python por la orientación continua

📈 Hoja de Ruta

  • Registro Mejorado - Registro JSON estructurado con más contexto
  • Soporte de Contenedores - Integración con Docker y políticas conscientes de contenedores
  • Herramientas de Red - Utilidades de red seguras (ping, traceroute, etc.)
  • Gestión de Procesos - Monitoreo y control seguro de procesos
  • Interfaz de Configuración - Interfaz web para gestión de políticas
  • Pruebas de Integración - Pruebas integrales de extremo a extremo
  • Optimización de Rendimiento - Caché y mejoras de rendimiento
  • Soporte Multi-Usuario - Controles de acceso basados en roles

Hecho para la comunidad de IA consciente de la seguridad

💡 Consejo Profesional: Comience con la política segura y aumente gradualmente los permisos según sea necesario. ¡Es más fácil agregar permisos que recuperarse de un incidente de seguridad!