gradiant/faroFARO - Detector de Sensibilidad de Documentos
FARO es una herramienta para detectar información sensible en documentos de una organización. Está orientada a su uso por pequeñas empresas y particulares que quieren realizar un seguimiento de sus documentos sensibles dentro de su organización, pero que no pueden dedicar mucho tiempo y dinero a configurar herramientas complejas de protección de datos.
FARO extrae indicadores de sensibilidad de los documentos (p. ej., identificadores de documentos, cantidades monetarias, correos electrónicos personales) y asigna una puntuación de sensibilidad al documento (de baja a alta) utilizando la frecuencia y el tipo de los indicadores del documento.
Actualmente, toda la funcionalidad de esta herramienta es para documentos escritos en español, aunque puede ampliarse fácilmente para cubrir más idiomas.
Esta herramienta está desarrollada por TEGRA R&D Cybersecurity Center.
El proyecto contiene las siguientes carpetas:
faro/ : este es el módulo de FARO con la funcionalidad principal.config/: aquí se encuentran los archivos de configuración yaml. Hay un archivo yaml por idioma (además de un nolanguage.yaml para proporcionar funcionalidad básica para idiomas no detectados) y un archivo yaml con configuraciones comunes para todos los idiomas config/commons.yaml.models/: esta es la carpeta para colocar los modelos de FARO.faro_detection.py: lanzador de FARO para operación autónoma sobre un solo archivo.faro_spider.sh: script para procesamiento masivo.docker_build_faro.sh: script para construir la imagen docker de FARO en Linux y Mac OS.docker_build_faro.bat: script para construir la imagen docker de FARO en Windows.docker_run_faro.sh: script para ejecutar un contenedor FARO en Linux y Mac OS.docker_run_faro.bat: script para ejecutar un contenedor FARO en Windows.FARO puede ejecutarse como un contenedor independiente usando Docker. Puedes crear la imagen tú mismo u obtenerla desde el repositorio de Docker Hub.
Si tienes Docker instalado y en ejecución en tu sistema, ejecuta el siguiente comando para obtener la última imagen de FARO desde Docker Hub.
docker pull gradiant/faro
Para ejecutar la imagen docker utiliza los scripts docker_run_faro.sh (Linux/Mac OS) o docker_run_faro.bat (Windows). Puedes encontrarlos en la raíz del proyecto o en la última versión.
Si tienes Docker instalado y en ejecución en tu sistema, haz lo siguiente para construir la imagen de FARO.
Linux y Mac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
Para ejecutar un contenedor FARO se proporcionan algunos scripts en la raíz del proyecto. Puedes copiar y usar esos scripts desde cualquier otro lugar por conveniencia. La carpeta "output" se creará en tu directorio actual.
Linux y Mac OS
./docker_run_faro.sh <your folder with files>
Windows
docker_run_faro.bat <your folder with files>
Hemos añadido soporte OCR a tika mediante su integración con tesseract. Algunas personalizaciones del proceso OCR se pueden ajustar mediante el uso de un archivo env cuya ruta debe proporcionarse como segundo argumento del script. Hemos incluido un ejemplo comentado que sirve como plantilla aquí
./docker_run_faro.sh <your folder with files> <path to env file>
por ejemplo:
./docker_run_faro.sh ../data docker_faro_env_example.list
FARO crea una carpeta "output" dentro de la carpeta actual y guarda los resultados de la ejecución en dos archivos:
output/scan.$CURRENT_TIME.csv: es un archivo csv con la puntuación asignada al documento y la frecuencia de indicadores en cada archivo.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: es un json con la lista de indicadores (desglosados) extraídos en un archivo. Por ejemplo:{"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 Y MAC OS X
El modo requiere un sistema operativo y librerías para funcionar correctamente.
Es recomendable usar un entorno virtual separado. Para instanciar un entorno virtual con virtualenv.
virtualenv -p `which python3` <yourenvname>
Para activar el entorno virtual en tu terminal, simplemente escribe:
source <yourenvname>/bin/activate
La forma más sencilla de poner el sistema en marcha es instalar las dependencias de esta manera
pip install -r requirements.txt
La lista de dependencias es la siguiente:
Estas otras dependencias se utilizan para las pruebas:
FARO depende de varios 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
En nuestro repositorio gestionamos los modelos mediante Git LFS debido a su tamaño. Si tienes git-lfs instalado, deberías tener los modelos descargados automáticamente cuando clonas nuestro repositorio por primera vez.
Si quieres descargar los modelos manualmente, ejecuta el siguiente comando desde la raíz del proyecto.
git lfs pull
Comprueba que las rutas que se muestran a continuación dentro del archivo config/es.yml apuntan a los modelos.
Nuestro spider es un script para analizar recursivamente los documentos dentro de una carpeta, guardando los resultados del análisis en un archivo.
./faro_spider.sh <your folder with files>
Después de añadir OCR, hay algunas configuraciones que se pueden personalizar para la ejecución de FARO mediante variables de entorno:
FARO_DISABLE_OCR: si se encuentra esta variable (con cualquier valor), FARO no ejecutará OCR en los documentosFARO_REQUESTS_TIMEOUT: Número de segundos antes de que FARO agote el tiempo de espera si el servidor tika no responde (por defecto: 60)FARO_PDF_OCR_RATIO: Bytes por carácter utilizados en documentos PDF mixtos (texto e imágenes) para forzar OCR (por defecto: 150 bytes/char)La configuración de registro también se puede configurar mediante variables de entorno:
FARO_LOG_LEVEL: Nivel de registro de Faro (por defecto: INFO)FARO_LOG_FILE: Archivo de registro de Faro (por defecto: None). Al usar docker, asegúrate de configurarlo dentro de la carpeta output para que persista en la máquina anfitriona.Puedes ejecutar la detección de FARO sobre un solo archivo usando nuestro script faro_detection.py
./faro_detection.py -i <your_file>
Se generan dos archivos de salida con las rutas <your_file>.entity y <your_file>.score.
a) <your_file>.entity: un json con la lista de entidades ordenadas por su tipo y el número de apariciones (salida del módulo detector 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) <your_file>.score: un json con los tipos de entidades y el número de veces que este tipo de entidad aparece en el texto. Este json también contiene la puntuación de sensibilidad en la propiedad "score" (puede ser "low", "medium" y "high").
{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}
Para obtener información sobre argumentos adicionales que se pueden pasar a nuestro script de detección, mira aquí.
El detector de entidades de FARO realiza dos pasos:
La lista de indicadores es la siguiente:
person_position_organization: este es un grupo de entidades (Persona, Puesto - Cargo, Organización) que se extrajeron y vincularon entre sí a partir de los documentos.
monetary_quantity: cantidad de dinero (actualmente solo se admiten euros y dólares).
signature: devuelve la persona que firma un documento
personal_email: correos electrónicos que no son corporativos (p. ej., no info@ rrhh@)
mobile_phone_number: números de teléfono móvil (filtrando los que no son móviles)
financial_data: tarjetas de crédito y números de cuenta IBAN
document_id: NIF y CIF españoles.
Los recuentos únicos de estas frases se recopilan en un objeto json y se transmiten como entrada al siguiente paso.
Se aplican las siguientes reglas:
Cada nivel de sensibilidad establece umbrales para los indicadores de sensibilidad. Un documento debe cumplir al menos uno de los umbrales (mínimo y máximo) para obtener esa puntuación.
Si aparecen diferentes umbrales de sensibilidad en el documento (actualmente configurados en tres), el documento aumenta el nivel de la puntuación de sensibilidad a pesar de cumplir todos los umbrales del nivel.
La puntuación "low" también se asigna a documentos donde no se encontró ningún indicador de sensibilidad.
Emplea un conjunto de archivos YAML para configurar su funcionalidad (los archivos YAML se encuentran dentro de la carpeta "config")
common.yaml: tiene la funcionalidad común para todos los idiomas
.yaml: tiene la configuración específica para un idioma (actualmente solo se admite español: código "es"). También indica dónde se encuentran los modelos de ML (p. ej., por defecto dentro de la carpeta "models")
Estas son una colección de condiciones que seleccionan una puntuación siguiendo la especificación del archivo de configuración. Los niveles se configuran en sensitivity_list ordenados por su intensidad (de menos a más sensible). El diccionario sensitivity contiene las condiciones (mín, máx) ordenadas por tipo de entidad. El sistema solo necesita cumplir una condición de un determinado nivel para marcar el documento con ese nivel de sensibilidad. Además, si se encuentran múltiples KPIs de un nivel determinado en el documento (como lo indica el parámetro sensitivity_multiple_kpis), el sistema aumenta su nivel de sensibilidad (p. ej., de medio a alto).
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 es la lista de las diferentes puntuaciones de sensibilidad ordenadas por intensidad.
sensitivity_multiple_kpis este número indica el número simultáneo de puntuaciones permitidas en un nivel antes de aumentar la puntuación de sensibilidad.
sensitivity es un diccionario con las condiciones de sensibilidad que deben cumplirse para alcanzar un nivel de sensibilidad.
La aplicación FARO utiliza Tika para el procesamiento de documentos. Por lo tanto, todos los formatos que procesa Tika se pueden usar como entrada. No obstante, los scripts faro_spider.sh/faro_spider.bat para procesamiento masivo están restringidos a las siguientes extensiones: .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt y .rtf.
FARO utiliza NER (construido con CRFs) para extraer entidades clásicas (Persona, Organización y Ubicación) y puestos de trabajo.
Otros indicadores se extraen con RegExp (identificadores de documentos, números de teléfono y tarjetas de crédito, etc.).
Los correos se extraen con RegExp. Se utilizan un clasificador de ML y heurísticas para distinguir entre correos corporativos y personales.
FARO tiene varias pruebas para verificar la funcionalidad del sistema (actualmente las pruebas solo cubren las expresiones regulares). Las pruebas se pueden ejecutar con el siguiente comando:
python test_suite.py
--dump: el sistema vuelca la información de <your_file>.score a stdout en formato csv. Por ejemplo, una salida podría ser:
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
Las rutas de los archivos de salida se pueden establecer explícitamente en la línea de comandos usando --output_entity_file y --output_score_file
python faro_detection.py --input_file <your_file> --output_entity_file <path to output> --output_score_file <path to output>
El comportamiento predeterminado de nuestro script de detección es mostrar solo el tipo de entidades que afecta directamente a la puntuación de sensibilidad. Para mostrar todas las entidades detectadas, usa el parámetro --verbose en la línea de comandos.
Hay un parámetro adicional (--split_lines) que debe usarse con documentos en los que cada línea del documento es una oración (o párrafo). Por defecto, FARO intenta unir las líneas del documento porque en muchos casos una línea distinta no implica una oración distinta (p. ej., en PDFs).
Sigue las instrucciones para instalar git-lfs (GIT Large File Storage) según
Descarga el paquete en https://git-lfs.github.com/ y sigue las instrucciones de instalación.
Instala "git bash" en Windows (consulta la sección de Windows en este enlace https://git-scm.com/downloads) y después visita https://git-lfs.github.com/ y sigue las instrucciones de instalación.
brew install git-lfs
git lfs install
Se creará una carpeta models con todos los modelos dentro.
La funcionalidad completa solo funciona con documentos en español, aunque es fácilmente ampliable con nuevos idiomas (especialmente si están soportados por SpaCy, la herramienta de NLP utilizada para procesar las frases y los documentos).
El sistema utiliza SpaCy para el análisis y el preprocesamiento de oraciones con partes de la oración (PoS). Aunque SpaCy proporciona un sistema NER entrenado para entidades clásicas, se utilizan NER personalizados para la extracción de entidades clásicas (Persona, Organización, Localización) y las profesiones/puestos de trabajo.
TEGRA es un Centro de Ciberseguridad de I+D con sede en Galicia (España). Es un esfuerzo conjunto de Telefónica, una empresa líder internacional de telecomunicaciones, a través de ElevenPaths, su unidad global de ciberseguridad, y Gradiant, un centro de I+D en TIC con más de 100 profesionales que trabajan en áreas como conectividad, seguridad e inteligencia, para crear productos y servicios innovadores dentro de la ciberseguridad.
El trabajo de TEGRA se centra en dos áreas dentro del panorama de la ciberseguridad: Seguridad de Datos y Analítica de Seguridad. Estamos comprometidos con la creación de tecnologías de vanguardia que puedan nutrir y, por tanto, aportar valor diferencial a nuestros productos.
Consulta el archivo CONTRIBUTORS.
CHANGELOG: registro de cambios de FARO.