Política de segurança de conteúdo

Política de Segurança de Conteúdo (CSP) é um mecanismo de segurança imposto pelo navegador que controla quais recursos externos, como scripts, estilos, imagens, fontes, frames e mais, podem ser carregados no seu Site da base de conhecimento. Quando o CSP é ativado no Document360, um diretor de política de segurança de conteúdo é incorporado na fonte da página do seu site, restringindo o carregamento de recursos apenas aos domínios que você configura explicitamente. Isso ajuda a proteger sua Base de Conhecimento contra vulnerabilidades comuns da web, como Cross-Site Scripting (XSS), clickjacking e ataques de injeção de dados.

Por que você precisa do CSP

Sem o CSP, os navegadores permitem que qualquer recurso carregue na sua página — incluindo scripts, imagens e frames de domínios que você não pretendia permitir. Isso cria vagas para:

• Scripts Multi-Site (XSS): Atacantes que injetam scripts maliciosos que roubam tokens de sessão ou manipulam o conteúdo da página.

• Clickjacking: Sua Base de Conhecimento embutida dentro de um iframe invisível em um site malicioso, enganando os usuários para cliques não intencionais.

• Injeção de dados: scripts não autorizados de terceiros que silenciosamente exfiltram dados ou análises de usuários.

O CSP permite definir uma lista de domínios confiáveis para cada tipo de recurso. O navegador aplica automaticamente, nenhuma alteração no código da sua aplicação é necessária.

Quando usar o CSP?

O CSP é mais valioso quando sua Base de Conhecimento incorpora conteúdo de terceiros (vídeos, widgets de chat, análises), usa scripts HTML ou inline personalizados, é implantada em um ambiente sensível à conformidade ou corporativo, ou precisa ser protegida contra ser enquadrada por sites externos.

Como o CSP funciona no Document360

O Document360 implementa o CSP por meio de um metaelemento embutido na fonte da página do seu site, em vez de um cabeçalho de resposta HTTP. Isso significa:

• Todas as regras CSP são aplicadas no nível da página por meio de uma <meta http-equiv="Content-Security-Policy"> tag.

• Se você validar o CSP inspecionando o cabeçalho de resposta HTTP, ele aparecerá ausente e esse é o comportamento esperado.

• Para confirmar se o CSP está ativo, clique com o botão direito no site da sua Base de Conhecimento, selecione Ver fonte da página e pesquise por "Content-Security-Policy".

Por que essa abordagem de metaelementos?

Cabeçalhos de resposta HTTP exigem configuração do lado do servidor. O Document360 usa um metaelemento para que você possa configurar o CSP inteiramente a partir da interface de configurações, sem nenhuma alteração na infraestrutura. A proteção de segurança é equivalente para a grande maioria das diretivas, com exceção dos ancestrais dos quadros, que só são suportados via cabeçalhos HTTP em alguns navegadores. O Document360 lida com isso automaticamente.

Ativando a política de segurança de conteúdo

1. Navegue até Configurações () > Site da base de conhecimento > Segurança.

2. Ative ativar para Ativar política de segurança de conteúdo.

3. Configure os grupos diretivas necessários. Você pode encontrar os seguintes campos fonte:
   a. Política de código
   b. Controle de recursos
   c. Incorporação e Segurança
   d. Reportagem

4. Clique em Salvar.

NOTA

Quando o CSP estiver ativado, certifique-se de que o marcador de atribuição nonce seja adicionado a todas as seções de scripts HTML personalizados. Exemplo:

<script nonce="{{Document360-Nonce}}">

NOTA

• O limite de caracteres para cada campo é 5000.

• Use vírgulas (,) para separar múltiplos domínios.

• Mantenha as URLs no seguinte formato: https://example.com.

• Configurações existentes de CSP permanecem preservadas ao desligar e ligar o CSP.

Grupos diretivos do CSP

As configurações do CSP são organizadas em quatro grupos lógicos. Cada grupo contém diretivas específicas controlando diferentes tipos de recursos. Todos os campos aceitam URLs de domínio separadas por vírgulas no formato  https://example.com.

1. Política de código

Esse grupo governa as fontes de onde o código e os recursos de estilo são carregados. Ele forma a base da sua configuração CSP, a diretiva de fonte padrão atua como um recurso de respaldo para qualquer tipo de recurso que não tenha uma regra mais específica definida.

