AnonShield - SBRC 2026 SF Submission

SBRC 2026 Salão de Ferramentas Submission

This release contains the stable version of AnonShield as described in the paper submitted to the SBRC 2026 Tool Session (SF).

Key Features in this Version:

• Performance: Up to 738x speedup compared to previous baselines.
• Accuracy: 94.2% F1-Score and 96.7% Recall.

---

Authors: Cristhian Kapelinski, Douglas Lautert, Beatriz Machado, Diego Kreutz, Isadora Garcia Ferrão.
Institution: UNIPAMPA / UBO.

AnonShield v1.0-alpha

Relatório Detalhado de Mudanças: Evolução do Animizador de Dados

Este relatório detalha as principais melhorias e mudanças arquiteturais implementadas na nova versão da ferramenta de anonimização em comparação com a versão anterior (o script monolítico). A atualização representa uma refatoração completa, transformando um único script num projeto modular, mais robusto, eficiente e extensível. 🚀

Resumo das Principais Mudanças

• Modularização do Código: O código foi dividido em ficheiros lógicos (config.py, engine.py, anon.py, deanonymize.py), abandonando a abordagem de script único.
• Gestão Centralizada de Configurações: Todas as variáveis de configuração, mapeamentos e inicialização da base de dados foram movidos para config.py.
• Abstração do Motor NLP: A lógica de inicialização e configuração dos motores Presidio (Analyzer e Anonymizer) foi isolada em engine.py.
• Interface de Linha de Comando (CLI) Avançada: A nova versão usa argparse para fornecer argumentos flexíveis como --lang, --preserve-entities e --allow-list.
• Suporte Multilíngue: O sistema agora suporta dinamicamente múltiplos idiomas, não se limitando mais ao português.
• Carregamento Sob Demanda (Lazy Loading): Os modelos de NLP são carregados e cacheados apenas quando necessários, melhorando significativamente o desempenho em execuções repetidas.
• Nova Ferramenta de Desanonimização: Foi adicionado o script deanonymize.py, que permite reverter um "slug" anonimizado para o seu texto original.
• Expansão do Suporte a Formatos: O suporte foi estendido para incluir nativamente ficheiros JSON, XML, e uma gama maior de formatos de imagem.
• Robustez e Tratamento de Erros: O sistema agora lida de forma mais inteligente com a ausência de dependências (como o Tesseract para OCR), emitindo avisos em vez de interromper a execução.

---

Análise Detalhada das Mudanças

1. Arquitetura e Modularização

A mudança mais impactante é a transição de um script monolítico para uma arquitetura modular.

• Versão Anterior: Todo o código—configuração, lógica de base de dados, inicialização dos motores, processamento de ficheiros e execução—estava contido num único ficheiro .py. Isso dificultava a manutenção, a reutilização de componentes e a clareza geral do projeto.
• Nova Versão: O projeto foi dividido em quatro ficheiros com responsabilidades claras:
  • config.py: Centraliza todas as configurações, como chaves de API (SECRET_KEY), mapeamentos de entidades (ENTITY_MAPPING), caminhos de modelos e a inicialização da base de dados.
  • engine.py: Isola toda a complexidade da criação e configuração dos motores AnalyzerEngine e AnonymizerEngine do Presidio. Contém a lógica de carregamento de modelos, adição de reconhecedores customizados e o operador CustomSlugAnonymizer.
  • anon.py: Atua como o ponto de entrada principal para o processo de anonimização. Ele lida com a análise de argumentos da linha de comando, o roteamento de ficheiros para as funções de processamento corretas (ex: process_csv_batched, process_docx_with_ocr) e a orquestração geral do fluxo.
  • deanonymize.py: Um novo utilitário totalmente separado que fornece a funcionalidade de reverter a anonimização, consultando a base de dados.

Benefício: Essa separação de responsabilidades torna o código mais fácil de entender, manter e estender. Por exemplo, para adicionar suporte a um novo formato de ficheiro, basta adicionar uma nova função de processamento em anon.py sem tocar na lógica do motor NLP.

2. Gestão de Configuração e CLI

A forma como as configurações e os argumentos são geridos foi completamente modernizada.

