McpSentinel — Guardião de Segurança de Infraestrutura para Model Context Protocol

McpSentinel é uma ponte segura e guardiã entre ferramentas de Inteligência Artificial e a infraestrutura tecnológica da sua empresa. Ele foi desenvolvido especialmente para o ecossistema do Model Context Protocol (MCP).

O que o McpSentinel faz de forma simples?

Pense no McpSentinel como uma portaria de segurança blindada:

• Protege suas senhas e acessos: Agentes de IA e assistentes virtuais nunca têm contato direto com senhas mestras, chaves secretas ou credenciais críticas de nuvem.
• Autoriza apenas o que é permitido: Se uma IA pedir para consultar um servidor na AWS, ver um código no GitLab ou GitHub, verificar uma entrega no Azure DevOps, disparar uma automação no Ansible AWX ou conferir uma esteira no Jenkins, o guardião verifica se ela tem permissão para isso.
• Bloqueia ações perigosas por engano: Se um comando puder apagar dados (como deletar servidores ou branches de código), o guardião exige autorização explícita e justificativa registrada.
• Registra tudo em histórico: Toda ação solicitada pela IA é registrada imediatamente em um livro de ocorrências (log de auditoria à prova de falhas).

---

📑 Sumário

• 🛡️ 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
  • Diagnóstico e Inspeção de Configurações (--configuration-summary / -s)
  • 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)
  • Monitoração, Visibilidade e Alertas (Slack e E-mail)
  • Observabilidade Contínua para SRE (Métricas Prometheus /metrics)
  • Diagnóstico Sintético Pré-Voo de Conexões (test-connections)
  • Inspeção Integrada com --check-upstreams (mcpsentinel status)
• 🔌 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

---

🛡️ 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

---

Diagnóstico e Inspeção de Configurações (--configuration-summary / -s)

A forma recomendada de inspecionar a configuração atual antes de subir o servidor ou colocar em produção é através da flag de diagnóstico humanizado -s (ou --configuration-summary). O comando lê as configurações ativas, cruza com a matriz de segurança e apresenta um diagnóstico visual imediato sem iniciar o servidor e com garantia de Zero Leakage (segredos e tokens mascarados):

# Inspeção rápida em linguagem humana (recomendado):
mcpsentinel -s

# Sintaxe equivalente longa:
mcpsentinel --configuration-summary

# Inspeção apontando para arquivos específicos:
mcpsentinel -s --conf-file /etc/mcpsentinel/producao.conf --config config/security.prod.yaml

# Saída estruturada em JSON (ideal para scripts e esteiras CI/CD):
mcpsentinel -s --json

O diagnóstico é organizado em 3 blocos didáticos:

1. Configurações Gerais da Aplicação: Caminho do arquivo .conf, origem da resolução (CLI, variável de ambiente, arquivo de usuário ou default), ambiente (development, staging, production), nível de log, interfaces de bind, porta TCP, caminhos de logs de auditoria e lista de IPs autorizados.
2. Provedores de Infraestrutura & Segredos: Localização do security.yaml, backend de segredos ativo (env, vault, vaultwarden) e contagem/identificadores de tenants cadastrados para cada conector (AWS, GitLab, GitHub, Azure DevOps, AWX, Jenkins).
3. Governança de Agentes de Inteligência Artificial: Totais consolidados de agentes, perfis e ferramentas MCP únicas, seguido do detalhamento de cada agente com token mascarado (ex: toke****), permissão de ações destrutivas (AUTORIZADO com alerta ou BLOQUEADO), tenants liberados e catálogo de ferramentas acessíveis.

