mcpsafetywarden

O MCP safety warden é um servidor proxy que encapsula qualquer servidor MCP e adiciona perfilamento comportamental, varredura de segurança, controle de risco e execução segura às suas ferramentas.

Conteúdo

• Visão Geral
• Pré-requisitos
• Instalação
• Configuração
• Integração MCP
• Referência da CLI
• Integrações Auxiliares
• Desenvolvimento
• Testes
• Leitura Adicional

[!IMPORTANT] A segurança MCP é uma área de pesquisa ativa. Pesquisas recentes catalogam várias categorias de ameaças específicas do protocolo, abrangendo envenenamento de ferramentas, injeção de prompt, ataques de rug-pull, comprometimento da cadeia de suprimentos, exfiltração de credenciais e ataques de composição em todo o ciclo de vida do servidor. Veja Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv) e MCP-38 Taxonomy (arXiv).

Visão Geral

Use como proxy para adicionar controle de segurança a qualquer servidor MCP, ou aponte-o para um servidor que você não possui e execute uma auditoria de segurança completa sem fazer uma única chamada de ferramenta.

Fig 1. Dois modos de operação: proxy e auditoria

Perfilamento comportamental: Classe de efeito, segurança de repetição, destrutividade. Assistido por LLM (Anthropic, OpenAI, Gemini, Ollama) com fallback baseado em regras. Estatísticas observadas (latência p50/p95, taxa de falha, tamanho da saída) atualizadas após cada chamada com proxy.

Varredura de segurança: mcpsafety+ pipeline de cinco estágios (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (análise de metadados). As integrações com Kali e Burp Suite enriquecem o pipeline com dados reais de rede e sondas na camada HTTP. Varredura de código-fonte do GitHub com detecção de entropia, AST, fluxo de taint e detecção de rug-pull.

Fig 2. Pipeline de cinco estágios do mcpsafety+, acionado quando você executa uma auditoria de segurança completa em qualquer servidor MCP

Execução segura: Varredura de argumentos (20+ categorias de ataque, segunda passagem por LLM). Varredura de injeção de saída em duas camadas. Controle de risco com alternativas e políticas por ferramenta. Detecção de deriva em cada chamada e verificação independente.

Fig 3. Pipeline de execução segura: as cinco verificações pelas quais toda chamada de ferramenta com proxy passa

CLI: 24 subcomandos, menu interativo de risco, sinalizador --json em todos os comandos, --yes para CI.

O que detecta

• Injeção de prompt: saídas de ferramentas que tentam sequestrar o agente: sequestro de função, jailbreaks, prompts falsos do sistema, substituições de instruções. Detecta 11 técnicas de ofuscação, incluindo semelhantes Unicode, caracteres de largura zero e payloads codificados em base64.
• Metadados maliciosos de ferramentas: descrições contendo strings de injeção, segredos codificados, URLs de download suspeitos, personificação de ferramentas (shadowing), execução financeira direta, modificação de serviços do sistema e dependências externas não confiáveis. Suportado por 19 verificações do Snyk.
• Injeção de argumentos: 20+ categorias de ataque verificadas em cada chamada de ferramenta antes do encaminhamento: SSRF para endpoints de metadados da nuvem (AWS, GCP, Azure, Alibaba), path traversal, acesso a arquivos de credenciais (.aws, .ssh, .kube, .env), injeção de comando, injeção SQL/NoSQL/LDAP/XPath, XXE, injeção de template (SSTI), CRLF, null byte, payloads de desserialização (Java, Python pickle, PHP, .NET), ataques Windows UNC/ADS e variantes ofuscadas em base64 de todos os acima.
• Riscos no código-fonte: obtém o código-fonte do servidor no GitHub e executa 6 camadas de análise: varredura de entropia para segredos codificados, rastreamento de fluxo de taint AST (parâmetro para sink perigoso), incompatibilidade entre descrição e implementação, SAST com Bandit e Semgrep, e raciocínio entre funções via LLM. Suporta Python e TypeScript/JavaScript.
• Rug-pull e deriva: armazena um hash SHA-256 do código-fonte do servidor na primeira varredura e alerta se ele mudar. Captura trocas de descrição, mudanças de esquema e remoção de ferramentas ao vivo em cada chamada por meio de um guarda de deriva por chamada.
• Anomalias comportamentais: classifica cada ferramenta por classe de efeito, destrutividade e 7 tags de risco: exposição de credenciais, execução arbitrária, exfiltração de dados, acesso ao sistema de arquivos, movimento lateral, escalonamento de privilégios e superfície de injeção de prompt.
• Ataques de composição: analisa conjuntos de ferramentas para riscos de encadeamento: cadeias IDOR, pares de leitura-escrita, exploração de fluxo de autenticação, sequências de escrever-depois-executar e caminhos de acúmulo de dados + exfiltração em múltiplas ferramentas.
• Riscos de rede e hospedeiro: quando o Kali Linux MCP está registrado: portas abertas, serviços em execução, impressão digital do SO via nmap. Quando o Burp Suite MCP está registrado: sondagem ativa na camada HTTP e SSRF cego via callbacks fora de banda.
• Exposição de credenciais nas saídas: redige segredos das respostas das ferramentas antes do armazenamento. Respostas sinalizadas por injeção são colocadas em quarentena e nunca retornadas ao agente chamador - armazenadas sob um ID de execução para revisão forense.

Pré-requisitos

• Python 3.10 ou posterior
• Pelo menos um servidor MCP encapsulado para usar como proxy (stdio, SSE ou streamable_http)
• Recomendado: uma chave de API LLM (Anthropic, OpenAI ou Gemini)

Sem uma chave, o wrapper opera apenas no modo baseado em regras: classificação de ferramenta com menor confiança, varredura de injeção apenas com regex, sem alternativas no controle de risco, sem pipeline mcpsafety+. Para uma configuração totalmente local, execute Ollama, defina OLLAMA_MODEL e passe --provider ollama explicitamente (Ollama não é detectado automaticamente).

[!NOTE] Servidores stdio que exigem configuração local (servidores stdio que precisam de configuração local antes de iniciar - arquivos de configuração ausentes, credenciais, diretórios de dados ou dependências específicas do SO) não podem ser inspecionados pelo wrapper - a descoberta de ferramentas falhará e 0 ferramentas serão armazenadas. Você ainda pode executar uma varredura de segurança completa do código-fonte sem iniciar o servidor passando --github-url para scan / onboard, ou o parâmetro github_url para security_scan_server. O pipeline mcpsafety+ buscará e analisará o código-fonte diretamente do GitHub. Servidores sse e streamable_http não são afetados.

Instalação

pip install mcpsafetywarden

Com todos os extras opcionais:

pip install "mcpsafetywarden[all]"

Ou extras específicos:

pip install "mcpsafetywarden[anthropic,snyk]"

A partir da fonte:

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

O banco de dados SQLite é criado automaticamente na primeira execução no diretório de dados do usuário da plataforma (~/.local/share/mcpsafetywarden/ no Linux, ~/Library/Application Support/mcpsafetywarden/ no macOS, %APPDATA%\mcpsafetywarden\ no Windows). Substitua com MCP_DB_PATH.

Proteção de credenciais (automática, nenhuma ação necessária)

Valores secretos passados para register_server ou onboard_server (tokens Bearer, chaves de API em headers ou env) são automaticamente detectados e substituídos por identificadores opacos cref_ antes que qualquer coisa toque no contexto do modelo. A credencial real é armazenada criptografada no banco de dados e resolvida silenciosamente no momento da conexão. O modelo, o histórico da conversa e os logs veem apenas cref_<id>.

Opcional: criptografia em repouso para credenciais armazenadas

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Defina a chave impressa como MCP_DB_ENCRYPTION_KEY antes de iniciar o servidor. Isso criptografa tanto as credenciais do servidor quanto os valores cref_ em repouso.

Configuração

Toda a configuração é feita através de variáveis de ambiente.

Nota de segurança: Nunca faça commit de chaves de API ou da chave de criptografia. O wrapper remove seus próprios segredos dos ambientes de processos filhos antes de iniciar servidores stdio.

Integração MCP

Conectando com o Claude Desktop

Adicione o wrapper ao claude_desktop_config.json:

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<chave_fernet_gerada>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/seunome/Documentos"]
    }
  }
}

