Pular para conteúdo

Segurança e HTTPS

Esta página reúne as configurações de segurança da instância: HTTPS e certificados, proteção contra bots (Anubis) e as variáveis mais sensíveis do arquivo .env.

Ela é voltada para quem administra a instância (SuperAdmin ou perfil técnico-operacional).

HTTPS e certificados

O Farinha roda atrás do Caddy, que cuida do HTTPS automaticamente:

  • Com um endereço público configurado (por exemplo, farinha.suaInstituicao.org): o Caddy obtém e renova certificados gratuitos automaticamente.
  • Com certificados próprios: coloque os arquivos fullchain.pem e privkey.pem na pasta certs/, na raiz do projeto. Eles terão prioridade sobre os certificados automáticos.
  • Sem endereço público e sem certificados próprios (por exemplo, localhost ou um IP): a segurança é desabilitada, porque os certificados automáticos exigiriam instalação de uma autoridade certificadora nos clientes. Nesse caso, é importante configurar um endereço público ou certificados próprios o quanto antes.

Se, por algum motivo, você quiser desabilitar o HTTPS de qualquer forma, defina no .env:

DISABLE_HTTPS=True

Farinha atrás de outro proxy reverso

É comum a instituição colocar o Farinha atrás de outra camada de proxy reverso (por exemplo, um proxy na borda, um balanceador, um CDN ou um painel de proxy como o Nginx Proxy Manager). A topologia fica assim:

Proxy/CDN externo
    ↓
Proxy reverso intermediário
    ↓
Caddy (container do Farinha)
    ↓
Gunicorn/Django

Nesse cenário, é comum o proxy intermediário não repassar ao Caddy as informações necessárias para concluir a validação automática do certificado (por exemplo, o domínio no handshake TLS, também chamado de SNI). Sem conseguir o certificado público, o Caddy passa a apresentar um certificado interno, emitido pela própria autoridade local dele:

Issuer: Caddy Local Authority - ECC Intermediate
Subject Alternative Name: farinha.exemplo.org

Esse certificado é válido para o Caddy, mas não é reconhecido pelos proxys à frente nem pelos navegadores. O resultado costuma ser um destes sintomas:

  • erro de certificado inválido no proxy/CDN externo (por exemplo, 526 Invalid SSL Certificate no Cloudflare em modo estrito);
  • 502 Bad Gateway no proxy intermediário por não conseguir concluir a conexão HTTPS segura com o Caddy;
  • loop de redirecionamento: o proxy encaminha para a porta 80, o Caddy responde 308 Permanent Redirect para HTTPS, e o navegador fica alternando entre os dois.

O problema é o mesmo em qualquer proxy; a causa normalmente está em uma destas duas coisas:

  1. o proxy não envia o domínio no handshake TLS (SNI), então o Caddy não seleciona o certificado certo;
  2. o proxy tenta validar o certificado do Caddy e o rejeita, porque ele é o certificado interno.

Solução prática (exemplo com o Nginx Proxy Manager):

  1. No Proxy Host do domínio, em Details, aponte para o Farinha via HTTPS na porta do Caddy:

  2. Scheme: https

  3. Forward Hostname/IP: IP do container do Farinha (ex.: 10.0.0.14)
  4. Forward Port: 443

Isso evita o loop, porque o proxy deixa de bater na porta 80 (que sempre redireciona para HTTPS).

  1. Na aba SSL, mantenha o certificado do domínio e o Force SSL ativado.

  2. Na aba Advanced, envie o domínio no handshake e permita o certificado interno do upstream:

proxy_ssl_server_name on;
proxy_ssl_name farinha.exemplo.org;
proxy_ssl_verify off;
  • proxy_ssl_server_name on;: envia o SNI no handshake, permitindo que o Caddy selecione o certificado correto para o domínio;
  • proxy_ssl_name farinha.exemplo.org;: define qual domínio é enviado como SNI;
  • proxy_ssl_verify off;: aceita o certificado interno do Caddy no upstream.

Em outros proxys, procure as opções equivalentes: habilitar SNI/preservar o nome do host no upstream e desabilitar a verificação do certificado do upstream.

Atenção: desligar a verificação mantém a conexão criptografada, mas não valida a identidade do certificado do Caddy. É aceitável como solução provisória em rede interna/controlada.

  1. Só depois que o acesso direto estiver funcionando, retome o modo mais estrito no proxy/CDN externo (por exemplo, Completo (estrito) no Cloudflare).

Soluções definitivas (preferíveis ao verify off):

  • Certificado público no Caddy: configurar FARINHA_URL com o domínio e permitir que ele complete o desafio ACME, para que o Caddy apresente um certificado confiável e a verificação possa ser reativada.
  • Certificados próprios confiáveis: usar certificados de uma autoridade reconhecida pelos proxys (opção certs/).
  • Desabilitar o HTTPS no Farinha com DISABLE_HTTPS=True e apontar o proxy para http na porta 80 do container. Funciona, mas o trecho entre o proxy e o Farinha deixa de ser criptografado; avalie o risco no seu ambiente. Nesse caso, mantenha o HTTPS apenas na ponta (proxy/CDN).

Proteção contra bots (Anubis)

O Farinha pode usar o Anubis, um firewall que exige uma pequena prova de trabalho dos visitantes para barrar acessos automatizados (bots), reduzindo sobrecarga em picos de tráfego.

