Guia de Boas Praticas de Desenvolvimento Seguro - ifpebj-ti/controle-acesso-veiculos GitHub Wiki

Guia de Boas Práticas de Desenvolvimento Seguro

Status: versão 1.1 sincronizada com os controles vigentes até o PR #309

Issue: #26

Este guia se aplica ao projeto completo: frontend, backend, banco, testes, containers, CI/CD, documentação e operação. A fonte versionada está em docs/security/secure-development-guide.md.

Fluxo de mudança

Vincular a mudança a uma Issue.
Criar branch com escopo claro.
Identificar dados, atores e fronteiras afetadas.
Implementar o menor escopo seguro.
Adicionar testes positivos e negativos.
Revisar diff, dependências, logs, migrations e documentação.
Exigir CI e revisão antes do merge.
Atualizar a modelagem de ameaças quando o desenho mudar.

Segredos

nunca versionar .env, senha, token, chave ou connection string real;
usar exemplos obviamente fictícios;
fornecer segredos por configuração segura do ambiente;
não incluir segredo em camada, ARG ou ENV de build Docker;
não imprimir configuração completa;
rotacionar imediatamente qualquer segredo exposto;
separar credenciais de aplicação, migration e administração em produção.

Privacidade

coletar somente dados com finalidade registrada;
manter documento opcional até validação institucional;
não usar dados pessoais reais em testes, seeds, imagens ou Issues;
não registrar documento completo em log;
restringir consulta e exportação;
validar retenção e descarte com os responsáveis institucionais.

Backend e API

tratar entrada HTTP como não confiável;
validar tipo, tamanho, formato, faixa e relação entre campos;
manter invariantes centrais no Domain;
não confiar somente no frontend;
negar acesso por padrão;
autorizar no servidor e no recurso solicitado;
limitar payload, paginação e tempo de execução;
não retornar stack trace, SQL, caminho ou configuração em produção;
usar correlation ID e contrato padronizado de erros;
não implementar criptografia própria.

Autenticação e autorização

utilizar contas individuais;
persistir somente hash de senha adequado;
impedir autenticação de usuário inativo;
aplicar políticas de menor privilégio;
proteger operações administrativas e auditoria;
testar permissão concedida e negada;
nunca registrar senha, token ou header de autorização.

A implementação pertence à Issue #29.

Banco e migrations

usar LINQ e queries parametrizadas;
manter constraints e mapeamentos na Infrastructure;
aplicar menor privilégio ao usuário PostgreSQL;
não expor o banco publicamente em produção;
não usar EnsureCreated com migrations;
não aplicar migration automaticamente no startup;
não editar migration já aplicada em ambiente compartilhado;
testar banco limpo, upgrade, downgrade e novo upgrade;
exigir backup antes de mudança de risco.

Backup e recuperação

tratar todo dump como dado confidencial;
manter dump e manifesto fora do Git e de canais pessoais;
verificar nome, tamanho e SHA-256 antes da restauração;
não tratar checksum como assinatura ou prova de origem;
restaurar somente em banco isolado por padrão;
manter criptografia, armazenamento protegido, acesso, retenção e responsáveis como decisões explícitas da Issue #30.

Logs e auditoria

Estado atual: a Issue #49 implementou correlation ID, respostas seguras em ProblemDetails, limite global de 1 MiB e logs HTTP com método, template de rota, status e duração, sem query string, corpo, credencial ou valores da URL. As Issues #51, #53, #55 e #57 adicionaram auditoria transacional aos fluxos geral e institucional e aos cadastros da frota e de motoristas, com falha fechada, atribuição ao operador e minimização de dados. Auditoria dos demais casos de uso, privilégios separados e observabilidade externa permanecem pendentes.

diferenciar log técnico de auditoria de negócio;
usar horário UTC e correlation ID;
não registrar segredo, token, connection string ou documento completo;
registrar usuário e mudança necessários à rastreabilidade;
definir o comportamento quando a auditoria falhar;
restringir acesso e retenção de logs.

Frontend

não considerar botão oculto como autorização;
não embutir segredo no bundle;
evitar renderização de HTML não confiável;
não persistir token ou dado pessoal sem decisão explícita;
não expor detalhe interno em mensagens;
manter dependências bloqueadas e auditadas;
configurar headers de segurança na implantação.

Containers e CI/CD

usar builds em múltiplos estágios;
copiar somente os artefatos necessários;
executar como usuário não privilegiado;
manter .dockerignore;
controlar e atualizar versões de imagens;
separar liveness de readiness;
analisar vulnerabilidades;
usar instalação determinística;
limitar permissões de workflows;
não disponibilizar segredo a código não confiável.

O hardening pertence à Issue #25.

Testes mínimos

entradas inválidas e limites;
autenticação válida, inválida, bloqueada e inativa;
autorização permitida e negada;
ausência de dado sensível em resposta e log;
constraints no PostgreSQL real;
migrations e recuperação;
indisponibilidade de dependências;
build e execução de containers;
auditoria de operações relevantes.

EF InMemory não substitui integração com PostgreSQL.

Checklist de Pull Request

Issue e riscos relacionados;
nenhum segredo ou dado pessoal real;
validação no servidor;
autorização no recurso/operação;
erros seguros;
logs e auditoria revisados;
dependências justificadas e auditadas;
migrations e rollback testados;
testes negativos incluídos;
CI aprovada;
README, Wiki e ameaças atualizados.

Vulnerabilidade ou incidente

Evitar divulgação pública explorável antes da contenção.
Preservar evidências e versões afetadas.
Revogar ou rotacionar segredos possivelmente expostos.
Conter o componente.
Corrigir e validar regressões.
Comunicar os responsáveis institucionais.
Registrar causa, impacto, recuperação e prevenção.