Boas Práticas de Segurança

O PrimeForge nasce com segurança como princípio: comunicação criptografada de ponta a ponta, serviços isolados por site, firewall configurado no provisionamento e endurecimento (hardening) automático de cada servidor. Ainda assim, boa parte da segurança está em como você opera o painel — quem tem acesso, como as credenciais são tratadas e o que fazer quando algo dá errado. Este guia é conceitual: reúne as práticas que mantêm a sua infraestrutura e as suas aplicações seguras. Não é uma tela específica do painel; cada seção aponta para as páginas onde as ações concretas acontecem.

#Higiene de credenciais e a conta inicial (bootstrap)

#A conta inicial

Numa instalação nova, o PrimeForge cria uma conta de administrador inicial (bootstrap) só para você ter por onde entrar. Essa conta pode ter uma senha padrão conhecida.

• Troque a senha da conta inicial imediatamente no primeiro login. Uma senha padrão é, por definição, pública — qualquer pessoa que encontre a instalação pode assumir o controle se você não trocá-la.
• Ative a autenticação em dois fatores na mesma hora (veja 2FA obrigatório abaixo).
• Depois de configurada a sua conta real, evite continuar usando credenciais genéricas.

#Credenciais únicas por site

O PrimeForge gera credenciais exclusivas para cada site, automaticamente — e essa é uma proteção que você não deve desfazer:

• Senhas de banco de dados — strings longas (32+ caracteres), únicas por site.
• Chaves de acesso do MinIO/S3 — chaves por site, com políticas IAM restritas ao bucket daquele site.
• Chaves do Reverb e APP_KEY do Laravel — únicas por site.
• Segredo do webhook de auto-deploy — 64 caracteres aleatórios por site, usado para verificar as entregas do GitHub.

Nunca substitua essas credenciais por valores compartilhados entre sites. Reaproveitar a mesma senha em vários sites significa que um único site comprometido expõe todos os outros. O PrimeForge já cria usuários de banco separados por site, cada um restrito ao seu próprio banco — não edite pg_hba.conf nem tabelas de permissão manualmente.

#Higiene de segredos

• Nunca comite segredos no Git. O seu arquivo .env é gerado e gerenciado pelo PrimeForge — ele nunca vai para o seu repositório. Use o Editor de Ambiente do painel para todas as variáveis.
• Mantenha APP_DEBUG=false e APP_ENV=production em produção. O modo debug vaza rastros de pilha, variáveis de ambiente e credenciais em respostas de erro. O PrimeForge já define isso automaticamente; confira após qualquer edição manual do .env.
• Rotacione credenciais periodicamente. As senhas geradas já são fortes, mas rotacioná-las de tempos em tempos é boa prática — atualize no Editor de Ambiente e faça um novo deploy.
• Rotacione o segredo do webhook de auto-deploy se a URL vazar. Se a URL do webhook aparecer num chat, num commit ou nos logs de CI, use a ação Rotacionar segredo em Site → Configurações → Serviços → Auto Deploy. A URL antiga para de funcionar imediatamente; hooks registrados pelo PrimeForge no GitHub são re-registrados sozinhos com a nova URL.

As credenciais de acesso (chaves SSH, provedores Git, registries de pacotes) são administradas centralmente na área de Credenciais.

#RBAC e o princípio do menor privilégio

O PrimeForge usa quatro papéis em hierarquia — Owner (4) > Admin (3) > Developer (2) > Viewer (1) — para controlar o acesso. A regra de ouro é o princípio do menor privilégio: cada pessoa recebe o menor nível que ainda permite fazer o seu trabalho.

Boas práticas:

• Minimize as contas Owner. Apenas quem criou a organização precisa ser Owner. Todos os outros devem ser Admin ou abaixo.
• Use Developer para automação (CI/CD). Se você cria API Keys para deploys automáticos, gere-as a partir de uma conta Developer — nunca Admin ou Owner.
• Use Viewer para quem só precisa enxergar — gerentes, clientes e stakeholders que precisam de visibilidade, mas não de controle.
• Revise os papéis com frequência. Quando alguém muda de função, ajuste o papel; quando sai, remova a conta imediatamente.

