Metadata-Version: 2.4
Name: mcpsentinel-gateway
Version: 1.3.0
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 — Secure Infrastructure Edge Gateway 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.3.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-535%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** é um **Secure Infrastructure Edge Gateway** de nível corporativo projetado para o ecossistema do **Model Context Protocol (MCP)**. Sua missão primordial é atuar como uma barreira de proteção de borda (*security edge proxy* e mediador de controle de acesso), viabilizando que agentes autônomos de Inteligência Artificial e LLMs interajam de forma governada, segura e auditável com ferramentas operacionais de infraestrutura de nuvem (**Amazon Web Services**), gestão de código/DevOps (**GitLab** e **Azure Repos**), automações (**Ansible AWX / Tower**) e esteiras de CI/CD (**Jenkins**).

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

---

## 📑 Sumário

- [🏗️ Arquitetura e Fluxo de Borda](#️-arquitetura-e-fluxo-de-borda)
- [🛡️ 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)
  - [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)
- [🔌 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)

---

## 🏗️ Arquitetura e Fluxo de Borda

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

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

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

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

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

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

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

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

---

## 🛡️ Pilares Fundamentais de Segurança

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

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

3. **GitOps RBAC Declarativo & Isolamento Multi-Tenant:**
   - A configuração de identidades, escopos e perfis reside integralmente no arquivo versionado [`config/security.yaml`](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
```

---

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

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

| Variável | Finalidade |
|---|---|
| `BWS_ACCESS_TOKEN` | Token de serviço (Service Account Token) para autenticação da CLI `bws` com o Vaultwarden / Bitwarden Secrets Manager. Obrigatório caso utilize o esquema `vaultwarden://`. |
| `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_ENABLED` | Habilita ou desabilita o conector Jenkins CI/CD (`true` / `false`). |
| `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>`). |

#### 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:
    - id: "dev-account"
      account_id: "111122223333"
      name: "Ambiente de Desenvolvimento"
      allowed_regions: ["us-east-1", "sa-east-1"]
    - id: "prod-account"
      account_id: "444455556666"
      name: "Ambiente de Produção"
      allowed_regions: ["us-east-1"]

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

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

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

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

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

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

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

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

---

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

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

O **McpSentinel** implementa nativamente a arquitetura definida nas [**ADR 004**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/004-resolucao-de-tokens-via-vaultwarden.md) e [**ADR 010**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/ADR-010-vaultwarden-bw-cli-support.md), e nas especificações [**OpenSPEC MCP-38**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-38-vault-tokens.md) e [**OpenSPEC MCP-75**](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/MCP-75-vaultwarden-bw-cli-support.md), integrando o módulo [`mcpsentinel.security.secrets`](file:///mnt/home/alexandre/Projetos/McpSentinel/src/mcpsentinel/security/secrets/) (`SecretsManager` e `VaultwardenResolver`).

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

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

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

```
vaultwarden://<item_id>/<campo>
```

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

Exemplos de URIs válidas:
```yaml
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/password
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/notes
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/fields.api_token
vaultwarden://b4a2c1d0-1234-5678-90ab-cdef12345678/value
```

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

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

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

#### 2. Configuração de Servidor e Login Não-Interativo
Em servidores e ambientes de gateway, **nunca execute login interativo com senha mestre**. Utilize autenticação estritamente via API Key:

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

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

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

#### 3. Destravar o Cofre e Exportar `BW_SESSION`
Após o login, o cofre permanece travado. Destrave-o de forma não-interativa e capture o token de sessão:

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

> [!IMPORTANT]
> Quando a variável `BW_SESSION` estiver presente no ambiente, o `VaultwardenResolver` seleciona automaticamente o CLI `bw` e executa consultas em background (`bw get item <item_id>`) sem qualquer prompt interativo. Se o CLI `bw` for selecionado e a variável `BW_SESSION` estiver ausente, o resolver falha imediatamente com `SecretAuthenticationError`, prevenindo bloqueios ou travamento de daemons.

---

### Integração com Bitwarden Secrets Manager (`bws`)

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

1. Instale o binário `bws` disponibilizado em [`bitwarden/sdk-sm`](https://github.com/bitwarden/sdk-sm/releases).
2. Gere um Access Token de Service Account no cofre corporativo.
3. Exporte a variável de ambiente:
   ```bash
   export BWS_ACCESS_TOKEN="0.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   ```
4. As URIs `vaultwarden://<item_id>/value` serão resolvidas via `bws secret get <item_id>`.

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

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

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

---

### Exemplos Práticos de Configuração

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

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

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

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

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

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

#### Retrocompatibilidade com Arquivos `.env`

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

---

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

O McpSentinel provê o assistente interativo `configure` (Terminal User Interface — TUI) para guiar o operador na configuração e inspeção dos parâmetros do gateway e integrações, evitando erros de digitação, URLs malformadas e vazamento visual de segredos ([ADR 012](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, BWS Access Token |
| `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 |
|---|---|
| `-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>` |
| `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` |

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

---

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

---

## 🐳 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}
      - BWS_ACCESS_TOKEN=${BWS_ACCESS_TOKEN}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-us-east-1}
    volumes:
      - ./config/security.yaml:/app/config/security.yaml:ro
      - sentinel-logs:/app/logs
    read_only: false
    security_opt:
      - no-new-privileges:true

volumes:
  sentinel-logs:
    driver: local
```

Suba o serviço de produção com:
```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.
