Documentação

CSP Reports — guia de configuração e integração

O SiteGuardian inclui um endpoint de ingestão integrado para violações da Content-Security-Policy e eventos da Reporting-API. Aponte a sua CSP para ele e as violações reportadas pelo navegador fluem para o painel do seu monitor em segundos.

1. Ativar num monitor

Na página de detalhe do monitor, abra o separador CSP Reports e clique em Ativar. Geramos um URL assinado com HMAC e um snippet de cabeçalho pronto a colar.

2. Colar os cabeçalhos

O snippet contém três cabeçalhos. Os navegadores fazem fallback sem problemas — pode publicar os três em simultâneo.

nginx

add_header Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp" always;
add_header Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"' always;
add_header Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}' always;

Apache

Header always set Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
Header always set Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"'
Header always set Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}'

Caddy

header {
    Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
    Reporting-Endpoints `sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"`
    Report-To `{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}`
}

3. Verificar

Carregue o seu site num navegador real. Em segundos, o separador CSP Reports mostra o primeiro bucket. Se o separador ficar vazio, a próxima análise de cabeçalhos também confirma — aparece um selo verde quando detetamos que a sua CSP anuncia o nosso endpoint.

Modo Report-Only

CSP acabada de criar? Publique-a primeiro em modo Report-Only — nada é efetivamente bloqueado, mas as violações são reportadas. Troque o nome do cabeçalho e mantenha as mesmas diretivas:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}

O que guardamos — e o que não guardamos

• Os IPs dos clientes são submetidos a hash com um salt rotativo diário. Guardamos apenas um prefixo de 16 caracteres.
• Os query strings e fragmentos são removidos de cada URL antes do armazenamento.
• As strings User-Agent são reduzidas a uma família (chrome/firefox/safari/edge/opera/outro).
• Cada bucket retém no máximo 3 amostras em bruto e 10 URIs de documentos afetados.
• Retenção: 180 dias (Compliance), 365 dias (Enterprise). Depois, os buckets expiram através de um índice TTL. A ingestão de CSP requer um plano Compliance ou superior.

Limites de taxa e pausa automática

O nginx aplica um limite de taxa na edge de 200 req/s por IP de origem. Cada monitor tem um limite flexível de 10 000 relatórios/minuto; três minutos consecutivos acima do limite colocam a ingestão automaticamente em pausa durante uma hora e enviam um e-mail ao proprietário do monitor. A rotação do URL do endpoint é um botão de emergência de um só clique no separador.

Outros tipos de relatório

O mesmo endpoint aceita relatórios NEL (Network Error Logging), Deprecation, Intervention e Expect-CT da Reporting API do navegador. Sem configuração adicional — basta adicioná-los ao seu grupo Report-To.

Endpoints da API

Acesso programático para painéis e CI:

• POST /api/v1/monitors/{id}/csp-reports/enable
• POST /api/v1/monitors/{id}/csp-reports/regenerate
• POST /api/v1/monitors/{id}/csp-reports/disable
• GET /api/v1/monitors/{id}/csp-reports?hours=24
• GET /api/v1/monitors/{id}/csp-reports/{bucket_id}
• GET /api/v1/monitors/{id}/csp-reports/trend/hourly?hours=24
• GET /api/v1/monitors/{id}/csp-reports/recommendations