Os convites e a gestão de papéis ficam em Equipe e Conta.

#Segurança de rede e a malha WireGuard

#Firewall (UFW)

O PrimeForge configura o UFW em cada servidor provisionado com a política negar tudo na entrada, permitir na saída. Só as portas essenciais ficam abertas, e quais delas dependem do que o servidor roda:

As portas dos serviços de infraestrutura (PostgreSQL, MySQL, Redis, MinIO) não ficam expostas na internet: só são acessíveis pela sub-rede do Docker e pela malha WireGuard. O provisionamento também instala fail2ban e as atualizações de segurança automáticas. Não abra portas adicionais a menos que seja absolutamente necessário — cada porta aberta é um vetor de ataque.

#HTTPS em todo lugar

O PrimeForge provisiona certificados TLS automaticamente via Let's Encrypt através do Traefik. Todo site tem HTTPS por padrão, com renovação automática antes do vencimento, TLS 1.2+ obrigatório e cabeçalhos HSTS. Nunca desative o TLS nem use certificados autoassinados em produção.

#A malha WireGuard (rede privada entre servidores)

Quando você tem mais de um servidor, o PrimeForge os conecta por uma malha WireGuard — uma rede privada criptografada (ChaCha20-Poly1305) por onde passa todo o tráfego entre servidores:

• consultas de banco entre um App Server e o servidor de banco;
• comandos de Redis entre servidores;
• uploads S3 para o servidor de armazenamento;
• conexões WebSocket do Reverb entre os sites e o servidor Reverb.

Nenhuma camada extra de VPN é necessária. As chaves do WireGuard são por servidor, então comprometer um servidor não expõe as chaves dos outros. Cada servidor gerenciado fica isolado: roda apenas os containers dos seus sites e o Agent do PrimeForge, e as credenciais de banco são restritas por site — um site não acessa os dados de outro.

#Assinatura de webhooks (HMAC)

O PrimeForge pode enviar notificações para endpoints externos (Slack, Discord, sua própria API) quando algo acontece — servidor offline, deploy com falha, disco cheio, Modo de Pânico ativado, etc. Para que o seu receptor tenha certeza de que a requisição veio mesmo do PrimeForge (e não de um atacante que descobriu a sua URL), o painel assina cada entrega com HMAC-SHA256 sempre que você configura um segredo.

Quando há segredo, cada entrega carrega o cabeçalho X-PrimeForge-Signature: sha256=<hex>, que é o HMAC-SHA256 calculado sobre o corpo bruto (raw body) da requisição. O seu receptor recalcula o HMAC com o mesmo segredo e compara — em tempo constante — com o valor recebido:

$secret = getenv('PRIMEFORGE_WEBHOOK_SECRET');
$body = file_get_contents('php://input');            // corpo BRUTO, antes de qualquer parser
$received = $_SERVER['HTTP_X_PRIMEFORGE_SIGNATURE'] ?? '';
$expected = 'sha256='.hash_hmac('sha256', $body, $secret);

if (! hash_equals($expected, $received)) {           // comparação em tempo constante
    http_response_code(401);
    exit('assinatura inválida');
}

Dois cuidados importantes:

• Calcule o HMAC sobre os bytes brutos, antes de qualquer parser de JSON tocar no corpo. Hashear o JSON já reserializado é a causa nº 1 de "copiei o segredo certo e mesmo assim dá 401".
• Cada regra/endpoint tem o seu próprio segredo. Comprometer um segredo não permite forjar entregas de outro. Rotacione editando a regra e informando um novo segredo.

O PrimeForge também tem uma proteção anti-SSRF: ele se recusa a entregar para URLs que resolvem para IPs privados/reservados (RFC 1918, loopback, link-local). Se você precisa alcançar um serviço interno, exponha-o por um ingresso público (Cloudflare Tunnel, ngrok, um proxy reverso) que valide a assinatura e encaminhe.

