Servidor MCP seguro para Ubuntu

🔒 S ervidor de protocolo de contexto de modelo seguro para operaciones seguras del sistema Ubuntu

Un servidor de Protocolo de Contexto de Modelo (MCP ) endurecido y listo para la producción 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.

características principales

🛡️ Arquitectura Security-First

• Resolución de Symlink con controles allowlist/denylist
• Saneamiento de comandos - Prevención de inyección de shell con análisis seguro de argumentos
• Límites de recursos: controles de tamaño de archivo, tiempo de espera de ejecución y tamaño de salida
• Registro de auditoría exhaustivo: todas las operaciones se registran con atribución al usuario
• Defensa en profundidad - Múltiples capas de seguridad con valores predeterminados a prueba de fallos

funciones básicas

• Operaciones con archivos - Lectura, escritura y listado de directorios con validación de permisos
• Ejecución de comandos - Ejecución segura de comandos shell con filtrado de listas blancas y negras
• Información del sistema - Detalles del sistema operativo, memoria y monitorización del uso del disco
• Gestión de paquetes - Búsqueda y listado de paquetes APT (la instalación requiere una configuración explícita)

🏗️ Preparado para la producción

• Diseño modular con una clara separación de intereses
• Gestión integral de errores con mensajes de error significativos
• Amplio conjunto de pruebas, incluidas pruebas de validación de seguridad
• Políticas configurables para diferentes casos de uso y entornos
• Seguridad de dependencia cero: la seguridad del núcleo 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 estándar de Unix (ls, cat, echo, etc.)

Instalación

# Clonar el repositorio git clone https://github.com/yourusername/secure-ubuntu-mcp.git cd secure-ubuntu-mcp # Crear y activar el entorno virtual python3 -m venv .venv source .venv/bin/activate # Instalar las dependencias pip install -r requirements.txt # Verificar la instalación con las pruebas incorporadas python main.py --test

Uso básico

# Iniciar con política segura (recomendado) python main.py --policy secure # Iniciar con política de desarrollo (más permisiva) python main.py --policy dev # Probar medidas de seguridad python main.py --security-test

🔧 Integración

Claude Desktop

Cómo obtener Claude Desktop en Linux

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

Método recomendado: Utilice el paquete Debian de la comunidad por @aaddrick:

# Descargue e instale Claude Desktop para 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 # Solucione cualquier problema de dependencia

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

Configuración

Una vez instalado Claude Desktop, añada 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: Utilizar rutas absolutas y el intérprete Python del entorno virtual

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

Otros clientes MCP

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

# Ejemplo con cliente mcp Python import asyncio from mcp.client import ClientSession async def ejemplo(): # Conectarse al servidor # La implementación depende de su pase de cliente MCP

🛡️ Políticas de seguridad

Política de seguridad (por defecto)

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 (sólo búsqueda)
• Límites de recursos: archivos de 1MB, tiempos de espera de 15s, salida de 256KB
• Sudo: Desactivado
• Ejecución Shell: Desactivado (utiliza ejecución directa segura)

Política de desarrollo

Más permisiva para entornos de desarrollo:

• Rutas adicionales permitidas: /opt, /usr/local
• Menos restricciones: Acceso a más áreas del sistema
• Límites más amplios: archivos de 10 MB, tiempos de espera de 60 s, salida de 1 MB
• Más comandos: Se permiten la mayoría de las herramientas de desarrollo
• Sudo: sigue desactivado por defecto (puede activarse)

Políticas personalizadas

Crea tu propia política de seguridad:

