FARO

FARO (Детектор чувствительности документов)

Содержание

• Что это такое
• Что здесь находится?
• Запуск FARO с помощью Docker
• Запуск FARO на хост-машине
  • Предварительные требования
  • Виртуальное окружение
  • Зависимости
  • NER-модели
  • FARO Spider
  • Обнаружение в одном файле
• Технические детали
  • Детектор сущностей FARO
  • Конфигурация
  • Поддерживаемые форматы входных файлов
  • Методы
  • Тестирование
  • Установка Git-LFS
  • Дополнительные аргументы обнаружения FARO
  • Известные проблемы
• Участники

Что это такое

FARO — это инструмент для обнаружения конфиденциальной информации в документах организации. Он ориентирован на малые компании и частных лиц, которые хотят отслеживать свои конфиденциальные документы внутри организации, но не могут тратить много времени и денег на настройку сложных инструментов защиты данных.

FARO извлекает индикаторы чувствительности из документов (например, идентификаторы документов, денежные суммы, личные электронные письма) и присваивает документу оценку чувствительности (от низкой до высокой) на основе частоты и типа индикаторов в документе.

В настоящее время весь функционал этого инструмента рассчитан на документы, написанные на испанском языке, хотя его можно легко расширить для поддержки других языков.

Этот инструмент разработан TEGRA R&D Cybersecurity Center.

Что здесь находится?

Проект содержит следующие папки:

• faro/ : это модуль FARO с основной функциональностью.
• config/: здесь находятся yaml-файлы конфигурации. Для каждого языка предусмотрен один yaml-файл (плюс один nolanguage.yaml для обеспечения базовой функциональности для нераспознанных языков) и один yaml-файл с общими настройками для всех языков config/commons.yaml.
• models/: это папка для размещения моделей FARO.
• faro_detection.py: запускающий скрипт FARO для автономной работы с одним файлом.
• faro_spider.sh: скрипт для пакетной обработки.
• docker_build_faro.sh: скрипт для сборки docker-образа FARO в Linux и Mac OS.
• docker_build_faro.bat: скрипт для сборки docker-образа FARO в Windows.
• docker_run_faro.sh: скрипт для запуска контейнера FARO в Linux и Mac OS.
• docker_run_faro.bat: скрипт для запуска контейнера FARO в Windows.

Запуск FARO с помощью Docker

FARO может работать как автономный контейнер с использованием Docker. Вы можете собрать образ самостоятельно или получить его из репозитория Docker Hub.

Получение образа FARO из Docker Hub

При условии, что Docker установлен и запущен в вашей системе, выполните следующую команду, чтобы получить последний образ FARO из Docker Hub.

docker pull gradiant/faro

Для запуска docker-образа используйте скрипты docker_run_faro.sh (Linux/Mac OS) или docker_run_faro.bat (Windows). Вы можете найти их в корне проекта или в последнем релизе.

Сборка образа FARO

При условии, что Docker установлен и запущен в вашей системе, выполните следующие действия для сборки образа FARO.

Linux и Mac OS

./docker_build_faro.sh

Windows

docker_build_faro.bat

Запуск контейнера FARO

Для запуска контейнера FARO в корне проекта предоставлены скрипты. Для удобства вы можете скопировать и использовать эти скрипты из любого другого места. Папка "output" будет создана в вашем текущем каталоге.

Linux и Mac OS

./docker_run_faro.sh <your folder with files>

Windows

docker_run_faro.bat <your folder with files>

Мы добавили поддержку OCR в tika через его интеграцию с tesseract. Некоторые параметры процесса OCR можно настроить с помощью env-файла, путь к которому необходимо указать вторым аргументом скрипта. Мы предоставили закомментированный пример, который можно использовать в качестве шаблона, здесь.

./docker_run_faro.sh <your folder with files> <path to env file>

например:

./docker_run_faro.sh ../data docker_faro_env_example.list

Результаты

FARO создает папку "output" внутри текущей папки и сохраняет результаты выполнения в двух файлах:

• output/scan.$CURRENT_TIME.csv: это csv-файл с оценкой, присвоенной документу, и частотой индикаторов в каждом файле.

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: это json со списком индикаторов (детализированных), извлеченных из файла. Например:

{"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"}

Запуск FARO на хост-машине

ПРИМЕЧАНИЕ: ТОЛЬКО LINUX И MAC OS X

Предварительные требования

Для правильной работы этого режима требуются определенная операционная система и библиотеки:

