Content Security Policy (CSP) sem quebrar seu site

Você já ouviu que Content Security Policy (CSP) é essencial para proteger seu site contra cross-site scripting (XSS) e ataques de injeção de dados. Mas quando você tenta adicioná-la, seu site quebra: imagens desaparecem, scripts param de funcionar, estilos somem. Parece um trade-off entre segurança e funcionalidade. Não precisa ser assim.

Neste guia, você aprenderá uma abordagem prática e passo a passo para implantar CSP sem quebrar seu site. Abordaremos as diretivas principais, como usar nonces e hashes, e como testar com segurança. Ao final, você terá uma CSP funcional que melhora a segurança sem sacrificar a experiência do usuário.

O que é CSP e por que ela quebra sites?

Content Security Policy é um padrão de segurança do navegador que permite restringir quais recursos (scripts, estilos, imagens, fontes, etc.) podem ser carregados na sua página. Ela é entregue via um cabeçalho HTTP como Content-Security-Policy: default-src 'self'.

CSP quebra sites porque bloqueia qualquer recurso que não corresponda à sua política. Se você tem scripts inline, scripts externos de CDNs ou estilos inline, eles serão bloqueados a menos que você os permita explicitamente. O comportamento padrão é bloquear tudo o que não é permitido, e é por isso que uma política rigorosa pode rapidamente quebrar um site.

A chave é começar com uma política permissiva e apertá-la gradualmente enquanto monitora violações.

Diretivas CSP principais que você precisa conhecer

CSP usa diretivas para controlar diferentes tipos de recursos. Aqui estão as mais comuns:

• default-src: Fallback para outras diretivas. Comece por aqui.
• script-src: Controla fontes de JavaScript.
• style-src: Controla fontes de CSS.
• img-src: Controla fontes de imagens.
• connect-src: Controla destinos de AJAX, WebSocket e fetch.
• font-src: Controla fontes de web fonts.
• frame-src: Controla fontes de iframes.
• report-uri / report-to: Para onde enviar relatórios de violação.

Você pode definir várias diretivas em um cabeçalho, separadas por ponto e vírgula. Por exemplo:

Content-Security-Policy: default-src 'self'; script-src 'self' https://trusted.cdn.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https://images.example.com

Cada diretiva aceita uma lista de fontes separadas por espaço. Fontes podem ser palavras-chave como 'self', 'unsafe-inline', 'unsafe-eval', ou URLs, ou nonces/hashes.

Passo a passo: Implante CSP sem quebrar seu site

Siga estes passos para implantar CSP com segurança.

1. Comece com uma política somente de relatório. Use o cabeçalho Content-Security-Policy-Report-Only em vez do de aplicação. Isso permite ver o que seria bloqueado sem realmente bloquear.
2. Defina uma política permissiva. Comece com algo como default-src 'self' 'unsafe-inline' 'unsafe-eval' https: para permitir a maioria das coisas. Isso minimiza quebras.
3. Colete relatórios de violação. Configure report-uri para um endpoint que registra violações. Revise esses relatórios para identificar recursos bloqueados.
4. Corrija violações. Atualize seu código para evitar scripts/estilos inline, ou adicione nonces/hashes. Mova recursos externos para domínios permitidos.
5. Aperte a política gradualmente. Remova 'unsafe-inline' e 'unsafe-eval' depois de refatorar. Restrinja domínios permitidos.
6. Mude para o modo de aplicação. Quando os relatórios não mostrarem bloqueios inesperados, mude o cabeçalho para Content-Security-Policy (sem -Report-Only).
7. Monitore continuamente. Mantenha o endpoint de relatórios ativo para capturar novos problemas.

Essa abordagem incremental garante que você não quebre seu site enquanto melhora a segurança.

Usando nonces e hashes para scripts inline

Scripts inline são uma causa comum de quebra de CSP. Em vez de permitir 'unsafe-inline', use um nonce (número usado uma vez) ou hash.

Abordagem com nonce: Gere um nonce aleatório por requisição, adicione-o ao seu cabeçalho CSP e inclua-o nas suas tags script.

Content-Security-Policy: script-src 'nonce-abc123'

<script nonce="abc123">...</script>

Abordagem com hash: Calcule o hash SHA do seu script inline e adicione-o à política.

Content-Security-Policy: script-src 'sha256-xyz...'

Hashes são melhores para scripts inline estáticos que não mudam com frequência. Nonces são melhores para conteúdo dinâmico.

Para estilos, você também pode usar nonces ou hashes, mas observe que style-src com nonces não cobre atributos de estilo inline (por exemplo, style="..."). Para esses, você precisa de 'unsafe-inline' ou refatorar para classes.

Diretivas CSP comuns e seu impacto

Use esta tabela como referência rápida ao construir sua política.

Testando e monitorando sua CSP

Antes de aplicar, teste minuciosamente. Use as ferramentas de desenvolvedor do navegador: a aba Console mostra violações de CSP como erros. A aba Network mostra o cabeçalho CSP.

Para testes automatizados, considere ferramentas como o CSP Evaluator do Google (online) ou o pacote npm csp_evaluator. Eles ajudam a identificar políticas fracas.

Configure um endpoint de relatórios para coletar violações em produção. Você pode usar um serviço como Report URI ou construir seu próprio endpoint que registra em arquivo ou banco de dados. Analise os relatórios regularmente para capturar novos problemas.

Lembre-se: CSP não é uma bala de prata. É uma camada de defesa. Combine-a com validação de entrada, codificação de saída e outras boas práticas de segurança.

FAQ

Qual é a diferença entre Content-Security-Policy e Content-Security-Policy-Report-Only?

O cabeçalho de aplicação (Content-Security-Policy) bloqueia violações. O cabeçalho somente de relatório (Content-Security-Policy-Report-Only) apenas relata violações sem bloquear, permitindo testar uma política com segurança.

Posso usar CSP com manipuladores de eventos inline como onclick?

Não, manipuladores de eventos inline são bloqueados por CSP a menos que você use 'unsafe-inline' (o que é desencorajado) ou refatore para usar addEventListener. Para melhor segurança, evite manipuladores de eventos inline.

Como permitir o Google Analytics com CSP?

Adicione os domínios do Google Analytics às suas diretivas script-src e connect-src. Por exemplo: script-src 'self' https://www.googletagmanager.com; connect-src 'self' https://www.google-analytics.com. Verifique a documentação do Google para os requisitos mais recentes.

Implantar CSP não precisa ser um processo doloroso. Com uma abordagem gradual, você pode proteger seus usuários contra XSS e outros ataques sem interromper seu site. Comece com o modo somente de relatório, corrija violações e aperte sua política com o tempo.

Se você precisa formatar ou validar rapidamente arquivos de configuração JSON para seus relatórios CSP, experimente nosso JSON Formatter para embelezar e depurar seus dados JSON.