Secure Ubuntu MCP Server

Um servidor MCP focado em segurança para realizar operações seguras em um sistema Ubuntu, com controles de segurança robustos e registro de auditoria.

GitHub
44

Documentação

Secure Ubuntu MCP Server

🔒 Segurança em Primeiro Lugar — Servidor Model Context Protocol para operações seguras do sistema Ubuntu

Um servidor Model Context Protocol (MCP) endurecido e pronto para produção que fornece a assistentes de IA acesso seguro e controlado às operações do sistema Ubuntu. Construído com controles de segurança abrangentes, registro de auditoria e princípios de defesa em profundidade.

License: MIT Python 3.9+ Security Focused MCP Compatible

✨ Principais Recursos

🛡️ Arquitetura com Segurança em Primeiro Lugar

  • Proteção contra travessia de caminho — Resolução de symlinks com controles de allowlist/denylist
  • Sanitização de comandos — Prevenção de injeção de shell com análise segura de argumentos
  • Limites de recursos — Tamanho de arquivo, timeouts de execução e controles de tamanho de saída
  • Registro de auditoria abrangente — Todas as operações registradas com atribuição de usuário
  • Defesa em profundidade — Múltiplas camadas de segurança com padrões de fail-safe

🎯 Capacidades Principais

  • Operações de Arquivo — Ler, escrever e listar diretórios com validação de permissão
  • Execução de Comandos — Execução segura de comandos shell com filtragem de whitelist/blacklist
  • Informações do Sistema — Detalhes do SO, memória e monitoramento de uso de disco
  • Gerenciamento de Pacotes — Busca e listagem de pacotes APT (instalação requer configuração explícita)

🏗️ Pronto para Produção

  • Design modular com clara separação de responsabilidades
  • Tratamento abrangente de erros com mensagens de erro significativas
  • Suíte de testes extensiva incluindo testes de validação de segurança
  • Políticas configuráveis para diferentes casos de uso e ambientes
  • Segurança com zero dependências — A segurança principal não depende de pacotes externos

🚀 Início Rápido

Pré-requisitos

  • Ubuntu 18.04+ (testado em 20.04, 22.04, 24.04)
  • Python 3.9 ou superior
  • Utilitários Unix padrão (ls, cat, echo, etc.)

Instalação

# 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

🔧 Integração

Claude Desktop

Obtendo o Claude Desktop no Linux

Suporte Oficial: O Claude Desktop não suporta oficialmente Linux, mas a comunidade criou soluções!

Método Recomendado: Use o pacote Debian da comunidade 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 outros métodos e solução de problemas, consulte: https://github.com/aaddrick/claude-desktop-debian

Configuração

Depois que o Claude Desktop estiver instalado, adicione à sua configuração (~/.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 caminhos absolutos e o interpretador Python do ambiente virtual

Verificação: Após reiniciar o Claude Desktop, você deve ver "secure-ubuntu" listado como um servidor conectado, e o Claude terá acesso às ferramentas de controle do sistema.

Outros Clientes MCP

O servidor implementa o protocolo MCP padrão e funciona com qualquer cliente compatível com 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 Segurança

Política Segura (Padrão)

Recomendada para ambientes de produção e não confiáveis:

  • Caminhos Permitidos: ~/, /tmp, /var/tmp
  • Caminhos Proibidos: /etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
  • Whitelist de Comandos: ls, cat, echo, pwd, whoami, date, find, grep, apt (somente busca)
  • Limites de Recursos: Arquivos de 1MB, timeouts de 15s, saída de 256KB
  • Sudo: Desabilitado
  • Execução de Shell: Desabilitada (usa execução direta segura)

Política de Desenvolvimento

Mais permissiva para ambientes de desenvolvimento:

  • Caminhos Permitidos Adicionais: /opt, /usr/local
  • Menos Restrições: Acesso a mais áreas do sistema
  • Limites Maiores: Arquivos de 10MB, timeouts de 60s, saída de 1MB
  • Mais Comandos: A maioria das ferramentas de desenvolvimento permitidas
  • Sudo: Ainda desabilitado por padrão (pode ser habilitado)

Políticas Personalizadas

Crie sua própria política de segurança:

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
)

🔍 Ferramentas Disponíveis

Operações de Arquivo

  • list_directory(path) — Lista o conteúdo do diretório com metadados
  • read_file(file_path) — Lê o conteúdo do arquivo com validação de tamanho
  • write_file(file_path, content, create_dirs=False) — Escreve com operações atômicas

Operações do Sistema

  • execute_command(command, working_dir=None) — Executa comandos shell com segurança
  • get_system_info() — Obtém informações de SO, memória e disco

