FARO（文档敏感度检测器）

FARO LOGO

这是什么

FARO 是一个用于检测组织中文档敏感信息的工具。它面向那些希望追踪组织内部敏感文档，但又不愿花费大量时间和金钱配置复杂数据保护工具的小公司和特定用户。

FARO 从文档中提取敏感指标（例如文档 ID、货币数量、个人电子邮件），并根据文档中指标的出现频率和类型为文档分配敏感度评分（从低到高）。

目前，该工具的所有功能均适用于西班牙语编写的文档，但可以轻松扩展以支持更多语言。

该工具由 TEGRA R&D 网络安全中心开发。

这里有什么？

该项目包含以下文件夹：

faro/ : 这是 FARO 模块，包含主要功能。
config/: Yaml 配置文件存放于此。每种语言有一个 yaml 文件（外加一个 nolanguage.yaml 为未检测到的语言提供基本功能），以及一个所有语言通用配置的 yaml 文件 config/commons.yaml。
models/: 此文件夹用于放置 FARO 模型。
faro_detection.py: 用于对单个文件进行独立操作的 FARO 启动器。
faro_spider.sh: 用于批量处理的脚本。
docker_build_faro.sh: 用于在 Linux 和 Mac OS 上构建 FARO Docker 镜像的脚本。
docker_build_faro.bat: 用于在 Windows 上构建 FARO Docker 镜像的脚本。
docker_run_faro.sh: 用于在 Linux 和 Mac OS 上运行 FARO 容器的脚本。
docker_run_faro.bat: 用于在 Windows 上运行 FARO 容器的脚本。
CHANGELOG: FARO 变更日志。

使用 Docker 运行 FARO

FARO 可以作为独立容器使用 Docker 运行。您可以自行构建镜像，也可以从 Docker Hub 仓库获取。

从 Docker Hub 获取 FARO 镜像

假设您的系统已安装并运行 Docker，执行以下命令从 Docker Hub 获取最新的 FARO 镜像。

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>

我们通过 tika 的 tesseract 集成添加了 OCR 支持。可以通过使用环境变量文件对 OCR 过程进行一些自定义，该文件的路径需要作为脚本的第二个参数提供。我们提供了一个带注释的示例作为模板此处

./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（用于加速爬虫脚本。您可以在此处查看有关该工具的更多信息 here）
已安装 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 依赖于多个 ML 模型才能工作。

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

我们的爬虫是一个脚本，用于递归分析文件夹中的文档，并将分析结果存储在文件中。

./faro_spider.sh <your folder with files>

添加 OCR 后，可以通过环境变量自定义 FARO 执行的一些配置：

FARO_DISABLE_OCR：如果找到此变量（任意值），FARO 将不会对文档执行 OCR
FARO_REQUESTS_TIMEOUT：如果 tika 服务器没有响应，FARO 超时前等待的秒数（默认：60）
FARO_PDF_OCR_RATIO：用于混合文档（文本和图像）的 PDF 在强制 OCR 时的字节/字符比（默认：150 字节/字符）

日志配置也可以通过环境变量进行配置：

FARO_LOG_LEVEL：Faro 日志级别（默认：INFO）
FARO_LOG_FILE：Faro 日志文件（默认：None）。使用 Docker 时，请确保将其设置在 output 文件夹内，以便在宿主机上持久化。

单个文件检测

您可以使用我们的 faro_detection.py 脚本对单个文件执行 FARO 检测

./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 实体检测器执行两个步骤：

提取敏感指标：指标是实体和其他文本元素（例如货币数量），它们很可能出现在敏感文档中。

指标列表如下：

person_position_organization：这是从文档中提取并链接在一起的一组实体（人、职位、组织）。
monetary_quantity：货币数量（目前仅支持欧元和美元）。
signature：输出文档的签署人
personal_email：非企业邮箱（例如不是 info@ rrhh@ 等）
mobile_phone_number：手机号码（过滤掉非手机号码）
financial_data：信用卡和 IBAN 账号
document_id：西班牙 NIF 和 CIF。

这些句子的唯一计数被收集到 json 对象中，并作为下一步的输入。

对文档的敏感度进行评分：应用分类规则（使用阈值）对阶段 1 中提取的指标进行敏感度评分。

