La referencia de directivas CSP cubre todos los campos de directivas disponibles en la configuración de Política de Seguridad de Contenidos de Document360, junto con las mejores prácticas para configurarlos, métodos para probar tu política y orientaciones para solucionar problemas de recursos bloqueados. Utiliza esta referencia una vez que hayas habilitado CSP y estés listo para configurar o validar tu política.
Grupos directivos CSP
Los entornos CSP en Document360 están organizados en cuatro grupos. Todos los campos aceptan URLs de dominio separadas por comas en el formato https://example.com.
Política de código
Este grupo gobierna las fuentes de las que se cargan el código y los recursos de estilo. La directiva de origen por defecto actúa como un respaldo para cualquier tipo de recurso que no tenga una regla más específica definida.
| Directiva | Nombre del campo | Descripción |
|---|---|---|
default-src |
Fuente predeterminada | Define dominios permitidos de respaldo para todos los tipos de recursos que no estén cubiertos por una directiva más específica. Un valor inicial común es 'self', que restringe todos los tipos de recursos no listados a tu propio dominio. |
script-src |
Fuente del guion | Especifica qué dominios pueden servir JavaScript en tu Base de Conocimiento. Solo los scripts de las fuentes listadas serán ejecutados por el navegador. |
style-src |
Fuente de estilo | Especifica qué dominios pueden proporcionar hojas de estilo y CSS. Evita que se inyecten estilos maliciosos. |
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.
| Directiva | Nombre del campo | Descripción |
|---|---|---|
img-src |
Fuente de la imagen | Especifica los dominios permitidos para cargar imágenes en tu sitio de la Base de Conocimiento. |
font-src |
Fuente fuente | Especifica los dominios permitidos para servir archivos de fuente usados por tu Base de Conocimientos. |
connect-src |
Conectar fuente | Especifica los dominios a los que los scripts pueden conectarse al realizar llamadas a la API o solicitudes de red (por ejemplo, fetch, XHR, WebSocket). |
worker-src |
Fuente del trabajador | Especifica los dominios permitidos para cargar scripts worker en segundo plano usados por tu Knowledge Base. |
Incrustación y seguridad
Este grupo controla cómo tu Base de Conocimiento integra 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.
| Directiva | Nombre del campo | Descripción |
|---|---|---|
frame-src |
Fuente de tramas | Especifica los dominios que se pueden incrustar como frames o iframes dentro de tu Base de Conocimiento (por ejemplo, YouTube, Vimeo). |
frame-ancestors |
Ancestros del marco | Especifica qué dominios pueden incrustar tus páginas de la Base de Conocimientos en sus propios marcos. Utiliza esto para evitar el encuadre no autorizado. |
form-action |
Acción de forma | Especifica los dominios a los que se permiten enviar envíos de formularios desde tu Base de Conocimiento. |
object-src |
Fuente del objeto | Especifica los dominios permitidos para cargar contenido de plugins como <object> o <embed> elementos. Ponlo en 'none' si no es necesario. |
Reportajes
El grupo de Reportes instruye a los navegadores a enviar informes de infracciones a un punto final designado siempre que un recurso sea bloqueado por tu política. Esto es esencial para identificar configuraciones erróneas y posibles intentos de ataque sin interrumpir tu sitio.
| Directiva | Nombre del campo | Descripción |
|---|---|---|
report-endpoint |
Endpoint de informe | Especifica la URL donde los navegadores deben enviar informes cuando los recursos están bloqueados por tu CSP. Introduce una o más URLs de endpoint de informes separadas por comas. |
report-to |
Informe a | Especifica el nombre del grupo de reporte que utiliza el navegador para enviar los informes de violaciones de CSP. Esto debe coincidir con un grupo de reportes definido en la configuración de informes de tu centro. |
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 debe aceptar solicitudes POST y responder con un código de estado 2xx.
Mejores prácticas
-
Empieza con un valor por defecto restrictivo — Establece el código fuente por defecto como
'self'primero. Esto crea una línea base segura donde solo se permiten recursos de tu propio dominio, salvo que se permita explícitamente en otros lugares. Añadir dominios específicos en campos específicos en lugar de ampliar el código fuente predeterminado. -
Utiliza directivas específicas en lugar de listas de permisos amplias — En lugar de añadir muchos dominios al código fuente por defecto, usa los campos objetivos: código fuente de script, fuente de tramas, fuente de conexión, y así sucesivamente. Esto facilita el mantenimiento de la póliza y reduce la sobreexposición accidental.
-
Utiliza los informes antes de hacer cumplir la ley — Configura primero el endpoint de los informes 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 personalizados en línea — 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.
Cómo comprobar 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: Vía 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.
- Pulsa Ctrl+F (Windows) o Cmd+F (Mac) y busca
Content-Security-Policy. - Si se encuentra, la configuración completa del CSP aparece junto a este término, confirmando que está activa.
Método 2: A través de herramientas para desarrolladores de navegadores
- Abre las herramientas de desarrollo de tu navegador (F12 o haz clic derecho > Inspección).
- Navega a la pestaña de Red .
- Visita tu Base de Conocimientos y selecciona cualquier solicitud de página.
- Revisa el HTML de la página para la meta etiqueta CSP.
Método 3: A través de herramientas online
También puedes utilizar herramientas externas como securityheaders.com para analizar la configuración de seguridad de tu sitio. Dado que Document360 utiliza un metaelemento en lugar de una cabecera de respuesta, algunas herramientas pueden informar que CSP está ausente a nivel de cabecera — esto es de esperar.
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 referencias de Frame, o el dominio varía entre tipos de incrustación (por ejemplo, https://www.youtube.com para incrustaciones estándar frente https://www.youtube-nocookie.com a incrustaciones con privacidad mejorada). Añade ambos a la fuente de Frame.
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 la fuente de estilo y https://fonts.gstatic.com a la fuente de fuentes.
El widget de chat carga pero no funciona
Los widgets de chat suelen cargar scripts, hacer llamadas a API y cargar imágenes desde múltiples dominios. Revisa la consola del navegador para todas las solicitudes bloqueadas — puede que haya varias. Añadir todos los dominios necesarios a los campos directivos correspondientes (Código fuente de script, Conexión fuente, Fuente de imagen).
Se bloquea la presentación de formularios
Si un formulario en tu Base de Conocimientos 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
Content-Type: application/csp-reportla solicitud. - 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 elemento meta en la fuente de la página, no mediante una cabecera de respuesta HTTP. Las herramientas que solo revisan 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:
frame-ancestorsse ignora cuando se entrega mediante un elemento meta en algunas versiones antiguas del navegador. Si la protección contra la 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 en silencio.
Los proyectos de Base de Conocimiento Privada no pueden integrarse 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 Conocimiento en otra aplicación, usa un Knowledge base widget en su lugar.
Preguntas frecuentes
¿Cuál es la diferencia entre frame-src y frame-ancestors?
Estas dos directivas controlan direcciones opuestas de incrustación. frame-src controla qué dominios externos puede incrustar tu Base de Conocimiento (por ejemplo, un vídeo de YouTube en un artículo). frame-ancestors controla qué dominios externos pueden incrustar tu Base de Conocimiento dentro de sus propias páginas.
¿Cómo uso las directrices de Informe?
Introduce la URL de tu endpoint de reporte en el campo de endpoint de informe . Cuando un navegador bloquea un recurso, envía un informe JSON a esa URL. Report to funciona junto con el endpoint de Report y especifica un grupo de informes con nombre preconfigurado en la infraestructura de informes de tu sitio — útil para configuraciones empresariales con monitorización centralizada de seguridad.
¿Qué debería añadir al campo fuente predeterminado?
Empieza por 'self', que restringe todos los tipos de recursos no listados a tu propio dominio. Luego añade dominios específicos en los campos más específicos (código fuente de script, fuente de imagen, etc.) en lugar de ampliar el código fuente por defecto. Un código fuente por defecto restrictivo con excepciones granulares es más seguro y fácil de auditar.
¿Qué es un informe de infracción del CSP y cómo se ve?
Cuando un navegador bloquea un recurso, envía una carga útil JSON a tu endpoint de Reporte. Un informe típico es el siguiente:
{
"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'"
}
}
El blocked-uri campo te indica exactamente qué dominio añadir a tu lista de permisos. El violated-directive campo te indica qué campo directivo actualizar en la configuración de Document360.