Segurança

Autenticação JWT

O sistema usa dois secrets JWT distintos com suporte a key rotation:

Todo token é validado com: assinatura, expiração, iss, aud, jti (blacklist) e UUID do usuário.

Key Rotation

O sistema suporta rotação de secrets sem downtime usando múltiplas versões:

# Configuração para key rotation
JWT_SECRET_KID=v2              # Chave ativa para novos tokens
JWT_SECRET_v1=secret_antigo    # Ainda válido para tokens existentes
JWT_SECRET_v2=secret_novo      # Usado para novos tokens

Tokens assinados com v1 continuam válidos enquanto novos tokens usam v2. Remova a chave anterior somente depois da maior validade possível dos tokens emitidos e da confirmação nos logs de que ela não é mais usada.

ThreatScorer — Sistema de Pontuação de Ameaças

O ThreatScorer detecta comportamento suspeito acumulando pontos por IP. Quando o score atinge um threshold, o sistema aplica delays progressivos ou bloqueia o acesso.

Pontuação de Eventos

Thresholds e Ações

Storage

O ThreatScorer usa Redis quando disponível (distribuído entre múltiplos servidores) ou file storage (servidor único). A configuração é automática baseada na presença de REDIS_HOST no .env.

Sistema de Auditoria

O sistema registra automaticamente eventos de segurança na tabela audit_logs e emite logs estruturados para stderr (compatível com Fail2Ban, Datadog, CloudWatch).

Eventos Registrados

Detecção de Comportamento Suspeito

O sistema detecta automaticamente padrões suspeitos e emite alertas:

• Força bruta: 10+ falhas de login em 5 minutos do mesmo IP
• Scanning: Múltiplos 404 em rotas diferentes
• Honeypot hits: Acesso a rotas falsas
• Anomalias de user-agent: Padrões de bots maliciosos

Webhook de Alertas

Configure SECURITY_ALERT_WEBHOOK no .env para receber alertas em tempo real:

SECURITY_ALERT_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Payload enviado:

{
  "alert": "BRUTE_FORCE_DETECTED",
  "dados": {
    "ip": "192.168.1.100",
    "falhas_5min": 12,
    "threshold": 10,
    "acao_sugerida": "Bloquear IP temporariamente"
  },
  "timestamp": "2026-04-19T14:30:00+00:00"
}

Endpoints de Auditoria (Admin)

Rate Limiting

Dupla camada: por IP e por usuário autenticado. Usa Redis (distribuído) ou File (servidor único). Configurável por rota com middleware RateLimitMiddleware.

// 5 requisições por minuto por IP
$rateLimit = [RateLimitMiddleware::class, ['limit' => 5, 'window' => 60]];
$router->post('/api/register', [Controller::class, 'register'], [$rateLimit]);

Middlewares de Segurança

Middlewares aplicados automaticamente pelo Kernel:

Headers de Segurança

Headers adicionados automaticamente em todas as respostas:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Cross-Origin-Opener-Policy: same-origin
• Referrer-Policy: strict-origin-when-cross-origin
• Content-Security-Policy (configurável)
• Strict-Transport-Security (HTTPS apenas)

Cobertura relacionada ao OWASP Top 10

Os itens abaixo são controles de apoio, não uma certificação automática. A cobertura final depende do código de cada módulo, das permissões do banco, do proxy, das dependências e da operação do servidor.

Boas Práticas

• Sempre use APP_DEBUG=false em produção.
• Configure APP_ENV=production para ativar validações extras.
• Nunca concatene variáveis em SQL — use prepared statements.
• Nunca acesse tabelas de outros módulos diretamente.
• Valide todos os inputs no Controller ou Service.
• Use OwnershipGuard para verificar posse de recursos.
• Gere secrets JWT com openssl rand -hex 32 (mínimo 32 chars).
• Configure COOKIE_SECURE=true e COOKIE_SAMESITE=Lax em produção.
• Use HTTPS em produção — configure TRUST_PROXY=true com proxy reverso.
• Configure SECURITY_ALERT_WEBHOOK para monitoramento em tempo real.
• Monitore logs de auditoria regularmente via /api/audit/logs.
• Implemente rate limiting em todas as rotas públicas.

Checklist antes de ativar uma rota

Exemplo mínimo de rota autenticada

O UUID do usuário vem da identidade validada. O repository deve incluir esse UUID na consulta, impedindo que um usuário altere um recurso de outro apenas trocando o parâmetro da URL.

<?php

use Ramsey\Uuid\Uuid;
use Src\Kernel\Auth;

// 20 alterações por minuto, autenticação obrigatória e circuit breaker do banco.
$router->patch(
    '/api/tarefas/{uuid}',
    [TarefaController::class, 'atualizar'],
    Auth::user(limit: 20, key: 'tarefas.atualizar', db: true),
);

final class TarefaController
{
    public function __construct(private readonly TarefaService $service) {}

    public function atualizar(Request $request): Response
    {
        $usuarioUuid = (string) Auth::id($request);
        $tarefaUuid = (string) $request->param('uuid');
        $titulo = trim((string) ($request->body['titulo'] ?? ''));

        if (!Uuid::isValid($tarefaUuid)) {
            return Response::json(['error' => 'Identificador inválido.'], 422);
        }
        if ($titulo === '' || mb_strlen($titulo) > 160) {
            return Response::json(['error' => 'Título deve ter entre 1 e 160 caracteres.'], 422);
        }

        // O service/repository busca por tarefaUuid + usuarioUuid.
        $tarefa = $this->service->atualizarDoUsuario($tarefaUuid, $usuarioUuid, $titulo);

        return Response::json(['data' => $tarefa]);
    }
}