McpSentinel — Secure Infrastructure Edge Gateway para Model Context Protocol

McpSentinel é um Secure Infrastructure Edge Gateway de nível corporativo projetado para o ecossistema do Model Context Protocol (MCP). Sua missão primordial é atuar como uma barreira de proteção de borda (security edge proxy e mediador de controle de acesso), viabilizando que agentes autônomos de Inteligência Artificial e LLMs interajam de forma governada, segura e auditável com ferramentas operacionais de infraestrutura de nuvem (Amazon Web Services), gestão de código/DevOps (GitLab e Azure Repos), automações (Ansible AWX / Tower) e esteiras de CI/CD (Jenkins).

Ao isolar completamente o cliente IA do plano direto de execução de comandos, o McpSentinel intercepta todas as requisições em tempo real, aplica controle de acesso baseado em papéis (RBAC Declarativo GitOps), valida salvaguardas para ações de alto impacto (Tríade de Confirmação), impõe filtragem de tráfego de rede (Allowlist CIDR) e gera uma trilha forense síncrona sob a política estrita de Fail-Secure.

📑 Sumário

• 🏗️ Arquitetura e Fluxo de Borda
• 🛡️ Pilares Fundamentais de Segurança
• ⚙️ Inventário Completo de Configurações
  • Precedência Canônica de Configurações
  • Arquivo Canônico de Configuração: mcpsentinel.conf
  • Variáveis de Ambiente e Suporte a .env
  • Arquivo Declarativo GitOps: config/security.yaml
• 🔐 Resolução Dinâmica de Segredos via Vaultwarden / Bitwarden Secrets Manager
  • Como Funciona o Esquema de URI vaultwarden://
  • Pré-requisitos Operacionais
  • Exemplos Práticos de Configuração
  • Tratamento de Falhas, Timeouts e Fail-Secure
• ⚡ Guia de Instalação e Uso (Quickstart)
  • Instalação e Uso Direto via PyPI (pip / uv tool / pipx / uvx)
  • Desenvolvimento Local e Contribuição (Repositório Git)
  • Inicialização do Ambiente de Configuração (mcpsentinel init)
  • Assistente Interativo de Configuração (mcpsentinel configure)
  • Comandos da CLI do Gateway (mcpsentinel)
  • Gerenciamento como Serviço Systemd no Linux (CLI)
  • Controle Inter-Processos do Daemon (mcpsentinel ctl)
• 🔌 Guia de Integração com Clientes MCP
• 🐳 Implantação em Produção e Contêineres
  • Dockerfile Multi-Stage com CLI bws
  • Execução via Docker Compose
  • Execução Nativa como Serviço Systemd
• 🧪 Testes Herméticos e Quality Gates
• 📚 Documentação Complementar do Harness
• 📄 Licença e Governança

🏗️ Arquitetura e Fluxo de Borda

O fluxo de dados e execução do McpSentinel é estruturado em pipeline estrito de interceptores assíncronos (ASGI / Starlette / FastMCP), garantindo que nenhuma requisição não autorizada ou maliciosa atinja os provedores de infraestrutura:

flowchart TD
    subgraph Client["Camada de Agente IA / Cliente MCP"]
        IA["Agente Autônomo / Claude Desktop / IDE"]
    end

    subgraph Admin["Operador / Administração Local (CLI)"]
        CLI["mcpsentinel ctl / CLI Local<br/>(status / connections / logs / reload)"]
    end

    subgraph Edge["McpSentinel Edge Gateway"]
        direction TB
        IPFilter["1. Interceptor de Rede<br/>(Allowlist CIDR & Bind Filter)"]
        AuthMid["2. Interceptor de Autenticação<br/>(Bearer Token Validation & Vaultwarden)"]
        RBACMid["3. RBAC & Guardrail Multi-Tenant<br/>(Dynamic Tool Catalog & Scope Check)"]
        AuditStart["4. Trilha de Auditoria Síncrona<br/>(Status: PENDING / Fail-Secure Lock)"]
        ExecEngine["5. Motor de Execução de Ferramentas<br/>(FastMCP Dispatcher)"]
        SanitizeMid["6. Sanitização Recursiva<br/>(Regex Masking -> [REDACTED])"]
        AuditEnd["7. Conclusão da Auditoria Síncrona<br/>(Status: SUCCESS / FAILED / BLOCKED)"]

        subgraph IPCSub["Canal de Controle Inter-Processos (IPC / Daemon)"]
            UDSSocket["Unix Domain Socket (0600)<br/>control.sock / JSON-RPC 2.0"]
            ConnTrack["ConnectionTracker<br/>(Sessões & Kill Cirúrgico)"]
            LogHub["LogBroadcastHub<br/>(RingBuffer & Streaming Filtrado)"]
        end
    end

    subgraph Providers["Provedores de Infraestrutura e Serviços"]
        AWS["AWS API (STS AssumeRole / Boto3)"]
        GitLab["GitLab REST API v4"]
        Azure["Azure DevOps REST API"]
        AWX["Ansible AWX / Tower API"]
        Jenkins["Jenkins REST API (Crumb / Queue)"]
    end

    IA -->|HTTP / Server-Sent Events (SSE)| IPFilter
    IPFilter -->|IP Autorizado| AuthMid
    IPFilter -.->|IP Não Autorizado| BlockIP["HTTP 403 Forbidden"]
    
    AuthMid -->|Token Válido| RBACMid
    AuthMid -.->|Token Inválido / Ausente| BlockAuth["HTTP 401 Unauthorized"]
    
    RBACMid -->|Permitido & Confirmado| AuditStart
    RBACMid -.->|Negado / Falha de Tríade| BlockRBAC["Audit BLOCKED & Tool Error"]
    
    AuditStart -->|Audit Escrito em Disco| ExecEngine
    AuditStart -.->|Falha de I/O em Audit| FailSecure["Fail-Secure: Aborta Execução"]
    
    ExecEngine --> AWS
    ExecEngine --> GitLab
    ExecEngine --> Azure
    ExecEngine --> AWX
    ExecEngine --> Jenkins
    
    AWS --> SanitizeMid
    GitLab --> SanitizeMid
    Azure --> SanitizeMid
    AWX --> SanitizeMid
    Jenkins --> SanitizeMid
    
    SanitizeMid --> AuditEnd
    AuditEnd -->|JSON Estruturado & Sanitizado| IA

    %% Controle IPC
    CLI <-->|UDS Local / Permissão 0600| UDSSocket
    UDSSocket <--> ConnTrack
    UDSSocket <--> LogHub
    ConnTrack -.->|Teardown Cirúrgico| IA
    AuditEnd -.->|Fan-Out Assíncrono| LogHub

