McpSentinel — Secure Infrastructure Gateway for Model Context Protocol

McpSentinel é um gateway corporativo de segurança e mediação para o Model Context Protocol (MCP), projetado para conceder a agentes autônomos de Inteligência Artificial acesso controlado, governado e auditável a ferramentas operacionais de infraestrutura de nuvem (Amazon Web Services) e gestão de código (GitLab e Azure Repos).

O McpSentinel atua como uma barreira de proteção de borda (security edge proxy), centralizando a execução de ferramentas, interceptando requisições, aplicando controle de acesso baseado em papéis (RBAC) multi-tenant e gerando uma trilha de auditoria síncrona com bloqueio imediato (fail-secure).

---

🛡️ Princípios de Arquitetura e Segurança

O gateway foi concebido sob cinco pilares de segurança fundamentais:

flowchart LR
    A[Agente IA / Cliente MCP] -->|1. Bearer Token via SSE| B(McpSentinel Edge Gateway)
    B -->|2. RBAC & Tenant Check| C{Permitido?}
    C -- Não -->|Bloqueio Imediato & Log BLOCKED| A
    C -- Sim -->|3. Log Síncrono PENDING| D[(Audit Trail / stdout)]
    D -->|4. STS AssumeRole / PAT| E[Infraestrutura: AWS / Git]
    E -->|5. Sanitização REDACTED| B
    B -->|6. Log SUCCESS & Resposta Segura| A

1. Zero Credential Leakage: Nenhuma credencial privilegiada de nuvem (IAM Keys, credenciais STS) ou tokens de repositório (PATs) é exposta ou trafegada para o cliente de IA. Todas as operações são mediadas pelo gateway, que assume temporariamente IAM Roles via AWS STS e despacha comandos com menor privilégio estrito.
2. Gestão Declarativa via GitOps: Identidades de agentes, perfis RBAC e tenants autorizados são integralmente modelados em arquivo declarativo versionado (config/security.yaml). Mudanças passam por revisão por pares e esteiras de CI/CD, sem dependência de banco de dados relacional ou painel web mutável.
3. RBAC Multi-Tenant e Filtragem Dinâmica de Catálogo:
   • Descoberta (tools/list): O catálogo MCP é dinamicamente filtrado; agentes visualizam estritamente as ferramentas autorizadas para seu respectivo perfil.
   • Invocação (tools/call): Validação mandatória em tempo de execução garantindo que a ferramenta solicitada e o tenant/conta AWS de destino pertençam ao escopo do agente autenticado.
4. Trilha de Auditoria Síncrona Fail-Secure: Cada invocação emite um evento estruturado em JSONLines na entrada (PENDING) e na saída (SUCCESS, FAILED ou BLOCKED). Sob a política Fail-Secure, qualquer falha no subsistema de persistência de log bloqueia incondicionalmente a chamada da ferramenta, garantindo que nenhuma ação seja executada sem rastro forense.
5. Higienização e Mascaramento Automático: Todos os payloads de entrada, saída e registros de log passam por sanitização recursiva, substituindo senhas, tokens e parâmetros sensíveis pelo marcador [REDACTED].

---

📋 Requisitos de Ambiente

• Sistema Operacional: Linux (x86_64 ou ARM64) ou macOS.
• Runtime: Python >= 3.12.
• Gerenciador de Pacotes e Toolchain: uv (recomendado) ou pip/venv.
• Credenciais de Provedor: AWS Credentials configuradas no ambiente hospedeiro via variáveis de ambiente padrão (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION), arquivo de credenciais ~/.aws/credentials ou perfil de instância/IAM Role (EC2/ECS/EKS).

---

⚡ Instalação

Via PyPI (Recomendado para uso)

pip install mcpsentinel-gateway

A partir do código-fonte (Desenvolvimento)

Clone o repositório e sincronize o ambiente virtual isolado com o uv:

# Clone do repositório
git clone https://github.com/Defendi/McpSentinel.git
cd McpSentinel

# Criação do venv e instalação de todas as dependências (incluindo dev)
uv sync

Caso utilize o pip padrão:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

---

⚙️ Configuração

O McpSentinel é configurado via variáveis de ambiente e arquivos declarativos versionados.

Variáveis de Ambiente Suportadas

As variáveis podem ser definidas no ambiente do sistema operacional ou em um arquivo .env na raiz do projeto:

Variável	Padrão	Descrição
SENTINEL_AUTH_TOKEN	sentinel-secret-token	Bearer token legado de fallback para validação de requisições HTTP.
SENTINEL_SECURITY_CONFIG	config/security.yaml	Caminho do arquivo de configuração declarativa GitOps (RBAC e agentes).
SENTINEL_AUDIT_LOG_PATH	logs/audit.log	Caminho do arquivo local para persistência síncrona de eventos de auditoria JSONLines.
SENTINEL_HOST	0.0.0.0	Endereço IP de ligação do servidor ASGI.
SENTINEL_PORT	8000	Porta TCP de escuta do servidor HTTP/SSE.
SENTINEL_ENVIRONMENT	development	Ambiente operacional (development, staging, production).
SENTINEL_LOG_LEVEL	INFO	Nível de logging da aplicação (DEBUG, INFO, WARNING, ERROR).

Configuração Declarativa GitOps (config/security.yaml)

O arquivo config/security.yaml define formalmente a tríade de segurança: Tenants, Profiles e Agents. Suporta interpolação de variáveis de ambiente com valores padrão ${VAR_NAME:-default}.

version: "1.0"

