FAROは、組織内の文書における機密情報を検出するためのツールです。複雑なデータ保護ツールの設定に多くの時間や費用をかけられない、機密文書を組織内で追跡したいと考えている小規模企業や個人を対象としています。
FAROは文書から感度指標（例：文書ID、金額、個人メールアドレス）を抽出し、文書内の指標の頻度と種類を用いて文書に感度スコア（低〜高）を付けます。
現在、このツールのすべての機能はスペイン語で書かれた文書を対象としていますが、より多くの言語に対応するよう簡単に拡張できます。
このツールは、TEGRA R&Dサイバーセキュリティセンターによって開発されています。
このプロジェクトには次のフォルダが含まれています：
faro/ ：これは主要機能を持つFAROモジュールです。config/：ここにyaml設定ファイルを置きます。言語ごとに1つのyamlファイルがあり（未検出言語に基本機能を提供する nolanguage.yaml が1つ追加）、全言語共通の設定を持つyamlファイル config/commons.yaml が1つあります。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の変更履歴です。FAROはDockerを使用してスタンドアロンコンテナとして実行できます。自分でイメージをビルドするか、Docker Hubリポジトリから取得できます。
Dockerがシステムにインストールされ実行されている場合は、次のコマンドを実行してDocker Hubから最新のFAROイメージを取得します。
docker pull gradiant/faro
Dockerイメージを実行するには、スクリプト docker_run_faro.sh（Linux/Mac OS）または docker_run_faro.bat（Windows）を使用します。これらはプロジェクトのルートまたは最新リリースにあります。
Dockerがシステムにインストールされ実行されている場合は、次の手順でFAROイメージをビルドします。
LinuxおよびMac OS
./docker_build_faro.sh
Windows
docker_build_faro.bat
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プロセスの一部のカスタマイズは、envファイルを使用して調整できます。このファイルのパスはスクリプトの2番目の引数として指定する必要があります。テンプレートとして機能するコメント付きの例をここに用意しました。
./docker_run_faro.sh <your folder with files> <path to env file>
例：
./docker_run_faro.sh ../data docker_faro_env_example.list
FAROは現在のフォルダ内に「output」フォルダを作成し、実行結果を2つのファイルに保存します：
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"}
注：LinuxおよびMac OS Xのみ
このモードが正しく動作するには、いくつかのOSとライブラリが必要です。
独立した仮想環境を使用することをお勧めします。virtualenvで仮想環境を作成するには、次のようにします。
virtualenv -p `which python3` <yourenvname>
ターミナルで仮想環境を有効にするには、次のように入力します：
source <yourenvname>/bin/activate
システムを起動して実行する最も簡単な方法は、次のように依存関係をインストールすることです。
pip install -r requirements.txt
依存関係のリストは次のとおりです：
以下の依存関係はテストに使用されます：
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.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>
2つの出力ファイルがパス <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エンティティ検出器は2つのステップを実行します：
指標のリストは次のとおりです：
これらの文の一意のカウントはJSONオブジェクトに収集され、次のステップへの入力として渡されます。
以下のルールが適用されます：
機能を設定するためにYAMLファイル群を使用します（YAMLファイルは「config」フォルダ内にあります）。
これらは、設定ファイルの仕様に従ってスコアを選択する条件の集まりです。レベルは sensitivity_list に強度順（低感度から高感度へ）で設定されます。 sensitivity ディクショナリには、エンティティのタイプごとに並べられた条件（最小、最大）が含まれます。システムは、その感度レベルで文書をフラグ付けするために、特定のレベルの条件を1つ満たすだけで済みます。さらに、文書内に特定のレベルの複数の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
....
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
--dump：システムは <your_file>.score の情報をCSV形式でstdoutにダンプします。例：出力例は次のようになります：
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 Large File Storage）をインストールする手順に従ってください。
https://git-lfs.github.com/ でパッケージをダウンロードし、インストール手順に従ってください。
Windowsに「git bash」をインストールし（このリンクのWindowsセクションを確認してください：https://git-scm.com/downloads）、その後 https://git-lfs.github.com/ にアクセスしてインストール手順に従ってください。
brew install git-lfs
git lfs install
すべてのモデルを含む models フォルダが作成されます。
完全な機能はスペイン語の文書でのみ動作しますが、新しい言語で簡単に拡張できます（特に、文書を処理するNLPツールであるSpaCyがサポートしている場合）。
システムは、構文解析と品詞（PoS）文の前処理にSpaCyを使用しています。SpaCyは古典的なエンティティ用のトレーニング済みNERシステムを提供しますが、古典的なエンティティ（人物、組織、場所）および職業/役職の抽出にはカスタムNERが使用されます。
TEGRAは、スペインのガリシアに拠点を置く研究開発サイバーセキュリティセンターです。これは、大手国際通信事業者であるTelefónicaが、そのグローバルサイバーセキュリティユニットであるElevenPathsと、接続性、セキュリティ、インテリジェンスなどの分野で100人以上の専門家が働くICT研究開発センターであるGradiantを通じて、サイバーセキュリティ分野における革新的な製品とサービスを生み出すための共同事業です。
TEGRAの活動は、サイバーセキュリティ分野の2つの領域（データセキュリティとセキュリティ分析）に焦点を当てています。私たちは、製品に育成価値をもたらし、差別化を提供できる最先端技術の創出に取り組んでいます。
CONTRIBUTORSファイルを参照してください。