#Auditoria de SSH

O acesso SSH do painel aos seus servidores é justamente o que mais importa quando algo já deu errado — atualizações de Agent, reinstalações e rollbacks de emergência dependem dele. Por isso o PrimeForge audita esse acesso de forma proativa:

• Uma auditoria semanal tenta uma conexão SSH inofensiva (um echo ok) a cada servidor de que o painel tem coordenadas SSH.
• Sempre que todos os métodos de autenticação SSH falham em um servidor — seja na auditoria, seja em uma operação real — o PrimeForge dispara uma notificação server.ssh_auth_failed (severidade de aviso, no máximo uma vez a cada 6 horas por servidor) e mantém um alerta visível até o SSH voltar a funcionar.

Se você receber esse alerta, verifique a chave de provisionamento da organização e as credenciais SSH do servidor. O canal do Agent não é afetado (o Agent conecta para fora, em direção ao painel), então o dia a dia continua funcionando — mas conserte o SSH logo, porque ele é o caminho de recuperação de último recurso.

Gerencie sempre as chaves SSH pelo painel, na área de Credenciais, e nunca adicionando-as direto no servidor. Isso garante o registro no log de auditoria e permite a revogação centralizada: ao excluir uma chave, o authorized_keys de todos os servidores é reescrito em paralelo, em segundos.

#2FA obrigatório

A autenticação em dois fatores (2FA) por aplicativo autenticador (TOTP) deve ser tratada como obrigatória para toda conta com acesso ao painel — não como um extra opcional. Com o 2FA ligado, uma senha vazada, sozinha, não abre o painel: o login exige também um código de seis dígitos que muda a cada 30 segundos.

Cada usuário ativa o 2FA em Configurações → Segurança, escaneando o QR Code no seu aplicativo autenticador e guardando os códigos de recuperação em local seguro. O passo a passo completo está em Equipe e Conta. Como política de equipe, exija que todo novo membro ative o 2FA logo no primeiro acesso.

#Resposta a incidentes

Se você suspeitar de um incidente de segurança — acesso indevido, comportamento estranho de um site, credenciais possivelmente vazadas — aja rápido e em ordem.

#Modo de Pânico como kill-switch

O Modo de Pânico é a sua primeira reação. Ele bloqueia o tráfego de um site na camada de rede (Traefik/nginx) em menos de 1 segundo, exibindo uma página de manutenção, sem parar os containers — ou seja, você contém o incidente imediatamente e ainda investiga a aplicação com ela de pé. Ative-o nos sites afetados assim que desconfiar de algo. Detalhes em Modo de Pânico.

#Checklist de resposta

1. Ative o Modo de Pânico nos sites afetados para conter o tráfego na hora.
2. Abra Segurança → Logs → Incidentes para ver a linha do tempo unificada de alertas e ativações de pânico.
3. Revise o Log de Auditoria em busca de ações não autorizadas (deploys, edições de ambiente, mudanças de servidor).
4. Rotacione credenciais — senhas de banco, API Keys, APP_KEY, segredos de webhook.
5. Revise as chaves SSH — remova qualquer chave desconhecida (a revogação se propaga a todos os servidores em segundos).
6. Confira as métricas e as sondas HTTP dos servidores — padrões incomuns de CPU ou respostas 5xx inesperadas podem indicar comprometimento.
7. Avise a equipe — garanta que todos estão cientes e ninguém está sob engenharia social.
8. Atualize e aplique patches — confirme que todos os servidores estão com as atualizações de segurança em dia.

O isolamento por site do PrimeForge significa que um site comprometido não dá acesso automático aos outros sites nem ao painel. A resposta a incidentes é, na prática, conter um site, investigar e rotacionar — não recomeçar tudo do zero.

#Próximos passos

• Modo de Pânico — o kill-switch de emergência em detalhe.
• Equipe e Conta — papéis, 2FA e gestão da equipe.
• Credenciais — chaves SSH, provedores Git e registries de pacotes.
• Solução de Problemas — referência de sintomas e correções.