• Linux или Mac OS
• Java 1.7 или выше
• virtualenv (необязательно, но настоятельно рекомендуется)
• GNU parallel (для ускорения работы нашего spider-скрипта. Более подробную информацию об этом инструменте можно посмотреть здесь
• установленный git lfs.

Виртуальное окружение

Рекомендуется использовать отдельное виртуальное окружение. Чтобы создать виртуальное окружение с помощью virtualenv:

virtualenv -p `which python3` <yourenvname>

Чтобы активировать виртуальное окружение в вашем терминале, просто введите:

source <yourenvname>/bin/activate

Зависимости

Самый простой способ запустить систему — установить зависимости следующим образом:

pip install -r requirements.txt

Список зависимостей приведен ниже:

• SpaCy с как минимум испанской языковой моделью
• numpy
• scipy
• sklearn
• gensim
• sklearn-crfsuite
• fuzzywuzzy
• tika
• gensim
• pyyaml
• pandas

Следующие зависимости используются для тестирования:

• mox
• unittest-xml-reporting

NER-модели

FARO для своей работы использует несколько моделей машинного обучения.

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

В нашем репозитории мы храним модели через Git LFS из-за их размера. Если у вас установлен git-lfs, модели будут автоматически загружены при первом клонировании нашего репозитория.

Если вы хотите загрузить модели вручную, выполните следующую команду из корня проекта:

git lfs pull

Убедитесь, что пути, указанные ниже в файле config/es.yml, указывают на модели.

FARO spider

Наш spider — это скрипт для рекурсивного анализа документов внутри папки, сохраняющий результаты анализа в файл.

./faro_spider.sh <your folder with files>

После добавления OCR появились некоторые параметры конфигурации, которые можно настроить для выполнения FARO через переменные окружения:

• FARO_DISABLE_OCR: если эта переменная присутствует (с любым значением), FARO не будет выполнять OCR для документов
• FARO_REQUESTS_TIMEOUT: количество секунд до истечения времени ожидания FARO, если сервер tika не отвечает (по умолчанию: 60)
• FARO_PDF_OCR_RATIO: количество байт на символ, используемое в смешанных PDF-документах (текст и изображения) для принудительного выполнения OCR (по умолчанию: 150 байт/символ)

Конфигурацию журналирования также можно настроить через переменные окружения:

• FARO_LOG_LEVEL: уровень журналирования FARO (по умолчанию: INFO)
• FARO_LOG_FILE: файл журналирования FARO (по умолчанию: None). При использовании docker обязательно укажите его внутри папки output, чтобы сохранить его на хост-машине.

Обнаружение в одном файле

Вы можете выполнить обнаружение FARO для одного файла с помощью нашего скрипта faro_detection.py:

./faro_detection.py -i <your_file>

Создаются два выходных файла с путями <your_file>.entity и <your_file>.score.

a) <your_file>.entity: json со списком сущностей, упорядоченных по их типу и количеству вхождений (выходные данные модуля детектора сущностей):

