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
🔐 Resolução Dinâmica de Segredos via Vaultwarden / Bitwarden Secrets Manager
⚡ Guia de Instalação e Uso (Quickstart)
🧰 Catálogo de Ferramentas e Recursos Azure DevOps (Azure Repos & Pipelines)
🔌 Guia de Integração com Clientes MCP
🐳 Implantação em Produção e Contêineres
🧪 Testes Herméticos e Quality Gates
📚 Documentação Complementar do Harness
📄 Licença e Governança

🛡️ Pilares Fundamentais de Segurança

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>.
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.
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.
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.
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].
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:

Argumentos de Linha de Comando (CLI): Flags explícitas passadas na invocação (--port, --bind, --conf-file, etc.) têm prioridade máxima.
Variável de Ambiente SENTINEL_CONF_FILE: Permite apontar um caminho arbitrário de arquivo .conf ou .env.
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.
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).
Variáveis de Ambiente do Sistema Operacional (Shell OS): Valores exportados diretamente no ambiente com prefixo SENTINEL_.
Valores Padrão (Defaults da Aplicação): Definidos nas classes de configuração do gateway.
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:

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.
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).
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 (Expansão MCP-117 — 19 Ferramentas Homologadas)

O conector Jenkins expõe 19 ferramentas padronizadas para observabilidade profunda, controle de execução, ciclo de vida/CRUD e mutações críticas com protocolo HITL (Human-in-the-Loop), governadas por RBAC declarativo, catálogo de jobs permitidos (allowed_jobs), parâmetros bloqueados (disallowed_parameters), confirmação obrigatória para ações sensíveis (require_confirmation_jobs), proteção Anti-XXE (defusedxml) e desafio criptográfico Two-Phase Gated Action:

Ferramenta MCP	Descrição	Parâmetros Principais	Salvaguarda / Guardrail
`jenkins_list_jobs`	Descoberta hierárquica de jobs e pastas	`instance`, `folder_path`, `depth`	Filtragem por whitelist `allowed_jobs`
`jenkins_get_job_details`	Metadados completos do job, parâmetros e health report	`instance`, `job_name`	Restrição de tenant e `allowed_jobs`
`jenkins_get_build_status`	Status, duração, resultado (`SUCCESS`, `FAILURE`) e URLs	`instance`, `job_name`, `build_number`	Escopo de instância e restrição de `allowed_jobs`
`jenkins_get_build_console`	Coleta saída de console com paginação e mascaramento de segredos	`instance`, `job_name`, `build_number`, `start_line`, `limit_lines`	Sanitização regex recursiva (Zero Leakage)
`jenkins_get_build_test_report`	Relatório consolidado de testes (pass, fail, skip, traces)	`instance`, `job_name`, `build_number`	Restrição de tenant e `allowed_jobs`
`jenkins_get_pipeline_stages`	Árvore de estágios via Pipeline Graph API	`instance`, `job_name`, `build_number`	Restrição de tenant e `allowed_jobs`
`jenkins_get_build_failure_summary`	Diagnóstico sintético de causa raiz de falha	`instance`, `job_name`, `build_number`	Agregação segura de traces e erros
`jenkins_trigger_job`	Dispara execução de job simples ou parametrizado	`instance`, `job_name`, `parameters`, `wait_for_build_number`, `confirm_action`, `justification`	Valida `allowed_jobs`, bloqueia `disallowed_parameters`, exige confirmação explícita para jobs críticos
`jenkins_rebuild_job`	Reexecuta build reaproveitando parâmetros anteriores	`instance`, `job_name`, `build_number`, `confirm_action`, `justification`	Restrição de tenant e `allowed_jobs`
`jenkins_stop_build`	Interrupção imediata de build em andamento	`instance`, `job_name`, `build_number`, `confirm_action`, `justification`	Ação destrutiva governada por Tríade de Confirmação
`jenkins_get_queue`	Inspeção de itens agendados e bloqueados na fila	`instance`	Restrição de escopo de tenant
`jenkins_cancel_queue_item`	Remoção de item enfileirado antes do início	`instance`, `queue_id`, `confirm_action`, `justification`	Confirmação e auditoria operacional
`jenkins_get_job_config`	Leitura do `config.xml` declarativo do job	`instance`, `job_name`	Sanitização preventiva de credenciais no XML
`jenkins_create_job`	Criação de novo job a partir de XML	`instance`, `job_name`, `config_xml`, `confirm_action`, `justification`	Validação Anti-XXE obrigatória (`defusedxml`) + `allowed_jobs`
`jenkins_copy_job`	Duplicação de job existente para novo pipeline	`instance`, `from_job_name`, `to_job_name`, `confirm_action`, `justification`	Restrição de tenant e `allowed_jobs`
`jenkins_enable_job`	Reativação de job desativado	`instance`, `job_name`	Restrição de tenant e `allowed_jobs`
`jenkins_disable_job`	Desativação preventiva de job sem exclusão	`instance`, `job_name`, `confirm_action`, `justification`	Confirmação explícita e auditoria
`jenkins_update_job_config`	Atualização de `config.xml` com Two-Phase Gated Action	`instance`, `job_name`, `config_xml`, `confirmation_code`, `justification`	Protocolo HITL Two-Phase: Emissão de código `AUTH-XXXX` com diff unificada e relatório de impacto na Fase 1; anti-tampering e anti-replay na Fase 2
`jenkins_delete_job`	Exclusão permanente de job e históricos	`instance`, `job_name`, `confirm_action`, `justification`	Ação Destrutiva: Tríade de Confirmação estrita + flag RBAC `destructive_actions_allowed`

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

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.
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"
```
Tip

O parâmetro VAULTWARDEN_MASTER_KEY aceita a senha mestra textual, a chave derivada via CLI bw ou a chave hexadecimal calculada por PBKDF2. Para instruções detalhadas e scripts de pré-derivação, consulte a Seção 5.2 do Manual de Operação.
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:

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

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

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.
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.
Mascaramento Rigoroso de Senhas: Tokens e credenciais sensíveis (secret=True) utilizam entrada oculta/mascarada no terminal, prevenindo vazamento visual (shoulder surfing).
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.
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

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.
6 - Central de Aprovações Human-in-the-Loop (HITL): Acessa diretamente a fila de aprovação e autorização de requisições retidas com contagem regressiva de TTL, exibindo badge dinâmico [N pendente(s)].
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

🛡️ Central de Aprovações Human-in-the-Loop (HITL) no Wizard e CLI

A Central HITL (adicionada no Épico MCP-130) introduz uma barreira de autorização humana obrigatória e em tempo real para operações sensíveis ou mutações críticas disparadas por agentes de IA autônomos (como alterações de configurações XML no Jenkins ou templates destrutivos no Ansible AWX).

1. Como Acessar a Central de Aprovações

Existem duas formas principais de interagir com a fila de aprovações:

Pelo Assistente Interativo (mcpsentinel configure):
- No menu principal do assistente, a opção [6] Central de Aprovações Human-in-the-Loop (HITL) exibe dinamicamente o número de tickets pendentes (ex: [2 pendente(s)] ou [Daemon Offline]).
- Ao selecionar a opção 6, a tela TUI dedicada é aberta no terminal.
Pelo Comando Dedicado da CLI (mcpsentinel approvals / mcpsentinel approve):
- Utilitário direto de linha de comando para operadores de SecOps e SRE inspecionarem e deliberarem sobre chamadas pendentes.

# Abrir a Central HITL interativa no terminal (TUI)
mcpsentinel approvals

# Alias de comando equivalente
mcpsentinel approve

# Iniciar diretamente no modo Live Watch (atualização contínua a cada 3 segundos)
mcpsentinel approvals -w
mcpsentinel approvals --watch

# Listar requisições pendentes em JSON puro (ideal para automações e dashboards externos)
mcpsentinel approvals --json

# Apontar para socket UDS customizado
mcpsentinel approvals --socket /var/run/mcpsentinel/control.sock

2. Funcionalidades da Central HITL

Identificador Amigável e TTL Estrito: Cada solicitação recebe um ticket determinístico REQ-XXXX (ex: REQ-8A2F) com tempo de vida útil de 300 segundos (5 minutos). Se não houver decisão antes do timeout, a solicitação expira automaticamente (EXPIRED), garantindo a diretriz de Fail-Secure.
Inspeção de Unified Diff Colorido ANSI: Ao abrir um ticket pendente, o operador visualiza o diff unificado da alteração com destaque sintático de cores (verde para adições, vermelho para deleções, ciano para marcadores de bloco). Em ambientes sem suporte a terminal TTY, o sistema adota fallback automático em ASCII limpo.
Sanitização de Segredos: Dados de identificação do agente, tenant, justificativa da IA e parâmetros são apresentados de forma clara, com mascaramento automático de credenciais ([REDACTED]).
Deliberação Humana Autenticada:
- Aprovar ([A]): Autoriza a execução da ação upstream pelo gateway, com suporte a inserção de anotação/observação opcional pelo operador.
- Rejeitar ([R]): Bloqueia a execução imediatamente e exige justificativa obrigatória do operador humano (mínimo de 5 caracteres), a qual é devolvida ao agente de IA.
- Rastreabilidade de Operador: O operador responsável pela aprovação ou rejeição é capturado do usuário local do sistema (getpass.getuser()) e gravado no log de auditoria síncrono.
Histórico Efêmero e Persistência Perpétua: O daemon mantém ring buffer de até 500 decisões tomadas nas últimas 24 horas, além da gravação perpétua à prova de falhas em audit.log.

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>`
`approvals` / `approve`	Central de Aprovações Human-in-the-Loop (HITL) para autorizar ações retidas de IA	`-w` (`--watch`), `--json`, `--socket <path>`
`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évios 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évio de conectividade e integridade de cofres e segredos	`--vault {vaultwarden,bw,bws,hashicorp-vault,local,all}`, `--timeout <segundos>`, `--conf-file <caminho>`, `--json`
`skill`	Gera skills normativas do McpSentinel para agentes de IA (Antigravity, Claude, Cursor)	`generate`, `--format <nome>`, `--target <path>`, `--force`

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
```
Tip