• Versão Anterior: Configurações como ALLOW_LIST e TRANSFORMER_MODEL eram constantes globais no topo do script. A execução dependia de um único argumento posicional (sys.argv[1]).
• Nova Versão:
  • config.py torna as configurações explícitas e fáceis de modificar.
  • anon.py utiliza o módulo argparse, oferecendo uma CLI robusta e amigável. Agora é possível:
    • Especificar o idioma do documento com --lang.
    • Manter certas entidades sem anonimização com --preserve-entities.
    • Adicionar palavras a uma lista de permissões em tempo de execução com --allow-list.

Benefício: Maior flexibilidade e usabilidade para o utilizador final, que pode customizar o processo de anonimização sem alterar o código.

3. Melhorias de Funcionalidade e Extensibilidade

• Suporte Multilíngue: A versão anterior tinha o idioma português ("pt") fixo no código. A nova versão deteta o idioma via argumento --lang e carrega os modelos spaCy correspondentes dinamicamente, além de sempre carregar o modelo em inglês como fallback.
• Utilitário de Desanonimização: A adição de deanonymize.py é uma funcionalidade completamente nova. Ela permite que um utilizador autorizado (que possua a ANON_SECRET_KEY) consulte a base de dados para encontrar o valor original de um slug anonimizado (ex: [PERSON_hash]), aumentando a utilidade da ferramenta em cenários de auditoria.
• Suporte a Novos Formatos: A versão anterior era limitada a TXT, PDF, DOCX, XLSX e CSV. A nova versão adiciona processadores dedicados para JSON e XML, que preservam a estrutura aninhada dos ficheiros, e formaliza o processamento para uma gama muito maior de formatos de imagem (PNG, JPEG, GIF, etc.).

Benefício: A ferramenta torna-se muito mais versátil e aplicável a uma variedade maior de casos de uso e tipos de dados.

4. Otimização de Desempenho e Eficiência

• Carregamento Sob Demanda (Lazy Loading): Na versão anterior, os modelos de NLP eram carregados a cada execução do script. A nova versão implementa uma cache (_ENGINES_CACHE em anon.py) através da função get_or_create_engines_lazily. Os motores para um determinado idioma são inicializados apenas uma vez e reutilizados em chamadas subsequentes, resultando numa inicialização muito mais rápida após a primeira execução.
• Gestão de OCR: A lógica de OCR foi aprimorada. Em vez de extrair e processar imagens incondicionalmente, a função ensure_ocr_policy verifica se o Tesseract está disponível e se o ficheiro realmente precisa de OCR, emitindo um aviso e continuando o processo (para o texto extraível) caso a dependência não esteja presente.

Benefício: Redução do tempo de inicialização e uso mais inteligente de recursos, além de maior resiliência a falhas de dependência.

---

Tabela Comparativa (Resumo)

Característica	Versão Anterior (Monolítica)	Nova Versão (Modular)
Estrutura do Código	Script único com mais de 400 linhas.	Múltiplos ficheiros (config, engine, anon, deanonymize).
Configuração	Variáveis globais hardcoded no script.	Centralizada no ficheiro config.py.
Interface de CLI	Argumento único via sys.argv.	argparse com múltiplas opções (--lang, --preserve-entities, etc.).
Suporte a Idiomas	Fixo para português ("pt").	Dinâmico, com suporte a vários idiomas via flag --lang.
Carregamento de Modelos	Carregados a cada execução.	Lazy loading com cache para reutilização.
Desanonimização	Funcionalidade inexistente.	Utilitário deanonymize.py dedicado.
Formatos Suportados	TXT, PDF, DOCX, XLSX, CSV.	Adiciona suporte nativo a JSON, XML e mais formatos de imagem.
Tratamento de Erros (OCR)	Interrompe a execução se o Tesseract não for encontrado.	Emite um aviso e continua o processamento do texto do ficheiro.
Manutenibilidade	Baixa. Alterações podem ter efeitos colaterais.	Alta. Responsabilidades são isoladas e claras.

Conclusão

A transição da versão anterior para a nova representa um salto significativo em maturidade de software. A nova arquitetura não é apenas uma melhoria, mas uma reconstrução fundamental que adota as melhores práticas de engenharia de software. O resultado é uma ferramenta de anonimização mais poderosa, flexível, eficiente, robusta e fácil de manter.