2. Controle de recursos

Esse grupo controla quais domínios externos podem fornecer recursos de mídia e dados, como imagens, fontes, chamadas de API e scripts de trabalhadores em segundo plano no seu site da Base de Conhecimento.

3. Incorporação e Segurança

Esse grupo controla como sua Base de Conhecimento incorpora conteúdo externo e como ele pode ser incorporado em outros sites. É particularmente importante para prevenir ataques de clickjacking e gerenciar conteúdos de terceiros, como vídeos, widgets e portais.

4. Reporte

O grupo de Relatórios permite que você monitore seu CSP na prática, instruindo os navegadores a enviarem relatórios de violação para um endpoint designado sempre que um recurso for bloqueado pela sua política. Isso é essencial para identificar configurações incorretas e possíveis tentativas de ataque sem atrapalhar seu site.

NOTA

Certifique-se de que as URLs de endpoint inseridas nos campos de Relatórios sejam válidas e acessíveis publicamente antes de salvar. O endpoint do relatório também deve aceitar solicitações POST e responder com um código de status 2xx.

Proteção X-Frame

A opção de proteção contra X-Frame está disponível junto com as configurações do CSP na página de Segurança. Quando ativada, ela adiciona um cabeçalho de resposta X-Frame-Options: SAMEORIGIN às suas páginas da Base de Conhecimento, impedindo que sejam carregadas dentro de um iframe em qualquer domínio externo.

Isso oferece proteção contra clickjacking para navegadores e ferramentas que processam cabeçalhos HTTP em vez de meta-tags CSP. É um controle mais simples e direto do que os ancestrais dos frames. Não permite que você permita domínios confiáveis específicos

NOTA

As Opções X-Frame e a frame-ancestors diretiva CSP governam o comportamento de incorporação de frames. Se você configurar ambas, certifique-se de que sejam consistentes para evitar regras conflitantes.

Por exemplo, não ative a Proteção contra X-Frames enquanto também adiciona um domínio externo aos ancestrais dos quadros – o cabeçalho X-Frame irá sobrescrever a diretiva CSP em navegadores que suportam ambos.

Casos de uso para política de segurança de conteúdo

Vídeos incorporados

Se seus artigos incluírem vídeos do YouTube ou Vimeo, use a diretiva de fonte Frame para permitir apenas esses domínios confiáveis.

• Adicionar à fonte do quadro: https://www.youtube.com, https://player.vimeo.com

• Isso garante que a mídia embutida carregue corretamente enquanto bloqueia conteúdo iframe não autorizado.

Ferramentas de análise e feedback de terceiros

Se sua Base de Conhecimento usa Google Analytics, Mixpanel ou um widget de feedback, adicione os domínios de script e coleta de dados deles à fonte do Script e à fonte do Connect.

• Exemplo da fonte do script: https://www.google-analytics.com, https://cdn.mixpanel.com

• Conectar exemplo de fonte: https://api.mixpanel.com

Widgets de chat ao vivo

Widgets de chat como Intercom ou Zendesk normalmente precisam de permissões entre múltiplas diretivas porque carregam scripts, fazem chamadas de API e servem sua própria interface.

• Fonte do roteiro: https://widget.intercom.io, https://js.intercomcdn.com

• Fonte do contato: https://api.intercom.io, https://nexus-websocket-a.intercom.io

• Fonte da imagem: https://static.intercomassets.com

Fontes personalizadas

Google Fonts e Adobe Typekit carregam de dois domínios diferentes - um para a folha de estilo e outro para os arquivos de fonte reais. Ambos devem estar listados.

• Estilo de origem: https://fonts.googleapis.com

• Fonte: https://fonts.gstatic.com

Incorporando sua Base de Conhecimento em um portal de clientes

Se você precisar exibir sua Base de Conhecimento dentro de um iframe dentro do seu próprio produto ou aplicação SaaS, use a diretiva Frame ancestors para permitir esse domínio específico.

• Exemplo dos ancestrais frame: https://app.yourcompany.com

• Definir os ancestrais do Frame como 'nenhum' bloqueia todo o enquadramento externo. Só mude isso se você tiver um requisito legítimo de embedding.

