Política de seguridad de contenidos

La Política de Seguridad de Contenidos (CSP) es un mecanismo de seguridad impuesto por el navegador que controla qué recursos externos como scripts, estilos, imágenes, fuentes, marcos y más pueden cargar en tu Sitio de la base de conocimientos. Cuando CSP está habilitado en Document360, se integra un director de política de seguridad de contenidos en el código fuente de tu página, restringiendo la carga de recursos solo a los dominios que configuras explícitamente. Esto ayuda a proteger tu Base de Conocimiento de vulnerabilidades web comunes como el Cross-Site Scripting (XSS), el clickjacking y ataques por inyección de datos.

Por qué necesitas CSP

Sin CSP, los navegadores permiten que cualquier recurso cargue en tu página — incluyendo scripts, imágenes y marcos de dominios que no tenías intención de permitir. Esto crea espacios para:

• Scripting entre sitios (XSS): Atacantes que inyectan scripts maliciosos que roban tokens de sesión o manipulan el contenido de la página.

• Clickjacking: Tu base de conocimiento incrustada dentro de un iframe invisible en un sitio malicioso, engañando a los usuarios para que hagan clics no intencionados.

• Inyección de datos: scripts no autorizados de terceros que exfiltran silenciosamente datos o análisis de usuarios.

CSP te permite definir una lista de dominios de confianza para cada tipo de recurso. El navegador lo aplica automáticamente, no es necesario cambiar el código de tu aplicación.

¿Cuándo usar CSP?

CSP es más valioso cuando tu Base de Conocimiento incorpora contenido de terceros (vídeos, widgets de chat, analítica), utiliza scripts HTML o en línea personalizados, se despliega en un entorno empresarial o sensible al cumplimiento normativo, o necesita ser protegida para que no sea enmarcada por sitios externos.

Cómo funciona CSP en Document360

Document360 implementa CSP mediante un elemento meta incrustado en la fuente de la página de tu sitio, en lugar de mediante una cabecera de respuesta HTTP. Esto significa:

• Todas las reglas CSP se aplican a nivel de página mediante una <meta http-equiv="Content-Security-Policy"> etiqueta.

• Si validas CSP inspeccionando la cabecera de respuesta HTTP, aparecerá ausente y este es el comportamiento esperado.

• Para confirmar que CSP está activo, haz clic derecho en tu sitio de la Base de Conocimientos, selecciona Ver fuente de la página y busca "Content-Security-Policy".

¿Por qué el enfoque del metaelemento?

Las cabeceras de respuesta HTTP requieren configuración en el lado del servidor. Document360 utiliza un metaelemento para que puedas configurar CSP completamente desde la interfaz de configuración sin cambios en la infraestructura. La protección de seguridad es equivalente para la gran mayoría de las directivas, con la excepción de los antepasados de tramas, que solo se soportan mediante encabezados HTTP en algunos navegadores. Document360 gestiona esto automáticamente.

Activación de la política de seguridad de contenidos

1. Navega a Configuración () > Sitio de la base de conocimientos > Seguridad.

2. Activa la opción Activar política de seguridad de contenido.

3. Configura los grupos de directivas requeridos. Puedes encontrar los siguientes campos fuente:
   a. Política del código
   b. Control de recursos
   c. Incrustación y Seguridad
   d. Reportes

4. Haz clic en Guardar.

NOTA

Cuando CSP esté habilitado, asegúrate de que el marcador de posición del atributo nonce se añada a todas las secciones de scripts HTML personalizados. Ejemplo:

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

NOTA

• El límite de caracteres para cada campo es de 5000.

• Usa comas (,) para separar varios dominios.

• Mantén las URLs en el siguiente formato: https://example.com.

• Las configuraciones existentes de CSP se mantienen al desactivar y activar CSP.

Grupos directivos CSP

La configuración del CSP está organizada en cuatro grupos lógicos. Cada grupo contiene directivas específicas que controlan diferentes tipos de recursos. Todos los campos aceptan URLs de dominio separadas por comas en el formato  https://example.com.

1. Política de código