🛡️ Pilares Fundamentais de Segurança

1. Zero Credential Leakage (Vazamento Zero de Credenciais):

   • Agentes de IA jamais recebem ou manipulam tokens de longa duração, chaves secretas AWS (AWS_SECRET_ACCESS_KEY), Personal Access Tokens (PATs) de GitLab/Azure DevOps ou tokens de automação do AWX.
   • O gateway gerencia as sessões com menor privilégio estrito, recorrendo a credenciais temporárias do AWS STS via AssumeRole ou injeção segura de segredos em tempo de execução.
   • Resoluções dinâmicas de credenciais suportam cofres corporativos através do esquema vaultwarden://<item_id>/<campo>.

2. Trilha de Auditoria Síncrona Fail-Secure:

   • Cada chamada de ferramenta gera eventos forenses obrigatórios em formato estruturado JSONLines (audit.log).
   • Ciclo de vida determinístico: evento de entrada (PENDING) gravado e descarregado em disco antes do despacho, seguido do evento de desfecho (SUCCESS, FAILED ou BLOCKED).
   • Sob a diretriz estrita de Fail-Secure: se houver qualquer indisponibilidade de I/O, disco cheio ou erro de gravação do log de auditoria, a execução da ferramenta é abortada imediatamente. Nenhuma ação operacional ocorre às cegas.

3. GitOps RBAC Declarativo & Isolamento Multi-Tenant:

   • A configuração de identidades, escopos e perfis reside integralmente no arquivo versionado config/security.yaml.
   • Sem dependência de bancos relacionais dinâmicos ou interfaces web mutáveis sujeitas a adulteração externa. Toda alteração passa por revisão de código (Pull Request / Merge Request).
   • Filtragem Dinâmica de Catálogo (tools/list): Cada agente só visualiza as ferramentas atribuídas ao seu perfil.
   • Isolamento de Tenant (tools/call): Validação em tempo de execução garante que o agente opere estritamente dentro das contas AWS, projetos de repositório e organizações de automação declaradas para ele.

4. Tríade de Confirmação para Ações Destrutivas (Guardrails Operacionais):

   • Operações classificadas como destrutivas (ex: aws_ec2_terminate_instances, aws_s3_delete_bucket, gitlab_delete_branch, azure_delete_branch, ou templates críticos de AWX como teardown-*) exigem o cumprimento simultâneo de três condições obrigatórias:
     1. Habilitação em Perfil: O perfil RBAC deve possuir a flag destructive_actions_allowed: true.
     2. Flag Explícita de Confirmação: O parâmetro confirm_action=true deve ser enviado na chamada.
     3. Justificativa Operacional: Um argumento justification não vazio (mínimo de caracteres exigido) deve ser fornecido para registro em auditoria.
   • Caso qualquer condição falhe, a ação é bloqueada com status BLOCKED e auditada imediatamente.

5. Sanitização e Mascaramento Recursivo Automático:

   • Todos os payloads de entrada, saídas brutas de ferramentas, payloads de erro e rastros de pilha (tracebacks) são processados por rotinas recursivas de sanitização antes de serem transmitidos ao cliente IA ou gravados em log.
   • Padrões sensíveis (senhas, cabeçalhos Authorization, chaves privadas, tokens JWT/PAT, hashes de credenciais) são substituídos pelo token padronizado [REDACTED].

6. Defesa em Profundidade de Rede (Network Allowlist):

   • Interceptor de borda integrado na camada ASGI valida a origem das requisições contra regras de IP individuais ou blocos CIDR autorizados (allowed_origins), bloqueando tráfego não confiável antes de qualquer processamento HTTP/SSE.

⚙️ Inventário Completo de Configurações

O McpSentinel adota o padrão de configuração em camadas, permitindo flexibilidade sem comprometer a previsibilidade da segurança.

Precedência Canônica de Configurações

O McpSentinel adota uma precedência determinística em camadas para resolução de parâmetros operacionais:

1. Argumentos de Linha de Comando (CLI): Flags explícitas passadas na invocação (--port, --bind, --conf-file, etc.) têm prioridade máxima.
2. Variável de Ambiente SENTINEL_CONF_FILE: Permite apontar um caminho arbitrário de arquivo .conf ou .env.
3. Arquivo de Configuração Canônico do Usuário (mcpsentinel.conf): Localizado no diretório padrão de configurações do sistema operacional via platformdirs:
   • Linux: ~/.config/mcpsentinel/mcpsentinel.conf (conforme especificação XDG).
   • macOS: ~/Library/Application Support/mcpsentinel/mcpsentinel.conf.
   • Windows: %APPDATA%\mcpsentinel\mcpsentinel.conf.
4. Retrocompatibilidade Local (Fallback CWD .env): Caso o arquivo canônico do usuário não exista, o gateway busca automaticamente por um arquivo .env no diretório de execução atual (Current Working Directory).
5. Variáveis de Ambiente do Sistema Operacional (Shell OS): Valores exportados diretamente no ambiente com prefixo SENTINEL_.
6. Valores Padrão (Defaults da Aplicação): Definidos nas classes de configuração do gateway.
7. Arquivo Declarativo GitOps (config/security.yaml): Matriz base estruturada de segurança (RBAC, tenants e perfis).

Arquivo Canônico de Configuração: mcpsentinel.conf

A partir da versão 1.1.0, o McpSentinel adota mcpsentinel.conf como o arquivo canônico de configuração do usuário, substituindo a dependência obrigatória de arquivos .env soltos no diretório do projeto.

O arquivo pode ser gerado automaticamente com permissões restritas através do subcomando:

mcpsentinel init

Por padrão, em sistemas POSIX (Linux/macOS), o utilitário assegura permissão 0700 (rwx------) no diretório de configuração e 0600 (rw-------) no arquivo mcpsentinel.conf, prevenindo leitura não autorizada de tokens e segredos por outros usuários do sistema operacional.

Caso deseje sobrescrever o arquivo padrão durante a execução do gateway, utilize a flag --conf-file <caminho> disponível nos subcomandos start e restart:

# Iniciar utilizando um arquivo de configuração específico
mcpsentinel start --conf-file /etc/mcpsentinel/producao.conf

# Reiniciar o serviço apontando para nova configuração
mcpsentinel restart -d --conf-file /etc/mcpsentinel/producao.conf

Variáveis de Ambiente e Suporte a .env

As configurações definidas em mcpsentinel.conf ou .env utilizam sintaxe padrão chave-valor (KEY=VALUE) e são mapeadas para os parâmetros internos via pydantic-settings:

Variáveis de Provedores de Nuvem e DevOps (Interpolação no security.yaml)

Ferramentas MCP do Conector GitHub

