gradiant/faroFARO - Document Sensitivity Detector
FARO est un outil de détection d'informations sensibles dans les documents d'une organisation. Il est destiné aux petites entreprises et aux particuliers qui souhaitent suivre leurs documents sensibles au sein de leur organisation, mais qui ne peuvent pas consacrer beaucoup de temps et d'argent à configurer des outils complexes de protection des données.
FARO extrait des indicateurs de sensibilité des documents (par exemple, identifiants de documents, montants monétaires, emails personnels) et attribue un score de sensibilité au document (de faible à élevé) en fonction de la fréquence et du type des indicateurs présents dans le document.
Actuellement, toutes les fonctionnalités de cet outil sont destinées aux documents rédigés en espagnol, bien qu'il puisse être facilement étendu pour couvrir d'autres langues.
Cet outil est développé par TEGRA R&D Cybersecurity Center.
Le projet contient les dossiers suivants :
faro/ : module FARO contenant les fonctionnalités principales.config/ : fichiers de configuration YAML. Il y a un fichier YAML par langue (plus un nolanguage.yaml pour fournir des fonctionnalités de base aux langues non détectées) et un fichier YAML avec les configurations communes à toutes les langues config/commons.yaml.models/ : dossier pour placer les modèles FARO.faro_detection.py : lanceur de FARO pour une exécution autonome sur un seul fichier.faro_spider.sh : script pour le traitement par lots.docker_build_faro.sh : script pour construire l'image Docker FARO sous Linux et Mac OS.docker_build_faro.bat : script pour construire l'image Docker FARO sous Windows.docker_run_faro.sh : script pour exécuter un conteneur FARO sous Linux et Mac OS.docker_run_faro.bat : script pour exécuter un conteneur FARO sous Windows.FARO peut être exécuté comme un conteneur autonome avec Docker. Vous pouvez construire l'image vous-même ou l'obtenir depuis le dépôt Docker Hub.
Si Docker est installé et fonctionne sur votre système, exécutez la commande suivante pour obtenir la dernière image FARO depuis Docker Hub.
docker pull gradiant/faro
Pour exécuter l'image Docker, utilisez les scripts docker_run_faro.sh (Linux/Mac OS) ou docker_run_faro.bat (Windows). Vous les trouverez à la racine du projet ou dans la dernière version.
Si Docker est installé et fonctionne sur votre système, procédez comme suit pour construire l'image FARO.
Linux et Mac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
Des scripts sont fournis à la racine du projet pour exécuter un conteneur FARO. Vous pouvez les copier et les utiliser depuis n'importe quel autre emplacement pour plus de commodité. Le dossier "output" sera créé dans votre répertoire courant.
Linux et Mac OS
./docker_run_faro.sh <votre dossier contenant les fichiers>
Windows
docker_run_faro.bat <votre dossier contenant les fichiers>
Nous avons ajouté la prise en charge de l'OCR dans tika via son intégration tesseract. Une certaine personnalisation du processus d'OCR peut être effectuée via un fichier d'environnement dont le chemin doit être fourni comme second argument au script. Nous avons fourni un exemple commenté pour servir de modèle ici
./docker_run_faro.sh <votre dossier contenant les fichiers> <chemin vers le fichier d'environnement>
par exemple :
./docker_run_faro.sh ../data docker_faro_env_example.list
FARO crée un dossier "output" dans le dossier courant et stocke les résultats de l'exécution dans deux fichiers :
output/scan.$CURRENT_TIME.csv : fichier CSV contenant le score attribué au document et la fréquence des indicateurs dans chaque fichier.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 : fichier JSON contenant la liste des indicateurs (désagrégés) extraits d'un fichier. Par exemple :{"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"}
REMARQUE : UNIQUEMENT LINUX ET MAC OS X
Le mode nécessite un système d'exploitation et des bibliothèques pour fonctionner correctement.
Il est conseillé d'utiliser un environnement virtuel séparé. Pour instancier un environnement virtuel avec virtualenv.
virtualenv -p `which python3` <nomdevotreenv>
Pour activer l'environnement virtuel dans votre terminal, tapez simplement :
source <nomdevotreenv>/bin/activate
Le moyen le plus simple de faire fonctionner le système est d'installer les dépendances de cette façon :
pip install -r requirements.txt
La liste des dépendances est la suivante :
Ces autres dépendances sont utilisées pour les tests :
FARO s'appuie sur plusieurs modèles de ML pour fonctionner.
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
Dans notre dépôt, nous gérons les modèles via Git LFS en raison de leur taille. Si vous avez git-lfs installé, vous devriez avoir automatiquement les modèles téléchargés lors du premier clonage de notre dépôt.
Si vous souhaitez télécharger les modèles manuellement, exécutez la commande suivante depuis la racine du projet.
git lfs pull
Vérifiez que les chemins indiqués ci-dessous dans le fichier config/es.yml pointent vers les modèles.
Notre spider est un script pour analyser récursivement les documents dans un dossier, en stockant les résultats de l'analyse dans un fichier.
./faro_spider.sh <votre dossier contenant les fichiers>
Après avoir ajouté l'OCR, certaines configurations peuvent être personnalisées pour l'exécution de FARO via des variables d'environnement :
FARO_DISABLE_OCR : si cette variable est trouvée (avec n'importe quelle valeur), FARO n'exécutera pas l'OCR sur les documentsFARO_REQUESTS_TIMEOUT : nombre de secondes avant que FARO n'expire si le serveur tika ne répond pas (par défaut : 60)FARO_PDF_OCR_RATIO : octets par caractère utilisés dans les documents PDF mixtes (texte et images) pour forcer l'OCR (par défaut : 150 octets/car.)La configuration de la journalisation peut également être configurée via des variables d'environnement :
FARO_LOG_LEVEL : niveau de journalisation Faro (par défaut : INFO)FARO_LOG_FILE : fichier de journalisation Faro (par défaut : None). Lors de l'utilisation de Docker, assurez-vous de le définir dans le dossier output pour le conserver sur la machine hôte.Vous pouvez exécuter la détection FARO sur un seul fichier en utilisant notre script faro_detection.py
./faro_detection.py -i <votre_fichier>
Deux fichiers de sortie sont générés avec les chemins <votre_fichier>.entity et <votre_fichier>.score.
a) <votre_fichier>.entity : un JSON avec la liste des entités classées par type et le nombre d'apparitions (sortie du module de détection d'entités) :
{"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) <votre_fichier>.score : un JSON avec les types d'entités et le nombre de fois que ce type d'entité apparaît dans le texte. Ce JSON contient également le score de sensibilité dans la propriété "score" (peut être "low", "medium" et "high").
{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}
Pour plus d'informations sur les arguments supplémentaires pouvant être passés à notre script de détection, consultez ici.
Le détecteur d'entités FARO effectue deux étapes :
La liste des indicateurs est la suivante :
person_position_organization : groupe d'entités (Personne, Profession/Poste, Organisation) extraites et liées entre elles à partir des documents.
monetary_quantity : quantité monétaire (actuellement seuls les euros et les dollars sont pris en charge).
signature : indique la personne qui signe un document.
personal_email : emails qui ne sont pas corporatifs (par exemple, pas info@ rrhh@ ).
mobile_phone_number : numéros de téléphone mobile (en filtrant les numéros non mobiles).
financial_data : numéros de cartes de crédit et de compte IBAN.
document_id : NIF et CIF espagnols.
Les comptages uniques de ces indicateurs sont rassemblés dans un objet JSON et transmis en entrée à l'étape suivante.
Les règles suivantes sont appliquées :
Chaque niveau de sensibilité définit des seuils pour les indicateurs de sensibilité. Un document doit satisfaire au moins un des seuils (min et max) pour obtenir ce score.
Si différents seuils de sensibilité apparaissent dans le document (actuellement configuré à trois), le document augmente son niveau de sensibilité même s'il satisfait à tous les seuils pour ce niveau.
Le score "low" est également attribué aux documents où aucun indicateur de sensibilité n'a été trouvé.
Un ensemble de fichiers YAML est utilisé pour configurer ses fonctionnalités (les fichiers YAML se trouvent dans le dossier "config").
common.yaml : contient les fonctionnalités communes à toutes les langues.
.yaml : contient la configuration spécifique à une langue (actuellement seul l'espagnol est pris en charge : code "es"). Il indique également où se trouvent les modèles ML (par défaut dans le dossier "models").
CHANGELOG : journal des modifications de FARO.Ensemble de conditions qui sélectionnent un score selon la spécification du fichier de configuration. Les niveaux sont configurés dans sensitivity_list triés par leur intensité (du moins au plus sensible). Le dictionnaire sensitivity contient les conditions (min, max) classées par type d'entité. Le système n'a besoin de satisfaire qu'une seule condition d'un certain niveau pour marquer le document avec ce niveau de sensibilité. De plus, si plusieurs KPI d'un certain niveau sont trouvés dans le document (comme indiqué par le paramètre sensitivity_multiple_kpis), le système augmente leur niveau de sensibilité (par exemple, de moyen à élevé).
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 est la liste des différents scores de sensibilité classés par intensité.
sensitivity_multiple_kpis ce nombre indique le nombre simultané de scores dans un niveau autorisé avant d'augmenter le score de sensibilité.
sensitivity est un dictionnaire avec les conditions de sensibilité qui doivent être satisfaites pour atteindre un niveau de sensibilité.
L'application FARO utilise Tika pour le traitement des documents. Par conséquent, tous les formats que Tika peut traiter peuvent être utilisés comme entrée. Néanmoins, les scripts faro_spider.sh/faro_spider.bat pour le traitement par lots sont limités aux extensions suivantes : .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt et .rtf.
FARO utilise NER (construit avec des CRF) pour extraire les entités classiques (Personne, Organisation et Lieu) et les postes.
D'autres indicateurs sont extraits avec des expressions régulières (identifiants de documents, numéros de téléphone et de carte de crédit, etc.).
Les courriels sont extraits avec des expressions régulières. Un classifieur ML et des heuristiques sont utilisés pour distinguer les courriels corporatifs des courriels personnels.
FARO dispose de plusieurs tests pour vérifier les fonctionnalités du système (actuellement, les tests ne couvrent que les expressions régulières). Les tests peuvent être exécutés avec la commande suivante :
python test_suite.py
--dump : le système affiche les informations de <votre_fichier>.score sur la sortie standard au format CSV. Par exemple, un exemple de sortie pourrait être :
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
Les chemins des fichiers de sortie peuvent être définis explicitement en ligne de commande à l'aide de --output_entity_file et --output_score_file
python faro_detection.py --input_file <votre_fichier> --output_entity_file <chemin vers la sortie> --output_score_file <chemin vers la sortie>
Le comportement par défaut de notre script de détection est d'afficher uniquement les types d'entités qui affectent directement le score de sensibilité. Pour afficher toutes les entités détectées, utilisez le paramètre --verbose en ligne de commande.
Il existe un paramètre supplémentaire (--split_lines) qui doit être utilisé avec les documents où chaque ligne du document est une phrase (ou un paragraphe). Par défaut, FARO essaie de joindre les lignes du document car dans de nombreux cas, une ligne différente n'implique pas une phrase différente (par exemple dans les PDF).
Suivez les instructions pour installer git-lfs (GIT Large File Storage) selon le système.
Téléchargez le paquet sur https://git-lfs.github.com/ et suivez les instructions d'installation.
Installez "git bash" sur Windows (consultez la section Windows dans ce lien https://git-scm.com/downloads) puis rendez-vous sur https://git-lfs.github.com/ et suivez les instructions d'installation.
brew install git-lfs
git lfs install
Un dossier models sera créé avec tous les modèles à l'intérieur.
La fonctionnalité complète ne fonctionne qu'avec des documents en espagnol, bien qu'elle soit facilement extensible à de nouvelles langues (surtout si elles sont prises en charge par SpaCy, l'outil NLP utilisé pour traiter les phrases et les documents).
Le système utilise SpaCy pour l'analyse syntaxique et le prétraitement des phrases (Part-of-Speech). Bien que SpaCy fournisse un système NER entraîné pour les entités classiques, des NER personnalisés sont utilisés pour l'extraction des entités classiques (Personne, Organisation, Localisation) et des professions/postes.
TEGRA est un centre de R&D en cybersécurité basé en Galice (Espagne). Il est le fruit d'un effort conjoint entre Telefónica, une entreprise internationale de télécommunications leader, via ElevenPaths, son unité mondiale de cybersécurité, et Gradiant, un centre de R&D en TIC avec plus de 100 professionnels travaillant dans des domaines tels que la connectivité, la sécurité et l'intelligence, pour créer des produits et services innovants dans le domaine de la cybersécurité.
Le travail de TEGRA se concentre sur deux domaines du paysage de la cybersécurité : la sécurité des données et l'analyse de sécurité. Nous nous engageons à créer des technologies de pointe qui peuvent nourrir et ainsi apporter une valeur différenciante à nos produits.
Voir le fichier CONTRIBUTORS.