Este grupo gobierna las fuentes desde las que se cargan el código y los recursos de estilo. Forma la base de tu configuración CSP; la directiva de código fuente por defecto actúa como respaldo para cualquier tipo de recurso que no tenga definida una regla más específica.

2. Control de recursos

Este grupo controla qué dominios externos pueden suministrar recursos multimedia y de datos como imágenes, fuentes, llamadas a API y scripts de trabajo en segundo plano en tu sitio de la Base de Conocimiento.

3. Incrustación y Seguridad

Este grupo controla cómo tu Base de Conocimiento integra el contenido externo y cómo puede incrustarse en otros sitios web. Es especialmente importante para prevenir ataques de clickjacking y gestionar contenido de terceros como vídeos, widgets y portales.

4. Reportes

El grupo de Reportes te permite monitorizar tu CSP en la práctica indicando a los navegadores que envíen informes de infracciones a un punto final designado cada vez que un recurso sea bloqueado por tu política. Esto es esencial para identificar configuraciones erróneas e intentos de ataque potenciales sin interrumpir tu sitio.

NOTA

Asegúrate de que las URLs de endpoint introducidas en los campos de Reporte sean válidas y accesibles públicamente antes de guardarlas. El endpoint del informe también debe aceptar solicitudes POST y responder con un código de estado 2xx.

Protección X-Frame

La opción de protección contra X-Frame está disponible junto con la configuración de CSP en la página de Seguridad. Cuando está activada, añade un encabezado de respuesta X-Frame-Options: SAMEORIGIN a tus páginas de la Base de Conocimientos, impidiendo que se carguen dentro de un iframe en cualquier dominio externo.

Esto proporciona protección contra clickjacking para navegadores y herramientas que procesan cabeceras HTTP en lugar de CSP con meta-etiquetas. Es un control más sencillo y directo que los antepasados de los tramos. No permite permitir dominios confiables específicos

NOTA

Las Opciones de X-Frame y la frame-ancestors directiva CSP rigen el comportamiento de incrustación de tramas. Si configuras ambas, asegúrate de que sean consistentes para evitar reglas conflictivas.

Por ejemplo, no actives la protección contra tramas X mientras además añades un dominio externo a los ancestros de tramas: la cabecera de tramas X anulará la directiva CSP en navegadores que soportan ambos.

Casos de uso para la política de seguridad de contenidos

Vídeos incrustados

Si tus artículos incluyen vídeos de YouTube o Vimeo, utiliza la directiva de código fuente Frame para permitir solo esos dominios confiables.

• Añadir a la fuente del fotograma: https://www.youtube.com, https://player.vimeo.com

• Esto garantiza que los medios incrustados se carguen correctamente mientras bloquean contenido iframe no autorizado.

Herramientas de análisis y retroalimentación de terceros

Si tu Base de Conocimiento utiliza Google Analytics, Mixpanel o un widget de feedback, añade sus dominios de script y recopilación de datos al código fuente de Scripts y al código fuente Connect.

• Ejemplo de fuente del guion: https://www.google-analytics.com, https://cdn.mixpanel.com

• Conectar ejemplo fuente: https://api.mixpanel.com

Widgets de chat en vivo

Los widgets de chat como Intercom o Zendesk suelen necesitar permisos entre varias directivas porque cargan scripts, hacen llamadas a la API y sirven su propia interfaz.

• Fuente del guion: https://widget.intercom.io, https://js.intercomcdn.com

• Fuente de conexión: https://api.intercom.io, https://nexus-websocket-a.intercom.io

• Fuente de la imagen: https://static.intercomassets.com

Fuentes personalizadas

Google Fonts y Adobe Typekit se cargan desde dos dominios diferentes: uno para la hoja de estilo y otro para los archivos de fuente reales. Ambos deben estar listados.

• Style source: https://fonts.googleapis.com

• Fuente source: https://fonts.gstatic.com

Incrustar tu Base de Conocimiento en un portal para clientes

Si necesitas mostrar tu Base de Conocimiento dentro de un iframe dentro de tu propio producto o aplicación SaaS, utiliza la directiva de ancestros de Frame para permitir ese dominio específico.

• Ejemplo de ancestros de marco: https://app.yourcompany.com

