gradiant/faroFARO - Detector de Sensibilidade de Documentos
FARO é uma ferramenta para detetar informação sensível em documentos numa organização. Está orientada para ser usada por pequenas empresas e particulares que queiram rastrear os seus documentos sensíveis dentro da sua organização, mas que não possam gastar muito tempo e dinheiro a configurar ferramentas complexas de Proteção de Dados.
FARO extrai indicadores de sensibilidade de documentos (ex.: IDs de documentos, quantias monetárias, emails pessoais) e atribui uma pontuação de sensibilidade ao documento (de baixa a alta) usando a frequência e o tipo dos indicadores no documento.
Atualmente toda a funcionalidade desta ferramenta é para documentos escritos em espanhol, embora possa ser facilmente atualizada para cobrir mais idiomas.
Esta ferramenta é desenvolvida pela TEGRA R&D Cybersecurity Center.
O projeto contém as seguintes pastas:
faro/ : este é o módulo FARO com a funcionalidade principal.config/: os ficheiros de configuração yaml vão aqui. Há um ficheiro yaml por idioma (mais um nolanguage.yaml para fornecer funcionalidade básica para idiomas não detetados) e um ficheiro yaml com configurações comuns para todos os idiomas config/commons.yaml.models/: esta é a pasta para colocar os modelos FARO.faro_detection.py: lançador do FARO para operação autónoma sobre um único ficheiro.faro_spider.sh: script para processamento em lote.docker_build_faro.sh: script para construir a imagem Docker do FARO no Linux e Mac OS.docker_build_faro.bat: script para construir a imagem Docker do FARO no Windows.docker_run_faro.sh: script para executar um contentor FARO no Linux e Mac OS.docker_run_faro.bat: script para executar um contentor FARO no Windows.CHANGELOG: registo de alterações do FARO.O FARO pode ser executado como um contentor autónomo usando o Docker. Pode construir a imagem por si ou obtê-la do repositório Docker Hub.
Assumindo que tem o Docker instalado e em execução no seu sistema, execute o seguinte comando para obter a imagem FARO mais recente do Docker Hub.
docker pull gradiant/faro
Para executar a imagem Docker utilize os scripts docker_run_faro.sh (Linux/Mac OS) ou docker_run_faro.bat (Windows). Pode encontrá-los na raiz do projeto ou na versão mais recente.
Assumindo que tem o Docker instalado e em execução no seu sistema, faça o seguinte para construir a imagem FARO.
Linux e Mac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
Para executar um contentor FARO, alguns scripts são fornecidos na raiz do projeto. Pode copiá-los e usá-los a partir de qualquer outro local por conveniência. A pasta "output" será criada sob o seu diretório atual.
Linux e Mac OS
./docker_run_faro.sh <a sua pasta com ficheiros>
Windows
docker_run_faro.bat <a sua pasta com ficheiros>
Adicionámos suporte OCR ao tika através da sua integração com o tesseract. É possível personalizar alguns parâmetros do processo de OCR através do uso de um ficheiro env cujo caminho precisa de ser fornecido como segundo argumento do script. Fornecemos um exemplo comentado para servir de modelo aqui
./docker_run_faro.sh <a sua pasta com ficheiros> <caminho para o ficheiro env>
por exemplo:
./docker_run_faro.sh ../data docker_faro_env_example.list
O FARO cria uma pasta "output" dentro da pasta atual e armazena os resultados da execução em dois ficheiros:
output/scan.$CURRENT_TIME.csv: é um ficheiro csv com a pontuação atribuída ao documento e a frequência dos indicadores em cada ficheiro.filepath,score,person_position_organization,monetary_quantity,signature,personal_email,mobile_phone_number,financial_data,document_id,custom_words,meta:content-type,meta:author,meta:pages,meta:lang,meta:date,meta:filesize,meta:num_words,meta:num_chars,meta:ocr
/Users/test/code/FARO_datasets/quick_test_data/Factura_NRU_0_1_001.pdf,high,0,0,0,0,0,0,1,4,application/pdf,Powered By Crystal,1,es,,85739,219,1185,False
/Users/test/code/FARO_datasets/quick_test_data/Factura_Plancha.pdf,high,0,6,0,0,0,0,2,8,application/pdf,Python PDF Library - http://pybrary.net/pyPdf/,1,es,,77171,259,1524,True
/Users/test/code/FARO_datasets/quick_test_data/20190912-FS2019.pdf,high,0,3,0,0,0,0,1,2,application/pdf,FPDF 1.6,1,es,2019-09-12T20:08:19Z,1545,62,648,False
output/scan.$CURRENT_TIME.entity: é um json com a lista de indicadores (desagregados) extraídos num ficheiro. Por exemplo:{"filepath": "/Users/test/code/FARO_datasets/quick_test_data/Factura_NRU_0_1_001.pdf", "entities": {"custom_words": {"facturar": 3, "total": 1}, "prob_currency": {"12,0021": 1, "12,00": 1, "9,92": 1, "3,9921": 1, "3,99": 1, "3,30": 1, "15,99": 1, "13,21": 1, "1.106.166": 1, "1,00": 1, "99,00": 1}, "document_id": {"89821284M": 1}}, "datetime": "2019-12-11 14:19:17"}
{"filepath": "/Users/test/code/FARO_datasets/quick_test_data/Factura_Plancha.pdf", "entities": {"document_id": {"H82547761": 1, "21809943D": 2}, "custom_words": {"factura": 2, "facturar": 2, "total": 2, "importe": 2}, "monetary_quantity": {"156,20": 4, "2,84": 2, "0,00": 2, "159,04": 2, "32,80": 4, "191,84": 2}, "prob_currency": {"1,00": 6, "189,00": 2}}, "datetime": "2019-12-11 14:19:27"}
{"filepath": "/Users/test/code/FARO_datasets/quick_test_data/20190912-FS2019.pdf", "entities": {"document_id": {"C-01107564": 1}, "custom_words": {"factura": 1, "total": 1}, "monetary_quantity": {"3,06": 1, "0,64": 1, "3,70": 1}}, "datetime": "2019-12-11 14:19:33"}
NOTA: APENAS LINUX E MAC OS X
O modo requer algum sistema operativo e bibliotecas para funcionar corretamente
É aconselhável usar um ambiente virtual separado. Para instanciar um ambiente virtual com virtualenv.
virtualenv -p `which python3` <nome_do_ambiente>
Para ativar o ambiente virtual no seu terminal basta digitar:
source <nome_do_ambiente>/bin/activate
A maneira mais fácil de deixar o sistema operacional é instalar as dependências desta forma
pip install -r requirements.txt
A lista de dependências é a seguinte:
Estas outras dependências são usadas para testes:
O FARO depende de vários modelos de ML para funcionar.
detection:
nlp_model : es_core_news_sm
crf_ner_list: models/crf_professions_v1.joblib
personal_email_detection: models/email_detector.joblib
target_list: models/legal.txt
crf_ner_classic: models/crf_classic_step1.joblib,models/crf_classic_step2.joblib,models/crf_classic_step3.joblib,models/crf_classic_step4.joblib,models/crf_classic_step5.joblib
corp_mail_list: models/corp_mail_list.txt
No nosso repositório estamos a gerir modelos através do Git LFS devido ao seu tamanho. Se tiver git-lfs instalado, deve ter automaticamente os modelos descarregados quando clonar o nosso repositório pela primeira vez.
Se quiser descarregar modelos manualmente, execute o seguinte comando a partir da raiz do projeto.
git lfs pull
Verifique que os caminhos mostrados abaixo dentro do ficheiro config/es.yml apontam para os modelos.
O nosso spider é um script para analisar recursivamente os documentos dentro de uma pasta, armazenando os resultados da análise num ficheiro.
./faro_spider.sh <a sua pasta com ficheiros>
Após adicionar OCR, existem algumas configurações que podem ser personalizadas para a execução do FARO através de variáveis de ambiente:
FARO_DISABLE_OCR: se esta variável for encontrada (com qualquer valor), o FARO não executará OCR nos documentosFARO_REQUESTS_TIMEOUT: Número de segundos antes de o FARO expirar se o servidor tika não responder (padrão: 60)FARO_PDF_OCR_RATIO: Bytes por caractere usados em documentos PDF mistos (texto e imagens) para forçar OCR (padrão: 150 bytes/char)A configuração de registo (logging) também pode ser configurada através de variáveis de ambiente:
FARO_LOG_LEVEL: Nível de registo do Faro (padrão: INFO)FARO_LOG_FILE: Ficheiro de registo do Faro (padrão: None). Ao usar docker, certifique-se de o definir dentro da pasta output para o persistir na máquina anfitriã.Pode executar a deteção do faro sobre um único ficheiro usando o nosso script faro_detection.py
./faro_detection.py -i <o_seu_ficheiro>
Dois ficheiros de saída são gerados com os caminhos <o_seu_ficheiro>.entity e <o_seu_ficheiro>.score.
a) <o_seu_ficheiro>.entity: um json com a lista de entidades ordenadas pelo seu tipo e o número de ocorrências (saída do módulo detetor de entidades):
{"LOC": {"Pontevedra": 1}, "MONEY": {"1.000 euros": 2}, "PER": {"Betty Corti\u00f1as": 1, "Eva Expósito": 1, "Belén Portela": 1, "Marta Rivadulla": 1, "Miguel Rivas": 1}, "PROF": {"el tutor": 1}, "ORG": {"Centro de Recursos Educativos": 1}}
b) <o_seu_ficheiro>.score: um json com os tipos de entidades e o número de vezes que esse tipo de entidade aparece no texto. Este json também contém a pontuação de sensibilidade na propriedade "score" (pode ser "low", "medium" e "high").
{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}
Para obter informações sobre argumentos adicionais que podem ser passados ao nosso script de deteção, veja aqui.
O detetor de entidades FARO executa dois passos:
A lista de indicadores é a seguinte:
person_position_organization: este é um grupo de entidades (Pessoa, Cargo - Posição, Organização) que foram extraídas e ligadas entre si a partir dos documentos.
monetary_quantity: quantia monetária (atualmente apenas euros e dólares são suportados).
signature: devolve a pessoa que assina um documento
personal_email: emails que não são corporativos (ex.: não info@ rrhh@ )
mobile_phone_number: números de telemóvel (filtrando os não móveis)
financial_data: cartões de crédito e números de conta IBAN
document_id: NIF e CIF espanhóis.
As contagens únicas destas frases são reunidas num objeto json e transmitidas como entrada para o próximo passo.
As seguintes regras são aplicadas:
Cada nível de sensibilidade define limiares para os indicadores de sensibilidade. Um documento deve cumprir pelo menos um dos limiares (mínimo e máximo) para obter essa pontuação.
Se diferentes limiares de sensibilidade aparecerem no documento (atualmente configurados para três), o documento sobe o nível de sensibilidade apesar de cumprir todos os limiares para o nível.
A pontuação "low" também é atribuída a documentos onde nenhum indicador de sensibilidade foi encontrado
Utiliza um conjunto de ficheiros YAML para configurar a sua funcionalidade (os ficheiros YAML estão localizados dentro da pasta "config")
common.yaml: tem a funcionalidade comum a todos os idiomas
<código de idioma>.yaml: tem a configuração específica para um idioma (atualmente apenas espanhol é suportado: código "es"). Também indica onde estão localizados os Modelos ML (ex.: por padrão dentro da pasta "models")
São uma coleção de condições que selecionam uma pontuação seguindo a especificação do ficheiro de configuração. Os níveis são configurados na sensitivity_list ordenados pela sua intensidade (do menos para o mais sensível). O dicionário sensitivity contém as condições (min, max) ordenadas por tipo de entidade. O sistema precisa apenas de cumprir uma condição de um certo nível para sinalizar o documento com esse nível de sensibilidade. Além disso, se vários KPIs de um determinado nível forem encontrados no documento (conforme marcado pelo parâmetro sensitivity_multiple_kpis), o sistema aumenta o seu nível de sensibilidade (ex.: de medium para high).
sensitivity_list:
- low
- medium
- high
sensitivity_multiple_kpis: 3
sensitivity:
low:
person_position:
min: 1
max: 5
monetary_quantity:
min: 1
max: 5
signature:
min: 0
max: 0
personal_email:
min: 0
max: 0
....
sensitivity_list é a lista de diferentes pontuações de sensibilidade ordenadas por intensidade.
sensitivity_multiple_kpis este número indica o número simultâneo de pontuações num nível permitido antes de subir o nível de sensibilidade
sensitivity é um dict com as condições de sensibilidade que devem ser satisfeitas para alcançar um nível de sensibilidade.
A aplicação FARO utiliza Tika para processamento de documentos. Portanto, todos os formatos que o Tika processa podem ser usados como entrada. No entanto, os scripts faro_spider.sh/faro_spider.bat para processamento em lote estão restritos às seguintes extensões: .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt e .rtf.
O FARO usa NER (construído com CRFs) para extrair entidades clássicas (Pessoa, Organização e Localização) e cargos.
Outros indicadores são extraídos com RegExp (IDs de documentos, números de telefone e cartão de crédito, etc.).
Os emails são extraídos com RegExp. Um classificador de ML e heurísticas são usados para distinguir entre emails corporativos e pessoais.
O FARO tem vários testes para verificar a funcionalidade do sistema (atualmente os testes cobrem apenas as expressões regulares). Os testes podem ser executados com o seguinte comando:
python test_suite.py
--dump: o sistema imprime a informação de <o_seu_ficheiro>.score para stdout em formato csv. Exemplo de saída:
id_file,score,person_jobposition_organization,monetary_quantity,sign,personal_email,mobile_phone_number,credit_account_number,id_document
data/test/test2.pdf,medium,3,0,1,0,0,0,0
Os caminhos dos ficheiros de saída podem ser definidos explicitamente na linha de comandos usando --output_entity_file e --output_score_file
python faro_detection.py --input_file <o_seu_ficheiro> --output_entity_file <caminho para a saída> --output_score_file <caminho para a saída>
O comportamento padrão do nosso script de deteção é mostrar apenas o tipo de entidades que afetam diretamente a pontuação de sensibilidade. Para mostrar todas as entidades detetadas, use o parâmetro --verbose na linha de comandos.
Existe um parâmetro adicional (--split_lines) que deve ser usado com documentos em que cada linha do documento é uma frase (ou parágrafo). Por padrão, o FARO tenta juntar linhas no documento porque em muitos casos uma linha diferente não implica uma frase diferente (ex.: em PDFs).
Siga as instruções para instalar git-lfs (GIT Large File Storage) dependendo
Descarregue o pacote em https://git-lfs.github.com/ e siga as instruções de instalação.
Instale "git bash" no Windows (verifique a secção Windows neste link https://git-scm.com/downloads) e depois visite https://git-lfs.github.com/ e siga as instruções de instalação.
brew install git-lfs
git lfs install
Uma pasta models será criada com todos os modelos no interior.
A funcionalidade completa funciona apenas com documentos em espanhol, embora seja facilmente expansível para novos idiomas (especialmente se forem suportados pelo SpaCy, a ferramenta de PLN usada para processar a frase e os documentos).
O sistema usa SpaCy para análise e pré-processamento de frases PoS. Embora o SpaCy forneça um sistema NER treinado para entidades clássicas, NERs personalizados são usados para a extração de entidades clássicas (Pessoa, Organização, Localização) e profissões/cargos.
TEGRA é um Centro de I&D em Cibersegurança sediado na Galiza (Espanha). É um esforço conjunto da Telefónica, uma empresa líder internacional de telecomunicações, através da ElevenPaths, a sua unidade global de cibersegurança, e da Gradiant, um centro de I&D em TIC com mais de 100 profissionais a trabalhar em áreas como conectividade, segurança e inteligência, para criar produtos e serviços inovadores no domínio da cibersegurança.
O trabalho da TEGRA está focado em duas áreas no panorama da cibersegurança: Segurança de Dados e Análise de Segurança. Estamos empenhados em criar tecnologias de ponta que possam nutrir e assim fornecer valor diferenciador aos nossos produtos.
Consulte o ficheiro CONTRIBUTORS.