gradiant/faroFARO - Dokument-Sensitivitätsdetektor
FARO ist ein Werkzeug zur Erkennung sensibler Informationen in Dokumenten einer Organisation. Es ist für kleine Unternehmen und Privatpersonen gedacht, die ihre sensiblen Dokumente innerhalb ihrer Organisation nachverfolgen möchten, aber nicht viel Zeit und Geld für die Konfiguration komplexer Datenschutz-Tools aufwenden können.
FARO extrahiert Sensitivitätsindikatoren aus Dokumenten (z. B. Dokumenten-IDs, Geldbeträge, persönliche E-Mails) und weist dem Dokument anhand der Häufigkeit und Art der Indikatoren einen Sensitivitätswert zu (von niedrig bis hoch).
Derzeit ist die gesamte Funktionalität dieses Tools auf Dokumente in spanischer Sprache ausgelegt, obwohl es problemlos erweitert werden kann, um weitere Sprachen abzudecken.
Dieses Tool wurde vom TEGRA R&D Cybersecurity Center entwickelt.
Das Projekt enthält die folgenden Ordner:
faro/: Dies ist das FARO-Modul mit der Hauptfunktionalität.config/: Hier liegen die YAML-Konfigurationsdateien. Es gibt eine YAML-Datei pro Sprache (plus eine nolanguage.yaml, um die Grundfunktionalität für nicht erkannte Sprachen bereitzustellen) und eine YAML-Datei mit gemeinsamen Konfigurationen für alle Sprachen: config/commons.yaml.models/: In diesen Ordner werden die FARO-Modelle gelegt.faro_detection.py: Starter von FARO für den eigenständigen Betrieb über eine einzelne Datei.faro_spider.sh: Skript für die Stapelverarbeitung.docker_build_faro.sh: Skript zum Erstellen des FARO-Docker-Images auf Linux und Mac OS.docker_build_faro.bat: Skript zum Erstellen des FARO-Docker-Images auf Windows.docker_run_faro.sh: Skript zum Ausführen eines FARO-Containers auf Linux und Mac OS.docker_run_faro.bat: Skript zum Ausführen eines FARO-Containers auf Windows.FARO kann als eigenständiger Container mit Docker ausgeführt werden. Sie können das Image selbst erstellen oder es aus dem Docker-Hub-Repository beziehen.
Vorausgesetzt, Docker ist auf Ihrem System installiert und läuft, führen Sie den folgenden Befehl aus, um das neueste FARO-Image von Docker Hub zu erhalten.
docker pull gradiant/faro
Um das Docker-Image auszuführen, verwenden Sie die Skripte docker_run_faro.sh (Linux/Mac OS) oder docker_run_faro.bat (Windows). Sie finden sie im Projektstamm oder in der neuesten Version.
Vorausgesetzt, Docker ist auf Ihrem System installiert und läuft, führen Sie Folgendes aus, um das FARO-Image zu erstellen.
Linux und Mac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
Zum Ausführen eines FARO-Containers sind im Projektstamm einige Skripte enthalten. Sie können diese Skripte zur Bequemlichkeit kopieren und von überall aus verwenden. Der Ordner output wird in Ihrem aktuellen Verzeichnis erstellt.
Linux und Mac OS
./docker_run_faro.sh <your folder with files>
Windows
docker_run_faro.bat <your folder with files>
Wir haben tika über die Tesseract-Integration OCR-Unterstützung hinzugefügt. Einige Anpassungen des OCR-Prozesses können über eine Umgebungsdatei (env file) vorgenommen werden, deren Pfad als zweites Argument an das Skript übergeben werden muss. Ein auskommentiertes Beispiel als Vorlage finden Sie hier
./docker_run_faro.sh <your folder with files> <path to env file>
zum Beispiel:
./docker_run_faro.sh ../data docker_faro_env_example.list
FARO erstellt einen Ordner output im aktuellen Ordner und speichert die Ergebnisse der Ausführung in zwei Dateien:
output/scan.$CURRENT_TIME.csv: ist eine CSV-Datei mit dem dem Dokument zugewiesenen Score und der Häufigkeit der Indikatoren in jeder Datei.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: ist ein JSON mit der Liste der in einer Datei extrahierten Indikatoren (aufgeschlüsselt). Zum Beispiel:{"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"}
HINWEIS: NUR LINUX UND MAC OS X
Der Modus erfordert einige Betriebssystem- und Bibliotheksvoraussetzungen, um ordnungsgemäß zu funktionieren.
Es ist ratsam, eine separate virtuelle Umgebung zu verwenden. So erstellen Sie eine virtuelle Umgebung mit virtualenv:
virtualenv -p `which python3` <yourenvname>
Um die virtuelle Umgebung in Ihrem Terminal zu aktivieren, geben Sie einfach Folgendes ein:
source <yourenvname>/bin/activate
Der einfachste Weg, das System zum Laufen zu bringen, ist, die Abhängigkeiten auf diese Weise zu installieren:
pip install -r requirements.txt
Die Liste der Abhängigkeiten ist die folgende:
Diese weiteren Abhängigkeiten werden für Tests verwendet:
FARO benötigt mehrere ML-Modelle, um zu funktionieren.
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
In unserem Repository verwalten wir Modelle aufgrund ihrer Größe über Git LFS. Wenn Sie git-lfs installiert haben, werden die Modelle beim ersten Klonen unseres Repos automatisch heruntergeladen.
Wenn Sie die Modelle manuell herunterladen möchten, führen Sie den folgenden Befehl vom Projektstamm aus aus:
git lfs pull
Stellen Sie sicher, dass die unten gezeigten Pfade in der Datei config/es.yml auf die Modelle verweisen.
Unser Spider ist ein Skript, das die Dokumente in einem Ordner rekursiv analysiert und die Ergebnisse der Analyse in einer Datei speichert.
./faro_spider.sh <your folder with files>
Nach dem Hinzufügen von OCR gibt es einige Konfigurationen, die für die FARO-Ausführung über Umgebungsvariablen angepasst werden können:
FARO_DISABLE_OCR: Wenn diese Variable (mit einem beliebigen Wert) vorhanden ist, führt FARO keine OCR an den Dokumenten durch.FARO_REQUESTS_TIMEOUT: Anzahl der Sekunden, bevor FARO einen Timeout auslöst, wenn der Tika-Server nicht antwortet (Standard: 60)FARO_PDF_OCR_RATIO: Bytes pro Zeichen, die in PDF-Mischdokumenten (Text und Bilder) verwendet werden, um OCR zu erzwingen (Standard: 150 Bytes/Zeichen)Die Protokollierungskonfiguration kann ebenfalls über Umgebungsvariablen konfiguriert werden:
FARO_LOG_LEVEL: FARO-Protokollierungsstufe (Standard: INFO)FARO_LOG_FILE: FARO-Protokolldatei (Standard: None). Achten Sie bei Docker darauf, sie im Ordner output zu setzen, um sie auf dem Host-Rechner zu speichern.Sie können die FARO-Erkennung für eine einzelne Datei mit unserem Skript faro_detection.py ausführen:
./faro_detection.py -i <your_file>
Es werden zwei Ausgabedateien mit den Pfaden <your_file>.entity und <your_file>.score erzeugt.
a) <your_file>.entity: ein JSON mit der Liste der Entitäten, geordnet nach ihrem Typ und der Anzahl der Vorkommen (Ausgabe des Entitätsdetektor-Moduls):
{"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: ein JSON mit den Entitätstypen und der Anzahl, mit der dieser Entitätstyp im Text vorkommt. Dieses JSON enthält außerdem den Sensitivitätswert in der Eigenschaft score (er kann low, medium und high sein).
{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}
Informationen zu zusätzlichen Argumenten, die an unser Erkennungsskript übergeben werden können, finden Sie hier.
Der FARO-Entitätsdetektor führt zwei Schritte aus:
Die Liste der Indikatoren ist die folgende:
person_position_organization: Dies ist eine Gruppe von Entitäten (Person, Beruf/Position, Organisation), die aus den Dokumenten extrahiert und miteinander verknüpft wurden.
monetary_quantity: Geldbetrag (derzeit werden nur Euro und Dollar unterstützt).
signature: gibt die Person aus, die ein Dokument unterzeichnet.
personal_email: E-Mails, die nicht unternehmensbezogen sind (z. B. nicht info@ rrhh@).
mobile_phone_number: Mobiltelefonnummern (nicht mobile Nummern werden herausgefiltert).
financial_data: Kreditkarten und IBAN-Kontonummern.
document_id: Spanische NIF und CIF.
Die eindeutigen Zählungen dieser Sätze werden in einem JSON-Objekt gesammelt und als Eingabe an den nächsten Schritt weitergeleitet.
Die folgenden Regeln werden angewendet:
Jede Sensitivitätsstufe legt Schwellenwerte für die Sensitivitätsindikatoren fest. Ein Dokument muss mindestens einen der Schwellenwerte (min und max) erfüllen, um diesen Wert zu erhalten.
Wenn verschiedene Sensitivitätsschwellenwerte im Dokument vorkommen (derzeit auf drei konfiguriert), wird der Sensitivitätswert des Dokuments angehoben, obwohl es alle Schwellenwerte für die Stufe erfüllt.
Der Wert low wird auch Dokumenten zugewiesen, bei denen kein Sensitivitätsindikator gefunden wurde.
Zur Konfiguration seiner Funktionalität verwendet es eine Reihe von YAML-Dateien (die YAML-Dateien befinden sich im Ordner config).
common.yaml: enthält die gemeinsame Funktionalität für jede Sprache.
.yaml: enthält die spezifische Konfiguration für eine Sprache (derzeit wird nur Spanisch unterstützt: Code es). Es gibt auch an, wo sich die ML-Modelle befinden (z. B. standardmäßig im Ordner models).
Dies ist eine Sammlung von Bedingungen, die einen Wert gemäß der Spezifikation der Konfigurationsdatei auswählt. Die Stufen sind in der sensitivity_list nach ihrer Intensität sortiert (von weniger zu stärker sensibel). Das sensitivity-Wörterbuch enthält die Bedingungen (min, max), geordnet nach Entitätstyp. Das System benötigt nur die Erfüllung einer Bedingung einer bestimmten Stufe, um das Dokument mit dieser Sensitivitätsstufe zu kennzeichnen. Wenn außerdem mehrere KPIs einer bestimmten Stufe im Dokument gefunden werden (wie durch den Parameter sensitivity_multiple_kpis markiert), erhöht das System deren Sensitivitätsstufe (z. B. von medium auf 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 ist die Liste der verschiedenen Sensitivitätswerte, geordnet nach Intensität.
sensitivity_multiple_kpis: Diese Zahl gibt die gleichzeitige Anzahl von Werten in einer Stufe an, die erlaubt ist, bevor der Sensitivitätswert angehoben wird.
sensitivity ist ein Wörterbuch mit den Sensitivitätsbedingungen, die erfüllt sein müssen, um eine Sensitivitätsstufe zu erreichen.
Die FARO-Anwendung verwendet Tika zur Dokumentverarbeitung. Daher können alle Formate, die Tika verarbeitet, als Eingabe verwendet werden. Die Skripte faro_spider.sh/faro_spider.bat für die Stapelverarbeitung sind jedoch auf die folgenden Erweiterungen beschränkt: .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt und .rtf.
FARO verwendet NER (mit CRFs erstellt), um klassische Entitäten (Person, Organisation und Ort) und Berufspositionen zu extrahieren.
Andere Indikatoren werden mit RegExp extrahiert (Dokumenten-IDs, Telefon- und Kreditkartennummern usw.).
E-Mails werden mit RegExp extrahiert. Ein ML-Klassifikator und Heuristiken werden verwendet, um zwischen Unternehmens- und persönlichen E-Mails zu unterscheiden.
FARO verfügt über mehrere Tests, um die Funktionalität des Systems zu überprüfen (derzeit decken die Tests nur die regulären Ausdrücke ab). Die Tests können mit dem folgenden Befehl ausgeführt werden:
python test_suite.py
--dump: Das System gibt die Informationen von <your_file>.score im CSV-Format auf stdout aus. Ein Beispiel für eine Ausgabe könnte sein:
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
Die Pfade der Ausgabedateien können über die Befehlszeile explizit mit --output_entity_file und --output_score_file festgelegt werden:
python faro_detection.py --input_file <your_file> --output_entity_file <path to output> --output_score_file <path to output>
Das Standardverhalten unseres Erkennungsskripts besteht darin, nur die Entitätstypen anzuzeigen, die den Sensitivitätswert direkt beeinflussen. Um alle erkannten Entitäten anzuzeigen, verwenden Sie den Parameter --verbose in der Befehlszeile.
Es gibt einen zusätzlichen Parameter (--split_lines), der bei Dokumenten verwendet werden muss, in denen jede Zeile des Dokuments ein Satz (oder Absatz) ist. Standardmäßig versucht FARO, Zeilen im Dokument zusammenzuführen, da in vielen Fällen eine andere Zeile nicht einen anderen Satz bedeutet (z. B. bei PDFs).
Befolgen Sie die Anweisungen zur Installation von git-lfs (GIT Large File Storage) je nach Betriebssystem:
Laden Sie das Paket unter https://git-lfs.github.com/ herunter und befolgen Sie die Installationsanweisungen.
Installieren Sie git bash unter Windows (siehe Windows-Abschnitt unter diesem Link https://git-scm.com/downloads) und besuchen Sie anschließend https://git-lfs.github.com/ und befolgen Sie die Installationsanweisungen.
brew install git-lfs
git lfs install
Ein Ordner models wird mit allen Modellen darin erstellt.
Die volle Funktionalität funktioniert nur mit spanischen Dokumenten, obwohl sie leicht um neue Sprachen erweitert werden kann (insbesondere, wenn diese mit SpaCy unterstützt werden, dem NLP-Werkzeug, das zur Verarbeitung der Sätze und Dokumente verwendet wird).
Das System verwendet SpaCy für das Parsing und die PoS-Satzvorverarbeitung. Obwohl SpaCy ein trainiertes NER-System für klassische Entitäten bereitstellt, werden benutzerdefinierte NERs für die Extraktion klassischer Entitäten (Person, Organisation, Ort) und der Berufe/Positionen verwendet.
TEGRA ist ein Forschungs- und Entwicklungszentrum für Cybersicherheit mit Sitz in Galicien (Spanien). Es ist eine gemeinsame Initiative von Telefónica, einem führenden internationalen Telekommunikationsunternehmen, über ElevenPaths, seine globale Cybersicherheitseinheit, und Gradiant, einem IKT-Forschungs- und Entwicklungszentrum mit mehr als 100 Fachkräften, die in Bereichen wie Konnektivität, Sicherheit und Intelligenz arbeiten, um innovative Produkte und Dienstleistungen im Bereich der Cybersicherheit zu schaffen.
Die Arbeit von TEGRA konzentriert sich auf zwei Bereiche in der Cybersicherheitslandschaft: Datensicherheit und Sicherheitsanalytik. Wir sind bestrebt, modernste Technologien zu entwickeln, die unsere Produkte fördern und ihnen so einen differenzierenden Mehrwert verleihen.
Siehe die Datei CONTRIBUTORS.
CHANGELOG: FARO-Änderungsprotokoll.