应用以下规则：

每个敏感度级别为敏感度指标设置阈值。文档必须至少满足其中一个阈值（最小值和最大值）才能获得该评分。
如果文档中出现不同的敏感度阈值（当前配置为三个），即使不满足该级别的所有阈值，文档的敏感度评分也会升级。
对于未检测到任何敏感指标的文档，也会分配 "low" 评分。

配置

它使用一组 YAML 文件来配置其功能（YAML 文件位于 "config" 文件夹中）。

common.yaml：包含所有语言的通用功能
.yaml：包含特定语言的配置（目前仅支持西班牙语："es" 代码）。它还指示 ML 模型的位置（例如，默认在 "models" 文件夹内）。

敏感度评分配置

这些是一组条件，按照配置文件的规范选择评分。级别在 sensitivity_list 中按强度排序（从低到高）。sensitivity dict 包含按实体类型排序的条件（min, max）。系统只需满足某个级别的一个条件即可将该文档标记为该敏感度级别。此外，如果在文档中找到某个级别的多个 KPI（如 sensitivity_multiple_kpis 参数所标记），系统将提高其敏感度级别（例如从中等提高到高）。

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 是一个 dict，包含必须满足的敏感度条件才能达到特定敏感度级别。

支持的输入文件格式

FARO 应用程序使用 Tika 进行文档处理。因此，Tika 处理的所有格式都可以用作输入。不过，用于批量处理的 faro_spider.sh/faro_spider.bat 脚本仅限于以下扩展名：.doc、.docx、.pptx、.ppt、.xls、.pdf、.odt、.ods、.odp、.txt 和 .rtf。

技术

FARO 使用 NER（基于 CRF 构建）来提取经典实体（人物、组织和地点）以及职位。

其他指标通过正则表达式提取（文档 ID、电话号码和信用卡号码等）。

邮件通过正则表达式提取。使用 ML 分类器和启发式方法区分企业邮箱和个人邮箱。

测试

FARO 有几个测试来验证系统的功能（目前测试仅覆盖正则表达式）。可以使用以下命令执行测试：

python test_suite.py

Faro 检测附加参数

--dump：系统将 <your_file>.score 的信息以 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 大文件存储）。

Linux

在 https://git-lfs.github.com/ 下载软件包并按照安装说明进行操作。

Windows

在 Windows 上安装 "git bash"（请参阅此链接中的 Windows 部分：https://git-scm.com/downloads），然后访问 https://git-lfs.github.com/ 并按照安装说明进行操作。

Mac OS

brew install git-lfs
git lfs install

将创建一个 models 文件夹，其中包含所有模型。

已知问题

完整功能仅适用于西班牙语文档，但可以轻松扩展以支持新语言（特别是如果使用 SpaCy 支持，SpaCy 是用于处理句子和文档的 NLP 工具）。
系统使用 SpaCy 进行解析和词性句子预处理。虽然 SpaCy 为经典实体提供了训练好的 NER 系统，但自定义 NER 用于提取经典实体（人物、组织、地点）以及专业/职位。

贡献者

TEGRA 是一个位于西班牙加利西亚的 R&D 网络安全中心。它是 Telefónica（一家领先的国际电信公司，通过其全球网络安全部门 ElevenPaths）和 Gradiant（一个拥有 100 多名专业人员的 ICT 研发中心，研究领域包括连接性、安全和智能）的共同努力，旨在创建网络安全领域的创新产品和服务。

TEGRA 的工作专注于网络安全领域的两大方向：数据安全和安全分析。我们致力于创造最先进的技术，以培育并为我们产品提供差异化价值。

请参阅 CONTRIBUTORS 文件。

FARO

最受欢迎

FARO（文档敏感度检测器）

目录

这是什么

这里有什么？

使用 Docker 运行 FARO

从 Docker Hub 获取 FARO 镜像

构建 FARO 镜像

运行 FARO 容器

结果

在宿主机上运行 FARO

前提条件

虚拟环境

依赖项

NER 模型

FARO Spider

单个文件检测

技术细节

FARO 实体检测器

配置

敏感度评分配置

支持的输入文件格式

技术

测试

Faro 检测附加参数

安装 Git-lfs

Linux

Windows

Mac OS

已知问题

贡献者