Um registro de segurança serve para reconstruir quem tentou fazer o quê, em qual recurso, quando e com qual resultado. Não é uma cópia de todas as solicitações nem um despejo de exceções. Seu objetivo é fornecer evidências úteis para investigar acessos e ações suspeitas, com o mínimo de dados necessário e controles que evitem que o próprio registro se torne uma fonte de exposição.
Para projetar o logging de segurança em PHP, convém primeiro definir os eventos importantes e o uso que terão: detecção, investigação, auditoria operacional ou conformidade com uma política interna. Em seguida, estabelece-se um formato comum, decide-se quem pode consultar os registros e testa-se o fluxo completo. Um log que existe, mas não permite ordenar eventos, identificar o resultado ou distinguir tentativas de ações concluídas, não atende à necessidade de investigação.
Separar logs técnicos, atividade e eventos de segurança
Os logs técnicos descrevem o funcionamento da aplicação: erros, exceções, latência, falhas de conexão ou problemas de configuração. Ajudam a diagnosticar disponibilidade e comportamento. O registro de atividade documenta ações de negócio atribuíveis a usuários, como editar uma fatura ou alterar os dados de uma conta. Já os eventos de segurança se concentram em fatos relevantes para proteger identidades, permissões, recursos e limites de acesso.
Há interseções, mas as categorias não são intercambiáveis. Uma alteração de função pode ser uma atividade de negócio e um evento de segurança; uma exceção de banco de dados costuma ser técnica, embora uma sequência de falhas em uma operação sensível possa justificar um alerta de segurança. Definir os propósitos evita duplicar informações sem critério e permite atribuir políticas adequadas de retenção, acesso e formato.
Não use o log de segurança como um repositório de auditoria ilimitado nem como substituto de métricas e traces. Tampouco presuma que registrar um evento equivale a detectá-lo: para gerar alertas, são necessárias regras, limites e responsáveis pela resposta. Documente qual sistema produz cada dado e qual equipe o utiliza.
Escolher ações e contexto que permitam investigar
Comece por um inventário de ações e ameaças relevantes para a aplicação. Entre os eventos que costumam exigir consideração estão tentativas de login malsucedidas, bloqueios de conta, alterações de credenciais, concessões ou revogações de permissões, alterações de configuração, exportações sensíveis e operações administrativas. A lista deve refletir o produto: registrar cada leitura de uma página pode gerar ruído, enquanto omitir uma alteração de privilégios impede reconstruir um acesso indevido.
Para cada evento, defina qual pergunta deve ser possível responder. Se estiver investigando uma alteração de permissão, por exemplo, é importante identificar o ator, o usuário ou recurso afetado, a permissão anterior e a nova, o resultado e o momento. Em uma autenticação malsucedida, pode ser relevante o identificador de conta normalizado ou pseudonimizado, conforme a política, além do resultado e da origem da solicitação, se a coleta for justificada. Evite inferir uma identidade com base em um endereço IP compartilhado.
Distinga tentativa, decisão e resultado. Uma solicitação negada não é uma alteração concluída; uma solicitação aceita pode falhar antes de ser persistida. Registre o resultado real e, quando necessário para a investigação, a etapa alcançada. Defina também o significado de cada valor, como denied, failed ou succeeded, para que diferentes componentes não os usem de maneira contraditória.
Usar um esquema consistente e correlacionável
Um formato estruturado, normalmente JSON, facilita filtrar e correlacionar eventos em ferramentas operacionais. Como base, considere estes campos:
- Identificador do evento: nome estável e versionado, por exemplo
authorization.permission_changed. - Momento: data e hora em UTC, com precisão adequada e relógios dos sistemas sincronizados.
- Ator: identificador interno ou pseudônimo; represente explicitamente processos e tarefas automatizadas.
- Ação e recurso: operação realizada e tipo e identificador do recurso afetado, sem incluir seu conteúdo.
- Resultado: sucesso, rejeição ou falha, com um motivo categorizado e não sensível.
- Correlação: identificador de solicitação ou operação para relacionar eventos sem despejar a solicitação inteira.
- Origem contextual: serviço ou componente que emitiu o evento e, se justificado, dados limitados da origem da rede.
Os nomes e tipos dos campos devem permanecer estáveis. Uma correlação de solicitação precisa ser gerada ou validada pela infraestrutura; aceitar sem controle um identificador arbitrário pode permitir colisões ou confusão. Não inclua cabeçalhos completos, corpos HTTP nem parâmetros indiscriminadamente. O contexto deve ajudar a reconstruir a sequência, não replicar todos os dados processados.
Excluir segredos e minimizar dados pessoais
Nunca registre senhas, tokens de acesso, chaves de API, segredos de sessão, códigos de recuperação nem valores que permitam autenticação. Evite também dados pessoais completos quando um identificador interno for suficiente. Para campos como e-mail, telefone ou endereço, decida se é imprescindível armazená-los, se podem ser mascarados ou se convém usar uma referência pseudonimizada. A decisão depende do propósito, do risco e das obrigações aplicáveis.
A sanitização deve ocorrer antes de o evento sair do processo; não confie apenas em um filtro posterior do agregador. Em PHP, evite serializar diretamente objetos de solicitação, cabeçalhos ou exceções que possam conter valores sensíveis. Crie um objeto ou array explícito com uma lista permitida de campos; uma estratégia de lista de bloqueio é frágil quando surgem campos novos. Valide e limite também o comprimento de valores controláveis pelo usuário para reduzir injeção de linhas, ruído e consumo excessivo.
Teste casos em que os dados secretos aparecem em parâmetros ou mensagens de erro e verifique se não chegam ao destino dos logs. A sanitização deve preservar informações suficientes para investigar, por exemplo, uma categoria de erro, sem guardar a mensagem completa se ela puder incluir credenciais.
Proteger acesso, integridade e ciclo de vida
Os registros também contêm informações sensíveis. Restrinja quem pode gravar, ler, exportar e administrar a retenção; essas funções podem exigir permissões distintas. Proteja o transporte e o armazenamento com os controles apropriados para a infraestrutura e evite que uma conta comprometida da aplicação possa apagar ou alterar todo o histórico sem deixar rastros. Quando o risco justificar, use armazenamento append-only ou controles de integridade verificáveis e documente seus limites.
Defina uma política de retenção explícita por classe de evento. Conservar os dados indefinidamente aumenta a exposição e o custo; eliminá-los cedo demais pode prejudicar uma investigação. A política deve contemplar cópias, exportações, ambientes de teste e solicitações de exclusão que afetem dados pessoais. Registre e revise o acesso dos operadores aos próprios logs, especialmente exportações ou alterações de política.
O logging pode falhar devido à indisponibilidade do destino, a limites de armazenamento ou a erros de serialização. Decida o que acontece em cada caso conforme a criticidade. Não transforme uma indisponibilidade do sistema de logs em uma forma de concluir silenciosamente uma operação de alto risco, mas também não permita que uma exceção de logging provoque resultados inconsistentes ou duplique uma transação. Para operações críticas, pode ser necessário garantir a gravação do evento junto com a alteração por meio de uma estratégia transacional, como o padrão outbox. Se uma fila for usada, defina novas tentativas, deduplicação e tratamento de eventos pendentes.
Testar se o evento existe e é seguro
Os testes devem verificar mais do que uma chamada a uma função de logging. Percorra cenários representativos: acesso negado, privilégio concedido, privilégio revogado e alteração sensível concluída ou malsucedida. Verifique se o evento inclui ator, recurso, resultado, momento e correlação; se o resultado corresponde ao que realmente aconteceu; e se não aparecem senhas, tokens ou dados desnecessários.
Inclua testes de falhas do destino dos logs e observe se a operação principal permanece em um estado consistente, se um sinal alternativo é gerado e se o erro fica visível para a equipe de operações. Em uma ação sensível, confirme que não há indicação de sucesso se a alteração não foi persistida. Teste também limites e entradas manipuladas, como quebras de linha em valores controláveis, e a leitura por função: um usuário de negócio não deveria ter acesso por padrão ao repositório de eventos.
Lista de verificação para revisar uma implementação
- Cada evento tem um propósito, um responsável e uma política de retenção definidos?
- Tentativas, rejeições, falhas e operações concluídas são diferenciadas?
- O esquema permite identificar ator, ação, recurso, resultado e momento?
- Há correlação com a solicitação sem registrar todo o seu conteúdo?
- Segredos são excluídos e os dados pessoais são minimizados antes do envio?
- O acesso, o transporte, o armazenamento e a exclusão são controlados?
- Foram testados a indisponibilidade do destino, a integridade da operação e as permissões de leitura?
Priorize primeiro os eventos que protegem contas, privilégios e operações de maior impacto. Depois, padronize o esquema, limite os dados e automatize testes que falhem se um segredo entrar nos logs. Assim, o logging de segurança em PHP fornece evidências acionáveis sem se tornar um segundo banco de dados de informações sensíveis.
