Pular para conteúdo

security-headers: módulo NGINX para envio de cabeçalhos de segurança

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e 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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_security_headers_module.so;

Este documento descreve nginx-module-security-headers v0.3.0 lançado em 15 de fevereiro de 2026.

Este módulo NGINX adiciona cabeçalhos de segurança e remove cabeçalhos inseguros, da maneira certa (c).

Test Build

Sinopse

http {
    security_headers on;
    ...
}

Executar curl -IL https://example.com/ resultará nos cabeçalhos de segurança adicionados:

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

Em geral, o módulo apresenta o envio de cabeçalhos HTTP de segurança de uma maneira que melhor se conforma aos padrões. Por exemplo, o cabeçalho Strict-Transport-Security não deve ser enviado para solicitações HTTP simples. O módulo segue essa recomendação.

Nota importante sobre Strict-Transport-Security

O módulo adiciona vários cabeçalhos de segurança, incluindo Strict-Transport-Security. Note que preload é enviado no valor deste cabeçalho, por padrão. Isso significa que o Chrome pode e irá incluir seus sites na sua lista de domínios pré-carregados que são apenas HTTPS.

Normalmente, é isso que você deseja, mas tenha em mente que em alguns casos extremos você pode querer acessar um subdomínio através de uma conexão não criptografada.

Se você tem certeza absoluta de que todos os seus domínios e subdomínios utilizados com o módulo operarão principalmente em HTTPS, prossiga sem nenhum passo extra.

Se você não tem certeza se precisará acessar seus sites ou qualquer um de seus subdomínios através do protocolo HTTP inseguro, assegure-se de incluir security_headers_hsts_preload off; em sua configuração antes de iniciar o NGINX com o módulo para evitar que seu domínio seja pré-carregado pelo Chrome.

Principais recursos

  • Plug-n-Play: o conjunto padrão de cabeçalhos de segurança pode ser ativado com security_headers on; na sua configuração do NGINX
  • Envia apenas cabeçalhos de segurança relevantes para tipos HTML, não enviando para outros, por exemplo, X-Frame-Options é inútil para CSS
  • Funciona bem com solicitações GET condicionais: os cabeçalhos de segurança não são incluídos desnecessariamente
  • Não sofre as armadilhas da diretiva add_header
  • Oculta X-Powered-By e outros cabeçalhos que frequentemente vazam informações sobre a versão do software
  • Oculta completamente o cabeçalho Server, não apenas as informações da versão

Diretrizes de configuração

security_headers

  • sintaxe: security_headers on | off
  • padrão: off
  • contexto: http, server, location

Habilita ou desabilita a aplicação de cabeçalhos de segurança. O conjunto padrão inclui:

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

O cabeçalho obsoleto X-XSS-Protection é removido ativamente por padrão.

Os valores desses cabeçalhos (ou sua inclusão) podem ser controlados com outras diretivas security_headers_* abaixo.

hide_server_tokens

  • sintaxe: hide_server_tokens on | off
  • padrão: off
  • contexto: http, server, location

Habilita a ocultação de cabeçalhos que vazam informações sobre o software:

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

Vale a pena notar que alguns desses cabeçalhos têm uso funcional, por exemplo, a documentação do X-Page-Speed menciona:

... é usado para evitar loops infinitos e reescritas desnecessárias quando o PageSpeed busca recursos de uma origem que também usa PageSpeed

Portanto, é melhor especificar hide_server_tokens on; em instâncias do NGINX voltadas para o público, por exemplo, aquela que é acessada por navegadores reais, e não aquelas consumidas pelo Varnish ou outro software.

Na maioria dos casos, você estará bem com security_headers on; e hide_server_tokens on;, sem ajustes adicionais.

Para ajustes finos, use as diretivas específicas de cabeçalho abaixo. Um valor especial omit desabilita o envio de um cabeçalho específico pelo módulo (útil se você quiser que seu aplicativo backend o envie).

security_headers_xss

  • sintaxe: security_headers_xss off | on | block | omit | unset
  • padrão: unset
  • contexto: http, server, location

Controla o cabeçalho X-XSS-Protection.

  • unset (padrão): Remove ativamente o cabeçalho das respostas, incluindo qualquer cabeçalho definido por servidores upstream. Esta é a configuração recomendada porque o cabeçalho está obsoleto e introduz vulnerabilidades XSS em navegadores que o suportam.
  • omit: Não adiciona nem remove o cabeçalho; permite que os cabeçalhos upstream passem inalterados.
  • off: Envia X-XSS-Protection: 0 para desabilitar explicitamente a filtragem XSS do navegador.
  • on: Envia X-XSS-Protection: 1.
  • block: Envia X-XSS-Protection: 1; mode=block.

security_headers_frame

  • sintaxe: security_headers_frame sameorigin | deny | omit
  • padrão: sameorigin
  • contexto: http, server, location

Controla a inclusão e o valor do cabeçalho X-Frame-Options. O valor especial omit desabilitará o envio do cabeçalho pelo módulo.

security_headers_referrer_policy

  • sintaxe: security_headers_referrer_policy no-referrer | no-referrer-when-downgrade | same-origin | origin | strict-origin | origin-when-cross-origin | strict-origin-when-cross-origin | unsafe-url | omit
  • padrão: strict-origin-when-cross-origin
  • contexto: http, server, location

Controla a inclusão e o valor do cabeçalho Referrer-Policy. O valor especial omit desabilitará o envio do cabeçalho pelo módulo.

security_headers_corp

  • sintaxe: security_headers_corp same-site | same-origin | cross-origin | omit
  • padrão: same-site
  • contexto: http, server, location

Controla a inclusão e o valor do cabeçalho Cross-Origin-Resource-Policy. Este cabeçalho controla como seus recursos podem ser incorporados por outras origens. O valor especial omit desabilitará o envio do cabeçalho pelo módulo.

O padrão same-site é uma escolha segura que impede a incorporação entre sites enquanto permite solicitações do mesmo site.

security_headers_coop

  • sintaxe: security_headers_coop same-origin | same-origin-allow-popups | unsafe-none | omit
  • padrão: omit
  • contexto: http, server, location

Controla a inclusão e o valor do cabeçalho Cross-Origin-Opener-Policy. Este cabeçalho controla as relações de abertura de janelas entre origens. O valor especial omit desabilitará o envio do cabeçalho pelo módulo.

O padrão é omit porque habilitar este cabeçalho pode quebrar padrões de comunicação de popup/window.opener. Habilite explicitamente apenas se você entender as implicações.

security_headers_coep

  • sintaxe: security_headers_coep require-corp | credentialless | unsafe-none | omit
  • padrão: omit
  • contexto: http, server, location

Controla a inclusão e o valor do cabeçalho Cross-Origin-Embedder-Policy. Este cabeçalho controla a incorporação de recursos de origens cruzadas. O valor especial omit desabilitará o envio do cabeçalho pelo módulo.

O padrão é omit porque habilitar este cabeçalho pode quebrar sites que carregam recursos de terceiros (análises, ativos de CDN, anúncios) sem os cabeçalhos CORS adequados.

Isolamento entre origens

Para habilitar isolamento entre origens (necessário para SharedArrayBuffer e temporizadores de alta resolução), configure todos os três cabeçalhos de origem cruzada:

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

Atenção: Esta configuração quebrará o carregamento de quaisquer recursos de origem cruzada que não permitam explicitamente via CORS.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-security-headers.