Saltar a contenido

security-headers: módulo NGINX para enviar encabezados de seguridad

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-security-headers

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-security-headers

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_security_headers_module.so;

Este documento describe nginx-module-security-headers v0.3.0 lanzado el 15 de febrero de 2026.

Este módulo NGINX añade encabezados de seguridad y elimina encabezados inseguros, de la manera correcta (c).

Test Build

Sinopsis

http {
    security_headers on;
    ...
}

Ejecutar curl -IL https://example.com/ generará los encabezados de seguridad añadidos:

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 21 May 2019 16:15:46 GMT
Content-Type: text/html; charset=UTF-8
Vary: Accept-Encoding
Accept-Ranges: bytes
Connection: keep-alive
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Cross-Origin-Resource-Policy: same-site
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

En general, el módulo se caracteriza por enviar encabezados HTTP de seguridad de una manera que se ajusta mejor a los estándares. Por ejemplo, el encabezado Strict-Transport-Security no debe enviarse para solicitudes HTTP simples. El módulo sigue esta recomendación.

Nota importante sobre Strict-Transport-Security

El módulo añade varios encabezados de seguridad, incluyendo Strict-Transport-Security. Ten en cuenta que preload se envía en el valor de este encabezado, por defecto. Esto significa que Chrome puede y añadirá tus sitios web a su lista de dominios precargados que son solo HTTPS.

Normalmente, es lo que deseas, pero ten en cuenta que en algunos casos extremos podrías querer acceder a un subdominio a través de una conexión no encriptada.

Si estás absolutamente seguro de que todos tus dominios y subdominios utilizados con el módulo operarán principalmente en HTTPS, procede sin ningún paso adicional.

Si no estás seguro de si tienes o tendrás la necesidad de acceder a tus sitios web o a cualquiera de sus subdominios a través del protocolo HTTP no seguro, asegúrate de incluir security_headers_hsts_preload off; en tu configuración antes de iniciar NGINX con el módulo para evitar que tu dominio sea precargado por Chrome.

Características clave

  • Plug-n-Play: el conjunto predeterminado de encabezados de seguridad se puede habilitar con security_headers on; en tu configuración de NGINX
  • Envía encabezados de seguridad solo para tipos relevantes, no enviando para otros, por ejemplo, X-Frame-Options es inútil para CSS
  • Funciona bien con solicitudes GET condicionales: los encabezados de seguridad no se incluyen innecesariamente
  • No sufre las trampas de la directiva add_header
  • Oculta X-Powered-By y otros encabezados que a menudo filtran información sobre la versión del software
  • Oculta completamente el encabezado Server, no solo la información de la versión

Directivas de configuración

security_headers

  • sintaxis: security_headers on | off
  • predeterminado: off
  • contexto: http, server, location

Habilita o deshabilita la aplicación de encabezados de seguridad. El conjunto predeterminado incluye:

  • X-Frame-Options: SAMEORIGIN
  • Referrer-Policy: strict-origin-when-cross-origin
  • X-Content-Type-Options: nosniff
  • Cross-Origin-Resource-Policy: same-site

El encabezado obsoleto X-XSS-Protection se elimina activamente por defecto.

Los valores de estos encabezados (o su inclusión) se pueden controlar con otras directivas security_headers_* a continuación.

hide_server_tokens

  • sintaxis: hide_server_tokens on | off
  • predeterminado: off
  • contexto: http, server, location

Habilita ocultar encabezados que filtran información del software:

  • Server
  • X-Powered-By
  • X-Page-Speed
  • X-Varnish

Vale la pena mencionar que algunos de esos encabezados tienen un uso funcional, por ejemplo, la documentación de X-Page-Speed menciona:

... se utiliza para prevenir bucles infinitos y reescrituras innecesarias cuando PageSpeed obtiene recursos de un origen que también usa PageSpeed

Por lo tanto, es mejor especificar hide_server_tokens on; en instancias de NGINX orientadas al público, por ejemplo, la que es accedida por navegadores reales, y no las consumidas por Varnish u otro software.