---

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ável	Padrão	Descrição Didática
SENTINEL_AUTH_TOKEN	sentinel-secret-token	Bearer token estático de fallback utilizado em testes ou inicializações básicas.
SENTINEL_CONF_FILE	(nenhum)	Caminho customizado para sobrescrever o arquivo de configuração (.conf ou .env).
SENTINEL_SECURITY_CONFIG	config/security.yaml	Caminho do arquivo declarativo GitOps com os perfis RBAC, tenants e agentes.
SENTINEL_AUDIT_LOG_PATH	logs/audit.log	Destino do arquivo síncrono de trilha forense JSONLines.
SENTINEL_HOST	0.0.0.0	Endereço IP padrão para escuta do servidor ASGI Starlette/FastMCP.
SENTINEL_PORT	8000	Porta TCP para escuta das requisições MCP/SSE.
SENTINEL_ENVIRONMENT	development	Identificador de ambiente operacional (development, staging, production).
SENTINEL_LOG_LEVEL	INFO	Granularidade dos logs operacionais (DEBUG, INFO, WARNING, ERROR).
SENTINEL_PID_FILE	~/.mcpsentinel/mcpsentinel.pid	Caminho do arquivo de trava (lockfile) e PID para o daemon de segundo plano.
SENTINEL_LOG_FILE	~/.mcpsentinel/logs/mcpsentinel.log	Caminho do arquivo de log dedicado das operações do daemon.
SENTINEL_CONTROL_SOCK	~/.mcpsentinel/control.sock	Caminho explícito do Unix Domain Socket (UDS) para controle IPC do daemon.
SENTINEL_SECRETS_BACKEND	env	Mecanismo ativo para resolução de segredos (env, vault, vaultwarden).
SENTINEL_ALLOWED_IPS	* (ou vazio)	Lista de IPs ou blocos CIDR autorizados separados por vírgula (ex: 127.0.0.1,10.0.0.0/24).
SENTINEL_BIND_INTERFACES	127.0.0.1	Interfaces de rede permitidas para ligação do socket local.
SENTINEL_METRICS_ENABLED	true	Habilita ou desabilita o endpoint de métricas Prometheus /metrics (true/false).
SENTINEL_METRICS_PORT	(nenhum)	Porta TCP dedicada opcional para o servidor isolado de métricas (se nula, expõe na porta principal).
SENTINEL_METRICS_HOST	0.0.0.0	Endereço IP de escuta para o servidor dedicado de métricas Prometheus.

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