• Poner los antepasados de Frame en 'ninguno' bloquea todo el encuadre externo. Solo cambia esto si tienes un requisito legítimo de incrustación.

HTML personalizado y scripts en línea

Si tus artículos o tema incluyen secciones HTML personalizadas con etiquetas <script> en línea, esos scripts serán bloqueados por un CSP estricto, a menos que lleven un atributo nonce. Usa el marcador de posición nonce de Document360:

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

  // Your custom inline script 

</script> 

El {{Document360-Nonce}} marcador de posición se reemplaza en tiempo de renderizado por un valor único por solicitud que coincide con el nonce listado en el CSP. Esto permite que el script en línea de confianza se ejecute sin necesidad de debilitar tu política con 'unsafe-inline'.

Entornos reforzados en cumplimiento y seguridad

Los equipos que operan bajo marcos como SOC 2, ISO 27001 o HIPAA suelen requerir una política documentada de carga de recursos. CSP proporciona una versión impuesta por máquina de esa política. Las directrices de Reporte además te proporcionan un rastreo de auditoría de cualquier intento de violación de la política.

Mejores prácticas

Empieza con un predeterminado restrictivo

Configura el código fuente por defecto como 'self' primero. Esto crea una línea base segura, solo se permiten recursos de tu propio dominio a menos que se permitan explícitamente en otros lugares. Añade dominios específicos en los campos objetivo en lugar de ampliar el código fuente por defecto.

Utiliza directivas específicas en lugar de listas de permisos amplias

En lugar de añadir muchos dominios al código fuente por defecto, utiliza los campos objetivos: código fuente de script, fuente de tramas, fuente de conexión, y así sucesivamente. Esto facilita el mantenimiento de la política y reduce la sobreexposición accidental.

Evita los comodines

Usar *. example.com permite cualquier subdominio de ese dominio, incluidos aquellos que no controles o que puedan verse comprometidos. Solo usa subdominios comodines cuando poseas todos los subdominios de ese dominio y no tengas alternativa. Nunca uses un solo (permitir todo) en ninguna directiva.

Utiliza los informes antes de hacer cumplir

Configura primero el endpoint de reportar para poder monitorizar los recursos bloqueados antes de que la política afecte a tus lectores. Revisa los informes de infracciones durante varios días o semanas antes de endurecer la política.

Usa nonce para scripts en línea personalizados

Usa siempre el {{Document360-Nonce}} marcador de posición en secciones de scripts HTML personalizados. Esto permite que los scripts en línea confiables se ejecuten de forma segura sin usar 'unsafe-inline', lo que socavaría toda tu política de scripts.

Mantén los ajustes de los fotogramas alineados

Si tanto la Protección de Tramas X como los antepasados de trama están configurados, asegúrate de que sigan el mismo comportamiento previsto. Configuraciones desalineadas pueden causar bloqueos inesperados de iframes o permitir el encuadre cuando se pretendía bloquearlo.

Revisión trimestral

Las herramientas de terceros cambian los dominios CDN con el tiempo. Revisa la configuración de tu CSP tras cualquier cambio de integración y con un calendario regular (al menos trimestral) para detectar cambios que hayan dañado silenciosamente el contenido incrustado.

Probando tu política de seguridad de contenidos

Después de configurar y guardar la configuración de tu CSP, verifica que la política funciona como se espera usando uno de los siguientes métodos.

Método 1: A través de la fuente de la página

• Abre tu sitio de la Base de Conocimientos en un navegador.

• Haz clic derecho en cualquier parte de la página y selecciona Ver fuente de la página.

• Utiliza Ctrl+F (Windows) o Cmd+F (Mac) y busca "Content-Security-Policy".

• Si se encuentra, la configuración completa del CSP aparecerá junto a este término, confirmando que está activa.

Método 2: A través de herramientas de desarrollo de navegador

1. Abre las herramientas de desarrollo de tu navegador (F12 o haz clic derecho > Inspección).

2. Navega a la pestaña de Red .

3. Visita tu Base de Conocimientos y selecciona cualquier solicitud de página.

4. Revisa el HTML de la página para la meta etiqueta CSP.

Método 3: A través de herramientas online