En la mayoría de los casos, estarás bien con security_headers on; y hide_server_tokens on;, sin ningún ajuste.

Para un ajuste fino, utiliza las directivas específicas de encabezados a continuación. Un valor especial omit desactiva el envío de un encabezado particular por el módulo (útil si deseas que tu aplicación backend lo envíe).

security_headers_xss

  • sintaxis: security_headers_xss off | on | block | omit | unset
  • predeterminado: unset
  • contexto: http, server, location

Controla el encabezado X-XSS-Protection.

  • unset (predeterminado): Elimina activamente el encabezado de las respuestas, incluyendo cualquier encabezado establecido por servidores upstream. Esta es la configuración recomendada porque el encabezado está obsoleto y introduce vulnerabilidades XSS en los navegadores que lo soportan.
  • omit: No añade ni elimina el encabezado; permite que los encabezados upstream pasen sin cambios.
  • off: Envía X-XSS-Protection: 0 para deshabilitar explícitamente el filtrado XSS del navegador.
  • on: Envía X-XSS-Protection: 1.
  • block: Envía X-XSS-Protection: 1; mode=block.

security_headers_frame

  • sintaxis: security_headers_frame sameorigin | deny | omit
  • predeterminado: sameorigin
  • contexto: http, server, location

Controla la inclusión y el valor del encabezado X-Frame-Options. El valor especial omit desactivará el envío del encabezado por el módulo.

security_headers_referrer_policy

  • sintaxis: security_headers_referrer_policy no-referrer | no-referrer-when-downgrade | same-origin | strict-origin | origin-when-cross-origin | strict-origin-when-cross-origin | unsafe-url | omit
  • predeterminado: strict-origin-when-cross-origin
  • contexto: http, server, location

Controla la inclusión y el valor del encabezado Referrer-Policy. El valor especial omit desactivará el envío del encabezado por el módulo.

security_headers_corp

  • sintaxis: security_headers_corp same-site | same-origin | cross-origin | omit
  • predeterminado: same-site
  • contexto: http, server, location

Controla la inclusión y el valor del encabezado Cross-Origin-Resource-Policy. Este encabezado controla cómo tus recursos pueden ser incrustados por otros orígenes. El valor especial omit desactivará el envío del encabezado por el módulo.

El valor predeterminado same-site es una opción segura que previene la incrustación entre sitios mientras permite solicitudes del mismo sitio.

security_headers_coop

  • sintaxis: security_headers_coop same-origin | same-origin-allow-popups | unsafe-none | omit
  • predeterminado: omit
  • contexto: http, server, location

Controla la inclusión y el valor del encabezado Cross-Origin-Opener-Policy. Este encabezado controla las relaciones de apertura de ventanas entre orígenes. El valor especial omit desactivará el envío del encabezado por el módulo.

El valor predeterminado es omit porque habilitar este encabezado puede romper patrones de comunicación de popup/window.opener. Habilítalo explícitamente solo si entiendes las implicaciones.

security_headers_coep

  • sintaxis: security_headers_coep require-corp | credentialless | unsafe-none | omit
  • predeterminado: omit
  • contexto: http, server, location

Controla la inclusión y el valor del encabezado Cross-Origin-Embedder-Policy. Este encabezado controla la incrustación de recursos de diferentes orígenes. El valor especial omit desactivará el envío del encabezado por el módulo.

El valor predeterminado es omit porque habilitar este encabezado puede romper sitios que cargan recursos de terceros (analítica, activos de CDN, anuncios) sin los encabezados CORS adecuados.

Aislamiento entre orígenes

Para habilitar el aislamiento entre orígenes (requerido para SharedArrayBuffer y temporizadores de alta resolución), configura los tres encabezados de origen cruzado:

security_headers on;
security_headers_corp same-origin;
security_headers_coop same-origin;
security_headers_coep require-corp;

Advertencia: Esta configuración romperá la carga de cualquier recurso de origen cruzado que no lo permita explícitamente a través de CORS.

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-security-headers.