A proteção é controlada por duas configurações do aplicativo, no painel interno de administração (Django Admin):

  • Webapp -> Configurações do Aplicativo -> "Anubis habilitado?"
  • Webapp -> Configurações do Aplicativo -> "Dificuldade do Desafio Anubis" (Muito leve (1), Leve (3), Padrão (4) e Forte (10))

Lista de configurações do aplicativo com mapa e Anubis

As configurações do aplicativo incluem o mapa do portal e a proteção contra bots (Anubis).

Pontos importantes:

  • A mudança do Anubis (ligar/desligar ou dificuldade) tem efeito após reiniciar o Farinha. Ao salvar, o painel avisa sobre isso.
  • O run (scripts run.sh/run.bat) lê essas configurações do banco e as aplica na subida da instância.
  • A dificuldade "Padrão (4)" é um bom começo. Valores altos deixam o desafio mais pesado e podem incomodar usuários; valores muito baixos reduzem a proteção.
  • Se o desafio não aparecer para os visitantes, verifique se "Anubis habilitado?" está marcado e reinicie o Farinha.

Veja também: Portal.

Variáveis sensíveis do .env

O arquivo .env (criado a partir do .env-sample na primeira execução) concentra as configurações da instância. As mais relevantes para segurança:

  • FARINHA_URL: domínio(s) ou IP(s) de acesso, separados por vírgula (sem https://). Com um domínio público, o HTTPS é ativado automaticamente.
  • ADMIN_PATH: caminho do painel interno de administração. Padrão: admin/. Veja Usuário SuperAdmin.
  • SECRET_KEY: chave que protege dados sensíveis. É obrigatória: sem ela o Farinha não sobe. É gerada automaticamente pelo run.sh/run.bat; se você criar manualmente, não use o caractere $ (o Docker Compose o interpretaria como variável de ambiente).
  • SECURE_HSTS_SECONDS: HSTS. Mantenha 0 (desabilitado) até ter certeza de que o HTTPS funciona, porque o HSTS pode deixar o site inacessível se os certificados não estiverem corretos. Habilite somente se souber o que está fazendo.
  • SECURE_HSTS_INCLUDE_SUBDOMAINS: inclui subdomínios no HSTS.
  • SECURE_PROXY_SSL_HEADER e SECURE_PROXY_SSL_HEADER_VALUE: informam ao Django que a requisição original é segura quando há proxy na frente (já configurado por padrão para o Caddy).
  • SECURE_CONTENT_TYPE_NOSNIFF: impede que navegadores tentem adivinhar o tipo de arquivo.
  • DEBUG: em produção, mantenha False (é o padrão do .env-sample).
  • SQLITE_BUSY_TIMEOUT_MS: tempo de espera do banco quando estiver ocupado.

Cuidados:

  • Nunca publique o arquivo .env nem a SECRET_KEY (não envie por e-mail, chat ou issues).
  • Ao mudar variáveis, pare e suba a instância novamente (./down.sh && ./run.sh no Linux; .\down.bat e .\run.bat no Windows).

Boas práticas

  • Mantenha permissões restritas no .env; ele contém a SECRET_KEY.
  • Gere uma SECRET_KEY própria e exclusiva por instância (o run já faz isso automaticamente). Nunca reaproveite a chave de outra instalação.
  • Antes de ligar o HSTS (SECURE_HSTS_SECONDS), confirme que o HTTPS está funcionando em todos os domínios e subdomínios usados. O HSTS é difícil de reverter no lado do cliente.
  • Em produção, mantenha DEBUG=False.
  • Se trocar o caminho do painel com ADMIN_PATH, guarde o novo endereço com a equipe e evite caminhos óbvios como admin/ ou painel/.
  • Tenha cópia de segurança do banco (db/) e dos certificados próprios (certs/), se usar.
  • Ao usar outro proxy reverso na frente do Farinha, prefira a solução definitiva (certificado público ou próprio confiável) em vez de manter a verificação de certificado desligada no upstream por muito tempo.

Problemas comuns

  • O Farinha não sobe: verifique se a SECRET_KEY existe no .env e se contém $. O erro aparece nos logs do container.
  • Aviso de certificado inválido no navegador: pode ser o certificado interno do Caddy aparecendo porque o domínio não está configurado corretamente em FARINHA_URL, ou porque a validação automática não conseguiu ser concluída. Confira também a subseção de proxy acima.
  • Erro de certificado (526) ou 502 no proxy/CDN: veja a subseção Farinha atrás de outro proxy reverso; normalmente é o upstream HTTPS sem SNI e com verificação de certificado ligada.
  • Loop de redirecionamento: o proxy está apontando para a porta 80 do Caddy, que sempre redireciona para HTTPS. Use https na porta 443 ou desabilite o HTTPS no Farinha.
  • O desafio do Anubis não aparece: confirme se "Anubis habilitado?" está marcado nas Configurações do Aplicativo e reinicie o Farinha.
  • Mudei a configuração do Anubis e nada mudou: as alterações só valem após reiniciar o Farinha (o aviso aparece no painel ao salvar).
  • O desafio do Anubis atrapalha integrações internas: avalie desabilitar a proteção ou reduzir a dificuldade, lembrando do reinício necessário.