HTML personalizado e scripts inline

Se seus artigos ou tema incluírem seções HTML personalizadas com tags <script> inline, esses scripts serão bloqueados por um CSP estrito, a menos que carreguem um atributo nonce. Use o marcador de posição nonce do Document360:

<script nonce="{{Document360-Nonce}}"> 

  // Your custom inline script 

</script> 

O {{Document360-Nonce}} marcador é substituído no momento de renderização por um valor único por requisição que corresponde ao nonce listado no CSP. Isso permite que o script inline confiável rode sem precisar enfraquecer sua política com 'unsafe-inline'.

Ambientes reforçados em conformidade e segurança

Equipes operando sob estruturas como SOC 2, ISO 27001 ou HIPAA frequentemente exigem uma política documentada de carregamento de recursos. O CSP fornece uma versão imposta por máquina dessa política. As diretrizes de relatórios também fornecem um rastreio de auditoria de quaisquer tentativas de violação da política.

Melhores práticas

Comece com um padrão restritivo

Defina a fonte padrão para 'self' primeiro. Isso cria uma linha de base segura, apenas recursos do seu próprio domínio são permitidos, a menos que explicitamente permitidos em outros lugares. Adicione domínios específicos nos campos alvo em vez de ampliar a fonte padrão.

Use diretrizes específicas em vez de listas de permissões amplas

Em vez de adicionar muitos domínios à fonte padrão, use os campos alvo: Código de código, Fonte de quadros, Conectar código, e assim por diante. Isso facilita a manutenção da política e reduz a superexposição acidental.

Evite curingas

Usar *. example.com permite qualquer subdomínio desse domínio, incluindo aqueles que você não controla ou que podem ser comprometidos. Use subdomínios coringa apenas quando você possui todos os subdomínios desse domínio e não tiver alternativa. Nunca use um bare (permitir todos) em qualquer diretiva.

Use relatórios antes de aplicar

Configure primeiro o endpoint de Reporte para monitorar recursos bloqueados antes que a política afete seus leitores. Revise os relatórios de violação por vários dias ou semanas antes de apertar a política.

Use nonce para scripts inline personalizados

Sempre use o {{Document360-Nonce}} marcador de posição nas seções de scripts HTML personalizados. Isso permite que scripts inline confiáveis rodem com segurança sem usar 'unsafe-inline', o que prejudicaria toda a sua política de scripts.

Mantenha as configurações de quadros alinhadas

Se a Proteção X-Frame e os ancestrais dos quadros estiverem configurados, certifique-se de que sigam o mesmo comportamento pretendido. Configurações desalinhadas podem causar bloqueios inesperados de iframe ou permitir enquadramento quando você pretendia bloqueá-lo.

Revisão trimestral

Ferramentas de terceiros mudam domínios CDN ao longo do tempo. Revise as configurações do seu CSP após qualquer alteração na integração e em um cronograma regular (pelo menos trimestral) para detectar alterações que possam ter quebrado silenciosamente o conteúdo embutido.

Testando sua Política de Segurança de Conteúdo

Após configurar e salvar suas configurações de CSP, verifique se a política está funcionando como esperado usando um dos seguintes métodos.

Método 1: Via Fonte da Página

• Abra seu site da Base de Conhecimento em um navegador.

• Clique com o botão direito em qualquer lugar da página e selecione Ver fonte da página.

• Use Ctrl+F (Windows) ou Cmd+F (Mac) e procure por "Content-Security-Policy".

• Se for encontrado, a configuração completa do CSP aparecerá ao lado deste termo, confirmando que está ativa.

Método 2: Via Ferramentas de Desenvolvimento de Navegador

1. Abra as ferramentas de desenvolvimento do seu navegador (F12 ou clique com o botão direito > Inspecionar).

2. Navegue até a aba Rede .

3. Visite sua Base de Conhecimento e selecione qualquer solicitação de página.

4. Revise o HTML da página para a meta tag CSP.

Método 3: Via Ferramentas Online

Você também pode usar ferramentas externas como securityheaders.com para analisar a configuração de segurança do seu site. Lembre-se de que, como o Document360 usa um meta elemento em vez de um cabeçalho de resposta, algumas ferramentas podem relatar o CSP como ausente no nível do cabeçalho, o que é esperado.

