Ir para o conteúdo

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

  1. Li as instruções em .agents, o índice de documentação e o POM raiz.
  2. Executei sh scripts/compile.sh; o script usa Maven com -DskipTests, portanto esta validação confirma build/empacotamento, não os testes.
  3. Li os POMs, construí o grafo de dependências internas e procurei ciclos.
  4. 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.
  5. 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.
  6. Consultei a árvore de dependências e as versões disponíveis com o Versions Maven Plugin.
  7. Comparei código, variáveis de ambiente, regras compartilhadas e documentação de Fabric, privacidade e publicação de experimentos.
  8. 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

  1. Tornar escritas Fabric fail-closed e mover contrato/consentimento ao ledger.
  2. Bloquear flag de secure aggregation enquanto não houver implementação e rever a alegação DP/geração do ruído.
  3. Proteger o endpoint de implantação e validar a rede Fabric de staging antes de publicar.
  4. Fazer checkpoint e reconciliar o index com as fontes restauradas.
  5. Reduzir as classes administrativas e dependências dos experimentos na API.
  6. Alinhar documentação, adicionar CI/Wrapper/Enforcer e ativar análise estática gradualmente.
  7. 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 ClientUpdate e AggregationReport e os mapas de RoundConfig/AggregationReport defensivos 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.yaml e o teste correspondente passou na execução subsequente.
  • mvn verify -DskipTests gerou os relatórios atuais e compilou o reator. sh scripts/run-tests.sh --fast foi 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 em BlockchainExplorerHttpTest e ExperimentDeployHttpTest (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.