docs-masked

ドキュメントを言語モデルに送信する前にローカルで匿名化し、応答後に元に戻します。

ドキュメントは元の状態でマシンから送出されることはありません。個人データは永続的なタグ（#PERSON_1#、#PHONE_2#、#ADDRESS_1#）に置き換えられ、モデルにはタグ付きのテキストのみが送信され、受け取った応答はローカルの対応ファイル（セーフ）を使って復元されます。

документ ──▶ маска ──▶ контроль утечки ──▶ модель ──▶ обратная подстановка
           локально      локально          сеть           локально

これはClaude Codeのスキル、他のエージェント向けのMCPサーバー、および通常のコマンドラインユーティリティとして機能します。

仕組み

1. マスキング. ドキュメントは段落、セル、マークアップノードなどのテキスト断片に分解されます。それぞれから個人データが検出され、各値に永続的なタグが割り当てられます。同一人物にはドキュメント全体で同じタグが付与され、格変化やイニシャルも考慮されます。「Иванов Иван Иванович」、「Иванову」、「Иванов И.И.」はすべて同じ #PERSON_1# になります。

2. 漏洩チェック. マスクされたテキストはすべての検出器とパラノイアモードのパスで再度スキャンされます。@、7桁以上の数字列、電話番号パターンなどが残っている場合、ログへの警告ではなく例外により送信がブロックされます。

3. 送信. 外部に送信されるのはタグ付きテキストのみです。唯一のネットワーク出口は llm.send() 関数であり、この関数はリクエスト前にチェックを実行する必要があります。各送信は ~/.pii_shield/egress.jsonl に記録されます（時刻、プロバイダ、モデル、サイズ、sha256、チェックステータス）。内容自体は記録されません。

4. 復元. モデルの応答はセーフを通して処理され、タグが元の値に置き換えられます。氏名（ФИО）については、復元された主格が使用されます。ドキュメント内で「Кузнецову Ивану Петровичу」としか言及されていなかった場合でも、応答では「Кузнецов Иван Петрович」になります。

Related MCP server: Doc Sanitizer MCP Server

インストール

git clone https://github.com/kpshinnik/docs_masked.git ~/.docs_masked/src
cd ~/.docs_masked/src && ./install.sh

スクリプトが依存関係をインストールし、スキルを ~/.claude/skills/docs-masked に配置し、完成したMCP設定の断片を出力します。詳細とオプションについては、docs/INSTALL.md を参照してください。

エージェントへの接続

各ハーネスの詳細な手順については、docs/HARNESSES.md を参照してください。

MCPサーバーは依存関係なしで書かれています。必要なのは python3 のみです。mask_text、unmask_text、verify_text、scan_document、mask_document、unmask_document の6つのツールを提供します。

使用法

docs-masked scan   договор.docx                    # что будет скрыто
docs-masked mask   договор.docx                    # маска + сейф
docs-masked report договор.docx --open             # посмотреть глазами
docs-masked ask    договор.docx -p "Найди риски по срокам"
docs-masked unmask договор.masked.docx --vault договор.docx.vault.json

コマンド

全フラグのリストは skills/docs-masked/references/cli.md を参照してください。

認識されるもの

氏名（ФИО：ロシア語、ラテン文字、翻字）、組織、住所、メール、電話、パスポートおよび発行元コード、SNILS、INN、OGRN、KPP、BIK、決済口座、銀行カード、IBAN、OMS保険証、運転免許証、自動車ナンバー、IPアドレス、@ニックネーム、生年月日および書類発行日、詳細コード（OKTMO、OKPO、KBK）、およびユーザー定義の文字列。

識別子は実際に検証されます：SNILSのチェックサム、INNおよびOGRNのチェックディジット、カードのLuhnアルゴリズム、IBANのmod-97。完全な表は references/coverage.md を参照してください。

フォーマット

DOCXは document.paragraphs ではなくXML経由で処理されます。そうしないと、コンテンツコントロール内やテキストボックス内の段落が失われるためです。実際の契約書では、これにより詳細ブロックの列全体が欠落していました。テーブルでは、列ヘッダーがコンテキストとして使用されます。セル 500100732259 はそれだけではランダムな数字と区別がつきませんが、「INN」列にある場合は確実に認識されます。

Python API

from pii_shield import ask_document

res = ask_document("договор.docx", "Составь резюме и найди риски",
                   provider="anthropic")
print(res.answer)          # имена уже восстановлены

各ステップを手動で制御：

from pii_shield import mask_text, assert_clean, unmask_text

r = mask_text(raw)                 # r.text — с тегами, r.vault — сейф
assert_clean(r.text)               # LeakGuardError, если что-то осталось
answer = call_model(r.text)        # наружу уходит только маска
final, unknown = unmask_text(answer, r.vault, mode="canonical")

詳細は references/api.md を参照してください。

セーフ（対応ファイル）

セーフは、タグと元の値を結び付ける唯一のものです。これなしでは復元は不可能です。

• ドキュメントと同じ場所に <ファイル>.vault.json として作成され、パーミッションは 0600 に設定されます。

• --pass-env フラグで暗号化されます（scrypt + Fernet）。

• 正準形、出現したすべての異形、およびドキュメント内での出現順のログを保持します。ログにより、正確な復元では元の語形（正準形ではなく）が返されます。

• .gitignore に追加されています。コミットしないでください。

精度と限界

このツールは安全側に誤るように設計されています。つまり、見逃すよりも余分にマスクする方が望ましいです。注意点：

• テキスト層のないスキャンPDFは処理されません。OCRが必要です。

• イニシャルのない同姓の人物は別々のタグが割り当てられ、同一人物として統合されません。

• ヒントのない裸の数字は識別子として認識されない可能性がありますが、パラノイアモードのパスにより、そのようなテキストが外部に漏れることはありません。

• スラブ語の語尾や敬称（Mr.、Dr.）のない任意のラテン文字名は認識されません。任意の大文字2単語を捕捉すると、害の方が大きくなるためです。

重要なドキュメントでは、docs-masked report を一度目視確認することをお勧めします。

開発

python3 -m pytest tests/ -q          # тесты
python3 -m pii_shield.cli selftest
python3 samples/make_samples.py      # пересоздать тестовые документы

破ってはいけない不変条件は AGENTS.md にリストされています。samples/ 内のすべては合成データです。examples/ ディレクトリはローカルドキュメント用に予約されており、リポジトリには含まれません。

ライセンス

MIT。