Resolução de Problemas ao Executar com sudo (command not found ou ModuleNotFoundError):
Se o mcpsentinel foi instalado no escopo de usuário (ex: pip install --user em ~/.local/lib/... ou uv tool):
1. sudo: 'mcpsentinel': command not found: O sudo redefine a variável PATH. Resolva indicando o caminho absoluto (sudo $(which mcpsentinel) ...) ou preservando o ambiente (sudo env "PATH=$PATH" mcpsentinel ...).
2. ModuleNotFoundError: No module named 'mcpsentinel': O interpretador Python invocado pelo root não carrega pacotes do diretório pessoal do usuário. Soluções:
  - (Recomendado) Se instalado no usuário, prefira o modo de usuário com lingering sem sudo:
    mcpsentinel install-service --user --enable --start --linger
  - Repassar PYTHONPATH ao sudo:
    sudo PYTHONPATH="$HOME/.local/lib/python3.12/site-packages" mcpsentinel install-service --system --enable --start
  - Instalar o pacote globalmente no sistema:
    sudo pip install mcpsentinel-gateway
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

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

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.
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.
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 Preventivo: 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évio 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évio 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).

🧰 Catálogo de Ferramentas e Recursos Azure DevOps (Azure Repos & Pipelines)

A partir da versão 1.8.0 (Épico MCP-131), o conector do Azure DevOps consolidou 72 ferramentas homologadas para o provedor e 172 ferramentas globais no gateway.