Registre cada servidor com o wrapper antes de usar:

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/seunome/Documentos"]'

Para uma configuração de gateway obrigatório onde todas as chamadas de ferramenta devem passar pelo wrapper, veja docs/DEPLOYMENT.md.

Ferramentas MCP disponíveis

Veja docs/TOOLS.md para a referência completa das ferramentas.

Referência da CLI

24 subcomandos cobrindo todas as 25 ferramentas MCP. Todo comando suporta --json para saída legível por máquina e --yes / -y para pular prompts de confirmação.

Veja docs/CLI.md para a referência completa com sinalizadores e exemplos.

Integrações de Ferramentas de Segurança Auxiliares

Kali Linux MCP, Burp Suite MCP e Snyk integram-se automaticamente uma vez registrados. O Kali enriquece o estágio Recon e ping_server com dados reais de nmap/traceroute. O Burp adiciona sondagem HTTP bruta, callbacks fora de banda e evidências de proxy. O Snyk analisa metadados de ferramentas em busca de strings de injeção, shadowing de ferramentas, segredos codificados e outras 16 verificações.

Veja docs/INTEGRATIONS.md para instruções de configuração.

Desenvolvimento

Instale em modo editável:

pip install -e ".[all]"

Execute o servidor e observe os logs:

mcpsafetywarden-server 2>server.log

Cada módulo usa logging.getLogger(__name__). O servidor não chama logging.basicConfig por conta própria - configure o logging no seu ponto de entrada antes de importar.

Testes

pytest tests/ -v

Defina uma chave de API LLM para incluir testes assistidos por LLM; sem ela, eles são pulados automaticamente. Veja docs/TESTING.md para verificação passo a passo de classificação, varredura de injeção, controle de risco e aplicação de políticas.

Leitura Adicional

Contribuindo

Veja CONTRIBUTING.md para padrões de código e diretrizes de pull requests.

Licença

Licença Apache 2.0. Veja LICENSE para detalhes.