O conector GitHub expõe 8 ferramentas com paridade funcional ao GitLab, governadas por RBAC declarativo, whitelist de repositórios autorizados (allowed_repositories), proteção inviolável de branches em memória (BranchProtectionGuardrail) e validação da Tríade de Confirmação para ações destrutivas:

Ferramentas MCP do Conector Jenkins CI/CD

O conector Jenkins expõe ferramentas padronizadas para acionamento e acompanhamento de esteiras de integração contínua, governadas por RBAC declarativo, catálogo de jobs permitidos (allowed_jobs), parâmetros bloqueados (disallowed_parameters) e confirmação obrigatória para ações sensíveis (require_confirmation_jobs):

Arquivo Declarativo GitOps: config/security.yaml

O arquivo config/security.yaml é o coração da segurança do gateway. É dividido em 4 seções principais:

version: "1.0"

# 1. Filtros de Rede (Opcional no YAML, pode ser sobrescrito por CLI)
network_filter:
  bind_addresses:
    - "127.0.0.1"
  allowed_origins:
    - "127.0.0.1"
    - "192.168.1.0/24"

# 2. Tenants Corporativos Autorizados
tenants:
  aws_accounts:
    - id: "dev-account"
      account_id: "111122223333"
      name: "Ambiente de Desenvolvimento"
      allowed_regions: ["us-east-1", "sa-east-1"]
    - id: "prod-account"
      account_id: "444455556666"
      name: "Ambiente de Produção"
      allowed_regions: ["us-east-1"]

  gitlab_organizations:
    - id: "gitlab-corp"
      name: "GitLab Corporativo"
      base_url: "${GITLAB_BASE_URL:-https://gitlab.com}"
      token: "${GITLAB_TOKEN}"
      allowed_projects: ["infra/*", "apps/*"]

  azure_organizations:
    - id: "azure-corp"
      name: "Azure DevOps Corp"
      organization: "mycorp"
      base_url: "${AZURE_DEVOPS_BASE_URL:-https://dev.azure.com}"
      token: "${AZURE_DEVOPS_TOKEN}"
      allowed_projects: ["InfraCore", "Apps-*"]

  awx_organizations:
    - id: "awx-corp"
      name: "Cluster AWX Principal"
      base_url: "${AWX_BASE_URL:-https://awx.corp.internal}"
      token: "${AWX_TOKEN}"
      allowed_templates: ["deploy-app", "backup-database", "teardown-cluster"]
      destructive_templates: ["teardown-cluster"]

  jenkins_instances:
    - id: "jenkins-corp"
      name: "Cluster Jenkins Corporativo"
      base_url: "${JENKINS_BASE_URL:-https://jenkins.corp.internal:8080}"
      username: "${JENKINS_USERNAME:-svc_mcpsentinel}"
      api_token: "${JENKINS_TOKEN}"
      allowed_jobs: ["ci-*", "build-*", "deploy-staging-*", "release-service-*"]
      disallowed_parameters: ["ADMIN_OVERRIDE", "BYPASS_APPROVAL", "ROOT_TOKEN"]
      require_confirmation_jobs: ["release-service-*"]

# 3. Perfis RBAC (Matriz de Autorização)
profiles:
  sre_operations:
    description: "Perfil operacional SRE com permissão de alto risco"
    destructive_actions_allowed: true
    tools:
      - "aws_get_caller_identity"
      - "aws_ec2_describe_instances"
      - "aws_ec2_terminate_instances"
      - "gitlab_get_project"
      - "gitlab_delete_branch"
      - "awx_launch_job_template"
      - "jenkins_trigger_job"
      - "jenkins_get_build_status"
      - "jenkins_get_build_console"
    allowed_tenants:
      aws_accounts: ["dev-account", "prod-account"]
      gitlab_organizations: ["gitlab-corp"]
      awx_organizations: ["awx-corp"]
      jenkins_instances: ["jenkins-corp"]

  developer_iac:
    description: "Perfil restrito a ambientes de desenvolvimento sem ações destrutivas"
    destructive_actions_allowed: false
    tools:
      - "aws_get_caller_identity"
      - "aws_ec2_describe_instances"
      - "gitlab_get_project"
      - "gitlab_create_branch"
    allowed_tenants:
      aws_accounts: ["dev-account"]
      gitlab_organizations: ["gitlab-corp"]

# 4. Agentes e Identidades (Vinculação de Token -> Perfil)
agents:
  - agent_id: "agent-sre-01"
    name: "Agente SRE Principal"
    token: "${SENTINEL_TOKEN_SRE:-token-sre-01-secret}"
    profile: "sre_operations"

  - agent_id: "agent-dev-01"
    name: "Agente IaC Dev"
    token: "${SENTINEL_TOKEN_DEV:-token-dev-01-secret}"
    profile: "developer_iac"

🔐 Resolução Dinâmica de Segredos via Vaultwarden / Bitwarden (bw / bws)

Em ambientes corporativos com requisitos estritos de segurança, tokens de longa duração e chaves de API não devem ser gravados em texto plano dentro de arquivos de configuração versionados (security.yaml) ou arquivos locais (.env), eliminando os riscos de vazamento acidental em commits de Git ou extração por processos locais (Zero Credential Leakage).

O McpSentinel implementa nativamente a arquitetura definida nas ADR 004 e ADR 010, e nas especificações OpenSPEC MCP-38 e OpenSPEC MCP-75, integrando o módulo mcpsentinel.security.secrets (SecretsManager e VaultwardenResolver).

O resolver suporta tanto o Bitwarden CLI padrão (bw) (amplamente utilizado em servidores Vaultwarden auto-hospedados) quanto o Bitwarden Secrets Manager CLI (bws) via detecção defensiva e transparente.

Como Funciona o Esquema de URI vaultwarden://

Qualquer campo de token configurado para provedores (GitLab, Azure DevOps, AWX) ou agentes pode ser declarado com a URI canônica:

vaultwarden://<item_id>/<campo>

• <item_id>: Identificador único universal (UUID) do item armazenado no cofre (ex: b4a2c1d0-1234-5678-90ab-cdef12345678).
• <campo>: Propriedade do segredo a ser extraída:
  • Login: password (busca em .login.password), username (.login.username), totp (.login.totp) ou sintaxe aninhada login.<propriedade>.
  • Campos Raiz: notes (anotações do item), name, id ou qualquer chave de primeiro nível do JSON.
  • Campos Customizados: fields.<nome> (busca no array fields por item com name == nome) ou busca direta pelo nome do campo como fallback.
  • Bitwarden Secrets Manager (bws): extração direta da chave no JSON (ex: value).

Exemplos de URIs válidas:

vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/password
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/notes
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/fields.api_token
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/value

Integração com Vaultwarden usando Bitwarden CLI (bw)