A expansão cobre todo o ciclo de vida de engenharia de software e DevOps: Git Repos & Tags, Governança de Pull Requests & Code Review, Execução, Definições e Inspeção de Pipelines YAML, Autorizações de Recursos, Bibliotecas de CI/CD (Variable Groups e Secure Files), Ambientes e Aprovações (Gates), além de Qualidade de Software (Test Runs e Code Coverage) e Classic Releases (VSRM).

Tabela de Recursos do Azure DevOps (72 Ferramentas Homologadas)

1. Azure Repos — Git Tags, Histórico, Commits e Itens

Ferramenta MCP	Tipo / Ação	Endpoint Azure REST (v7.0/v7.1)	Guardrails & Controles de Segurança
`azure_list_tags`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/refs?filter=tags`	Validação de `allowed_projects` e `allowed_repositories`.
`azure_get_tag`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/annotatedtags/{objectId}`	Metadados da tag e mensagem de anotação.
`azure_create_tag`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/annotatedtags`	Criação de tags anotadas e referências Git.
`azure_delete_tag`	Destrutiva	`/{project}/_apis/git/repositories/{repositoryId}/refs`	Tríade de Confirmação obrigatória (`confirm_action`, `justification`).
`azure_compare_branches`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/diffs/commits`	Delta ahead/behind, commits e arquivos modificados.
`azure_list_commits`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/commits`	Histórico paginado com filtros de branch, autor e período.
`azure_get_commit`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/commits/{commitId}`	Metadados de commit, pais e diffs de arquivos.
`azure_list_repository_items`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/items`	Árvore estruturada de arquivos/pastas por branch ou commit.
`azure_cherry_pick`	Mutação	`/{project}/_apis/git/repositories/{repositoryId}/cherryPicks`	Branch Protection Estrito: alvo proibido em branches protegidas.
`azure_revert_commit`	Mutação	`/{project}/_apis/git/repositories/{repositoryId}/reverts`	Branch Protection Estrito: alvo proibido em branches protegidas.
`azure_download_repository_archive`	Download	`/{project}/_apis/git/repositories/{repositoryId}/items?format=zip`	Teto de download em 50 MB e validação de repositório.
`azure_list_projects`	Descoberta	`/_apis/projects`	Filtragem declarativa por `allowed_projects`.
`azure_list_repositories`	Descoberta	`/{project}/_apis/git/repositories`	Respeita escopo de projetos e repositórios.
`azure_get_repository`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}`	Metadados, URL e default branch.
`azure_list_branches`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/refs?filter=heads`	Listagem de branches e commits de ponta.
`azure_create_branch`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/refs`	Criação de branches a partir de commit base.
`azure_delete_branch`	Destrutiva	`/{project}/_apis/git/repositories/{repositoryId}/refs`	Tríade de Confirmação (bloqueado em branches protegidas).
`azure_get_file_contents`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/items?path={path}`	Leitura de código com decodificação segura.
`azure_create_or_update_file`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/pushes`	Suporte a `encoding="base64"` e proteção de branches.
`azure_push_files`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/pushes`	Commits atômicos de múltiplos arquivos (`add`, `edit`, `delete`).

2. Azure Repos — Governança de Pull Requests e Code Review

Ferramenta MCP	Tipo / Ação	Endpoint Azure REST (v7.0/v7.1)	Guardrails & Controles de Segurança
`azure_get_pull_request`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}`	Detalhes de branches origem/destino, merge status e conflitos.
`azure_list_pull_request_reviewers`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/reviewers`	Lista revisores, votos e status obrigatório (`isRequired`).
`azure_set_pull_request_reviewer_vote`	Voto	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/reviewers/{reviewerId}`	Registro de parecer numérico (`10`, `5`, `0`, `-5`, `-10`).
`azure_list_pull_request_work_items`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/workitems`	Rastreabilidade com itens de trabalho do Azure Boards.
`azure_link_pull_request_work_item`	Escrita	`/{project}/_apis/wit/workitems/{id}`	Vínculo bidirecional rastreável entre PR e Work Item.
`azure_list_pull_request_statuses`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/statuses`	Verificação de status checks customizados e validações.
`azure_post_pull_request_status`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/statuses`	Publicação de status check (`succeeded`, `failed`, `pending`).
`azure_list_pull_request_threads`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/threads`	Threads de discussão e comentários inline de código.
`azure_create_pull_request_comment`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/threads`	Abertura ou réplica de comentário com path e linha.
`azure_get_pull_request_policy_evaluations`	Leitura	`/{project}/_apis/policy/evaluations?artifactId={artifactUri}`	Auditoria de Branch Policies e gates bloqueantes de merge.
`azure_list_branch_policies` (Novo v1.8.0)	Leitura	`/{project}/_apis/policy/configurations`	Consulta prévia de políticas de branch por ref (`refs/heads/*`).
`azure_complete_pull_request`	Ação Crítica	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}`	Branch Policy Gate + Tríade de Confirmação: merge bloqueado se houver policies com falha.
`azure_abandon_pull_request`	Destrutiva	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}`	Tríade de Confirmação para encerramento sem merge.
`azure_list_pull_requests`	Leitura	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests`	Listagem por status (`active`, `completed`, `abandoned`).
`azure_create_pull_request`	Escrita	`/{project}/_apis/git/repositories/{repositoryId}/pullrequests`	Abertura formal de PR entre branches de trabalho.

3. Azure Pipelines — CI/CD, Execuções, Segredos e Qualidade

Ferramenta MCP	Tipo / Ação	Endpoint Azure REST (v7.0/v7.1)	Guardrails & Controles de Segurança
`azure_preview_pipeline`	Validação	`/{project}/_apis/pipelines/{pipelineId}/preview`	Valida sintaxe e renderiza templates YAML sem criar run.
`azure_get_pipeline_run`	Leitura	`/{project}/_apis/pipelines/{pipelineId}/runs/{runId}`	Detalhes do run, fases, jobs, etapas e commit associado.
`azure_retry_pipeline_run`	Execução	`/{project}/_apis/build/builds/{runId}?retry=true`	Reinício de pipeline com suporte a retry exclusivo de jobs falhos.
`azure_cancel_pipeline_run`	Destrutiva	`/{project}/_apis/build/builds/{runId}`	Tríade de Confirmação para interrupção de run em andamento.
`azure_list_variable_groups`	Leitura	`/{project}/_apis/distributedtask/variablegroups`	Descoberta de grupos de variáveis em projetos autorizados.
`azure_get_variable_group`	Leitura	`/{project}/_apis/distributedtask/variablegroups/{groupId}`	Mascaramento Nativo: valores de `isSecret: true` mascarados para `*MASKED_SECRET*`.
`azure_create_variable_group`	Escrita	`/{project}/_apis/distributedtask/variablegroups`	Criação de grupos de variáveis e segredos no projeto.
`azure_update_variable_group`	Crítica	`/{project}/_apis/distributedtask/variablegroups/{groupId}`	Tríade de Confirmação com registro forense em auditoria.
`azure_list_secure_files`	Leitura	`/{project}/_apis/distributedtask/securefiles`	Descoberta de arquivos seguros na biblioteca CI/CD.
`azure_list_service_connections`	Leitura	`/{project}/_apis/serviceendpoint/endpoints`	Sanitização de Credenciais: tokens e chaves omitidos da saída.
`azure_list_pipeline_approvals`	Leitura	`/{project}/_apis/pipelines/approvals`	Consulta aprovações pendentes em gates de deployment.
`azure_update_pipeline_approval`	Aprovação	`/{project}/_apis/pipelines/approvals`	Concessão ou rejeição (requer justificativa para rejeições).
`azure_list_environments`	Leitura	`/{project}/_apis/distributedtask/environments`	Descoberta de ambientes (`dev`, `homolog`, `prod`).
`azure_get_environment`	Leitura	`/{project}/_apis/distributedtask/environments/{environmentId}`	Detalhes de recursos e políticas do ambiente.
`azure_list_pipeline_artifacts`	Leitura	`/{project}/_apis/pipelines/{pipelineId}/runs/{runId}/artifacts`	Metadados e links para download de artefatos de build.
`azure_get_test_runs`	Qualidade	`/{project}/_apis/test/runs?buildUri={buildUri}`	Higienização de stack traces e teto de 50 falhas detalhadas.
`azure_get_code_coverage`	Qualidade	`/{project}/_apis/test/codecoverage?buildId={buildId}`	Percentual global e métricas de cobertura por módulo.
`azure_list_pipelines`	Descoberta	`/{project}/_apis/pipelines`	Consulta pipelines declaradas no projeto.
`azure_get_pipeline` (Novo v1.8.0)	Leitura	`/{project}/_apis/build/definitions/{pipelineId}`	Inspeção detalhada de definições de pipelines YAML e variáveis.
`azure_update_pipeline` (Novo v1.8.0)	Escrita	`/{project}/_apis/build/definitions/{pipelineId}`	Atualização controlada com auto-fetch de revision e locking otimista.
`azure_delete_pipeline` (Novo v1.8.0)	Destrutiva	`/{project}/_apis/build/definitions/{pipelineId}`	Tríade de Confirmação para exclusão definitiva de pipelines YAML.
`azure_get_pipeline_resource_authorizations` (Novo v1.8.0)	Leitura	`/{project}/_apis/pipelines/pipelinePermissions/{resourceType}/{resourceId}`	Consulta autorizações de Service Connections, Pools e Variable Groups.
`azure_authorize_pipeline_resource` (Novo v1.8.0)	Autorização	`/{project}/_apis/pipelines/pipelinePermissions/{resourceType}/{resourceId}`	Concessão auditável de acesso a recursos corporativos para pipelines.
`azure_create_pipeline`	Escrita	`/{project}/_apis/pipelines`	Registro de nova pipeline YAML em repositório autorizado.
`azure_run_pipeline`	Execução	`/{project}/_apis/pipelines/{pipelineId}/runs`	Branch Protection: bloqueado em branches protegidas.
`azure_get_build_log`	Observabilidade	`/{project}/_apis/build/builds/{buildId}/timeline`	Timeline de jobs e extração de logs com truncamento em 100 KB.
`azure_list_agents`	Descoberta	`/_apis/distributedtask/pools/{poolId}/agents`	Runners registrados com capacidades (`system` e `user`).

4. Azure DevOps Classic Release Management (Host VSRM)

Operam no host especializado https://vsrm.dev.azure.com/{organization}/:

Ferramenta MCP	Tipo / Ação	Endpoint Azure REST (v7.0/v7.1)	Guardrails & Controles de Segurança
`azure_list_release_definitions`	Descoberta	`/{project}/_apis/release/definitions`	Consulta definições com filtro textual `searchText`.
`azure_create_release_definition`	Escrita	`/{project}/_apis/release/definitions`	Importação declarativa de pipeline clássico via JSON.
`azure_get_release_definition`	Leitura	`/{project}/_apis/release/definitions/{definitionId}`	Metadados, variáveis e ambientes configurados.
`azure_update_release_definition`	Escrita	`/{project}/_apis/release/definitions/{definitionId}`	Atualização controlada de definição de release.
`azure_delete_release_definition` (Novo v1.8.0)	Destrutiva	`/{project}/_apis/release/definitions/{definitionId}`	Tríade de Confirmação para exclusão de release definitions clássicas no VSRM.
`azure_list_releases` (Novo v1.8.0)	Leitura	`/{project}/_apis/release/releases`	Listagem paginada de releases com filtro de `definition_id` e fallback web URL.
`azure_create_release`	Execução	`/{project}/_apis/release/releases`	Criação de release associando artefatos de build.
`azure_deploy_release_environment`	Crítica	`/{project}/_apis/release/releases/{releaseId}/environments/{environmentId}`	Guardrail `--check` Mandatório: em `homologacao`/`producao`, exige flag `--check`; deploy real em produção é terminantemente bloqueado.
`azure_get_release`	Observabilidade	`/{project}/_apis/release/releases/{releaseId}`	Status de release, ambientes e logs das fases de deployment (drill-down 3 níveis).

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

Metadata

Release files for mcpsentinel-gateway 1.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcpsentinel-gateway 1.8.1
File	Size	Uploaded	Provenance
mcpsentinel_gateway-1.8.1.tar.gz	594.1 kB	Oct 20, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcpsentinel-gateway 1.8.1
File	Interpreter	ABI	Platform	Reset
mcpsentinel_gateway-1.8.1-py3-none-any.whl 427.8 kB Oct 20, 2026 Without provenance	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / mcpsentinel_gateway-1.8.1.tar.gz

Download URL	mcpsentinel_gateway-1.8.1.tar.gz
Size	594.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`6c8cc51e76a4217725c0e9eb53ef290bb566690e871d140880c792bac0106c91`
BLAKE2b-256 checksum How to use checksums	`a418bef5fc84b787c392dc8e64da9c13920e4aaba01436606fa6553e8e9021b7`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / mcpsentinel_gateway-1.8.1-py3-none-any.whl

Download URL	mcpsentinel_gateway-1.8.1-py3-none-any.whl
Size	427.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ac1c2c7f8d8057d9b1ee52f13a1ef8e937187769a76b394a6ddc45d99a876212`
BLAKE2b-256 checksum How to use checksums	`45b186946c1172146b7d6539d3637e7b539b019b5605505b6496bbf1b71c1105`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Security for mcpsentinel-gateway 1.8.1

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

Release history Release notifications | RSS feed

1.9.2

Oct 20, 2026 2 release files No provenance

1.9.1

Oct 20, 2026 2 release files No provenance

1.9.0

Oct 20, 2026 2 release files No provenance

This release

1.8.1 This release

Oct 20, 2026 2 release files No provenance

1.8.0

Oct 20, 2026 2 release files No provenance

1.7.0

Oct 20, 2026 2 release files No provenance

1.6.0

Oct 19, 2026 2 release files No provenance

1.5.5

Oct 19, 2026 2 release files No provenance

1.5.4

Oct 19, 2026 2 release files No provenance

1.5.3

Oct 19, 2026 2 release files No provenance

1.5.2

Oct 19, 2026 2 release files No provenance

1.5.1

Oct 16, 2026 2 release files No provenance

1.5.0

Oct 16, 2026 2 release files No provenance

1.4.17

Oct 16, 2026 2 release files No provenance

1.4.16

Oct 16, 2026 2 release files No provenance

1.4.15

Oct 16, 2026 2 release files No provenance

1.4.14

Oct 15, 2026 2 release files No provenance

1.4.13

Oct 15, 2026 2 release files No provenance

1.4.12

Oct 15, 2026 2 release files No provenance

1.4.11

Oct 14, 2026 2 release files No provenance

1.4.10

Oct 14, 2026 2 release files No provenance

1.4.9

Oct 13, 2026 2 release files No provenance

1.4.8

Oct 13, 2026 2 release files No provenance

1.4.7

Oct 13, 2026 2 release files No provenance

1.4.6

Oct 13, 2026 2 release files No provenance

1.4.2

Oct 9, 2026 2 release files No provenance

1.4.1

Oct 9, 2026 2 release files No provenance

1.4.0

Oct 9, 2026 2 release files No provenance

1.3.3

Oct 9, 2026 2 release files No provenance

1.3.2

Oct 9, 2026 2 release files No provenance

1.3.1

Oct 9, 2026 2 release files No provenance

1.3.0

Oct 9, 2026 2 release files No provenance

1.2.1

Oct 8, 2026 2 release files No provenance

1.2.0

Oct 8, 2026 2 release files No provenance

1.1.1

Oct 8, 2026 2 release files No provenance

1.1.0

Oct 8, 2026 2 release files No provenance

1.0.2

Oct 7, 2026 2 release files No provenance

1.0.1

Oct 7, 2026 2 release files No provenance

1.0.0

Oct 7, 2026 2 release files No provenance

0.3.0

Oct 7, 2026 2 release files No provenance

mcpsentinel-gateway 1.8.1

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

O que o McpSentinel faz de forma simples?

📑 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

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

Ferramentas MCP do Conector GitHub

Ferramentas MCP do Conector Jenkins CI/CD (Expansão MCP-117 — 19 Ferramentas Homologadas)

Arquivo Declarativo GitOps: config/security.yaml

🔐 Resolução Dinâmica de Segredos via Vaultwarden / Bitwarden

Como Funciona o Esquema de URI vaultwarden://

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

Resolução Fallback: Bitwarden CLI (bw)

Integração com HashiCorp Vault (vault)

Exemplos Práticos de Configuração

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

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

3. Retrocompatibilidade (Valores Literais)

Tratamento de Falhas, Timeouts e Fail-Secure

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

Pré-requisitos

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

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

2. Instalação via pip tradicional

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

4. Uso Imediato dos Comandos CLI

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

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

Conteúdo Gerado no mcpsentinel.conf

Retrocompatibilidade com Arquivos .env

Assistente Interativo de Configuração (mcpsentinel configure)

Como Funciona o Wizard TUI

Modos de Operação

1. Modo Wizard Interativo Completo (Menu de Categorias)

2. Modo Seletivo Direto com --service

🛡️ Central de Aprovações Human-in-the-Loop (HITL) no Wizard e CLI

1. Como Acessar a Central de Aprovações

2. Funcionalidades da Central HITL

Comandos da CLI do Gateway (mcpsentinel)

Flags Globais do Utilitário

Resumo de Subcomandos

Modo Interativo (Primeiro Plano / Foreground)

Modo Daemon POSIX (Segundo Plano / Background)

Gerenciamento como Serviço Systemd no Linux (CLI)

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

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

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

Como Funciona a Segurança do Canal IPC

Comandos Disponíveis e Exemplos Práticos

1. Status Operacional Detalhado (mcpsentinel ctl status)

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

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

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

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

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

1. Princípios Arquiteturais e Garantia Fail-Safe

2. Gatilhos de Notificação

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

4. Diagnóstico Preventivo: Subcomando mcpsentinel test-alerts

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

1. Coleta e Métricas Disponíveis

2. Exemplo de Raspagem via cURL

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

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

2. Exemplos Práticos de Execução

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

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

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

2. Exemplos Práticos de Execução

🧰 Catálogo de Ferramentas e Recursos Azure DevOps (Azure Repos & Pipelines)

Tabela de Recursos do Azure DevOps (72 Ferramentas Homologadas)

1. Azure Repos — Git Tags, Histórico, Commits e Itens

2. Azure Repos — Governança de Pull Requests e Code Review

3. Azure Pipelines — CI/CD, Execuções, Segredos e Qualidade

4. Azure DevOps Classic Release Management (Host VSRM)

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`

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

Arquivo Declarativo GitOps: `config/security.yaml`

Como Funciona o Esquema de URI `vaultwarden://`

Resolução Fallback: Bitwarden CLI (`bw`)

Integração com HashiCorp Vault (`vault`)

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

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

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

2. Instalação via `pip` tradicional

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

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

Conteúdo Gerado no `mcpsentinel.conf`

Retrocompatibilidade com Arquivos `.env`

Assistente Interativo de Configuração (`mcpsentinel configure`)

2. Modo Seletivo Direto com `--service`

Comandos da CLI do Gateway (`mcpsentinel`)

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

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

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

1. Status Operacional Detalhado (`mcpsentinel ctl status`)

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

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

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

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

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

4. Diagnóstico Preventivo: Subcomando `mcpsentinel test-alerts`

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

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

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

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

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

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