from main import SecurityPolicy custom_policy = SecurityPolicy( allowed_paths=["/su_ruta/personalizada"], forbidden_paths=["/áreas/sensibles"], allowed_commands=["seguro", "comandos"], forbidden_commands=["peligroso", "comandos"], max_command_timeout=30, allow_sudo=False, # Usar con extrema precaución audit_actions=True )

🔍 Herramientas disponibles

Operaciones con archivos

• list_directory(ruta) - Lista el contenido del directorio con metadatos
• read_file(file_path) - Leer el contenido de un archivo 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 shell de forma segura
• get_system_info() - Obtener información sobre el sistema operativo, la memoria y el disco

Gestión de paquetes

• search_packages(query) - Buscar en los repositorios de APT
• install_package(nombre_paquete) - Comprueba la disponibilidad de paquetes (sólo listado)

funciones de seguridad

Protección contra ataques comunes

Prevención de path traversal:

# Todos estos están bloqueados: ../../../etc/passwd /etc/passwd /tmp/../etc/passwd symlinks_to_sensitive_files

Prevención de inyección de comandos:

# Todos estos están bloqueados: echo hello; rm -rf / echo `cat /etc/passwd` echo $(whoami) ls | rm -rf /

Protección contra el agotamiento de recursos:

• Los límites de tamaño de archivo evitan el agotamiento de memoria
• Los tiempos de espera de ejecución evitan que los procesos se cuelguen
• Los límites de tamaño de salida evitan la inundación de registros
• Los límites de listado de directorios evitan ataques de enumeración

Registro de auditoría

Todas las operaciones se registran con:

• Atribución del usuario
• Marca de tiempo y tipo de operación
• Resolución completa de la ruta
• Estado de éxito/fracaso
• Detalles de la violación de seguridad

pruebas

Pruebas de funcionalidad

# Probar la funcionalidad del núcleo python main.py --test

Validación de seguridad

# Ejecutar pruebas de seguridad completas python main.py --security-test

Pruebas manuales

# Probar el protocolo MCP directamente python test_client.py --simple

📊 Ejemplo de uso

Una vez integrado con un asistente de IA:

Monitorización del sistema:

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

Gestión de archivos:

"Listar los archivos de mi directorio personal y mostrarme los más grandes"

Tareas de desarrollo:

"Comprobar si Python está instalado y mostrarme la versión"

Análisis de registros:

"Buscar cualquier archivo de error en el directorio de mi 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

Crear config.json para la configuración personalizada:

{ "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

Añadir nuevas herramientas

@mcp.tool("tu_nombre_de_herramienta") async def tu_herramienta(param: str) -> str: """Descripción de la herramienta para el asistente AI""" try: # Usa métodos del controlador para operaciones seguras result = controller.safe_operation(param) return json.dumps(result, indent=2) except Exception as e: return json.dumps({"error": str(e)}, indent=2)

Ampliación de la seguridad

def create_custom_policy() -> SecurityPolicy: """Crear una política de seguridad personalizada""" return SecurityPolicy( allowed_paths=["/tus/rutas"], forbidden_commands=["peligrosos", "comandos"], # ... otros ajustes )

🔧 Solución de problemas

Problemas comunes

"El servidor parece colgarse"

• ¡Esto es normal! Los servidores MCP funcionan continuamente y se comunican a través de stdio
• El servidor está esperando mensajes del protocolo MCP

"ModuleNotFoundError: No module named 'mcp'"

• Asegúrese de que está utilizando el intérprete Python del entorno virtual
• Compruebe que su configuración de Claude Desktop utiliza la ruta completa a .venv/bin/python3

"Errores "SecurityViolation

• Compruebe 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 el uso de la política de desarrollo para las pruebas

"Errores de "Permiso denegado

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

Modo Debug

# Habilite el registro detallado python main.py --log-level DEBUG --policy secure Compruebe los registros de auditoría tail -f /tmp/ubuntu_mcp_audit.log

🤝 Contribuir

¡Damos la bienvenida a las contribuciones! Por favor, vea nuestras Directrices de Contribución para más detalles.

Configuración de desarrollo

1. Abrir el repositorio
2. Crea una rama: git checkout -b feature/amazing-feature
3. Haga sus cambios con pruebas
4. Asegúrese de que todas las pruebas pasan: python main.py --test && python main.py --security-test
5. Envía un pull request

Normas de código

• Siga las directrices de estilo PEP 8
• Añadir sugerencias de tipo para todas las funciones públicas
• Incluir documentación completa
• Escribir pruebas para las nuevas funciones
• Mantener los principios de seguridad en primer lugar

📄 Licencia

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

🔐 Revelación de seguridad

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

🙏 Agradecimientos

• Al equipo deModel Context Protocol por el excelente protocolo
• Investigadores de seguridad y la comunidad 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
• Compatibilidad con contenedores - Integración con Docker y políticas compatibles con contenedores
• Herramientas de red - Utilidades de red seguras (ping, traceroute, etc.)
• Gestión de procesos: supervisión y control de procesos seguros
• Interfaz de usuario de configuración: interfaz web para la gestión de políticas
• Pruebas de integración - Pruebas completas de extremo a extremo
• Optimización del rendimiento: almacenamiento en caché y mejoras del rendimiento
• Soporte Multi-Usuario - Controles de acceso basados en roles

Hecho para la comunidad de IA preocupada por la seguridad

consejo profesional: Comience con la política segura y aumente gradualmente los permisos según sea necesario. ¡Es más fácil añadir permisos que recuperarse de un incidente de seguridad!