{"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: json с типами сущностей и количеством вхождений этого типа сущностей в текст. Этот json также содержит оценку чувствительности в свойстве "score" (может быть "low", "medium" и "high").

{"score": "high", "summary": {"monetary_quantity": 1, "person_position": 1, "mobile_phone_number": 1, "personal_email": 1, "credit_account_number": 2}}

Информацию о дополнительных аргументах, которые можно передать нашему скрипту обнаружения, смотрите здесь.

Технические детали

Детектор сущностей FARO

Детектор сущностей FARO выполняет два шага:

1. Извлечение индикаторов чувствительности: индикаторами являются сущности и другие текстовые элементы (например, денежные суммы), которые с высокой вероятностью встречаются в конфиденциальных документах.

Список индикаторов приведен ниже:

• person_position_organization: это группа сущностей (Person — человек, Job - Position — должность, Organization — организация), которые были извлечены из документов и связаны друг с другом.

• monetary_quantity: денежная сумма (в настоящее время поддерживаются только евро и доллары).

• signature: определяет лицо, подписывающее документ

• personal_email: электронные письма, которые не являются корпоративными (например, не info@ rrhh@)

• mobile_phone_number: номера мобильных телефонов (с фильтрацией немобильных номеров)

• financial_data: кредитные карты и номера счетов IBAN

• document_id: испанские NIF и CIF.

Уникальные счетчики этих индикаторов собираются в json-объект и передаются на вход следующему шагу.

2. Оценка чувствительности документа: к индикаторам, извлеченным на этапе 1, применяется правило классификации (с использованием пороговых значений) для присвоения документу оценки чувствительности.

Применяются следующие правила:

• Каждый уровень чувствительности задает пороговые значения для индикаторов чувствительности. Документ должен соответствовать хотя бы одному из пороговых значений (min и max), чтобы получить эту оценку.

• Если в документе присутствуют разные пороговые значения чувствительности (в настоящее время настроено три), документ повышает оценку чувствительности, даже если выполняются все пороговые значения для этого уровня.

• Оценка "low" также присваивается документам, в которых не было найдено ни одного индикатора чувствительности

Конфигурация

Для настройки функциональности используется набор YAML-файлов (YAML-файлы находятся в папке "config"):

• common.yaml: содержит общую функциональность для всех языков

• .yaml: содержит специфическую конфигурацию для языка (в настоящее время поддерживается только испанский: код "es"). Также указывает, где находятся модели машинного обучения (например, по умолчанию в папке "models")

Конфигурация оценки чувствительности

Это набор условий, которые выбирают оценку в соответствии со спецификацией файла конфигурации. Уровни настраиваются в sensitivity_list, отсортированном по интенсивности (от менее к более чувствительному). Словарь sensitivity содержит условия (min, max), упорядоченные по типу сущности. Системе достаточно выполнить одно условие определенного уровня, чтобы пометить документ этим уровнем чувствительности. Кроме того, если в документе обнаружено несколько KPI определенного уровня (как указано параметром sensitivity_multiple_kpis), система повышает уровень чувствительности (например, с medium до 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 — это список различных оценок чувствительности, упорядоченных по интенсивности.

• sensitivity_multiple_kpis — это число указывает допустимое количество одновременных оценок на уровне до повышения оценки чувствительности

• sensitivity — это словарь с условиями чувствительности, которые должны быть выполнены для достижения уровня чувствительности.

Поддерживаемые форматы входных файлов

Приложение FARO использует Tika для обработки документов. Поэтому все форматы, которые обрабатывает Tika, могут использоваться в качестве входных данных. Тем не менее, скрипты faro_spider.sh/faro_spider.bat для пакетной обработки ограничены следующими расширениями: .doc, .docx, .pptx, .ppt, .xls, .pdf, .odt, .ods, .odp, .txt и .rtf.

Методы

FARO использует NER (построенный с помощью CRF) для извлечения классических сущностей (Person — человек, Organization — организация, Location — местоположение) и должностей.

Другие индикаторы извлекаются с помощью RegExp (идентификаторы документов, номера телефонов и кредитных карт и т. д.).

Электронные письма извлекаются с помощью RegExp. Для различения корпоративных и личных электронных писем используются ML-классификатор и эвристики.

Тестирование

FARO имеет несколько тестов для проверки функциональности системы (в настоящее время тесты покрывают только регулярные выражения). Тесты можно выполнить с помощью следующей команды:

python test_suite.py

Дополнительные аргументы обнаружения FARO

--dump: система выводит информацию из <your_file>.score в stdout в формате csv. Например, выходные данные могут выглядеть так:

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

Пути к выходным файлам можно явно указать в командной строке с помощью --output_entity_file и --output_score_file:

python faro_detection.py --input_file <your_file> --output_entity_file <path to output> --output_score_file <path to output>

Поведение нашего скрипта обнаружения по умолчанию заключается в отображении только тех типов сущностей, которые напрямую влияют на оценку чувствительности. Чтобы отобразить все обнаруженные сущности, используйте параметр --verbose в командной строке.

Существует дополнительный параметр (--split_lines), который необходимо использовать с документами, в которых каждая строка документа является предложением (или абзацем). По умолчанию FARO пытается объединить строки в документе, потому что во многих случаях новая строка не означает новое предложение (например, в PDF-файлах).

Установка Git-lfs

Следуйте инструкциям по установке git-lfs (GIT Large File Storage) в зависимости от:

Linux

Загрузите пакет с https://git-lfs.github.com/ и следуйте инструкциям по установке.

Windows

Установите "git bash" в Windows (см. раздел Windows по этой ссылке https://git-scm.com/downloads), а затем посетите https://git-lfs.github.com/ и следуйте инструкциям по установке.

Mac OS

brew install git-lfs
git lfs install

Будет создана папка models, содержащая все модели.

Известные проблемы

• Полная функциональность работает только с испанскими документами, хотя ее легко расширить для новых языков (особенно если они поддерживаются SpaCy — инструментом NLP, используемым для обработки предложений в документах).

• Система использует SpaCy для парсинга и предобработки предложений с помощью частеречной разметки (PoS). Хотя SpaCy предоставляет обученную NER-систему для классических сущностей, для извлечения классических сущностей (Person — человек, Organization — организация, Localization — местоположение) и профессий/должностей используются собственные NER-модели.

Участники

TEGRA — это исследовательский центр кибербезопасности, расположенный в Галисии (Испания). Это совместный проект Telefónica, ведущей международной телекоммуникационной компании, через ElevenPaths, ее глобальное подразделение кибербезопасности, и Gradiant, ИКТ-исследовательского центра с более чем 100 специалистами, работающими в таких областях, как связь, безопасность и интеллектуальный анализ данных, с целью создания инновационных продуктов и услуг в сфере кибербезопасности.

Работа TEGRA сосредоточена на двух областях в сфере кибербезопасности: безопасность данных (Data Security) и аналитика безопасности (Security Analytics). Мы стремимся создавать передовые технологии, которые могут развиваться и, таким образом, придавать нашим продуктам отличительную ценность.

Смотрите файл CONTRIBUTORS.