Solução de problemas

Passo 1: Leia o erro do console do navegador

Quando o CSP bloqueia um recurso, o navegador registra um erro específico no console de desenvolvedores (F12 > aba Console). A mensagem de erro indica exatamente o que foi bloqueado e qual diretiva foi violada.

Por exemplo: Recusaram-se a carregar o script 'https://cdn.example.com/widget.js' porque ele viola a seguinte diretiva CSP: "script-src 'self'". Esse erro indica para adicionar https://cdn.example.com ao campo fonte do Script. Leia o domínio da mensagem de erro e adicione-o ao campo diretiva correspondente nas configurações do Document360.

Passo 2: Identificar a diretriz correta

Compare o tipo de recurso no erro do console com o campo diretivo correto:

Questões comuns

O vídeo mostra como 'Este conteúdo está bloqueado' em um artigo, mas não em outro

O domínio que serve o vídeo não está na sua lista de permissão de origem de frames, ou o domínio difere entre os tipos de embeds (por exemplo, https://www.youtube.com para embeds padrão versus https://www.youtube-nocookie.com para embeds com maior privacidade). Adicione ambos à fonte de frames.

A fonte personalizada é exibida incorretamente ou recorre à fonte do sistema

Provedores de fontes normalmente usam dois domínios diferentes - um para a folha de estilo CSS e outro para os arquivos de fonte reais. Ambos devem estar listados. Para o Google Fonts, adicione https://fonts.googleapis.com à fonte de estilo e https://fonts.gstatic.com à fonte da fonte.

O widget de chat carrega, mas não funciona

Widgets de chat frequentemente carregam scripts, fazem chamadas de API e carregam imagens de múltiplos domínios. Verifique o console do navegador para todas as requisições bloqueadas — pode haver várias. Adicione todos os domínios necessários aos campos diretores apropriados (Código-fonte do script, Código-fonte Conectar, Fonte da Imagem).

O envio do formulário é bloqueado

Se um formulário na sua base de conhecimento for submetido para um serviço externo, adicione o domínio desse serviço ao campo de ação do formulário.

Os relatórios de violação não estão chegando ao endpoint do Relatório

Verifique que:

• A URL do endpoint é acessível publicamente (não está atrás de VPN ou firewall).

• O endpoint aceita solicitações POST e retorna uma resposta 2xx.

• O endpoint suporta o formato de requisição Type-Content: application/csp-report request.

• Se estiver usando a diretiva Report to, o grupo de relatórios nomeado está corretamente configurado na sua infraestrutura.

A ferramenta de validação do CSP reporta o CSP como ausente

O Document360 implementa o CSP via um meta elemento na fonte da página, não via um cabeçalho de resposta HTTP. Ferramentas que apenas verificam cabeçalhos de resposta reportarão o CSP como ausente. Para confirmar que o CSP está ativado, veja a fonte da página e pesquise por Content-Security-Policy.

Diferenças nos navegadores

A maioria dos navegadores modernos (Chrome, Firefox, Edge, Safari) suporta o elemento meta CSP. Diferenças conhecidas para estar atento:

• O Frame-Ancestors é ignorado quando entregue via um metaelemento em algumas versões antigas do navegador. Se a proteção contra embedding de quadros for crítica, também ative a Proteção X-Frame.

• O Safari pode lidar com algumas diretivas CSP de forma diferente do Chrome e Firefox. Teste sua configuração no Safari se seus usuários estiverem em dispositivos Apple.

• Navegadores muito antigos (Internet Explorer 11 e inferiores) não suportam CSP. Se você tem usuários do IE11, o CSP será ignorado silenciosamente.

NOTA

Projetos de Base de Conhecimento Privada não podem ser incorporados em iframes. Cookies de autenticação não são configurados corretamente dentro dos iframes, o que causa tentativas repetidas de login e erros de redirecionamento. Se você precisar incorporar a Base de Conhecimento em outro aplicativo, use um Knowledge base widget .

{ 
"csp-report": 
{"document-uri": "https://docs.yourcompany.com/article", 
"violated-directive": "script-src 'self'", 
"blocked-uri": "https://cdn.example.com/widget.js", 
"original-policy": "default-src 'self'; script-src 'self'"} 
}