Variável	Finalidade
VAULTWARDEN_URL	URL base da API ou interface do Vaultwarden / Bitwarden (ex: https://vaultwarden.empresa.internal).
VAULTWARDEN_CLIENT_ID	Identificador de cliente (API Key do usuário) para autenticação REST autônoma M2M (ex: user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
VAULTWARDEN_CLIENT_SECRET	Segredo da API Key do usuário para autenticação REST autônoma M2M no Vaultwarden / Bitwarden.
VAULTWARDEN_MASTER_KEY	Chave mestre ou senha em texto plano utilizada para decriptografia em memória dos itens do cofre (compatível com VAULTWARDEN_PASSWORD).
BW_SESSION	Token de sessão do Bitwarden CLI (bw unlock --raw), utilizado como fallback opcional para instâncias locais com o utilitário bw.
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	Credenciais básicas AWS da máquina host para permitir o início de sessões STS.
AWS_DEFAULT_REGION	Região AWS padrão (ex: us-east-1, sa-east-1).
GITLAB_BASE_URL	URL base do GitLab (padrão: https://gitlab.com ou instância self-hosted).
GITLAB_TOKEN	Token com permissões de API para interagir com o GitLab (ou URI vaultwarden://<item_id>/<campo>).
GITHUB_BASE_URL	URL base da API do GitHub (padrão: https://api.github.com ou https://<host>/api/v3 para Enterprise).
GITHUB_TOKEN	Token de Acesso Pessoal (PAT clássico ou Fine-Grained) com permissões de repositório (ou URI vaultwarden://<item_id>/<campo>).
AZURE_DEVOPS_BASE_URL	URL base do Azure DevOps (padrão: https://dev.azure.com).
AZURE_DEVOPS_TOKEN	Personal Access Token (PAT) corporativo com escopo de leitura/escrita em repositórios (ou URI vaultwarden://<item_id>/<campo>).
AWX_BASE_URL	Endereço do cluster Ansible AWX / Automation Platform.
AWX_TOKEN	Token de autenticação Bearer para lançamento e monitoramento de Job Templates (ou URI vaultwarden://<item_id>/<campo>).
JENKINS_BASE_URL	URL raiz da instância Jenkins (ex: https://jenkins.corp.internal:8080).
JENKINS_USERNAME	Nome de usuário da conta de automação/serviço no Jenkins.
JENKINS_TOKEN	API Token gerado para o usuário Jenkins (ou URI vaultwarden://<item_id>/<campo>).
SLACK_WEBHOOK_URL	URL de Webhook de Entrada (Incoming Webhook) para notificações push no Slack (opcional).
SLACK_CHANNEL	Canal ou override opcional de exibição no Slack (ex: #secops-alerts).
SMTP_HOST	Host do servidor de e-mail SMTP para envio de notificações de alerta (opcional).
SMTP_PORT	Porta do servidor SMTP (padrão: 587 com suporte a STARTTLS).
SMTP_USER	Nome de usuário / credencial para autenticação no servidor SMTP (opcional).
SMTP_PASSWORD	Senha de aplicação ou credencial para autenticação no servidor SMTP (opcional).
ALERT_EMAIL_FROM	Endereço do remetente exibido nos e-mails de alerta (padrão: noreply@mcpsentinel.local).
ALERT_EMAIL_TO	Destinatário(s) para recebimento de alertas críticos e notificações de segurança.

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:

Ferramenta MCP	Descrição	Parâmetros Principais	Salvaguarda / Guardrail
github_get_repository	Metadados do repositório (visibilidade, default branch, etc.)	organization, repository	Restrição de tenant e allowed_repositories
github_list_branches	Listagem de branches com flag de proteção	organization, repository, protected_only	Restrição de tenant e allowed_repositories
github_get_file_contents	Leitura decodificada (Base64 UTF-8) com limite de tamanho seguro	organization, repository, file_path, ref	Validação de path e isolamento
github_list_pull_requests	Listagem e filtro de Pull Requests (abertos, fechados)	organization, repository, state	Restrição de tenant e allowed_repositories
github_create_branch	Criação de novas branches a partir de ref base	organization, repository, branch, ref	Bloqueio imediato se target for branch protegida
github_create_or_update_file	Commit atômico de arquivos com resolução automática de SHA	organization, repository, file_path, content, branch, commit_message	BranchProtectionGuardrail em memória
github_create_pull_request	Abertura formal de Pull Request	organization, repository, title, head, base, body	Restrição de tenant e allowed_repositories
github_delete_branch	Exclusão de branch remota	organization, repository, branch, confirm_action, justification	Precedência absoluta de branch protection + Tríade de Confirmação

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

Ferramenta MCP	Descrição	Parâmetros Principais	Salvaguarda / Guardrail
jenkins_trigger_job	Dispara execução de job simples ou parametrizado (build / buildWithParameters)	instance, job_name, parameters (dict), wait_for_build_number (bool), confirm_action (bool), justification (str)	Valida allowed_jobs, bloqueia disallowed_parameters, exige confirmação explícita para jobs críticos
jenkins_get_build_status	Consulta status, duração, resultado (SUCCESS, FAILURE, BUILDING) e URLs da build	instance, job_name, build_number (int ou alias ex: "lastBuild")	Escopo de instância e restrição de allowed_jobs
jenkins_get_build_console	Coleta saída de console da build com mascaramento automático de credenciais	instance, job_name, build_number, start_line (int), limit_lines (int)	Sanitização regex recursiva de segredos na saída

---

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:
    # Opção A: Configuração via Profile local do AWS CLI (~/.aws/config e ~/.aws/credentials)
    - id: "dev-account"
      profile: "dev-profile"
      name: "Ambiente de Desenvolvimento (Profile)"
      allowed_regions: ["us-east-1", "sa-east-1"]

    # Opção B: Especificação Direta com Account ID de 12 dígitos (AssumeRole ou credenciais base)
    - id: "prod-account"
      account_id: "444455556666"
      name: "Ambiente de Produção (Direto)"
      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

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, ADR 010, ADR 014 e ADR 015, integrando o conector mcpsentinel.security.secrets (SecretsManager e VaultwardenResolver).

A resolução é realizada primariamente via API REST direta (M2M) utilizando as chaves de API do usuário (client_credentials), sem necessidade de binários externos ou tokens comerciais proprietários (BWS_ACCESS_TOKEN), com fallback defensivo para a CLI oficial do Bitwarden (bw).

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.

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

Resolução Primária: API REST Autônoma (M2M Headless)

O modo primário e recomendado opera de maneira 100% autônoma (sem intervenção de operador humano e sem criação de processos de subprocesso em terminal):

1. Obtenção das Chaves de API no Vaultwarden Web:

   • Acesse o Vaultwarden no navegador.
   • Vá em Configurações da Conta > Segurança > aba Chaves de API.
   • Clique em Ver Chave de API, confirme sua senha mestre e copie o client_id e o client_secret.

2. Configuração no mcpsentinel.conf ou Ambiente:

   VAULTWARDEN_URL="https://vaultwarden.empresa.internal"
   VAULTWARDEN_CLIENT_ID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   VAULTWARDEN_CLIENT_SECRET="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
   VAULTWARDEN_MASTER_KEY="minha-senha-mestre-ou-chave-kdf"
   

3. O VaultwardenResolver realiza a autenticação OAuth2 M2M (grant_type=client_credentials), armazena o token de acesso temporário na memória com auto-renovação e decifra os ciphers solicitados diretamente em memória via criptografia AES-CBC/AES-GCM (Zero Credential Leakage).

Resolução Fallback: Bitwarden CLI (bw)

Caso as credenciais da API REST não estejam configuradas, o McpSentinel recorre à CLI oficial bw instalada no sistema caso uma sessão esteja ativa:

1. Configurar servidor e autenticar com API Key:

   bw config server https://seu-vaultwarden.empresa.com
   export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   export BW_CLIENTSECRET="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
   bw login --apikey
   

2. Destravar cofre e exportar BW_SESSION:

   export BW_SESSION="$(bw unlock --raw)"
   

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

# Configuração de segredos Vaultwarden / Bitwarden API REST (opcional)
VAULTWARDEN_URL=""
VAULTWARDEN_CLIENT_ID=""
VAULTWARDEN_CLIENT_SECRET=""
VAULTWARDEN_MASTER_KEY=""
BW_SESSION=""

# 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_BASE_URL=""
JENKINS_USERNAME=""
JENKINS_TOKEN=""

# Canais de Alerta e Monitoração (Slack e E-mail/SMTP - opcional)
SLACK_WEBHOOK_URL=""
SLACK_CHANNEL=""
SMTP_HOST=""
SMTP_PORT=587
SMTP_USER=""
SMTP_PASSWORD=""
ALERT_EMAIL_FROM="noreply@mcpsentinel.local"
ALERT_EMAIL_TO=""

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:

Identificador	Serviço / Módulo	Principais Parâmetros Configurados
server	Servidor HTTP & Rede	Host, Porta, Nível de Log, Ambiente, Auth Token, Allowlist CIDR
secrets	Provedor de Segredos	Backend (env, vault, vaultwarden), Vault URL/Token, Vaultwarden REST API Keys
aws	Amazon Web Services	Região Padrão, Credenciais Host (Access Key / Secret Key)
gitlab	GitLab DevOps	Base URL, Token de API
azure	Azure DevOps	Base URL, Personal Access Token (PAT)
awx	Ansible AWX / Tower	Base URL, Token de Automação Bearer
jenkins	Jenkins CI/CD	Habilitação (true/false), Base URL, Usuário, API Token

---

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

Flag	Descrição
-s, --configuration-summary	(Recomendado) Exibe o resumo detalhado e diagnóstico de configurações ativas, provedores e governança de agentes de IA em linguagem humana sem iniciar o servidor.
--json	Emite a saída do resumo de configuração (-s) formatada em JSON estruturado (ideal para scripts e CI/CD).
-v, --version	Exibe a versão atual instalada do McpSentinel e encerra.
-h, --help	Exibe a mensagem de ajuda com todos os subcomandos e opções disponíveis.
--pid-file <caminho>	Define caminho personalizado para o arquivo de trava/PID.

Resumo de Subcomandos

Subcomando	Finalidade	Principais Flags
init	Gera template canônico mcpsentinel.conf com permissões restritas	--force, --path <caminho>
configure	Assistente interativo de configuração (wizard) no terminal	--conf-file <caminho>, --service <nome>
start	Inicia o gateway em primeiro plano ou como daemon de fundo	-d (--daemon), --port, --bind, --allow-ip, --conf-file <caminho>, --config
restart	Reinicia a instância ativa do daemon	-d (--daemon), --conf-file <caminho>, --timeout <segundos>
status	Inspeciona estado e processo em execução (código LSB)	--pid-file <caminho>, --detailed, --check-upstreams, --json
reload	Envia sinal SIGHUP para recarregar políticas e logs	--pid-file <caminho>
stop	Interrompe o daemon de forma graciosa ou forçada	--force, --timeout <segundos>
install-service	Instala e registra o gateway como serviço systemd	--user, --system, --enable, --start, --linger, -f (--force), --conf-file <caminho>
uninstall-service	Desinstala e desativa o serviço systemd	--user, --system
ctl	Controle inter-processos e observabilidade do daemon (UDS/IPC)	status, connections, logs, reload, --socket <path>
connections	Alias direto de primeiro nível para mcpsentinel ctl connections	list, kill <id>
logs	Alias direto de primeiro nível para mcpsentinel ctl logs	-f, -n <linhas>, --level, --audit, --json
test-alerts	Dispara alerta sintético de teste para validação de Slack e E-mail	--channel {slack,email,all}, --conf-file <caminho>, --json
test-connections	Executa testes sintéticos pré-voo de conectividade e autenticação com provedores	--provider {aws,github,gitlab,azure,jenkins,awx}, --timeout <segundos>, --conf-file <caminho>, --config <path>, --json
test-vaults	Executa diagnóstico sintético pré-voo de conectividade e integridade de cofres e segredos	--vault {vaultwarden,bw,bws,hashicorp-vault,local,all}, --timeout <segundos>, --conf-file <caminho>, --json

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.

---

📡 Monitoração, Visibilidade e Alertas (Slack e E-mail)

O McpSentinel conta com um subsistema nativo e assíncrono de notificações em tempo real projetado para equipes de SRE, SecOps e administradores de infraestrutura (OpenSPEC SPEC-MCP-92-001 e PRD-MCP-92).

1. Princípios Arquiteturais e Garantia Fail-Safe

• Desacoplamento Assíncrono Não-Bloqueante: Todos os disparos de rede (HTTP POST para o webhook do Slack e conexões SMTP/TLS para E-mail) são despachados em segundo plano (asyncio.create_task ou threadpool dedicada). O cliente MCP recebe a resposta da ferramenta com latência mínima, sem jamais ficar esperando confirmação externa de notificação.
• Isolamento Absoluto (Fail-Safe): Se a rede oscilar, o webhook do Slack falhar, o servidor SMTP estiver fora do ar ou credenciais externas expirarem, o gateway MCP continua respondendo normalmente e a auditoria local em disco (audit.log) permanece 100% gravada sob a diretriz Fail-Secure. Falhas nos canais externos são registradas apenas como advertências operacionais (logger.warning) e nunca abortam o atendimento a agentes de IA.
• Opcionalidade Estrita (Zero Overhead): Se nenhuma variável de notificação for configurada, o subsistema opera em modo no-op, sem instanciar clientes HTTP, sem abrir conexões de socket e sem consumir recursos em memória.
• Deduplicação Inteligente (Anti-Spam de 60s): Eventos repetidos com a mesma assinatura (mesma ferramenta, agente, status e erro) dentro de uma janela de 60 segundos são deduplicados em memória, prevenindo rajadas de notificações caso uma IA entre em loop de tentativas.
• Zero Credential Leakage: Todos os alertas passam por rotinas recursivas de sanitização antes do envio. Tokens, senhas, chaves privadas e tracebacks brutos de erro são substituídos por [REDACTED].

2. Gatilhos de Notificação

O gateway monitora o ciclo de vida de ferramentas e despacha alertas push automaticamente nas seguintes situações:

1. Ações Destrutivas Autorizadas (HIGH RISK ACTION): Execução de operações críticas na nuvem ou repositórios (ex: exclusão de buckets S3, rescisão de instâncias EC2, remoção de branches no GitLab/GitHub), mesmo quando autorizadas pela Tríade de Confirmação.
2. Bloqueios de Segurança RBAC e Guardrails (SECURITY ALERT): Tentativas de agentes de IA executarem ferramentas fora do seu perfil, acessarem contas/tenants não atribuídos ou acionarem comandos destrutivos sem parâmetros obrigatórios.
3. Falhas Críticas de Sistema (CRITICAL SYSTEM ERROR): Erros graves de conectores de infraestrutura, indisponibilidade de provedores externos ou falhas de execução interna sanitizadas.

3. Variáveis de Configuração no mcpsentinel.conf / Ambiente

# Configurações do Canal Slack (Opcional)
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
SLACK_CHANNEL="#secops-alerts"

# Configurações do Canal E-mail / SMTP (Opcional)
SMTP_HOST="smtp.empresa.com"
SMTP_PORT=587
SMTP_USER="alertas@empresa.com"
SMTP_PASSWORD="senha-ou-app-password-do-smtp"
ALERT_EMAIL_FROM="noreply@mcpsentinel.local"
ALERT_EMAIL_TO="secops-team@empresa.com"

4. Diagnóstico Pré-Voo: Subcomando mcpsentinel test-alerts

O McpSentinel oferece o utilitário CLI test-alerts para disparar notificações sintéticas e validar conectividade, certificados TLS e credenciais de entrega sem precisar gerar incidentes reais:

# Testar todos os canais configurados (padrão):
mcpsentinel test-alerts

# Testar exclusivamente o canal Slack:
mcpsentinel test-alerts --channel slack

# Testar exclusivamente o canal E-mail/SMTP:
mcpsentinel test-alerts --channel email

# Apontar arquivo de configuração específico:
mcpsentinel test-alerts --conf-file /etc/mcpsentinel/producao.conf

# Saída estruturada em JSON (automação e CI/CD):
mcpsentinel test-alerts --json

Exemplo de saída de diagnóstico no terminal:

============================================================
Diagnóstico de Canais de Alerta (McpSentinel test-alerts)
============================================================
  • Canal:   SLACK
    Status:  SUCCESS
    Latência: 142ms
    Detalhes: OK
------------------------------------------------------------
  • Canal:   EMAIL
    Status:  SUCCESS
    Latência: 380ms
    Detalhes: OK
------------------------------------------------------------

Códigos de saída do utilitário (Exit Codes):

• 0: Todos os canais testados responderam com sucesso (ou nenhum canal configurado no modo all).
• 1: Ao menos um canal ativo falhou na validação sintética de envio ou canal específico não foi configurado.

---

📊 Observabilidade Contínua para SRE (Métricas Prometheus /metrics)

O McpSentinel implementa um coletor nativo em memória e formatador em conformidade estrita com o padrão Prometheus Exposition Format (text/plain; version=0.0.4), sem dependências externas de compilação em C e com latência de raspagem (scraping) $p99 < 30\text{ms}$ (OpenSPEC SPEC-MCP-91-001).

1. Coleta e Métricas Disponíveis

Por padrão, a rota GET /metrics fica disponível no próprio servidor HTTP/SSE do gateway (porta 8000). Para ambientes de alta segurança que exigem isolamento de portas, é possível direcionar a telemetria para uma porta dedicada através de SENTINEL_METRICS_PORT.

As métricas exportadas abrangem todo o ciclo de vida do serviço e das ferramentas:

• mcpsentinel_requests_total{provider, tool, status}: Contador monotônico do volume total de requisições atendidas pelo gateway, categorizadas por conector upstream (aws, github, gitlab, azure, awx, jenkins), nome da ferramenta e resultado da execução (success, failed, blocked).
• mcpsentinel_request_duration_seconds{provider, tool}: Histograma com 11 buckets padronizados (0.005 até 10.0 segundos) para medição precisa de latência operacional de chamadas a provedores e ferramentas.
• mcpsentinel_process_cpu_seconds_total: Consumo de tempo de CPU em segundos (usuário + sistema) do processo Python.
• mcpsentinel_process_resident_memory_bytes: Memória residente física (RSS) alocada pelo gateway em bytes.
• mcpsentinel_process_uptime_seconds: Tempo decorrido de atividade ininterrupta do serviço.
• mcpsentinel_active_connections: Quantidade instantânea de conexões ativas de clientes MCP (canais SSE abertos).
• mcpsentinel_provider_up{provider, tenant}: Gauge binário indicando a saúde sintética do provedor (1 = saudável / operacional, 0 = com falha de autenticação ou conectividade).
• mcpsentinel_provider_last_check_timestamp_seconds{provider, tenant}: Carimbo de tempo Epoch da última verificação bem-sucedida do provedor.

2. Exemplo de Raspagem via cURL

# Consultar métricas no endpoint padrão do gateway:
curl -s http://127.0.0.1:8000/metrics

# Exemplo de saída formatada em padrão Prometheus:
# HELP mcpsentinel_requests_total Total de chamadas a ferramentas MCP atendidas pelo gateway
# TYPE mcpsentinel_requests_total counter
mcpsentinel_requests_total{provider="aws",status="success",tool="aws_describe_instances"} 42
mcpsentinel_requests_total{provider="gitlab",status="blocked",tool="gitlab_delete_branch"} 3

# HELP mcpsentinel_active_connections Quantidade instantânea de conexões e canais SSE ativos
# TYPE mcpsentinel_active_connections gauge
mcpsentinel_active_connections 2

---

🔍 Diagnóstico Sintético Pré-Voo de Conexões (test-connections)

Para garantir que todas as credenciais de provedores externos (AWS, GitHub, GitLab, Azure DevOps, AWX, Jenkins) e segredos resolvidos via Vaultwarden estejam válidos antes de abrir o atendimento às IAs, o McpSentinel oferece o subcomando test-connections.

1. Princípios de Segurança e Não-Destrutividade

• Testes Estritamente Somente-Leitura (Read-Only / Ping / WhoAmI): Os testes sintéticos utilizam apenas APIs idempotentes e seguras (ex: GetCallerIdentity no AWS STS, GET /user no GitHub/GitLab, connectionData no Azure DevOps, /api/json no Jenkins e /api/v2/ping/ no AWX). Nenhuma alteração é gravada na infraestrutura.
• Execução Concorrente com Timeout Determinístico: Todas as verificações rodam em paralelo via asyncio.gather com timeout individual estrito (padrão de 5.0 segundos).
• Zero Credential Leakage: Tokens de autenticação, chaves de acesso e detalhes sensíveis de exceções de rede são rigorosamente mascarados ([REDACTED]).

2. Exemplos Práticos de Execução

# Testar todos os provedores e tenants configurados:
mcpsentinel test-connections

# Testar exclusivamente um provedor específico:
mcpsentinel test-connections --provider gitlab
mcpsentinel test-connections --provider aws

# Configurar timeout customizado de 10 segundos:
mcpsentinel test-connections --timeout 10.0

# Saída estruturada em JSON (ideal para esteiras de CI/CD e automações):
mcpsentinel test-connections --json

Exemplo de exibição com tabela formatada no terminal:

+----------------+----------------+-------------------------------+---------+----------+----------------------------+
| PROVEDOR       | TENANT / ALIAS | ENDPOINT / REGIÃO             | STATUS  | LATÊNCIA | IDENTIDADE / CONTA         |
+----------------+----------------+-------------------------------+---------+----------+----------------------------+
| AWS            | production     | us-east-1                     | OK      | 145ms    | arn:aws:iam::123456:role/..|
| GitLab         | default        | https://gitlab.com            | OK      | 210ms    | devops-bot                 |
| GitHub         | default        | https://api.github.com        | OK      | 185ms    | sentinel-ci                |
| Jenkins        | ci-cluster     | https://jenkins.corp.internal | OK      | 95ms     | svc_sentinel               |
+----------------+----------------+-------------------------------+---------+----------+----------------------------+
Sumário: 4 verificados | 4 saudáveis | 0 falhas | Tempo Total: 280ms

Códigos de saída (Exit Codes):

• 0: Todos os provedores testados estão operacionais e autenticados com sucesso.
• 1: Ao menos um provedor ativo falhou no teste sintético de conexão/autenticação.
• 2: Erro de sintaxe nos argumentos ou na carga dos arquivos de configuração.

---

🩺 Inspeção Integrada com --check-upstreams (mcpsentinel status)

Além de inspecionar o processo do daemon em segundo plano, o comando mcpsentinel status suporta a flag --check-upstreams. Ela aciona os testes sintéticos em tempo real e anexa o diagnóstico de conectividade com as nuvens diretamente após o estado do daemon:

# Inspecionar status do serviço e testar conectividade com provedores externos:
mcpsentinel status --check-upstreams

# Com saída completa estruturada em JSON:
mcpsentinel status --check-upstreams --json

---

🔐 Diagnóstico Sintético Pré-Voo de Cofres e Segredos (test-vaults)

Para assegurar que os serviços upstream de cofres e segredos (Vaultwarden API REST M2M, Bitwarden CLI bw/bws, HashiCorp Vault e variáveis de ambiente locais) estejam alcançáveis, ativos e autenticados antes da execução de cargas de trabalho, o McpSentinel provê o subcomando test-vaults (MCP-96).

1. Princípios de Segurança e Zero Credential Leakage

• Validações Seguras e Idempotentes: Requisições pontuais à API (POST /identity/connect/token no Vaultwarden, bw status / bws --version no Bitwarden CLI, GET /v1/sys/health e GET /v1/auth/token/lookup-self no HashiCorp Vault).
• Zero Credential Leakage: Chaves de API, senhas mestras, tokens de sessão (BW_SESSION) ou tokens do Vault jamais aparecem na saída, logs ou traces. O identificador autenticado é exibido com mascaramento preventivo (ex: Client ID: user_a****).
• Medição Precisa de Latência (RTT): Mensuração do tempo de resposta de cada serviço em milissegundos (ms).
• Detecção Passiva Local: Quando nenhum cofre remoto estiver presente no ambiente, o teste informa status NÃO CONFIGURADO ou OK (quando filtrado via --vault local) sem falhar a execução geral.

2. Exemplos Práticos de Execução

# Testar todos os serviços de cofres detectados no ambiente ou fallback local:
mcpsentinel test-vaults

# Testar especificamente o backend Vaultwarden REST M2M:
mcpsentinel test-vaults --vault vaultwarden

# Testar especificamente o Bitwarden CLI (bw ou bws):
mcpsentinel test-vaults --vault bw
mcpsentinel test-vaults --vault bws

# Testar especificamente a API do HashiCorp Vault:
mcpsentinel test-vaults --vault hashicorp-vault

# Testar exclusivamente as variáveis de ambiente locais:
mcpsentinel test-vaults --vault local

# Definir tempo limite de 10 segundos por verificação:
mcpsentinel test-vaults --timeout 10.0

# Saída puramente estruturada em JSON (sem caracteres ANSI, pronta para scripts e jq):
mcpsentinel test-vaults --json

Exemplo de saída no terminal:

                 Resultados do Diagnóstico Sintético de Cofres                  
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Cofre /       ┃ Endpoint /    ┃               ┃               ┃ Identidade / ┃
┃ Backend       ┃ Modo          ┃ Status        ┃ Latência (ms) ┃ Detalhes     ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Vaultwarden   │ https://vault │ OK            │       82.4 ms │ Client ID:   │
│ (REST M2M)    │ .example.com  │               │               │ user_a****   │
│ HashiCorp     │ https://vault │ OK            │       60.1 ms │ Display      │
│ Vault         │ .corp:8200    │               │               │ Name: token- │
│               │               │               │               │ mcp, ...     │
└───────────────┴───────────────┴───────────────┴───────────────┴──────────────┘
Status Geral: OK | Total de cofres: 2 | Sucesso: 2 | Falhas: 0 | Não configurados: 0 | Duração: 142.5 ms

Códigos de saída (Exit Codes LSB):

• 0: Todos os cofres testados retornaram status OK (ou NÃO CONFIGURADO em escopo geral all).
• 1: Ocorreu ao menos uma falha (FAILED) em cofre configurado ou explicitamente requisitado.
• 2: Erro de sintaxe nos argumentos (ex: --timeout -1, --vault invalido ou --conf-file inexistente).

---

🔌 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"}

---

3. Integração com Agentes de IA (Claude Code, Antigravity 1.x/2.x e Open Code)

Para instruções passo a passo detalhadas com exemplos de configuração em arquivo JSON e linha de comando para agentes autônomos, consulte a Seção 11 do Manual de Operação: 👉 Manual de Operação — Seção 11: Configuração em Agentes de IA (localizado em docs/manual-de-operacao.md).

---

🐳 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}
      - VAULTWARDEN_URL=${VAULTWARDEN_URL}
      - VAULTWARDEN_CLIENT_ID=${VAULTWARDEN_CLIENT_ID}
      - VAULTWARDEN_CLIENT_SECRET=${VAULTWARDEN_CLIENT_SECRET}
      - VAULTWARDEN_MASTER_KEY=${VAULTWARDEN_MASTER_KEY}
      - 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.