Content-Security-Policy
Proporciona cabeceras HTTP Content-Security-Policy para proteger contra XSS y otros ataques de inyección de código controlando qué recursos puede cargar el navegador.
csp
Install
composer require 'drupal/csp:^2.2'
Overview
El módulo Content-Security-Policy (CSP) permite a los sitios Drupal enviar cabeceras HTTP Content-Security-Policy, un poderoso mecanismo de seguridad que ayuda a prevenir cross-site scripting (XSS), clickjacking y otros ataques de inyección de código. CSP permite a los administradores del sitio especificar qué orígenes son fuentes confiables para scripts, hojas de estilo, imágenes, fuentes y otros recursos.
El módulo proporciona una interfaz administrativa completa para configurar tanto políticas de Solo Reporte como políticas Aplicadas, con soporte para todas las directivas CSP estándar. Detecta automáticamente los recursos externos definidos en las bibliotecas de Drupal y los añade a la política, reduciendo la configuración manual. El módulo también incluye soporte para nonces y hashes para permitir scripts y estilos inline específicos mientras bloquea otros.
Para desarrolladores, el módulo proporciona servicios y eventos para modificar programáticamente la política CSP, así como un sistema de plugins para implementar manejadores de reportes personalizados. Los themes pueden usar un hook alter dedicado para modificar la política según sea necesario.
Features
- Soporte de política dual: Configura cabeceras Content-Security-Policy tanto de Solo Reporte como Aplicadas de forma independiente
- Soporte completo de directivas: Configura todas las directivas CSP3 incluyendo default-src, script-src, style-src, img-src, font-src, connect-src, frame-src, frame-ancestors, form-action, base-uri, object-src, worker-src, manifest-src, media-src, prefetch-src, sandbox, webrtc, trusted-types y más
- Detección automática de bibliotecas: Escanea todos los módulos y themes habilitados para incluir automáticamente fuentes externas de scripts y hojas de estilo desde las definiciones de bibliotecas
- Soporte de nonce: Generación de nonce criptográfico por solicitud para permitir scripts y estilos inline específicos manteniendo la seguridad
- Soporte de hash: Calcula e incluye hashes SHA-256, SHA-384 o SHA-512 para permitir código inline específico
- Configuración flexible de fuentes: Establece la política base (self, none, any) y añade fuentes adicionales permitidas por directiva
- Soporte de flags de palabras clave: Habilita flags como 'unsafe-inline', 'unsafe-eval', 'unsafe-hashes', 'report-sample', 'wasm-unsafe-eval' e 'inline-speculation-rules' para las directivas aplicables
- Sistema de reportes extensible: Soporte incorporado para endpoints URI personalizados e integración con Report-URI.com, con arquitectura de plugins para manejadores de reportes personalizados
- Integración con CKEditor5: Añade automáticamente las excepciones requeridas cuando CKEditor5 está presente en una página
- Optimización de política: Reduce automáticamente fuentes redundantes y elimina directivas que coinciden con valores de respaldo
- Solución para bug de Firefox: Incluye solución alternativa para el bug de Firefox con nonces/hashes en default-src
- Arquitectura basada en eventos: El evento CspEvents::POLICY_ALTER permite a los módulos modificar la política antes de enviarla
- Soporte de hook para themes: hook_csp_policy_alter permite a los themes personalizar la política
- Integración con render elements: Adjunta fuentes CSP, nonces y hashes directamente a los render elements
Use Cases
Protección Básica contra XSS
Habilita tanto la política Solo Reporte como la Aplicada con 'self' como base para script-src y style-src. Esto previene la carga de scripts y estilos externos que podrían ser inyectados por atacantes. Usa primero la política Solo Reporte para identificar cualquier recurso externo legítimo que necesite ser permitido.
Prevención de Clickjacking
Configura la directiva frame-ancestors con 'self' o 'none' para prevenir que tus páginas sean incrustadas en frames en otros sitios. Esto protege contra ataques de clickjacking donde los atacantes superponen iframes transparentes sobre contenido legítimo.
Permitir Recursos de CDN
Añade nombres de host de CDN (ej. 'https://cdn.example.com') a las directivas apropiadas (script-src, style-src, font-src, img-src) para permitir recursos de CDNs confiables mientras bloqueas fuentes desconocidas. El módulo detecta automáticamente muchas fuentes de CDN desde las definiciones de bibliotecas de Drupal.
Usar Nonces para Scripts Inline
Para módulos que necesitan añadir scripts inline, usa el servicio csp.policy_helper para añadir nonces. Adjunta 'csp_nonce' a los render elements con un valor de respaldo. El nonce se añade automáticamente a script-src-elem y a la cabecera, permitiendo scripts inline específicos mientras bloquea otros.
Actualización de Contenido Mixto
Habilita 'upgrade-insecure-requests' en la política Aplicada para actualizar automáticamente solicitudes HTTP a HTTPS, ayudando con la migración a HTTPS sin romper recursos referenciados con URLs HTTP.
Integración de Widgets de Terceros
Al incrustar widgets de terceros (Google Maps, embeds de redes sociales, etc.), añade los dominios requeridos a las directivas frame-src, script-src y style-src. Comienza con el modo Solo Reporte para descubrir todas las fuentes requeridas, luego cambia al modo Aplicado.
Implementar Trusted Types
Habilita las directivas trusted-types y require-trusted-types-for para prevenir XSS basado en DOM requiriendo el uso de la API Trusted Types para sinks peligrosos de manipulación DOM. Esta es una característica avanzada para aplicaciones con JavaScript complejo.
Tips
- Siempre comienza con el modo Solo Reporte para descubrir las fuentes requeridas antes de aplicar la política
- Usa la característica Wizard de Report-URI.com durante el desarrollo para construir tu política fácilmente
- El flag 'report-sample' ayuda a identificar qué scripts o estilos inline están causando violaciones
- Las fuentes externas definidas en archivos *.libraries.yml se detectan automáticamente - verifica si las bibliotecas están definidas correctamente antes de añadir fuentes manualmente
- Usa las herramientas de desarrollador del navegador (pestañas Consola y Red) para identificar violaciones CSP
- La directiva frame-ancestors reemplaza la cabecera X-Frame-Options más antigua para protección contra clickjacking
- Considera habilitar 'upgrade-insecure-requests' al migrar a HTTPS para evitar problemas de contenido mixto
- Al usar nonces, siempre proporciona un valor de respaldo para navegadores que pueden no soportar nonces
- Las directivas marcadas con 'auto' en la interfaz de administración tienen fuentes detectadas automáticamente desde las bibliotecas
Technical Details
Admin Pages 1
/admin/config/system/csp
Configura las cabeceras Content-Security-Policy para tu sitio con soporte para políticas tanto de Solo Reporte como Aplicadas. La página usa pestañas verticales para separar la configuración de políticas.
Permissions 1
Hooks 1
hook_csp_policy_alter
Permite a los themes alterar la política CSP para la respuesta actual. Este hook solo se invoca para themes; los módulos deben usar el evento CspEvents::POLICY_ALTER en su lugar.
Troubleshooting 6
Comienza con el modo Solo Reporte habilitado y Aplicada deshabilitada. Monitorea la consola del navegador y el endpoint de reportes para violaciones. Añade las fuentes necesarias a las directivas apropiadas. Solo habilita el modo Aplicada después de que todas las fuentes legítimas estén permitidas.
El módulo añade automáticamente 'unsafe-inline' para CKEditor5 cuando se detecta. Asegúrate de que el módulo esté detectando CKEditor5 correctamente. Si los problemas persisten, añade manualmente 'unsafe-inline' a las directivas style-src.
Verifica si la biblioteca está definida en un archivo *.libraries.yml con la URL externa. El módulo las detecta automáticamente. Si no se detecta automáticamente, añade manualmente el host a las directivas script-src-elem y script-src.
Si no puedes evitar los estilos inline, añade 'unsafe-inline' a las directivas style-src. Para mejor seguridad, usa el servicio csp.policy_helper para añadir hashes para estilos inline específicos.
El módulo advertirá si las sub-directivas *-attr o *-elem están habilitadas sin una directiva de respaldo correspondiente (script-src, style-src o default-src). Habilita la directiva padre para asegurar compatibilidad con navegadores que no soportan sub-directivas.
Verifica que al menos una política (Solo Reporte o Aplicada) esté habilitada en la configuración. Verifica que el usuario tenga permiso para acceder a la página y que el caché no esté interfiriendo. Comprueba que ningún otro módulo o servidor web esté removiendo la cabecera.
Security Notes 6
- El permiso 'administer csp configuration' solo debe otorgarse a administradores de confianza ya que una mala configuración puede romper la funcionalidad del sitio o debilitar la seguridad
- Evita usar 'unsafe-inline' y 'unsafe-eval' en producción a menos que sea absolutamente necesario, ya que debilitan significativamente la protección CSP
- La palabra clave 'strict-dynamic' no es configurable a través de la UI ya que requiere implementación de hash o nonce en el código de la aplicación
- Las fuentes hash en script-src o style-src pueden bloquear funcionalidad que depende de código inline - prueba exhaustivamente
- La cabecera Solo Reporte permite monitorear violaciones sin bloquearlas - usa esto para desarrollar tu política de forma segura
- CSP es una medida de defensa en profundidad y no debe ser el único mecanismo de seguridad protegiendo tu sitio