Gerenciamento de Pacotes

  • search_packages(query) — Busca em repositórios APT
  • install_package(package_name) — Verifica disponibilidade de pacotes (somente listagem)

🔒 Recursos de Segurança

Proteção Contra Ataques Comuns

Prevenção de Travessia de Caminho:

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

Prevenção de Injeção de Comandos:

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

Proteção Contra Exaustão de Recursos:

  • Limites de tamanho de arquivo previnem exaustão de memória
  • Timeouts de execução previnem processos pendurados
  • Limites de tamanho de saída previnem inundação de logs
  • Limites de listagem de diretórios previnem ataques de enumeração

Trilha de Auditoria

Todas as operações são registradas com:

  • Atribuição de usuário
  • Timestamp e tipo de operação
  • Resolução completa do caminho
  • Status de sucesso/falha
  • Detalhes de violação de segurança

🧪 Testes

Testes de Funcionalidade

# Test core functionality
python main.py --test

Validação de Segurança

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

Testes Manuais

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

📊 Exemplo de Uso

Depois de integrado com um assistente de IA:

Monitoramento do Sistema:

"Verifique o status do meu sistema e o espaço em disco"

Gerenciamento de Arquivos:

"Liste os arquivos no meu diretório home e mostre-me os maiores"

Tarefas de Desenvolvimento:

"Verifique se o Python está instalado e mostre-me a versão"

Análise de Logs:

"Procure por arquivos de erro no meu diretório de projeto"

⚙️ Configuração

Variáveis de Ambiente

  • MCP_LOG_LEVEL — Nível de registro (DEBUG, INFO, WARNING, ERROR)
  • MCP_POLICY — Política de segurança (secure, dev)
  • MCP_CONFIG_PATH — Caminho para arquivo de configuração personalizado

Arquivo de Configuração

Crie config.json para configurações 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
  }
}

🛠️ Desenvolvimento

Adicionando Novas Ferramentas

@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)

Estendendo a Segurança

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

🔧 Solução de Problemas

Problemas Comuns

"O servidor parece travar"

  • Isso é normal! Servidores MCP rodam continuamente e se comunicam via stdio
  • O servidor está aguardando mensagens do protocolo MCP

"ModuleNotFoundError: No module named 'mcp'"

  • Certifique-se de usar o interpretador Python do ambiente virtual
  • Verifique se a configuração do Claude Desktop usa o caminho completo para .venv/bin/python3

Erros de "SecurityViolation"

  • Verifique se o caminho/comando é permitido pela sua política de segurança
  • Revise os logs de auditoria em /tmp/ubuntu_mcp_audit.log
  • Considere usar a política de desenvolvimento para testes

Erros de "Permission denied"

  • Verifique se seu usuário tem acesso aos caminhos solicitados
  • Verifique as permissões de arquivo/diretório com ls -la

Modo de Depuração

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

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

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes.

Configuração de Desenvolvimento

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade: git checkout -b feature/amazing-feature
  3. Faça suas alterações com testes
  4. Garanta que todos os testes passem: python main.py --test && python main.py --security-test
  5. Envie um pull request

Padrões de Código

  • Siga as diretrizes de estilo PEP 8
  • Adicione type hints para todas as funções públicas
  • Inclua docstrings abrangentes
  • Escreva testes para novas funcionalidades
  • Mantenha os princípios de segurança em primeiro lugar

📄 Licença

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para detalhes.

🔐 Divulgação de Segurança

Se você descobrir uma vulnerabilidade de segurança, envie um e-mail para [radjackbartok@proton.me] em vez de criar um issue público. Levamos a segurança a sério e responderemos prontamente.

🙏 Agradecimentos

  • Equipe do Model Context Protocol pelo excelente protocolo
  • Pesquisadores de segurança e a comunidade de infosec pelas melhores práticas
  • Comunidade de segurança Python pela orientação contínua

📈 Roteiro

  • Registro Aprimorado — Registro JSON estruturado com mais contexto
  • Suporte a Containers — Integração com Docker e políticas cientes de containers
  • Ferramentas de Rede — Utilitários de rede seguros (ping, traceroute, etc.)
  • Gerenciamento de Processos — Monitoramento e controle seguro de processos
  • UI de Configuração — Interface web para gerenciamento de políticas
  • Testes de Integração — Testes abrangentes de ponta a ponta
  • Otimização de Desempenho — Cache e melhorias de desempenho
  • Suporte Multi-Usuário — Controles de acesso baseados em funções

Feito para a comunidade de IA consciente de segurança

💡 Dica Profissional: Comece com a política segura e aumente gradualmente as permissões conforme necessário. É mais fácil adicionar permissões do que se recuperar de um incidente de segurança!