Instâncias auto-hospedadas do Vaultwarden utilizam as APIs do gerenciador de senhas do Bitwarden, sendo operadas pelo CLI oficial bw.

1. Onde Obter a Chave de API no Vaultwarden Web

1. Acesse a interface web da sua instância Vaultwarden.
2. Navegue até Configurações da Conta > Segurança > aba Chaves de API.
3. Clique em Ver Chave de API (solicitará a confirmação da sua senha mestre).
4. Guarde com segurança o client_id (ex: user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) e o client_secret (ex: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy).

2. Configuração de Servidor e Login Não-Interativo

Em servidores e ambientes de gateway, nunca execute login interativo com senha mestre. Utilize autenticação estritamente via API Key:

# Apontar o CLI para o servidor da sua instância Vaultwarden
bw config server https://seu-vaultwarden.empresa.com

# Exportar as credenciais da API Key
export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export BW_CLIENTSECRET="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

# Executar login não-interativo
bw login --apikey

3. Destravar o Cofre e Exportar BW_SESSION

Após o login, o cofre permanece travado. Destrave-o de forma não-interativa e capture o token de sessão:

# Destravar o cofre informando a senha mestre via pipe ou prompt único:
export BW_SESSION="$(bw unlock --raw)"

Integração com Bitwarden Secrets Manager (bws)

Caso utilize o serviço comercial do Bitwarden Secrets Manager:

1. Instale o binário bws disponibilizado em bitwarden/sdk-sm.
2. Gere um Access Token de Service Account no cofre corporativo.
3. Exporte a variável de ambiente:

   export BWS_ACCESS_TOKEN="0.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   

4. As URIs vaultwarden://<item_id>/value serão resolvidas via bws secret get <item_id>.

Integração com HashiCorp Vault (vault)

Além do Vaultwarden/Bitwarden, o McpSentinel oferece suporte declarativo e assistido via wizard ao HashiCorp Vault (KV v2 engine) como backend de segredos:

• Configuração no mcpsentinel.conf / Ambiente:
  • SENTINEL_SECRETS_BACKEND="vault"
  • VAULT_ADDR="https://vault.corp.internal:8200"
  • VAULT_TOKEN="s.xxxxxxxxxxxx"
  • VAULT_MOUNT_POINT="secret" (padrão)
  • VAULT_NAMESPACE="" (opcional, para instâncias Vault Enterprise)
• Modo Seguro: Os tokens e caminhos do Vault são gerenciados de forma isolada, prevenindo vazamento de credenciais na camada do LLM.

Exemplos Práticos de Configuração

1. Declaração Direta no config/security.yaml

Você pode referenciar a URI do cofre diretamente nos tenants corporativos:

version: "1.0"

tenants:
  gitlab_organizations:
    - id: "gitlab-corp"
      name: "GitLab Corporativo"
      base_url: "https://gitlab.com"
      # Resolução via bw (login.password) ou fields customizados
      token: "vaultwarden://4a72d3e1-8842-4f39-9d7a-112233445566/password"
      allowed_projects: ["infra/*", "apps/*"]

  azure_organizations:
    - id: "azure-corp"
      name: "Azure DevOps Corp"
      organization: "mycorp"
      base_url: "https://dev.azure.com"
      # Resolução de anotações seguras
      token: "vaultwarden://9f8e7d6c-5b4a-3210-fedc-ba9876543210/notes"
      allowed_projects: ["InfraCore", "Apps-*"]

  awx_organizations:
    - id: "awx-corp"
      name: "Cluster Ansible AWX"
      base_url: "https://awx.corp.internal"
      # Resolução de campo customizado fields.api_token
      token: "vaultwarden://11223344-5566-7788-99aa-bbccddeeff00/fields.api_token"
      allowed_templates: ["deploy-app", "backup-database"]

agents:
  - agent_id: "agent-sre-01"
    name: "Agente SRE Principal"
    token: "vaultwarden://aa11bb22-cc33-dd44-ee55-ff6677889900/password"
    profile: "sre_operations"

2. Interpolação Segura via .env ou mcpsentinel.conf

Também é possível combinar variáveis de ambiente com as URIs de cofre:

# Arquivo mcpsentinel.conf ou .env
BW_SESSION="token_da_sessao_gerado_no_unlock"
GITLAB_TOKEN="vaultwarden://4a72d3e1-8842-4f39-9d7a-112233445566/password"
AZURE_DEVOPS_TOKEN="vaultwarden://9f8e7d6c-5b4a-3210-fedc-ba9876543210/notes"
AWX_TOKEN="vaultwarden://11223344-5566-7788-99aa-bbccddeeff00/fields.api_token"

No security.yaml, os valores são interpolados normalmente:

token: "${GITLAB_TOKEN}"

3. Retrocompatibilidade (Valores Literais)

Se a string de token não contiver o separador de protocolo :// (por exemplo, glpat-abcdef123456), o SecretsManager adota comportamento transparente e utiliza o valor como literal sem executar nenhum processo externo.

Tratamento de Falhas, Timeouts e Fail-Secure

O VaultwardenResolver opera sob os mais rigorosos princípios de Fail-Secure e Zero Credential Leakage (MCP-49 e ADR 004):

