Metadata-Version: 2.4
Name: mcpsentinel-gateway
Version: 1.4.15
Summary: Prover acesso seguro a ferramentas de infraestrutura (AWS, Gitlab, Azure, Github) via protocolo MCP
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: platformdirs>=4.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"

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

[![Application Development Harness](https://img.shields.io/badge/Harness-Active-success)](./AGENTS.md)
[![PyPI Version](https://img.shields.io/pypi/v/mcpsentinel-gateway.svg)](https://pypi.org/project/mcpsentinel-gateway/)
[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](./pyproject.toml)
[![Python Version](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](./pyproject.toml)
[![Test Suite](https://img.shields.io/badge/Tests-749%20Passed-brightgreen.svg)](./tests/)
[![Test Coverage](https://img.shields.io/badge/Coverage-90%25%20Hermetic-brightgreen.svg)](./tests/)
[![Security](https://img.shields.io/badge/Security-Fail--Secure-red.svg)](./config/security.yaml)
[![Architecture](https://img.shields.io/badge/Architecture-Modular%20Gateway-purple.svg)](./docs/trd.md)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](./pyproject.toml)

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

> [!TIP]
> **Manual de Operação Completo:** Para o guia didático e normativo completo de administração, configuração do assistente interativo, integração com agentes de IA (Claude Code, Antigravity, Open Code), cofres de senhas e resolução de problemas, consulte o [**`Manual de Operação do McpSentinel`**](docs/manual-de-operacao.md) localizado na pasta [`docs/manual-de-operacao.md`](docs/manual-de-operacao.md).

---

## 📑 Sumário

- [🛡️ Pilares Fundamentais de Segurança](#️-pilares-fundamentais-de-segurança)
- [⚙️ Inventário Completo de Configurações](#️-inventário-completo-de-configurações)
  - [Precedência Canônica de Configurações](#precedência-canônica-de-configurações)
  - [Arquivo Canônico de Configuração: mcpsentinel.conf](#arquivo-canônico-de-configuração-mcpsentinelconf)
  - [Diagnóstico e Inspeção de Configurações (`--configuration-summary` / `-s`)](#diagnóstico-e-inspeção-de-configurações---configuration-summary---s)
  - [Variáveis de Ambiente e Suporte a .env](#variáveis-de-ambiente-e-suporte-a-env)
  - [Arquivo Declarativo GitOps: config/security.yaml](#arquivo-declarativo-gitops-configsecurityyaml)
- [🔐 Resolução Dinâmica de Segredos via Vaultwarden / Bitwarden Secrets Manager](#-resolução-dinâmica-de-segredos-via-vaultwarden--bitwarden-secrets-manager)
  - [Como Funciona o Esquema de URI vaultwarden://](#como-funciona-o-esquema-de-uri-vaultwarden)
  - [Pré-requisitos Operacionais](#pré-requisitos-operacionais)
  - [Exemplos Práticos de Configuração](#exemplos-práticos-de-configuração)
  - [Tratamento de Falhas, Timeouts e Fail-Secure](#tratamento-de-falhas-timeouts-e-fail-secure)
- [⚡ Guia de Instalação e Uso (Quickstart)](#-guia-de-instalação-e-uso-quickstart)
  - [Instalação e Uso Direto via PyPI (`pip` / `uv tool` / `pipx` / `uvx`)](#instalação-e-uso-direto-via-pypi-pip--uv-tool--pipx--uvx)
  - [Desenvolvimento Local e Contribuição (Repositório Git)](#desenvolvimento-local-e-contribuição-repositório-git)
  - [Inicialização do Ambiente de Configuração (`mcpsentinel init`)](#inicialização-do-ambiente-de-configuração-mcpsentinel-init)
  - [Assistente Interativo de Configuração (`mcpsentinel configure`)](#assistente-interativo-de-configuração-mcpsentinel-configure)
  - [Comandos da CLI do Gateway (`mcpsentinel`)](#comandos-da-cli-do-gateway-mcpsentinel)
  - [Gerenciamento como Serviço Systemd no Linux (CLI)](#gerenciamento-como-serviço-systemd-no-linux-cli)
  - [Controle Inter-Processos do Daemon (`mcpsentinel ctl`)](#-controle-inter-processos-do-daemon-mcpsentinel-ctl)
  - [Monitoração, Visibilidade e Alertas (Slack e E-mail)](#-monitoração-visibilidade-e-alertas-slack-e-e-mail)
  - [Observabilidade Contínua para SRE (Métricas Prometheus /metrics)](#-observabilidade-contínua-para-sre-métricas-prometheus-metrics)
  - [Diagnóstico Sintético Pré-Voo de Conexões (test-connections)](#-diagnóstico-sintético-pré-voo-de-conexões-test-connections)
  - [Inspeção Integrada com --check-upstreams (mcpsentinel status)](#-inspeção-integrada-com---check-upstreams-mcpsentinel-status)
- [🔌 Guia de Integração com Clientes MCP](#-guia-de-integração-com-clientes-mcp)
- [🐳 Implantação em Produção e Contêineres](#-implantação-em-produção-e-contêineres)
  - [Dockerfile Multi-Stage com CLI bws](#dockerfile-multi-stage-de-exemplo)
  - [Execução via Docker Compose](#execução-via-docker-compose-docker-composeyml)
  - [Execução Nativa como Serviço Systemd](#execução-nativa-como-serviço-systemd)
- [🧪 Testes Herméticos e Quality Gates](#-testes-herméticos-e-quality-gates)
- [📚 Documentação Complementar do Harness](#-documentação-complementar-do-harness)
- [📄 Licença e Governança](#-licença-e-governança)

---

## 🛡️ Pilares Fundamentais de Segurança

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

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

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

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

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

6. **Defesa em Profundidade de Rede (Network Allowlist):**
   - Interceptor de borda integrado na camada ASGI valida a origem das requisições contra regras de IP individuais ou blocos CIDR autorizados (`allowed_origins`), bloqueando tráfego não confiável antes de qualquer processamento HTTP/SSE.

---

## ⚙️ Inventário Completo de Configurações

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

### Precedência Canônica de Configurações

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

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

---

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

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

O arquivo pode ser gerado automaticamente com permissões restritas através do subcomando:
```bash
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`:
```bash
# 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):

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

# Sintaxe equivalente longa:
mcpsentinel --configuration-summary

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

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

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

---

### Variáveis de Ambiente e Suporte a `.env`

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

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

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

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

#### Ferramentas MCP do Conector GitHub

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

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

#### Ferramentas MCP do Conector Jenkins CI/CD

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

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

---

### Arquivo Declarativo GitOps: `config/security.yaml`

O arquivo [`config/security.yaml`](file:///mnt/home/alexandre/Projetos/McpSentinel/config/security.yaml) é o coração da segurança do gateway. É dividido em 4 seções principais:

```yaml
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**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/004-resolucao-de-tokens-via-vaultwarden.md), [**ADR 010**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/ADR-010-vaultwarden-bw-cli-support.md), [**ADR 014**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/014-vaultwarden-autonomous-api-resolver.md) e [**ADR 015**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/015-wizard-vaultwarden-api-keys.md), integrando o conector [`mcpsentinel.security.secrets`](file:///mnt/home/alexandre/Projetos/McpSentinel/src/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:
```yaml
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/password
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/notes
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/fields.api_token
```

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

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

1. **Obtenção das Chaves de API no Vaultwarden Web:**
   - Acesse o Vaultwarden no navegador.
   - Vá em **Configurações da Conta** > **Segurança** > aba **Chaves de API**.
   - Clique em **Ver Chave de API**, confirme sua senha mestre e copie o **client_id** e o **client_secret**.
2. **Configuração no `mcpsentinel.conf` ou Ambiente:**
   ```bash
   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](docs/manual-de-operacao.md#52-como-obter-e-configurar-o-vaultwarden_master_key).

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

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

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

1. **Configurar servidor e autenticar com API Key:**
   ```bash
   bw config server https://seu-vaultwarden.empresa.com
   export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   export BW_CLIENTSECRET="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
   bw login --apikey
   ```
2. **Destravar cofre e exportar `BW_SESSION`:**
   ```bash
   export BW_SESSION="$(bw unlock --raw)"
   ```

> [!IMPORTANT]
> Quando a variável `BW_SESSION` estiver presente no ambiente, o `VaultwardenResolver` pode utilizá-la em consultas locais (`bw get item <item_id>`) sem prompt interativo. Se o CLI `bw` for selecionado e a variável `BW_SESSION` estiver ausente, o resolver falha imediatamente com `SecretAuthenticationError`, prevenindo travamentos de daemons.

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

```yaml
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:

```bash
# 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:
```yaml
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`](https://github.com/astral-sh/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`**](https://pypi.org/project/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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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
```

> [!TIP]
> Em plataformas POSIX (Linux e macOS), o subcomando `init` aplica automaticamente `chmod 0700` (`rwx------`) no diretório de destino e `chmod 0600` (`rw-------`) no arquivo `mcpsentinel.conf`, garantindo que apenas o usuário proprietário possa ler os tokens e credenciais.

#### Conteúdo Gerado no `mcpsentinel.conf`

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

```ini
# 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](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/012-interactive-configure-wizard-and-service-registry.md) e [OpenSPEC MCP-77](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-77-interactive-configure-wizard.md)).

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

#### Modos de Operação

##### 1. Modo Wizard Interativo Completo (Menu de Categorias)
Inicia o assistente com menu interativo navegável por categorias:

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

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

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

##### 2. Modo Seletivo Direto com `--service`
Permite abrir diretamente o assistente focado em um serviço específico sem passar pelo menu principal:

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

# Configurar apenas o GitLab
mcpsentinel configure --service gitlab

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

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

---

### Comandos da CLI do Gateway (`mcpsentinel`)

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

#### Flags Globais do Utilitário

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

#### Resumo de Subcomandos

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

#### Modo Interativo (Primeiro Plano / Foreground)
Ideal para desenvolvimento, testes e inspeção de logs em tempo real:

```bash
# 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):

```bash
# 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:
  ```bash
  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:
  ```bash
  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:
  ```bash
  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:
  ```bash
  # 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:**
  ```bash
  mcpsentinel uninstall-service
  # ou explicitamente:
  mcpsentinel uninstall-service --user
  ```

- **Desinstalação no modo de sistema:**
  ```bash
  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](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/013-daemon-ctl-ipc-cli.md), [PRD-078](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/prds/PRD-078-daemon-ctl-ipc-cli.md) e [OpenSPEC MCP-078](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-078-daemon-ctl-ipc-cli.md)).

#### Como Funciona a Segurança do Canal IPC

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

```mermaid
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:

```bash
# 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:*
```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:

```bash
# 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**:

```bash
# 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
```

> [!NOTE]
> O encerramento cirúrgico aciona cooperativamente o cancelamento do canal SSE do cliente no `ConnectionTracker` e registra imediatamente um evento de auditoria forense com nível `WARNING` para rastreabilidade de segurança.

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

```bash
# 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`:

```bash
# 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.
```

> [!IMPORTANT]
> Se o novo arquivo de configuração contiver erros de sintaxe ou inconsistências semânticas, o daemon aborta o reload, preserva a configuração anterior intacta em execução (*Fail-Secure*) e reporta o erro detalhado diretamente no terminal do operador com código de saída 1.

---

### 📡 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](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-92-monitoring-notifications.md) e [PRD-MCP-92](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/prds/PRD-MCP-92-monitoring-notifications.md)).

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

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

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

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

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

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

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

```bash
# 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](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-91-visibilidade-prometheus-test-connections.md)).

#### 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
```bash
# Consultar métricas no endpoint padrão do gateway:
curl -s http://127.0.0.1:8000/metrics

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

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

---

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

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

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

#### 2. Exemplos Práticos de Execução
```bash
# 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:

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

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

---

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

Para assegurar que os serviços upstream de cofres e segredos (Vaultwarden API REST M2M, Bitwarden CLI `bw`/`bws`, HashiCorp Vault e variáveis de ambiente locais) estejam alcançáveis, ativos e autenticados **antes** da execução de cargas de trabalho, o McpSentinel provê o subcomando `test-vaults` ([MCP-96](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-96-test-vaults.md)).

#### 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
```bash
# Testar todos os serviços de cofres detectados no ambiente ou fallback local:
mcpsentinel test-vaults

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

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

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

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

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

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

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

*Códigos de saída (`Exit Codes` LSB):*
- `0`: Todos os cofres testados retornaram status `OK` (ou `NÃO CONFIGURADO` em escopo geral `all`).
- `1`: Ocorreu ao menos uma falha (`FAILED`) em cofre configurado ou explicitamente requisitado.
- `2`: Erro de sintaxe nos argumentos (ex: `--timeout -1`, `--vault invalido` ou `--conf-file` inexistente).

---

## 🔌 Guia de Integração com Clientes MCP

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

### 1. Claude Desktop

Abra o arquivo de configuração do seu Claude Desktop:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Adicione o McpSentinel na seção `mcpServers`:

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

> [!NOTE]
> Quando o Claude Desktop se conectar, ele enviará a requisição `tools/list`. O McpSentinel responderá **apenas** com as ferramentas vinculadas ao perfil do token (`sre_operations`), ocultando todas as outras.

---

### 2. Validação Rápida via cURL

Você pode inspecionar o handshake SSE diretamente no terminal:

```bash
# 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**](docs/manual-de-operacao.md#11-configuração-do-mcpsentinel-em-agentes-de-ia-claude-code-antigravity-open-code) (localizado em [`docs/manual-de-operacao.md`](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:

```dockerfile
# ----------------------------------------------------
# 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`)

```yaml
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:
```bash
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`)
```bash
# 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`](file:///mnt/home/alexandre/Projetos/McpSentinel/deploy/systemd/mcpsentinel.service):

```bash
# 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`](file:///mnt/home/alexandre/Projetos/McpSentinel/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

```bash
# 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

```bash
# 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`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/manual-de-operacao.md) — Guia detalhado para Administradores de Segurança e Auditores.
- **Operação de Daemon e Systemd:** [`docs/daemon-systemd.md`](file:///mnt/home/alexandre/Projetos/McpSentinel/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`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/trd.md) — Limites globais de latência, tolerância e componentes.
- **Registros de Decisões Arquiteturais (ADRs):**
  - [`ADR 001: Transporte Remoto HTTP para Servidor MCP Centralizado`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/001-transporte-remoto-http-mcp.md)
  - [`ADR 002: Modelo de Segurança Declarativo GitOps, RBAC e Guardrails Operacionais`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/002-seguranca-rbac-gitops-e-guardrails.md)
  - [`ADR 003: Trilha de Auditoria Síncrona Estruturada sob Paradigma Fail-Secure`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/003-auditoria-sincrona-fail-secure.md)
  - [`ADR 004: Resolução de Tokens via Vaultwarden / Bitwarden Secrets Manager`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/004-resolucao-de-tokens-via-vaultwarden.md)
  - [`ADR 005: Restrição de Rede via Allowlist de IPs e CIDR`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/005-ip-filtering-allowlist.md)
  - [`ADR 006: Background Daemon Service POSIX e Gerenciamento LSB`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/006-background-daemon-service.md)
  - [`ADR 007: Resolução Multiplataforma de Configuração e mcpsentinel.conf`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/007-multiplatform-conf-configuration-and-release.md)
  - [`ADR 008: Gerenciamento Nativo de Serviços Systemd via CLI`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/008-systemd-service-management-cli.md)
  - [`ADR 009: Orquestração de GitHub Release e Publicação Condicionada no PyPI`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/009-github-release-and-pypi-pipeline.md)
  - [`ADR 010: Suporte Híbrido ao Bitwarden CLI (bw) e Vaultwarden`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/010-vaultwarden-bw-cli-support.md)
  - [`ADR 011: Conector Jenkins REST API e Guardrails`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/011-conector-jenkins-rest-api-e-guardrails.md)
  - [`ADR 012: Assistente Interativo de Configuração e ServiceRegistry`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/012-interactive-configure-wizard-and-service-registry.md)
  - [`ADR 013: Controle Inter-Processos via Unix Domain Socket (UDS) e CLI mcpsentinel ctl`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/013-daemon-ctl-ipc-cli.md)
- **Especificações de Requisitos e OpenSPEC:**
  - [`PRD-078: Controle Inter-Processos e Interface CLI para Daemon`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/prds/PRD-078-daemon-ctl-ipc-cli.md)
  - [`OpenSPEC MCP-078: daemon-ctl-ipc-cli Specification`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-078-daemon-ctl-ipc-cli.md)

---

## 📄 Licença e Governança

Distribuído sob a licença **MIT**. Veja o arquivo [`pyproject.toml`](file:///mnt/home/alexandre/Projetos/McpSentinel/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.