También puedes usar herramientas externas como securityheaders.com para analizar la configuración de seguridad de tu sitio. Ten en cuenta que, dado que Document360 utiliza un elemento meta en lugar de una cabecera de respuesta, algunas herramientas pueden informar que CSP está ausente a nivel de cabecera, lo cual es de esperar.

Resolución de problemas

Paso 1: Leer el error de la consola del navegador

Cuando CSP bloquea un recurso, el navegador registra un error específico en la consola de desarrolladores (F12 > pestaña Consola). El mensaje de error te dice exactamente qué fue bloqueado y qué directiva se violó.

Por ejemplo: Se negó a cargar el script 'https://cdn.example.com/widget.js' porque viola la siguiente directiva CSP: "script-src 'self'". Este error te indica que añadas https://cdn.example.com al campo fuente del Script. Lee el dominio desde el mensaje de error y añádelo al campo directiva correspondiente en la configuración de Document360.

Paso 2: Identificar la directiva adecuada

Empareja el tipo de recurso en el error de la consola con el campo directivo correcto:

Cuestiones comunes

El vídeo muestra 'Este contenido está bloqueado' en un artículo pero no en otro

El dominio que sirve al vídeo no está en tu lista de permanencia de Frame source, o el dominio varía entre tipos de embed (por ejemplo, https://www.youtube.com para embedos estándar frente a https://www.youtube-nocookie.com para embedos con privacidad mejorada). Añade ambos a Frame source.

La fuente personalizada se muestra incorrectamente o recurre a la fuente del sistema

Los proveedores de fuentes suelen usar dos dominios diferentes: uno para la hoja de estilo CSS y otro para los archivos de fuente reales. Ambos deben estar listados. Para Google Fonts, añade https://fonts.googleapis.com a Style source y https://fonts.gstatic.com a Font source.

El widget de chat carga pero no funciona

Los widgets de chat suelen cargar scripts, hacer llamadas a la API y cargar imágenes desde varios dominios. Revisa la consola del navegador para todas las solicitudes bloqueadas; puede haber varias. Añade todos los dominios requeridos a los campos directivos correspondientes (código fuente de script, fuente de conexión, fuente de imagen).

Se bloquea la presentación de formularios

Si un formulario en tu base de conocimiento se envía a un servicio externo, añade el dominio de ese servicio al campo de acción del formulario.

Los informes de infracciones no llegan al endpoint de Reporte

Verifica que:

• La URL del endpoint es accesible públicamente (no detrás de una VPN o cortafuegos).

• El endpoint acepta solicitudes POST y devuelve una respuesta 2xx.

• El endpoint soporta el formato de solicitud Content-Type: application/csp-report.

• Si se utiliza la directiva Report to, el grupo de informes con nombre está correctamente configurado en tu infraestructura.

La herramienta de validación de CSP informa que CSP falta

Document360 implementa CSP mediante un metaelemento en la fuente de la página, no mediante un encabezado de respuesta HTTP. Las herramientas que solo comprueban los encabezados de respuesta informarán de CSP como ausente. Para confirmar que CSP está habilitado, consulta la fuente de la página y busca Content-Security-Policy.

Diferencias en los navegadores

La mayoría de los navegadores modernos (Chrome, Firefox, Edge, Safari) soportan el elemento meta CSP. Diferencias conocidas a tener en cuenta:

• Frame-ancestors se ignora cuando se entrega mediante un elemento meta en algunas versiones antiguas del navegador. Si la protección contra incrustación de tramas es crítica, también activa la protección X-Frame.

• Safari puede gestionar algunas directivas CSP de forma diferente a Chrome y Firefox. Prueba tu configuración en Safari si tus usuarios están en dispositivos Apple.

• Los navegadores muy antiguos (Internet Explorer 11 y inferiores) no soportan CSP. Si tienes usuarios de IE11, CSP será ignorado silenciosamente.

NOTA

Los proyectos de la Base de Conocimiento Privada no pueden incrustarse en iframes. Las cookies de autenticación no se configuran correctamente dentro de los iframes, lo que provoca intentos repetidos de inicio de sesión y errores de redirección. Si necesitas incrustar la Base de Conocimientos en otra aplicación, usa un 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'"} 
}