gradiant/faroFARO - Rilevatore di Sensibilità dei Documenti
FARO è uno strumento per rilevare informazioni sensibili nei documenti di un'organizzazione. È pensato per essere utilizzato da piccole aziende e privati che desiderano monitorare i propri documenti sensibili all'interno della propria organizzazione ma che non possono dedicare molto tempo e denaro alla configurazione di complessi strumenti di protezione dei dati.
FARO estrae indicatori di sensibilità dai documenti (ad es. ID di documenti, quantità monetarie, email personali) e assegna al documento un punteggio di sensibilità (da basso ad alto) utilizzando la frequenza e il tipo degli indicatori presenti nel documento.
Attualmente tutte le funzionalità di questo strumento sono per documenti scritti in spagnolo, anche se può essere facilmente ampliato per coprire più lingue.
Questo strumento è sviluppato dal Centro di ricerca e sviluppo in cybersecurity TEGRA.
Il progetto contiene le seguenti cartelle:
faro/: questo è il modulo FARO con la funzionalità principale.config/: i file di configurazione YAML vanno qui. C'è un file yaml per lingua (più un nolanguage.yaml per fornire funzionalità di base per lingue non rilevate) e un file yaml con configurazioni comuni per tutte le lingue config/commons.yaml.models/: questa è la cartella in cui inserire i modelli FARO.faro_detection.py: launcher di FARO per l'esecuzione standalone su un singolo file.faro_spider.sh: script per l'elaborazione in batch.docker_build_faro.sh: script per creare l'immagine Docker di FARO su Linux e Mac OS.docker_build_faro.bat: script per creare l'immagine Docker di FARO su Windows.docker_run_faro.sh: script per eseguire un container FARO su Linux e Mac OS.docker_run_faro.bat: script per eseguire un container FARO su Windows.FARO può essere eseguito come container standalone usando Docker. Puoi creare l'immagine da solo o ottenerla dal repository Docker Hub.
Se Docker è installato e in esecuzione sul tuo sistema, esegui il seguente comando per ottenere la versione più recente dell'immagine FARO da Docker Hub.
docker pull gradiant/faro
Per eseguire l'immagine Docker usa gli script docker_run_faro.sh (Linux/Mac OS) o docker_run_faro.bat (Windows). Puoi trovarli nella root del progetto o nell'ultima release.
Se Docker è installato e in esecuzione sul tuo sistema, segui questi passaggi per creare l'immagine FARO.
Linux e Mac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
Per eseguire un container FARO sono forniti alcuni script nella root del progetto. Puoi copiarli e usarli da qualsiasi altra posizione per comodità. La cartella "output" verrà creata nella directory corrente.
Linux e Mac OS
./docker_run_faro.sh <your folder with files>
Windows
docker_run_faro.bat <your folder with files>
Abbiamo aggiunto il supporto OCR a tika tramite la sua integrazione con tesseract. Alcune personalizzazioni del processo OCR possono essere modificate tramite un file env il cui percorso deve essere fornito come secondo argomento allo script. Abbiamo fornito un esempio commentato da usare come modello qui
./docker_run_faro.sh <your folder with files> <path to env file>
per esempio:
./docker_run_faro.sh ../data docker_faro_env_example.list
FARO crea una cartella "output" all'interno della cartella corrente e salva i risultati dell'esecuzione in due file:
output/scan.$CURRENT_TIME.csv: è un file csv con il punteggio assegnato al documento e la frequenza degli indicatori in ciascun file.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: è un json con l'elenco degli indicatori (disaggregati) estratti da un file. Per esempio:{"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: SOLO LINUX E MAC OS X
La modalità richiede alcuni sistemi operativi e librerie per funzionare correttamente.
È consigliabile utilizzare un ambiente virtuale separato. Per istanziare un ambiente virtuale con virtualenv.
virtualenv -p `which python3` <yourenvname>
Per attivare l'ambiente virtuale sul tuo terminale digita semplicemente:
source <yourenvname>/bin/activate
Il modo più semplice per far funzionare il sistema è installare le dipendenze in questo modo:
pip install -r requirements.txt
L'elenco delle dipendenze è il seguente:
Queste altre dipendenze sono usate per i test:
FARO dipende da diversi modelli ML per funzionare.
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
Nel nostro repository gestiamo i modelli tramite Git LFS a causa delle loro dimensioni. Se hai git-lfs installato, i modelli dovrebbero essere scaricati automaticamente quando cloni il nostro repo.
Se vuoi scaricare i modelli manualmente, esegui il seguente comando dalla root del progetto.
git lfs pull
Verifica che i percorsi mostrati di seguito nel file config/es.yml puntino ai modelli.
Il nostro spider è uno script per analizzare ricorsivamente i documenti all'interno di una cartella, salvando i risultati dell'analisi in un file.
./faro_spider.sh <your folder with files>
Dopo l'aggiunta dell'OCR, ci sono alcune configurazioni che possono essere personalizzate per l'esecuzione di FARO tramite variabili d'ambiente:
FARO_DISABLE_OCR: se questa variabile è presente (con qualsiasi valore) FARO non eseguirà l'OCR sui documentiFARO_REQUESTS_TIMEOUT: numero di secondi prima che FARO vada in timeout se il server tika non risponde (default: 60)FARO_PDF_OCR_RATIO: byte per carattere usati nei documenti PDF misti (testo e immagini) per forzare l'OCR (default: 150 byte/car)La configurazione del logging può essere impostata anche tramite variabili d'ambiente:
FARO_LOG_LEVEL: livello di logging di Faro (default: INFO)FARO_LOG_FILE: file di logging di Faro (default: None). Quando usi Docker assicurati di impostarlo all'interno della cartella output per renderlo persistente sulla macchina host.Puoi eseguire il rilevamento FARO su un singolo file usando il nostro script faro_detection.py
./faro_detection.py -i <your_file>
Vengono generati due file di output con i percorsi <your_file>.entity e <your_file>.score.
a) <your_file>.entity: un json con l'elenco delle entità ordinate per tipo e numero di occorrenze (output del modulo rilevatore di entità):
{"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) <your_file>.score: un json con i tipi di entità e il numero di volte in cui quel tipo di entità compare nel testo. Questo json contiene anche il punteggio di sensibilità nella proprietà "score" (può essere "low", "medium" e "high").
{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}
Per informazioni sugli argomenti aggiuntivi che possono essere passati al nostro script di rilevamento, dai un'occhiata qui.
Il rilevatore di entità FARO esegue due passaggi:
L'elenco degli indicatori è il seguente:
person_position_organization: questo è un gruppo di entità (Persona, Professione - Posizione, Organizzazione) estratte e collegate tra loro dai documenti.
monetary_quantity: quantità di denaro (attualmente sono supportati solo euro e dollari).
signature: restituisce la persona che firma un documento
personal_email: email che non sono aziendali (ad es. non info@ rrhh@ )
mobile_phone_number: numeri di telefono cellulare (escludendo quelli non mobile)
financial_data: carte di credito e numeri di conto IBAN
document_id: NIF e CIF spagnoli.
I conteggi unici di questi indicatori vengono raccolti in un oggetto json e passati come input al passaggio successivo.
Vengono applicate le seguenti regole:
Ogni livello di sensibilità imposta soglie per gli indicatori di sensibilità. Un documento deve rispettare almeno una delle soglie (min e max) per ottenere quel punteggio.
Se nel documento compaiono diverse soglie di sensibilità (attualmente configurate su tre), il documento aumenta il punteggio di sensibilità nonostante rispetti tutte le soglie per il livello.
Il punteggio "low" viene assegnato anche ai documenti in cui non è stato trovato alcun indicatore di sensibilità.
Utilizza un insieme di file YAML per configurare la sua funzionalità (i file YAML si trovano nella cartella "config")
common.yaml: contiene la funzionalità comune a ogni lingua
.yaml: contiene la configurazione specifica per una lingua (attualmente è supportato solo lo spagnolo: codice "es"). Indica anche dove si trovano i modelli ML (ad es. di default nella cartella "models")
Queste sono una raccolta di condizioni che selezionano un punteggio seguendo le specifiche del file di configurazione. I livelli sono configurati nella sensitivity_list ordinati per intensità (da meno a più sensibile). Il dizionario sensitivity contiene le condizioni (min, max) ordinate per tipo di entità. Il sistema deve soddisfare solo una condizione di un certo livello per contrassegnare il documento con quel livello di sensibilità. Inoltre, se nel documento vengono trovati più KPI di un certo livello (come indicato dal parametro sensitivity_multiple_kpis), il sistema aumenta il livello di sensibilità (ad es. da medium a 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 è l'elenco dei diversi punteggi di sensibilità ordinati per intensità.
sensitivity_multiple_kpis questo numero indica il numero simultaneo di punteggi in un livello consentito prima di aumentare il punteggio di sensibilità.
sensitivity è un dizionario con le condizioni di sensibilità che devono essere soddisfatte per raggiungere un livello di sensibilità.
L'applicazione FARO usa Tika per l'elaborazione dei documenti. Pertanto, tutti i formati che Tika processa possono essere usati come input. Tuttavia, gli script faro_spider.sh/faro_spider.bat per l'elaborazione in batch sono limitati alle seguenti estensioni: .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt e .rtf.
FARO usa NER (costruito con CRF) per estrarre entità classiche (Persona, Organizzazione e Località) e posizioni lavorative.
Altri indicatori vengono estratti con RegExp (ID di documenti, numeri di telefono e carte di credito, ecc.).
Le email vengono estratte con RegExp. Un classificatore ML ed euristiche vengono usati per distinguere tra email aziendali e personali.
FARO ha diversi test per verificare la funzionalità del sistema (attualmente i test coprono solo le espressioni regolari). I test possono essere eseguiti con il seguente comando:
python test_suite.py
--dump: il sistema invia le informazioni di <your_file>.score a stdout in formato csv. Ad es. un esempio di output potrebbe essere:
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
I percorsi dei file di output possono essere impostati esplicitamente dalla riga di comando usando --output_entity_file e --output_score_file
python faro_detection.py --input_file <your_file> --output_entity_file <path to output> --output_score_file <path to output>
Il comportamento predefinito del nostro script di rilevamento è mostrare solo il tipo di entità che influisce direttamente sul punteggio di sensibilità. Per mostrare tutte le entità rilevate usa il parametro --verbose dalla riga di comando.
C'è un parametro aggiuntivo (--split_lines) che deve essere usato con documenti in cui ogni riga del documento è una frase (o paragrafo). Di default, FARO cerca di unire le righe del documento perché in molti casi una riga diversa non implica una frase diversa (ad es. nei PDF).
Segui le istruzioni per installare git-lfs (GIT Large File Storage) a seconda di
Scarica il pacchetto da https://git-lfs.github.com/ e segui le istruzioni di installazione.
Installa "git bash" su Windows (controlla la sezione Windows in questo link https://git-scm.com/downloads) e successivamente visita https://git-lfs.github.com/ e segui le istruzioni di installazione.
brew install git-lfs
git lfs install
Verrà creata una cartella models con tutti i modelli all'interno.
La piena funzionalità funziona solo con documenti in spagnolo, anche se è facilmente espandibile a nuove lingue (soprattutto se sono supportate da SpaCy, lo strumento NLP usato per elaborare le frasi, i documenti).
Il sistema usa SpaCy per il parsing e la preelaborazione delle frasi con PoS. Sebbene SpaCy fornisca un sistema NER addestrato per entità classiche, NER personalizzati vengono usati per l'estrazione di entità classiche (Persona, Organizzazione, Località) e delle professioni/posizioni lavorative.
TEGRA è un centro di ricerca e sviluppo in cybersecurity con sede in Galizia (Spagna). È uno sforzo congiunto di Telefónica, azienda leader internazionale nelle telecomunicazioni, attraverso ElevenPaths, la sua unità globale di cybersecurity, e Gradiant, un centro di ricerca e sviluppo ICT con più di 100 professionisti che lavorano in aree come connettività, sicurezza e intelligenza, per creare prodotti e servizi innovativi nell'ambito della cybersecurity.
Il lavoro di TEGRA è focalizzato su due aree nel panorama della cybersecurity: Data Security e Security Analytics. Siamo impegnati a creare tecnologie all'avanguardia che possano alimentare e quindi fornire valore differenziante ai nostri prodotti.
Vedi il file CONTRIBUTORS.
CHANGELOG: changelog di FARO.