• Hard-Timeout de 10 Segundos: Se a CLI (bw ou bws) não responder em até 10 segundos (devido a instabilidades de rede ou cofre travado), o processo filho é encerrado forçadamente (kill) e uma exceção SecretTimeoutError é levantada, abortando a inicialização do provedor correspondente.
• Sanitização Recursiva de Logs e Tracebacks ([REDACTED]): Nenhuma mensagem de erro, rastro de pilha (traceback) ou saída padrão (stdout/stderr) expõe o conteúdo do segredo, sessões (BW_SESSION) ou tokens de acesso. Falhas em decodificação JSON são isoladas (from None), suprimindo __cause__.
• Validação de Esquema e Binários: Caso nem bw nem bws estejam no PATH, é lançada a exceção DependencyNotFoundError. Se o esquema não for registrado (ex: unsupportedvault://), é levantado UnknownResolverSchemeError.

⚡ Guia de Instalação e Uso (Quickstart)

Pré-requisitos

• Linux (Debian, Ubuntu, RHEL, Fedora, Arch) ou macOS.
• Python 3.12+.
• uv (recomendado) ou pip / pipx.

Instalação e Uso Direto via PyPI (pip / uv tool / pipx / uvx)

O McpSentinel é publicado oficialmente no PyPI sob o nome de pacote mcpsentinel-gateway.

Ele expõe dois pontos de entrada equivalentes de linha de comando no seu PATH:

• mcpsentinel (comando principal canônico)
• mcpsentinel-gateway (alias correspondente ao nome do pacote)

1. Instalação Isolada para Usuários Finais (Recomendado)

Para utilizar o gateway como utilitário de sistema sem poluir o ambiente Python global:

# Com uv tool (ultra-rápido)
uv tool install mcpsentinel-gateway

# Ou com pipx
pipx install mcpsentinel-gateway

2. Instalação via pip tradicional

Em um ambiente virtual dedicado ou contêiner:

pip install mcpsentinel-gateway

3. Execução Imediata sem Instalação Prévia via uvx

Para testar ou executar o gateway sob demanda sem instalar previamente no sistema:

uvx --from mcpsentinel-gateway mcpsentinel start --port 8000

4. Uso Imediato dos Comandos CLI

Após a instalação, os comandos já estarão disponíveis no terminal:

# Iniciar em primeiro plano (porta padrão 8000)
mcpsentinel start

# Iniciar em segundo plano como Daemon POSIX
mcpsentinel start -d --port 8000

# Consultar status do processo em execução
mcpsentinel status

# Parar o serviço em background
mcpsentinel stop

Desenvolvimento Local e Contribuição (Repositório Git)

Para desenvolvedores que desejam contribuir com o código, rodar os testes herméticos ou customizar o McpSentinel:

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

# 2. Crie o ambiente virtual e sincronize dependências
uv sync

# 3. Execute a CLI usando o ambiente sincronizado
uv run mcpsentinel start --port 8000

Inicialização do Ambiente de Configuração (mcpsentinel init)

O McpSentinel provê o subcomando init para gerar de forma automatizada o arquivo de configuração canônico mcpsentinel.conf com permissões seguras:

# Inicialização canônica no diretório do usuário (~/.config/mcpsentinel/mcpsentinel.conf no Linux)
mcpsentinel init

# Forçar a sobrescrita caso o arquivo já exista
mcpsentinel init --force

# Gerar em um caminho customizado
mcpsentinel init --path /etc/mcpsentinel/mcpsentinel.conf

Conteúdo Gerado no mcpsentinel.conf

O arquivo de configuração aceita todas as variáveis do gateway no formato KEY=VALUE:

# Interface e porta de escuta do servidor HTTP/SSE
SENTINEL_HOST=0.0.0.0
SENTINEL_PORT=8000

# Nível de log operacional (DEBUG, INFO, WARNING, ERROR)
SENTINEL_LOG_LEVEL=INFO

# Ambiente de execução (development, staging, production)
SENTINEL_ENVIRONMENT=development

# Token estático de autenticação Bearer para clientes MCP
SENTINEL_AUTH_TOKEN=troque-este-token-por-um-segredo-forte

# Caminho para arquivo de auditoria síncrona JSONLines
SENTINEL_AUDIT_LOG_PATH=~/.mcpsentinel/logs/audit.log

# Token de serviço do Bitwarden Secrets Manager / Vaultwarden (opcional, para URIs vaultwarden://)
BWS_ACCESS_TOKEN=""

# Tokens de agentes para RBAC multi-tenant
SENTINEL_TOKEN_SRE=token-sre-01-secret
SENTINEL_TOKEN_DEV=token-dev-01-secret

# Integração Jenkins CI/CD (opcional)
JENKINS_ENABLED=true
JENKINS_BASE_URL=""
JENKINS_USERNAME=""
JENKINS_TOKEN=""

Retrocompatibilidade com Arquivos .env

Para preservar o fluxo de trabalho de deploys legados ou repositórios locais, se o arquivo mcpsentinel.conf do usuário não existir, o McpSentinel busca de forma transparente o arquivo .env localizado no diretório atual de execução (CWD).

Assistente Interativo de Configuração (mcpsentinel configure)

O McpSentinel provê o assistente interativo configure (Terminal User Interface — TUI) para guiar o operador na configuração e inspeção dos parâmetros do gateway e integrações, evitando erros de digitação, URLs malformadas e vazamento visual de segredos (ADR 012 e OpenSPEC MCP-77).

Como Funciona o Wizard TUI

1. TTY Guard: O wizard exige um terminal TTY interativo para execução (sys.stdin.isatty()). Em pipelines não-interativos ou scripts cron, ele encerra de forma limpa prevenindo travamentos.
2. Preservação de Valores Anteriores: Caso o arquivo de configuração já exista, seus valores atuais são pré-carregados como defaults. Pressionar [Enter] mantém o valor atual sem alteração.
3. Mascaramento Rigoroso de Senhas: Tokens e credenciais sensíveis (secret=True) utilizam entrada oculta/mascarada no terminal, prevenindo vazamento visual (shoulder surfing).
4. Validação Inline Contínua: Campos como URLs (http:// ou https://), portas TCP (1024-65535) e IPs/CIDRs são validados no momento da digitação.
5. Persistência Atômica e Permissões Seguras: O arquivo é gravado atomicamente via arquivo temporário com permissões POSIX restritas 0600 (rw-------) e diretório pai 0700 (rwx------).

Modos de Operação

1. Modo Wizard Interativo Completo (Menu de Categorias)

Inicia o assistente com menu interativo navegável por categorias:

# Executar para o arquivo padrão (~/.config/mcpsentinel/mcpsentinel.conf)
mcpsentinel configure

# Executar apontando para arquivo customizado
mcpsentinel configure --conf-file /etc/mcpsentinel/mcpsentinel.conf

Categorias disponíveis no Menu Principal:

• 1 - Configuração Completa (Primeiro Uso): Percorre sequencialmente o servidor, backend de segredos e todos os serviços externos habilitados.
• 2 - Configurar Servidor & Rede: Endereço de bind (SENTINEL_HOST), porta (SENTINEL_PORT), nível de log (SENTINEL_LOG_LEVEL), ambiente (SENTINEL_ENVIRONMENT), token Bearer mestre e IPs autorizados.
• 3 - Configurar Provedores de Segredos: Seleção do backend ativo (env, vault ou vaultwarden) com configuração específica de URLs, tokens de máquina (bws) ou parâmetros do HashiCorp Vault.
• 4 - Configurar Serviços Externos: Submenu seletivo para habilitar/desabilitar e configurar integrações individuais de nuvem e DevOps.
• 5 - Salvar e Sair: Apresenta tela de resumo (Review Summary) com dados sensíveis mascarados (******) e confirmação de gravação atômica em disco.
• 0 - Cancelar / Sair sem Salvar: Encerra graciosamente sem gravar alterações (Ctrl+C também encerra com segurança).

2. Modo Seletivo Direto com --service

Permite abrir diretamente o assistente focado em um serviço específico sem passar pelo menu principal:

# Configurar apenas o conector do Jenkins
mcpsentinel configure --service jenkins

# Configurar apenas o GitLab
mcpsentinel configure --service gitlab

# Configurar apenas o backend de segredos
mcpsentinel configure --service secrets

Serviços suportados via --service:

Comandos da CLI do Gateway (mcpsentinel)

O McpSentinel provê uma CLI robusta (mcpsentinel ou mcpsentinel-gateway), compatível com códigos de saída padrão LSB (0=RUNNING, 3=STOPPED, 1=ERROR).

Flags Globais do Utilitário

Resumo de Subcomandos

Modo Interativo (Primeiro Plano / Foreground)

Ideal para desenvolvimento, testes e inspeção de logs em tempo real:

# Iniciar utilizando a configuração padrão resolvida
mcpsentinel start --port 8000

# Iniciar apontando para um arquivo de configuração explícito
mcpsentinel start --conf-file /etc/mcpsentinel/mcpsentinel.conf

# (Se estiver no ambiente do repositório: uv run mcpsentinel start --port 8000)

Modo Daemon POSIX (Segundo Plano / Background)

Executa em segundo plano com desacoplamento canônico (double-fork, trava exclusiva por lockfile de PID):

# Iniciar o daemon
mcpsentinel start --daemon

# Iniciar com restrição de origens, porta e arquivo de configuração customizado
mcpsentinel start -d --port 8000 --bind 127.0.0.1 --allow-ip 127.0.0.1 --conf-file ~/.config/mcpsentinel/mcpsentinel.conf

# Verificar o status atual (PID e uptime)
mcpsentinel status

# Recarregar configurações e arquivos de log (envia sinal SIGHUP sem derrubar conexões)
mcpsentinel reload

# Reiniciar o serviço (suporta sobrescrever conf-file)
mcpsentinel restart --daemon --conf-file ~/.config/mcpsentinel/mcpsentinel.conf

# Interromper o serviço graciosamente
mcpsentinel stop

# Interrupção forçada (caso exceda o timeout gracioso)
mcpsentinel stop --force --timeout 15

Gerenciamento como Serviço Systemd no Linux (CLI)

O McpSentinel provê automação nativa para instalação, configuração, inicialização e desinstalação de unidades do systemd, eliminando a necessidade de copiar arquivos manuais de unit ou configurar permissões no sistema.

1. Instalação e Ativação do Serviço (install-service)

O comando mcpsentinel install-service detecta o ambiente, resolve o caminho absoluto do binário executável e configura a unit do serviço correspondente.

• Uso padrão em modo de usuário (recomendado sem root): Instala a unit no escopo do usuário atual (~/.config/systemd/user/mcpsentinel.service), habilita a inicialização no login e inicia o serviço imediatamente:

  mcpsentinel install-service --enable --start
  

• Instalação no escopo de sistema (root / produção): Instala a unit global em /etc/systemd/system/mcpsentinel.service com gerenciamento de permissões:

  sudo mcpsentinel install-service --system --enable --start
  

• Opções úteis para instalação:

  • --linger: Habilita lingering de sessão via loginctl enable-linger $USER no modo de usuário, mantendo o serviço em execução contínua mesmo se o usuário fizer logout do terminal/SSH.
  • -f, --force: Sobrescreve o arquivo de unit systemd caso ele já exista no diretório de destino.
  • --conf-file <caminho>: Aponta explicitamente para o arquivo de configuração desejado a ser repassado ao serviço (ex: --conf-file /etc/mcpsentinel/producao.conf).
  • --service-user <usuario> e --service-group <grupo>: Permite definir usuário e grupo dedicados de execução (aplicável no modo --system).

  Exemplo combinando opções no modo de usuário:

  mcpsentinel install-service --user --enable --start --linger --conf-file ~/.config/mcpsentinel/mcpsentinel.conf
  

• Inspeção de Status e Logs com Utilitários Nativos do Systemd: Após a instalação do serviço, gerencie e acompanhe a execução em tempo real utilizando os comandos padrões do Linux:

  # Inspecionar status do serviço de usuário
  systemctl --user status mcpsentinel
  
  # Acompanhar stream contínuo de logs estruturados em tempo real
  journalctl --user -u mcpsentinel -f
  
  # (Caso instalado no modo sistema com --system):
  sudo systemctl status mcpsentinel
  sudo journalctl -u mcpsentinel -f
  

2. Desinstalação do Serviço (uninstall-service)

O comando mcpsentinel uninstall-service interrompe a execução do serviço, desabilita a inicialização automática, remove o arquivo de unit e recarrega os daemons do systemd de forma limpa e idempotente:

• Desinstalação no modo de usuário:

  mcpsentinel uninstall-service
  # ou explicitamente:
  mcpsentinel uninstall-service --user
  

• Desinstalação no modo de sistema:

  sudo mcpsentinel uninstall-service --system
  

🎛️ Controle Inter-Processos do Daemon (mcpsentinel ctl)

Quando o McpSentinel opera em segundo plano (em modo daemon POSIX via start -d ou como serviço gerenciado pelo systemd), ele ativa um canal seguro de controle inter-processos (IPC — Inter-Process Communication) baseado em Unix Domain Sockets (UDS) e mensagens estruturadas no padrão JSON-RPC 2.0 (ADR 013, PRD-078 e OpenSPEC MCP-078).

Como Funciona a Segurança do Canal IPC

1. Sem Portas de Rede Expostas: O canal de controle não abre portas TCP ou HTTP adicionais no host (evitando colisões e superfície de ataque de rede).
2. Isolamento e Hardening POSIX: A comunicação ocorre via socket de arquivo (control.sock) criado estritamente com permissões octais 0600 (rw-------) e diretório restrito 0700 (rwx------). Apenas o próprio usuário do sistema operacional que iniciou o daemon tem permissão no kernel Linux para conectar e enviar comandos.
3. Resolução Determinística do Socket:
   • Modo Usuário (não-root): ~/.mcpsentinel/control.sock
   • Modo Sistema (root / systemd system): /var/run/mcpsentinel/control.sock (ou caminho explícito via flag --socket <path>).
4. Tratamento de Stale Sockets: Se o daemon anterior sofrer uma parada não graciosa (ex: kill -9), o McpSentinel valida ativamente a liveness antes do bind e recicla sockets órfãos sem travar a inicialização.

flowchart LR
    subgraph Host["Host Linux (Segurança POSIX)"]
        direction TB
        subgraph Admin["Operador / Shell"]
            CLI["mcpsentinel ctl / aliases"]
        end

        subgraph UDSLayer["Kernel POSIX IPC"]
            SOCK["Unix Domain Socket<br/>control.sock (0600)"]
        end

        subgraph DaemonProcess["Processo Daemon McpSentinel"]
            RPC["ControlServer (JSON-RPC 2.0)"]
            Tracker["ConnectionTracker<br/>(Sessões Ativas)"]
            Hub["LogBroadcastHub<br/>(RingBuffer 1000)"]
            Engine["FastMCP / Provedores"]
        end
    end

    CLI <-->|JSON-RPC 2.0 Framing \n| SOCK
    SOCK <--> RPC
    RPC <--> Tracker
    RPC <--> Hub
    RPC -.->|Reload de Regras| Engine
    Tracker -.->|Kill Cirúrgico de Canal SSE| Engine

Comandos Disponíveis e Exemplos Práticos

Todos os comandos de controle estão disponíveis sob mcpsentinel ctl <subcomando> e contam com aliases de primeiro nível ergonômicos para os fluxos mais frequentes do dia a dia.

1. Status Operacional Detalhado (mcpsentinel ctl status)

Inspeciona o daemon em execução, tempo de atividade (uptime), quantidade de requisições atendidas, conexões ativas e a integridade dos provedores configurados:

# Exibição tabular amigável no terminal
mcpsentinel ctl status

# Saída estruturada em JSON (ideal para monitoramento e scripts)
mcpsentinel ctl status --json

Exemplo de saída formatada em JSON:

{
  "pid": 28419,
  "uptime_seconds": 3840,
  "status": "RUNNING",
  "active_connections": 2,
  "total_requests": 142,
  "providers": {
    "aws": "healthy",
    "gitlab": "healthy",
    "azure": "disabled",
    "awx": "healthy",
    "jenkins": "healthy"
  }
}

2. Listagem de Conexões MCP Ativas (mcpsentinel ctl connections list)

Lista em tempo real todos os clientes ou agentes MCP conectados via Server-Sent Events (SSE) ou HTTP, exibindo o ID único da sessão, identificador do cliente, endereço IP remoto, duração da sessão e contador de ferramentas executadas:

# Via subcomando canônico ctl
mcpsentinel ctl connections list

# Via alias direto de primeiro nível
mcpsentinel connections list

# Saída formatada em array JSON
mcpsentinel connections list --json

Exemplo de exibição em tabela:

+----------------+-----------------+---------------+----------+---------------+----------+
| ID             | CLIENT          | REMOTE IP     | DURATION | LAST ACTIVITY | REQUESTS |
+----------------+-----------------+---------------+----------+---------------+----------+
| conn-9f8a12bc  | claude-desktop  | 127.0.0.1     | 14m 20s  | 12s atrás     | 18       |
| conn-3e7b41df  | dev-agent-01    | 192.168.1.105 | 03m 12s  | 45s atrás     | 4        |
+----------------+-----------------+---------------+----------+---------------+----------+

3. Encerramento Cirúrgico de Conexão (mcpsentinel ctl connections kill)

Caso um cliente entre em loop infinito de requisições ou apresente comportamento anômalo, o operador pode encerrar cirurgicamente aquela sessão específica sem reiniciar o daemon e sem afetar as demais conexões ativas:

# Encerrar solicitando confirmação interativa no terminal
mcpsentinel ctl connections kill conn-3e7b41df

# Encerrar de forma forçada/não-interativa (-y ou --force)
mcpsentinel ctl connections kill conn-3e7b41df -y

# Via alias direto com retorno em JSON
mcpsentinel connections kill conn-3e7b41df -y --json

4. Visualização e Streaming de Logs em Tempo Real (mcpsentinel ctl logs)

Permite inspecionar o histórico recente armazenado no buffer circular em memória (RingBuffer) ou realizar streaming contínuo das novas linhas de log emitidas pelo daemon, com suporte a filtros granulares:

# Exibir as últimas 50 linhas de log (padrão)
mcpsentinel ctl logs

# Exibir as últimas 100 linhas
mcpsentinel ctl logs -n 100

# Acompanhar stream ao vivo em tempo real (-f ou --follow, encerra com Ctrl+C)
mcpsentinel ctl logs -f

# Filtrar exclusivamente eventos por nível de severidade (DEBUG, INFO, WARNING, ERROR)
mcpsentinel ctl logs -f --level WARNING

# Filtrar exclusivamente eventos forenses de auditoria MCP (chamadas a ferramentas)
mcpsentinel ctl logs -f --audit

# Utilizando o alias de primeiro nível com saída JSON
mcpsentinel logs -f --audit --json

5. Recarregamento de Políticas com Feedback Estruturado (mcpsentinel ctl reload)

Ao contrário do sinal unidirecional SIGHUP (onde o operador não recebe retorno direto no terminal), o comando ctl reload envia uma requisição síncrona via UDS, instruindo o daemon a reler o mcpsentinel.conf e o arquivo declarativo GitOps config/security.yaml:

# Recarregar configurações e validar consistência de regras
mcpsentinel ctl reload

# Com saída estruturada em JSON
mcpsentinel ctl reload --json

Exemplo de feedback de sucesso:

Configurações e políticas de segurança recarregadas com sucesso.
Regras validadas: 5 perfis RBAC, 3 tenants, 12 ferramentas ativas.

🔌 Guia de Integração com Clientes MCP

Todos os clientes autenticam-se via cabeçalho HTTP padrão Authorization: Bearer <TOKEN_DO_AGENTE>.

1. Claude Desktop

Abra o arquivo de configuração do seu Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione o McpSentinel na seção mcpServers:

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

2. Validação Rápida via cURL

Você pode inspecionar o handshake SSE diretamente no terminal:

# Conexão válida (Stream aberto aguardando eventos)
curl -N -H "Authorization: Bearer token-sre-01-secret" \
  http://localhost:8000/sse

# Tentativa não autenticada (Bloqueio 401 imediato)
curl -i http://localhost:8000/sse
# HTTP/1.1 401 Unauthorized
# {"error": "Unauthorized", "code": "AUTHENTICATION_ERROR", "detail": "Missing Authorization header"}

🐳 Implantação em Produção e Contêineres

Para ambientes de produção orquestrados (Kubernetes, AWS ECS, Docker Compose), o McpSentinel deve ser empacotado em contêineres mínimos, não-root e isolados.

Dockerfile Multi-Stage de Exemplo

Crie um arquivo Dockerfile na raiz do projeto:

# ----------------------------------------------------
# Estágio 1: Build & Dependências com uv e CLI bws
# ----------------------------------------------------
FROM python:3.12-slim-bookworm AS builder

WORKDIR /app

ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    curl \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# Instalar uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Instalar Bitwarden Secrets Manager CLI (bws) para resolução de segredos em runtime
ARG BWS_VERSION=1.0.0
RUN curl -fsSL -o /tmp/bws.zip "https://github.com/bitwarden/sdk-sm/releases/download/bws-v${BWS_VERSION}/bws-x86_64-unknown-linux-gnu-${BWS_VERSION}.zip" \
    && unzip /tmp/bws.zip -d /usr/local/bin/ \
    && chmod +x /usr/local/bin/bws \
    && rm -f /tmp/bws.zip

# Instalação das dependências do projeto
COPY pyproject.toml ./
RUN uv venv /opt/venv && uv pip install --prefix /opt/venv .

# ----------------------------------------------------
# Estágio 2: Imagem Final de Execução (Hardened)
# ----------------------------------------------------
FROM python:3.12-slim-bookworm AS runtime

WORKDIR /app

# Usuário não privilegiado para segurança do contêiner
RUN groupadd -g 10001 sentinel && \
    useradd -u 10001 -g sentinel -m -s /bin/bash sentinel && \
    mkdir -p /app/logs /app/config && \
    chown -R sentinel:sentinel /app

COPY --from=builder /usr/local/bin/bws /usr/local/bin/bws
COPY --from=builder --chown=sentinel:sentinel /opt/venv /opt/venv
COPY --chown=sentinel:sentinel src/ /app/src/
COPY --chown=sentinel:sentinel config/ /app/config/

USER sentinel

ENV PATH="/opt/venv/bin:$PATH" \
    PYTHONPATH="/app/src" \
    PYTHONUNBUFFERED=1 \
    SENTINEL_HOST="0.0.0.0" \
    SENTINEL_PORT="8000"

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()" || exit 1

ENTRYPOINT ["mcpsentinel"]
CMD ["start", "--port", "8000"]

Execução via Docker Compose (docker-compose.yml)

version: "3.8"

services:
  mcpsentinel:
    build: .
    container_name: mcpsentinel-gateway
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - SENTINEL_PORT=8000
      - SENTINEL_ENVIRONMENT=production
      - SENTINEL_LOG_LEVEL=INFO
      - SENTINEL_SECURITY_CONFIG=/app/config/security.yaml
      - SENTINEL_AUDIT_LOG_PATH=/app/logs/audit.log
      - SENTINEL_TOKEN_SRE=${SENTINEL_TOKEN_SRE}
      - BWS_ACCESS_TOKEN=${BWS_ACCESS_TOKEN}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-us-east-1}
    volumes:
      - ./config/security.yaml:/app/config/security.yaml:ro
      - sentinel-logs:/app/logs
    read_only: false
    security_opt:
      - no-new-privileges:true

volumes:
  sentinel-logs:
    driver: local

Suba o serviço de produção com:

docker compose up -d
docker compose logs -f

Execução Nativa como Serviço Systemd

Para implantações diretas em instâncias Linux dedicadas, o McpSentinel fornece automação completa via CLI como método recomendado, além de disponibilizar templates manuais caso necessário:

Método Recomendado: Automação via CLI (mcpsentinel install-service)

# Como serviço de usuário (sem privilégios de root, com boot automático e lingering)
mcpsentinel install-service --enable --start --linger

# Como serviço global de sistema (requer root / sudo)
sudo mcpsentinel install-service --system --enable --start

# Inspecionar status e logs
systemctl --user status mcpsentinel
journalctl --user -u mcpsentinel -f

Método Manual (Cópia do Template Unit File)

Caso prefira gerenciar os arquivos de unidade manualmente, o template está disponível em deploy/systemd/mcpsentinel.service:

# Como serviço de usuário (sem privilégios de root)
mkdir -p ~/.config/systemd/user/
cp deploy/systemd/mcpsentinel.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now mcpsentinel.service

# Verificar status
systemctl --user status mcpsentinel.service

Para detalhes adicionais sobre permissões em /var/log, opções avançadas de lingering e integração com logrotate, consulte a documentação detalhada em docs/daemon-systemd.md.

🧪 Testes Herméticos e Quality Gates

O projeto possui rigorosa disciplina de engenharia de software garantida por uma suíte de testes totalmente hermética — o que significa que nenhum teste realiza chamadas reais de rede a provedores de nuvem ou depende de bancos de dados externos.

Executando os Testes e Cobertura

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

• Total de testes: 535 testes automatizados (unidade, integração, guardrails, daemon, e2e blackbox, secrets, release pipeline).
• Cobertura Hermética Global: 90%.
• Módulos Centrais:
  • Audit Trail & Fail-Secure: 97%
  • Autenticação & Contexto: 97% - 100%
  • CLI & Daemon POSIX: 83% - 100%
  • Guardrails Destrutivos & Secrets: 93% - 100%

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

# Verificação de padrões de código com Ruff (linter)
uv run ruff check .

# Verificação estrita de tipagem estática com Mypy
uv run mypy src

📚 Documentação Complementar do Harness

Este repositório adota a disciplina canônica do Application Development Harness. Consulte a documentação técnica para aprofundamento:

• Manual de Operação e Governança: docs/manual-de-operacao.md — Guia detalhado para Administradores de Segurança e Auditores.
• Operação de Daemon e Systemd: docs/daemon-systemd.md — Especificação técnica do ciclo de vida em background e códigos LSB.
• Technical Requirements Document (TRD): docs/trd.md — Limites globais de latência, tolerância e componentes.
• 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 sob Paradigma Fail-Secure
  • ADR 004: Resolução de Tokens via Vaultwarden / Bitwarden Secrets Manager
  • ADR 005: Restrição de Rede via Allowlist de IPs e CIDR
  • ADR 006: Background Daemon Service POSIX e Gerenciamento LSB
  • ADR 007: Resolução Multiplataforma de Configuração e mcpsentinel.conf
  • ADR 008: Gerenciamento Nativo de Serviços Systemd via CLI
  • ADR 009: Orquestração de GitHub Release e Publicação Condicionada no PyPI
  • ADR 010: Suporte Híbrido ao Bitwarden CLI (bw) e Vaultwarden
  • ADR 011: Conector Jenkins REST API e Guardrails
  • ADR 012: Assistente Interativo de Configuração e ServiceRegistry
  • ADR 013: Controle Inter-Processos via Unix Domain Socket (UDS) e CLI mcpsentinel ctl
• Especificações de Requisitos e OpenSPEC:
  • PRD-078: Controle Inter-Processos e Interface CLI para Daemon
  • OpenSPEC MCP-078: daemon-ctl-ipc-cli Specification

📄 Licença e Governança

Distribuído sob a licença MIT. Veja o arquivo pyproject.toml para mais informações.

Contribuições devem seguir estritamente o padrão do Application Development Harness e o fluxo de trabalho orientado a especificações OpenSPEC. Todas as modificações em ferramentas ou políticas de segurança devem ser acompanhadas de testes herméticos e documentação atualizada.