Política de segurança de conteúdo

A 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 está ativado no Document360, uma diretiva de política de segurança de conteúdo é incorporada 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 seu site de base de conhecimento contra vulnerabilidades comuns da web, como Cross-Site Scripting (XSS), clickjacking e ataques de injeção de dados.

Por que o CSP é importante

Sem o CSP, 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 aberturas para:

• Scripts Multi-Site (XSS): Atacantes injetando 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 a aplica automaticamente; Não é necessária alteração no seu código de inscrição.

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 requerem configuração do lado do servidor. O Document360 usa um metaelemento para que você possa configurar o CSP inteiramente pela 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 de frames, que só são suportados via cabeçalhos HTTP em alguns navegadores. O Document360 resolve isso automaticamente.

Ativar 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 de diretrizes 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 atributo 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.

• Somente os proprietários do projeto, administradores ou usuários com acesso às configurações de Segurança podem configurar a Política de Segurança de Conteúdo.

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. Ela forma a base da sua configuração CSP, a diretiva Default source atua como um recurso alternativo 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. É especialmente 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 ativado, ele 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 CSP com metatags. É um controle mais simples e mais rombudo do que os ancestrais dos quadros. 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 quadros. Se você configurar ambos, 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.

• O Document360 também aplica o X-Content-Type-Options: nosniff cabeçalho de segurança em todos os recursos da Knowledge Base para ajudar a evitar que navegadores façam sniffing e interpretem arquivos com tipos de conteúdo incorretos.

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 propriamente ditos. 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 para '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 rigoroso, a menos que carreguem um atributo nonce. Use o marcador de posição Document360:

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

  // Your custom inline script 

</script> 

O {{Document360-Nonce}} marcador de posição é 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

Se suas equipes operam sob frameworks 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 qualquer tentativa de violação da política.

Melhores práticas

Comece com um padrão restritivo

Defina a fonte padrão como 'self' primeiro. Isso cria uma base segura, apenas recursos do seu próprio domínio são permitidos, a menos que sejam 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 direcionados: Código de código, Fonte de Frame, Conectar código, e assim por diante. Isso torna a apólice mais fácil de manter e reduz a superexposição acidental.

Evite curingas

Usando *. 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 (allow all) em qualquer diretiva.

Use relatórios antes de aplicar

Configure primeiro o endpoint de Relatório para monitorar recursos bloqueados antes que a política afete seus leitores. Revise os relatórios de infrações 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 lugar 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 política do seu script.

Mantenha as configurações de quadros alinhadas

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

Revisão trimestral

Ferramentas de terceiros mudam domínios de 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 incorporado.

Teste 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 elemento meta em vez de um cabeçalho de resposta, algumas ferramentas podem reportar 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 desenvolvedor (F12 > aba Console). A mensagem de erro diz 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 diretriz 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 diretivo 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 atende 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 privacidade). Adicione ambos ao Frame Source.

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 propriamente ditos. Ambos devem estar listados. Para fontes do Google, adicione https://fonts.googleapis.com à fonte de estilo e https://fonts.gstatic.com à fonte de 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 solicitações bloqueadas – pode haver várias. Adicione todos os domínios necessários aos campos diretores apropriados (Código de Script, Conectar Código, Fonte de 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 por meio de um metaelemento 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 Conteúdo-Segurança-Política.

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 contra X-Quadros.

• 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 estã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'"} 
}