Auditoria da estrutura e qualidade de engenharia do HDT-AF¶
Data: 23 de outubro de 2026 Escopo: arquitetura, dependências, qualidade estática, segurança, configuração e prontidão operacional. Tipo: auditoria estática com compilação de produção; não é pentest nem aceite de produção.
Resumo executivo¶
O HDT-AF tem uma base modular adequada para um MVP de pesquisa: há separação de módulos, grafo Maven acíclico e portas/fábricas em alguns pontos. A compilação de produção passou após a restauração das fontes. O projeto, porém, ainda não está pronto para produção: há configuração que permite falha silenciosa do Fabric, estado de contrato/consentimento mantido em objetos locais, agregação segura declarativa sem implementação e ruído de privacidade diferencial com semente previsível. Classes muito grandes, forte acoplamento de experimentos com a API administrativa e documentação contraditória também elevam o custo de manutenção.
Conclusão por área¶
| Área | Avaliação |
|---|---|
| Organização modular e direção das dependências | Boa base: 24 módulos e nenhum ciclo encontrado |
| Separação de responsabilidades | Precisa de refatoração: servidor HTTP e serviço administrativo concentram lógica |
| Persistência/governança Fabric | Não conforme ao requisito de Fabric como único armazenamento permanente |
| Privacidade/agregação | Risco alto: DP previsível e secure aggregation não implementada |
| Build de produção | Passou com testes ignorados |
| Testes, cobertura, SCA | Não verificados nesta auditoria |
| Documentação/configuração | Inconsistentes com o código atual |
Metodologia¶
- Li as instruções em .agents, o índice de documentação e o POM raiz.
- Executei sh scripts/compile.sh; o script usa Maven com -DskipTests, portanto esta validação confirma build/empacotamento, não os testes.
- Li os POMs, construí o grafo de dependências internas e procurei ciclos.
- Medi fontes de produção por módulo e tamanho de arquivo, excluindo saídas de build e comparando a distribuição dentro do próprio repositório.
- Analisei os relatórios Checkstyle e SpotBugs do reator Maven, contando apenas os 24 módulos declarados no POM raiz. Relatórios de benchmarks de pesquisa que recompilam fontes compartilhadas foram excluídos para evitar dupla contagem; severidade do analisador não foi tratada como vulnerabilidade confirmada.
- Consultei a árvore de dependências e as versões disponíveis com o Versions Maven Plugin.
- Comparei código, variáveis de ambiente, regras compartilhadas e documentação de Fabric, privacidade e publicação de experimentos.
- Não alterei código de produção nem executei a suíte de testes. Não encontrei ferramentas locais SCA, de complexidade por método ou clone detection.
Pontos positivos¶
- O reator separa módulos de dados, SDK, cliente, orquestração, agregação, artefatos, MQTT, Fabric, API e experimentos.
- O grafo Maven não contém ciclos.
- LedgerPort, MqttGateway e ExperimentSessionFactory oferecem alguns pontos de substituição e teste.
- DataComponent está definido como fronteira local para acesso aos dados de treinamento.
- O código de experimento implantado executa em processo separado da JVM do monitor.
- Checkstyle, SpotBugs e JaCoCo já estão configurados.
Achados críticos¶
1. Falhas do Fabric ainda podem ser toleradas¶
FabricGatewayConfig.fromEnvironment aceita FABRIC_FAIL_ON_ERROR=false mesmo no modo blockchain. .env e .env.example definem essa variável como false. FabricGatewayLedgerMirror pode então registrar a falha e devolver sem bloquear o fluxo. Isso contradiz a regra de falhar fechado e permite continuar sem confirmação de commit.
Evidência: modules/federated-rest-api/src/main/java/br/ufma/lsdi/admin/FabricGatewayConfig.java:31-33; FabricGatewayLedgerMirror.java:141-159; .env:71; .env.example:73.
Recomendação: remover a tolerância em produção ou rejeitar false no bootstrap. Confirmar a operação somente após confirmação de commit Fabric e cobrir a falha com teste de integração.
2. Contrato e consentimento têm estado local no bootstrap principal¶
O bootstrap instancia ExperimentContractChaincode e ClientConsentChaincode locais; somente FederatedExperimentChaincode recebe FabricGatewayLedgerMirror. Esse estado pode desaparecer no reinício e não constitui persistência permanente no Fabric.
Evidência: modules/federated-rest-api/src/main/java/br/ufma/lsdi/admin/AdminApplicationBootstrap.java:171-188; pendências BL-298/BL-299.
Recomendação: encaminhar contrato e consentimento a contratos/adaptadores Fabric em produção. Manter simuladores em memória apenas em testes e definir leitura, idempotência, confirmação e recuperação pelo ledger.
3. Secure aggregation aparece como configuração, mas não está implementada¶
PrivacyPolicy e a interface de criação oferecem secureAggregationEnabled/secureAggregation, mas não foi encontrada implementação correspondente no agregador. As estratégias consomem vetores individuais de ClientUpdateMessage. A própria documentação LGPD lista a função como não implementada. Um contrato marcado como seguro pode criar uma falsa expectativa.
Evidência: modules/federated-common/src/main/java/br/ufma/lsdi/common/model/PrivacyPolicy.java; modules/federated-rest-api/src/main/java/br/ufma/lsdi/admin/ExperimentContractFactory.java:304; modules/federated-aggregator/src/main/java/br/ufma/lsdi/aggregator/FedAvgAggregationStrategyImpl.java:77-83; docs/lgpd.md:422.
Recomendação: rejeitar a opção ligada até existir protocolo real. A implementação precisa definir troca de chaves, mascaramento, abandono de clientes, limiar e modelo de ameaça, com testes multi-cliente.
4. Semente de privacidade diferencial é previsível¶
O cliente deriva a semente por Objects.hash(experimentId, roundId, clientId) e o ruído usa java.util.Random(seed). Conhecendo os identificadores do protocolo, pode-se reconstruir o ruído; assim, a alegação de DP não deve ser considerada garantida.
Evidência: modules/federated-client/src/main/java/br/ufma/lsdi/client/FederatedClientService.java:410-416 e 189-191; modules/federated-local-cdm/src/main/java/br/ufma/lsdi/localcdm/DifferentialPrivacyMath.java:117-123.
Recomendação: usar fonte criptograficamente segura e imprevisível no cliente, sem derivar semente de identificadores. Especificar orçamento acumulado por participante (ε, δ), composição entre rodadas e proveniência antes de anunciar DP como proteção efetiva.
Achados altos¶
5. Configuração .env incompatível¶
LedgerMode aceita somente blockchain/fabric, mas .env contém FEDERATED_LEDGER_MODE=hybrid; carregar esse valor lança IllegalArgumentException. Corrigir apenas o modo não resolve o achado 1, pois FABRIC_FAIL_ON_ERROR continua false.
Evidência: modules/federated-rest-api/src/main/java/br/ufma/lsdi/admin/LedgerMode.java:14-33; .env:10; .env.example:10.
6. Arquivos administrativos muito grandes¶
AdminWebServer.java tem 7.526 linhas e AdminMonitoringService.java tem 2.384. O módulo federated-rest-api totaliza 18.279 linhas, contra mediana de 1.336 linhas por módulo. O servidor concentra rotas, HTML, serialização e regras de endpoint.
Recomendação: decompor gradualmente em roteadores/controladores, validadores, renderizadores, serviços de aplicação e adaptadores. Usar testes de caracterização para preservar contratos HTTP.
7. Experimentos dependem da API administrativa¶
Os POMs de ECG, MIMIC, MNIST e smoke dependem diretamente de federated-rest-api. Módulos de experimento declaram 14–16 dependências internas. Isso reduz a independência de plugins e acopla experimento ao monitor.
Recomendação: depender de interfaces estreitas no federated-experiment-sdk e deixar o monitor compor os adaptadores.
8. Endpoint de upload não tem autenticação própria¶
A documentação e ExperimentDeploymentService confirmam que o endpoint de implantação não autentica a própria chamada. O processo separado protege a JVM do monitor, mas não impede execução de código ou consumo excessivo de recursos no servidor.
Evidência: modules/federated-rest-api/src/main/java/br/ufma/lsdi/admin/ExperimentDeploymentService.java:35-45; docs/tutorial-create-experiment.md, seção 3.3.
Recomendação: autenticação/autorização, assinatura de pacotes, quotas, isolamento por usuário/container e auditoria.
9. Estado do Git impede uma restauração segura¶
Há muitas mudanças mistas no index e no diretório de trabalho; fontes restauradas aparecem como exclusões staged e arquivos não rastreados. Não há remote configurado. Um commit sem revisar/reindexar pode perpetuar as exclusões.
Recomendação: criar checkpoint, reconciliar index, adicionar fontes de forma seletiva e validar em checkout limpo antes de sincronizar com o servidor.
Achados médios¶
10. Documentação e instruções contradizem o código¶
O contexto ainda menciona modos memory/hybrid, enquanto as regras compartilhadas e LedgerMode só aceitam blockchain. Há trechos antigos da documentação Fabric sobre modo híbrido. AGENTS.md e docs/README.md apontam para agent/, mas a pasta existente é .agents/.
Recomendação: consolidar a regra e corrigir links; incluir verificação automática de links internos.
11. Análise estática mostra dívida¶
Na auditoria inicial, relatórios incluídos de benchmarks recompilavam fontes compartilhadas e inflavam os totais. Após correção e nova execução em 23/10/2026, os relatórios dos 24 módulos (17 relatórios disponíveis) mostram 0 violações Checkstyle e 261 achados SpotBugs (1 prioridade 1, 260 prioridade 2). Os maiores grupos são EI_EXPOSE_REP2 (105), EI_EXPOSE_REP (96) e NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE (20). EI_EXPOSE requer análise por classe; nesta rodada foram corrigidos os casos em AggregationReport, ClientUpdate e RoundConfig, que permitiam alteração externa de vetores ou mapas. Os achados restantes não foram assumidos como bugs confirmados.
O alerta de prioridade 1 restante é DMI_RANDOM_USED_ONLY_ONCE em HarCentralizedExperimentApp.shufflePair, onde Random(seed) fornece shuffle determinístico para benchmark. É um alerta compatível com o requisito de reprodutibilidade e não é o gerador do ruído DP. SpotBugs também informa falta de dependências externas no classpath em alguns módulos (Paho, Jackson, Fabric Gateway/gRPC); a análise deve ser repetida com classpath completo antes de classificar os 261 itens como defeitos ou falsos positivos.
A contagem divulgada inicialmente (398/422) misturava saídas antigas e relatórios repetidos de benchmark. A métrica reproduzível foi corrigida para contar somente os módulos declarados no POM raiz; a contagem atual é 0/261. A revisão também confirmou que o caminho DP ainda deriva semente previsível de IDs e usa java.util.Random; esse risco funcional está no achado 4 e não se resolve com supressão do aviso DMI do benchmark.
Recomendação: revisar primeiro encapsulamento de vetores e chamadas DP; depois ativar gates em etapas, iniciando por código novo.
12. Build não é reproduzível em ambiente limpo¶
Maven avisa que maven-jar-plugin não tem versão fixada em federated-common e federated-containers. O Versions Plugin informa que não existe versão mínima de Maven definida. Não encontrei Maven Wrapper na raiz nem workflows em .github/workflows. O script depende de Maven instalado localmente.
Recomendação: adicionar Maven Wrapper e Enforcer, fixar versões de plugins e CI para build, testes, análise estática e relatórios.
13. Atualizações exigem compatibilidade planejada¶
Na consulta de 23/10/2026, o Versions Plugin indicou Jackson 2.17.2→2.22.4, Fabric Gateway 1.11.0→1.13.0, JUnit 5.10.2→6.1.3, Testcontainers 1.19.8→2.0.5 e Logback 1.5.6→1.6.5. A árvore também mostra convergência transitiva protobuf 3.25.8→4.34.1 e gRPC 1.68.0→1.81.0. Isso não prova defeito; atualize separadamente e valide compatibilidade. Não adote SLF4J 2.1.0-alpha.
Plano de ação¶
- Tornar escritas Fabric fail-closed e mover contrato/consentimento ao ledger.
- Bloquear flag de secure aggregation enquanto não houver implementação e rever a alegação DP/geração do ruído.
- Proteger o endpoint de implantação e validar a rede Fabric de staging antes de publicar.
- Fazer checkpoint e reconciliar o index com as fontes restauradas.
- Reduzir as classes administrativas e dependências dos experimentos na API.
- Alinhar documentação, adicionar CI/Wrapper/Enforcer e ativar análise estática gradualmente.
- Integrar ferramenta SCA e atualizar dependências em mudanças controladas.
Mudanças e verificações desta sequência¶
- Restaurei 587 fontes Java ausentes da cópia no Google Drive. Os hashes coincidem; preservei dois arquivos exclusivos do checkout e quatro fontes existentes com conteúdo divergente.
- sh scripts/compile.sh terminou em BUILD SUCCESS; esse comando usa -DskipTests. A suíte não foi executada.
- Criei docs/analysis/collect-metrics.py para reproduzir métricas do reator, fontes, ciclos e relatórios de análise estática.
- Esta auditoria não mudou comportamento de produção nem implementou as recomendações.
- O Fabric remoto não foi rechecado agora. A última verificação desta conversa, de 22/10/2026, encontrou os containers parados; isso é contexto anterior, não status atualizado.
Apêndice A — métricas reproduzíveis¶
| Medida | Resultado | Comando |
|---|---|---|
| Módulos / declarações internas / ciclos | 24 / 174 / 0 | python3 docs/analysis/collect-metrics.py |
| Fontes Java de produção / LOC | 320 / 55.648 | python3 docs/analysis/collect-metrics.py |
| Mediana LOC por módulo | 1.336 | python3 docs/analysis/collect-metrics.py |
| Maior módulo | federated-rest-api: 57 fontes / 18.279 LOC | python3 docs/analysis/collect-metrics.py |
| Maiores arquivos | AdminWebServer: 7.526; AdminMonitoringService: 2.384 LOC | python3 docs/analysis/collect-metrics.py |
| Checkstyle / SpotBugs (24 módulos; 17 relatórios disponíveis) | 0 / 261 (1 prioridade 1) | python3 docs/analysis/collect-metrics.py |
| Build | sucesso, testes ignorados | sh scripts/compile.sh |
| Árvore Maven detalhada | sucesso, avisos de plugin e convergência de versões | Maven 3.8.6 local: dependency:tree -Dverbose -DskipTests |
| Consulta de atualizações | executada em 23/10/2026 | Maven 3.8.6 local: versions:display-dependency-updates versions:display-plugin-updates -DskipTests |
Apêndice B — limites¶
- Testes e cobertura: não executados nesta auditoria; sem correlação de tamanho com cobertura.
- CVE/SCA: não encontrei dependency-check, Trivy, Grype, Syft, OSV Scanner ou gh; sem remote Git para consultar alertas do host. Não afirmo ausência de vulnerabilidades.
- Complexidade ciclomática e duplicação: lizard, PMD e cloc não disponíveis; não há ranking por método nem clone detection.
- Regra de arquitetura: o grafo foi analisado, mas não encontrei ArchUnit ou CI para impor aciclicidade automaticamente.
- Fabric remoto: não houve nova consulta.
- Histórico/churn: index e arquivos em estado misto e ausência de remote tornam inadequado estimar churn ou preparar commit automaticamente.
Atualização de correções — 23/10/2026¶
- Corrigi a coleta para não somar relatórios de benchmarks que compilam novamente fontes já contadas no reator. Os totais 398/422 anteriores foram substituídos pela medição atual 0/261.
- Removi imports não usados/wildcard, separei instruções múltiplas e simplifiquei a expressão booleana que geravam violações Checkstyle; novo relatório: 0 avisos.
- Tornei os vetores de
ClientUpdateeAggregationReporte os mapas deRoundConfig/AggregationReportdefensivos na entrada e no acesso. Testes de regressão verificaram a mutação antes da implementação e passaram depois dela. - Ajustei o empacotamento do módulo REST para incluir
openapi-admin-monitor.yaml; isso corrige a resposta 500 de/openapi.yamle o teste correspondente passou na execução subsequente. mvn verify -DskipTestsgerou os relatórios atuais e compilou o reator.sh scripts/run-tests.sh --fastfoi interrompido manualmente durante replay de integração MNIST, após vários minutos. Os testes unitários direcionados às cópias defensivas passaram. Uma execução anterior do conjunto completo teve falhas intermitentes emBlockchainExplorerHttpTesteExperimentDeployHttpTest(respostas HTTP 400 e conexão encerrada); não atribuí esses resultados às mudanças de imutabilidade.- Restam 261 achados SpotBugs, incluindo alertas de mutabilidade, possíveis null dereferences e observações de ciclo de vida/estilo. Uma parte da análise reportou dependências ausentes do classpath. Os achados restantes precisam de triagem item a item; não foram suprimidos globalmente nem afirmados como bugs comprovados.