# 1. Tenants corporativos (Contas de nuvem e escopos)
tenants:
  aws_accounts:
    - id: "dev-account"
      account_id: "111122223333"
      name: "Ambiente de Desenvolvimento"
      allowed_regions:
        - "us-east-1"
        - "sa-east-1"

# 2. Perfis RBAC
profiles:
  sre_operations:
    description: "Perfil operacional SRE"
    tools:
      - "aws_get_caller_identity"
    allowed_tenants:
      aws_accounts:
        - "dev-account"

# 3. Identidades dos agentes clientes
agents:
  - agent_id: "agent-sre-01"
    name: "Agente Operacional SRE Principal"
    token: "${SENTINEL_TOKEN_SRE:-token-sre-01-secret}"
    profile: "sre_operations"

Restrição de Rede (Allowlist de IPs e Interfaces)

O McpSentinel pode restringir o acesso apenas a IPs e redes autorizadas (via blocos CIDR) e configurar em quais interfaces de rede o servidor irá escutar.

Exemplo no arquivo config/security.yaml:

network_filter:
  bind_addresses:
    - "127.0.0.1"       # Escuta apenas em localhost IPv4
    - "::1"             # Escuta apenas em localhost IPv6
  allowed_origins:
    - "192.168.1.100"   # IP exato autorizado
    - "10.0.0.0/24"     # Bloco CIDR (toda a sub-rede 10.0.0.x autorizada)

Variáveis de Ambiente: Também é possível configurar a restrição de rede passando variáveis de ambiente (separadas por vírgula):

• Origens permitidas: ALLOWED_IPS, ALLOWED-IP, ALLOWED_IP, SENTINEL_ALLOWED_IPS, SENTINEL_ALLOWED_IP
• Interfaces de escuta: BIND_INTERFACES, BIND-INTERFACES, BIND_INTERFACE, SENTINEL_BIND_INTERFACES, SENTINEL_BIND_INTERFACE

Exemplo: ALLOWED_IPS="192.168.1.10,10.0.0.0/24"

Precedência: Argumentos da CLI (--allow-ip, --bind) sobrescrevem Variáveis de Ambiente, que sobrescrevem o security.yaml.

---

🚀 Inicialização do Servidor

Execução via CLI Integrada (Recomendada)

O McpSentinel provê uma CLI embutida com suporte a configuração de rede, portas e regras de restrição de origens dinamicamente.

# Iniciar o servidor utilizando as configurações do security.yaml
uv run python -m mcpsentinel.server

# Sobrescrever as configurações de IP e portas dinamicamente via flags
uv run python -m mcpsentinel.server --bind 0.0.0.0 --port 8080 --allow-ip 10.0.0.0/24 --allow-ip 192.168.1.50

Você pode visualizar a ajuda completa da CLI via:

uv run python -m mcpsentinel.server --help

Execução Direta via Uvicorn

Caso prefira, você também pode inicializar a aplicação ASGI Starlette diretamente:

uv run uvicorn mcpsentinel.api.app:app --host 0.0.0.0 --port 8000

O gateway inicializará e disponibilizará o endpoint MCP SSE em:

• SSE Connection Endpoint: http://localhost:8000/sse
• Messages POST Endpoint: http://localhost:8000/messages/

---

🔌 Conectando Clientes MCP

Todos os clientes devem enviar o cabeçalho de autenticação HTTP padrão:

Authorization: Bearer <TOKEN_DO_AGENTE>

1. Claude Desktop

Configure o arquivo de configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcpsentinel": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer token-sre-01-secret"
      }
    }
  }
}

2. Chamadas HTTP Diretas (curl / httpx)

Você pode validar a inicialização e escuta da conexão SSE com o utilitário curl:

# Conectar ao stream de eventos SSE com Bearer Token
curl -N -H "Authorization: Bearer token-sre-01-secret" \
  http://localhost:8000/sse

Em caso de credencial ausente ou inválida, o gateway rejeita imediatamente com HTTP 401:

curl -i http://localhost:8000/sse
# HTTP/1.1 401 Unauthorized
# {"error": "Unauthorized", "code": "AUTHENTICATION_ERROR", "detail": "Missing Authorization header"}

---

🧪 Quality Gates e Testes Herméticos

O projeto possui uma suíte hermética de testes de unidade, integração e segurança, sem dependências de infraestrutura externa viva em runtime de teste.

Execução de Testes com Cobertura

# Execução da suíte completa com relatório de cobertura detalhado
uv run pytest --cov=src/mcpsentinel --cov-report=term-missing

Status atual da cobertura: 97% em 134 testes automatizados.

Inspeção Estática de Código e Tipagem

# Validação de formatação e linting estrito com Ruff
uv run ruff check

# Checagem estrita de tipos estáticos com Mypy
uv run mypy src

---

📚 Rastreabilidade e Documentação do Harness

Este repositório adota a disciplina canônica do Application Development Harness. Consulte a documentação complementar em docs/:

• Manual de Operação e Governança: docs/manual-de-operacao.md — Guia detalhado para o Administrador de Segurança (AT-01).
• Technical Requirements Document (TRD): docs/trd.md — Requisitos não-funcionais, stack e limites arquiteturais globais.
• Registros de Decisões Arquiteturais (ADRs):
  • ADR 001: Transporte Remoto HTTP para Servidor MCP Centralizado
  • ADR 002: Modelo de Segurança Declarativo GitOps, RBAC e Guardrails Operacionais
  • ADR 003: Trilha de Auditoria Síncrona Estruturada em JSON sob Paradigma Fail-Secure
• Especificações de Funcionalidades: docs/specs/
• Product Requirements Documents: docs/prds/