Metadata-Version: 2.4
Name: mcpsentinel-gateway
Version: 1.0.2
Summary: Prover acesso seguro a ferramentas de infraestrutura (AWS, Gitlab, Azure) 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
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 Gateway for 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/)
[![Python Version](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](./pyproject.toml)
[![Test Coverage](https://img.shields.io/badge/Coverage-97%25-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)

**McpSentinel** é um gateway corporativo de segurança e mediação para o **Model Context Protocol (MCP)**, projetado para conceder a agentes autônomos de Inteligência Artificial acesso controlado, governado e auditável a ferramentas operacionais de infraestrutura de nuvem (**Amazon Web Services**) e gestão de código (**GitLab** e **Azure Repos**).

O McpSentinel atua como uma barreira de proteção de borda (*security edge proxy*), centralizando a execução de ferramentas, interceptando requisições, aplicando controle de acesso baseado em papéis (RBAC) multi-tenant e gerando uma trilha de auditoria síncrona com bloqueio imediato (*fail-secure*).

---

## 🛡️ Princípios de Arquitetura e Segurança

O gateway foi concebido sob cinco pilares de segurança fundamentais:

```mermaid
flowchart LR
    A[Agente IA / Cliente MCP] -->|1. Bearer Token via SSE| B(McpSentinel Edge Gateway)
    B -->|2. RBAC & Tenant Check| C{Permitido?}
    C -- Não -->|Bloqueio Imediato & Log BLOCKED| A
    C -- Sim -->|3. Log Síncrono PENDING| D[(Audit Trail / stdout)]
    D -->|4. STS AssumeRole / PAT| E[Infraestrutura: AWS / Git]
    E -->|5. Sanitização REDACTED| B
    B -->|6. Log SUCCESS & Resposta Segura| A
```

1. **Zero Credential Leakage:** Nenhuma credencial privilegiada de nuvem (IAM Keys, credenciais STS) ou tokens de repositório (PATs) é exposta ou trafegada para o cliente de IA. Todas as operações são mediadas pelo gateway, que assume temporariamente IAM Roles via AWS STS e despacha comandos com menor privilégio estrito.
2. **Gestão Declarativa via GitOps:** Identidades de agentes, perfis RBAC e tenants autorizados são integralmente modelados em arquivo declarativo versionado ([`config/security.yaml`](file:///mnt/home/alexandre/Projetos/McpSentinel/config/security.yaml)). Mudanças passam por revisão por pares e esteiras de CI/CD, sem dependência de banco de dados relacional ou painel web mutável.
3. **RBAC Multi-Tenant e Filtragem Dinâmica de Catálogo:**
   - **Descoberta (`tools/list`):** O catálogo MCP é dinamicamente filtrado; agentes visualizam estritamente as ferramentas autorizadas para seu respectivo perfil.
   - **Invocação (`tools/call`):** Validação mandatória em tempo de execução garantindo que a ferramenta solicitada e o tenant/conta AWS de destino pertençam ao escopo do agente autenticado.
4. **Trilha de Auditoria Síncrona Fail-Secure:** Cada invocação emite um evento estruturado em JSONLines na entrada (`PENDING`) e na saída (`SUCCESS`, `FAILED` ou `BLOCKED`). Sob a política *Fail-Secure*, qualquer falha no subsistema de persistência de log bloqueia incondicionalmente a chamada da ferramenta, garantindo que nenhuma ação seja executada sem rastro forense.
5. **Higienização e Mascaramento Automático:** Todos os payloads de entrada, saída e registros de log passam por sanitização recursiva, substituindo senhas, tokens e parâmetros sensíveis pelo marcador `[REDACTED]`.

---

## 📋 Requisitos de Ambiente

- **Sistema Operacional:** Linux (x86_64 ou ARM64) ou macOS.
- **Runtime:** Python `>= 3.12`.
- **Gerenciador de Pacotes e Toolchain:** [`uv`](https://github.com/astral-sh/uv) (recomendado) ou `pip`/`venv`.
- **Credenciais de Provedor:** AWS Credentials configuradas no ambiente hospedeiro via variáveis de ambiente padrão (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`), arquivo de credenciais `~/.aws/credentials` ou perfil de instância/IAM Role (EC2/ECS/EKS).

---

## ⚡ Instalação

### Via PyPI (Recomendado para uso)

```bash
pip install mcpsentinel-gateway
```

### A partir do código-fonte (Desenvolvimento)

Clone o repositório e sincronize o ambiente virtual isolado com o `uv`:

```bash
# Clone do repositório
git clone https://github.com/Defendi/McpSentinel.git
cd McpSentinel

# Criação do venv e instalação de todas as dependências (incluindo dev)
uv sync
```

Caso utilize o `pip` padrão:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

---

## ⚙️ Configuração

O McpSentinel é configurado via variáveis de ambiente e arquivos declarativos versionados.

### Variáveis de Ambiente Suportadas

As variáveis podem ser definidas no ambiente do sistema operacional ou em um arquivo `.env` na raiz do projeto:

| Variável | Padrão | Descrição |
|---|---|---|
| `SENTINEL_AUTH_TOKEN` | `sentinel-secret-token` | Bearer token legado de fallback para validação de requisições HTTP. |
| `SENTINEL_SECURITY_CONFIG` | `config/security.yaml` | Caminho do arquivo de configuração declarativa GitOps (RBAC e agentes). |
| `SENTINEL_AUDIT_LOG_PATH` | `logs/audit.log` | Caminho do arquivo local para persistência síncrona de eventos de auditoria JSONLines. |
| `SENTINEL_HOST` | `0.0.0.0` | Endereço IP de ligação do servidor ASGI. |
| `SENTINEL_PORT` | `8000` | Porta TCP de escuta do servidor HTTP/SSE. |
| `SENTINEL_ENVIRONMENT` | `development` | Ambiente operacional (`development`, `staging`, `production`). |
| `SENTINEL_LOG_LEVEL` | `INFO` | Nível de logging da aplicação (`DEBUG`, `INFO`, `WARNING`, `ERROR`). |

### Configuração Declarativa GitOps (`config/security.yaml`)

O arquivo [`config/security.yaml`](file:///mnt/home/alexandre/Projetos/McpSentinel/config/security.yaml) define formalmente a tríade de segurança: **Tenants**, **Profiles** e **Agents**. Suporta interpolação de variáveis de ambiente com valores padrão `${VAR_NAME:-default}`.

```yaml
version: "1.0"

# 1. Tenants corporativos (Contas de nuvem e escopos)
tenants:
  aws_accounts:
    - id: "dev-account"
      account_id: "111122223333"
      name: "Ambiente de Desenvolvimento"
      allowed_regions:
        - "us-east-1"
        - "sa-east-1"

# 2. Perfis RBAC
profiles:
  sre_operations:
    description: "Perfil operacional SRE"
    tools:
      - "aws_get_caller_identity"
    allowed_tenants:
      aws_accounts:
        - "dev-account"

# 3. Identidades dos agentes clientes
agents:
  - agent_id: "agent-sre-01"
    name: "Agente Operacional SRE Principal"
    token: "${SENTINEL_TOKEN_SRE:-token-sre-01-secret}"
    profile: "sre_operations"
```

### Restrição de Rede (Allowlist de IPs e Interfaces)

O McpSentinel pode restringir o acesso apenas a IPs e redes autorizadas (via blocos CIDR) e configurar em quais interfaces de rede o servidor irá escutar.

**Exemplo no arquivo `config/security.yaml`:**
```yaml
network_filter:
  bind_addresses:
    - "127.0.0.1"       # Escuta apenas em localhost IPv4
    - "::1"             # Escuta apenas em localhost IPv6
  allowed_origins:
    - "192.168.1.100"   # IP exato autorizado
    - "10.0.0.0/24"     # Bloco CIDR (toda a sub-rede 10.0.0.x autorizada)
```

**Variáveis de Ambiente:**
Também é possível configurar a restrição de rede passando variáveis de ambiente (separadas por vírgula):
- **Origens permitidas:** `ALLOWED_IPS`, `ALLOWED-IP`, `ALLOWED_IP`, `SENTINEL_ALLOWED_IPS`, `SENTINEL_ALLOWED_IP`
- **Interfaces de escuta:** `BIND_INTERFACES`, `BIND-INTERFACES`, `BIND_INTERFACE`, `SENTINEL_BIND_INTERFACES`, `SENTINEL_BIND_INTERFACE`

*Exemplo:* `ALLOWED_IPS="192.168.1.10,10.0.0.0/24"`

**Precedência:**
Argumentos da CLI (`--allow-ip`, `--bind`) sobrescrevem Variáveis de Ambiente, que sobrescrevem o `security.yaml`.

---

## 🚀 Inicialização do Servidor

### Execução via CLI Integrada (Recomendada)

O McpSentinel provê uma CLI embutida com suporte a configuração de rede, portas e regras de restrição de origens dinamicamente.

```bash
# Iniciar o servidor utilizando as configurações do security.yaml
uv run python -m mcpsentinel.server

# Sobrescrever as configurações de IP e portas dinamicamente via flags
uv run python -m mcpsentinel.server --bind 0.0.0.0 --port 8080 --allow-ip 10.0.0.0/24 --allow-ip 192.168.1.50
```

Você pode visualizar a ajuda completa da CLI via:
```bash
uv run python -m mcpsentinel.server --help
```

### Execução Direta via Uvicorn

Caso prefira, você também pode inicializar a aplicação ASGI Starlette diretamente:

```bash
uv run uvicorn mcpsentinel.api.app:app --host 0.0.0.0 --port 8000
```

O gateway inicializará e disponibilizará o endpoint MCP SSE em:
- **SSE Connection Endpoint:** `http://localhost:8000/sse`
- **Messages POST Endpoint:** `http://localhost:8000/messages/`

---

## 🔌 Conectando Clientes MCP

Todos os clientes devem enviar o cabeçalho de autenticação HTTP padrão:
```http
Authorization: Bearer <TOKEN_DO_AGENTE>
```

### 1. Claude Desktop

Configure o arquivo de configuração do Claude Desktop (`claude_desktop_config.json`):

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

### 2. Chamadas HTTP Diretas (curl / httpx)

Você pode validar a inicialização e escuta da conexão SSE com o utilitário `curl`:

```bash
# Conectar ao stream de eventos SSE com Bearer Token
curl -N -H "Authorization: Bearer token-sre-01-secret" \
  http://localhost:8000/sse
```

Em caso de credencial ausente ou inválida, o gateway rejeita imediatamente com HTTP 401:

```bash
curl -i http://localhost:8000/sse
# HTTP/1.1 401 Unauthorized
# {"error": "Unauthorized", "code": "AUTHENTICATION_ERROR", "detail": "Missing Authorization header"}
```

---

## 🧪 Quality Gates e Testes Herméticos

O projeto possui uma suíte hermética de testes de unidade, integração e segurança, sem dependências de infraestrutura externa viva em runtime de teste.

### Execução de Testes com Cobertura

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

Status atual da cobertura: **97%** em 134 testes automatizados.

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

```bash
# Validação de formatação e linting estrito com Ruff
uv run ruff check

# Checagem estrita de tipos estáticos com Mypy
uv run mypy src
```

---

## 📚 Rastreabilidade e Documentação do Harness

Este repositório adota a disciplina canônica do **Application Development Harness**. Consulte a documentação complementar em [`docs/`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/):

- **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 o Administrador de Segurança (AT-01).
- **Technical Requirements Document (TRD):** [`docs/trd.md`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/trd.md) — Requisitos não-funcionais, stack e limites arquiteturais globais.
- **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 em JSON sob Paradigma Fail-Secure`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/adrs/003-auditoria-sincrona-fail-secure.md)
- **Especificações de Funcionalidades:** [`docs/specs/`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/specs/)
- **Product Requirements Documents:** [`docs/prds/`](file:///mnt/home/alexandre/Projetos/McpSentinel/docs/prds/)
