obsify

obsify

生の値がモデルのコンテキストに入ることなく、AI アシスタントが機密ファイルを扱えるようにします。

obsify はローカルで動作する決定論的なMCP サーバーです。フロンティアモデルは構造（スキーマ、合成データ、マスキングされたフィードバック）を基に推論し、決定論的なローカルコードが実データを扱って、マスキング・集計した結果だけを返します。実行時に LLM の呼び出しやネットワーク通信はありません。検出には、正規表現、チェックサム、辞書、およびPresidio のローカル NER を使用します。

オーストラリアのエンティティ（チェックサム検証済みの ABN／ACN／TFN）に加え、認証情報／シークレットの検出（クラウドキー、API トークン、秘密鍵、DB 接続文字列）と、ラベル駆動のルーティングレイヤーを備えています。これにより、「アシスタントが生データを避けるべきタイミング」を、判断に委ねず、決定論的に強制できます。

適用範囲について： run_on_real は、モデルが作成したコードをローカルのサンドボックスでベストエフォートで実行し、その出力をベストエフォートでマスキングします。これは隔離環境ではありません。漏洩が許されないデータを扱う前に、SECURITY.md をお読みください。集計結果を返してください。

概要

機密文書をホスト型 LLM に渡すと、実データが組織の管理範囲外に出てしまいます。よくある答えは「LLM を使わない」か「プロバイダーを信頼する」です。obsify は第三の道、データへの計算の持ち込みを採用します。データをモデルに持ち込むのではなく、コードをデータに持ち込みます。

• モデルに見えるのはスプレッドシートのスキーマであり、行データではありません。
• モデルは、実際の構造を保った合成データ（値は偽装）を使って開発します。
• モデルの分析コードはローカルで実行され、マスキング・集計された出力だけが返されます。

フロンティアモデルの推論能力は保たれます。取り除かれるのは、生の値を直接見ることだけです。

ツール

ツール	内容	戻り値
scan_pii(path)	ファイル／フォルダーをスキャンして PII を検出します	種類、位置、件数 — 値は決して返しません
make_synthetic_twin(path, out)	Excel ワークブックの忠実な偽データを作成します	スキーマの概要。偽装した値を漏洩検証済みの合成データにして out に書き込みます
run_on_real(code, data_path)	データへの計算の持ち込み：実ファイルに対してコードをローカルで実行します（DATA_PATH にバインド）	PII をマスキングし、サイズを制限した stdout/stderr のみ — 集計結果を返してください
redact_text(text)	文字列内の PII を <TYPE> トークンにマスキングします	マスキング後の文字列
verify_value_free(text, terms)	text に terms（またはその変化形）が漏れていないことをフェイルクローズで確認します	{"value_free": bool}

対応ドキュメント： PDF（テキスト＋表。複雑な表には obsify[tables] によるフォールバックを利用）、Excel .xlsx／.xlsm、Word .docx（段落＋表）。読み取れないファイルや未対応のファイルは、明示的な注記／検出漏れとして報告し、黙って除外することはありません。（OCR にはまだ対応していません。スキャン画像のページは文字起こしされず、カバー率が低いものとしてフラグ付けされます。）

既知のエンティティのマスキング（任意）。 非表示にする名前のリストをローカルの .obsify.entities に用意すると、scan_pii／redact_text がそれらを決定論的に検出します。NER では見逃される接尾辞／略称の変化形（Brightwater Holdings Pty Ltd に対する BRIGHTWATER HLDGS P/L など）も KNOWN_ENTITY として検出します。リストはローカルに保たれ、モデルのコンテキストに入ることはありません。docs/known_entities.md をご覧ください。

デモ

公式のMCP Inspectorを使って、合成データを対象に5つのツールすべてを実際に試せます。

python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp

./corpus_demo/ledger.xlsx に対して scan_pii を呼び出し、値ではなく種類／件数／位置のみが返されることを確認してください。docs/verifying.md をご覧ください。

試してみる — 合成コーパス

3つの形式すべてにまたがる、架空ながらも現実的なコーパスを生成します（すべて合成データで、ABN／ACN／TFN はチェックサム検証済み）。そのうえで、ツールに読み込ませます。

pip install "obsify[demo]"                 # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo

複数シートからなる Excel の台帳（数値による誤検知が多発する内容）、PDF の業務委託契約書（文章＋試算表）、DOCX の監査メモ（段落＋ベンダー表）が作成されます。実データに触れることなく、scan_pii／make_synthetic_twin の動作を試すのに最適です。

MCP サーバーとしてインストールして実行する

Python 3.11 以降が必要です。obsify は stdio 経由で MCP を使用します。クライアントがローカルのサブプロセスとして起動するため、リモートでホストされることはありません。クライアントの設定にブロックを1つ追加すれば、MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、VS Code、など）に登録できます。

推奨 — uvx によるインストール不要の実行：

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["--from", "obsify", "obsify-mcp"] } } }

uvx は PyPI から obsify を取得し、必要に応じて実行します。恒久的なインストールは不要です。初回実行時に obsify は spaCy の NER モデル（en_core_web_lg、約560 MB）を一度ダウンロードしてキャッシュします。この処理で取得するのは公開モデルであり、ユーザーデータは送信されません（ダウンロードを禁止するには OBSIFY_AUTO_DOWNLOAD=0 を設定し、モデルを自分でインストールしてください）。2回目以降はすぐに起動し、完全にオフラインで動作します。

または、インストールする（pip／pipx）：

pipx install obsify        # isolated, on PATH  (or: pip install obsify)

続いて、インストールしたコマンドをクライアントに指定します。

{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }

クライアントを再起動すると、ツールが表示されます。オプションの追加機能：obsify[tables]（camelot＋Ghostscript による複雑な表を含む PDF のフォールバック処理）、obsify[compute]（pandas。run_on_real のコード内で使うと便利です）。

PATH に関する注意（「サーバーに接続できない」原因の第1位）： command は、クライアントから見える PATH 上で解決できる必要があります。GUI クライアントからは、仮想環境の PATH が参照できないことがあります。対処方法：uvx／pipx を使う（グローバルに解決可能です）か、絶対パス（macOS／Linux では "/path/to/.venv/bin/obsify-mcp"、Windows では "C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe"）を指定してください。

このリポジトリから実行する場合（PyPI 公開前）：

pip install "git+https://github.com/Formative-Sum41/obsify.git"   # gets `obsify-mcp` + `obsify`

ルーティング層 — 決めつけではなく、確実に制御する

「機密ファイルは読まずに手伝って」という要望への対応で難しいのは、いつ保護するかを判断することです。obsify はその判断をモデルから切り離し、実行環境に委ねます。

1. .obsify.json — パスを分類するラベルマニフェスト（public／confidential／restricted）。
2. obsify.guard（python -m obsify.guard として実行）— ラベル付きファイルの直接読み取りをブロックし（終了コード 2）、アシスタントに scan_pii／make_synthetic_twin／run_on_real を使うよう促す PreToolUse ガード。
3. 規約（CLAUDE.md 内）— ガードに阻止される前に、アシスタントが obsify を優先するためのものです。

コマンド1つで設定できます。

obsify init [--dir PATH] [--with-claude-md]

obsify init は設計上、既存の内容を破壊しません。管理するのはファイル1つだけで、残りについては貼り付け用のスニペットを提示します。

• .obsify.json — obsify が管理します。init が書き込みます（--force を指定しない限り上書きされません）。
• .claude/settings.json — ユーザーが管理するファイルです。init は PreToolUse フックのブロックを出力するだけなので、貼り付けてください。コードを実行するため、登録するかどうかはユーザーが決められます。
• CLAUDE.md — ユーザーが管理するファイルです。規約は任意で追加できます。デフォルトでは出力するだけです。--with-claude-md を指定すると、マーカーで囲まれた、繰り返し実行しても安全なブロックを追記し、既存の内容は上書きしません。

規約の全文： docs/obsify_routing.md。

検出の精度を保つ仕組み

• チェックサムで検証する識別番号。 ABN／ACN／TFNの候補は正規表現で抽出し、公式のチェックサムで確認します。そのため、無関係な数字が識別番号として報告されることはありません。
• コンテキストが必須のID。 ラベル語句（「TFN」「ABN」「BSB」など）が近くにある場合に限り、単独の数字をABN／ACN／TFNとして認識します。これにより、数値台帳で連番の仕訳IDが誤検出される問題を防ぎます。
• 文字を含まない値／数字を含むNERの抑制。 数字だけの値、金額、日付、英数字コードは、氏名や組織名として検出されません。文字を含む実際の氏名、メールアドレス、住所には影響しません。検証済みの、文字を含まないPIIは引き続き対象外です。対象は、チェックサムで検証されたID（ABN／ACN／TFN／Medicare）、Luhnアルゴリズムに適合するカード番号、有効なIPアドレス、BSBに隣接する口座番号、コンテキストまたは電話番号の形式で認識される電話番号です。ただし、小数点がある場合は電話番号ではなく金額として扱います。
• PIIだけでなく認証情報も検出。 クラウドキー（AWS／GitHub／Google／Slack／Stripe）、JWT、秘密鍵ブロック、DB接続文字列は、アンカー付きパターンによってCREDENTIALとして検出されます。ベンダーのプレフィックス（AKIA…、ghp_…など）や、キーワードで条件付けたsecret = <value>を使い、16進数やBase64の台帳列で誤検出が多発するエントロピー判定は使いません。秘密鍵はヘッダーだけでなくBEGIN…ENDブロック全体をマスキングするため、鍵の本文が残ることはありません。

測定精度

obsifyには、スコア付きの評価ハーネスが含まれています（eval/ — ラベル付きの合成コーパス、正解データ、リリース版検出器を対象とするスコアラー、さらに独立した第三者によるクロスチェック）。合成コーパスでの主な結果は、検出対象として想定された項目の再現率100％、数値誤検出を徹底検証するシートでの誤検出0件（グループ化された数値への対策を含む）、およびコンテキスト条件付きの単独IDを正しく抑制できたことです。Microsoftのpresidio-researchとの独立したクロスチェックでは、EMAIL／IBANが100％、PERSONが94％でした。

評価ハーネスは成果を上げました。実際の欠陥を発見し、それらは修正されました。 クレジットカード番号と電話番号が数値ノイズフィルターによって気付かれないまま抑制されていましたが、現在はチェックサム検証／電話番号の形式によって対象外となっています。また、Medicare、IPアドレス、生年月日、AUパスポート、運転免許証の認識器がありませんでしたが、現在はチェックサムまたはコンテキストを条件として追加されています。手法、数値、残ることが文書化されている不足項目（SWIFT／BIC、生年月日以外の日付）の全文は、eval/README.mdを参照してください。

テスト

pip install -e ".[dev]"
pytest tests/            # or run any file directly: python tests/test_obsify.py

13のスイート（88件のテスト）を、LinuxおよびWindows上のPython 3.11と3.12でCI実行します。

• mcp-protocol — stdio経由で実際のサーバーを起動し、MCPで通信します（Claudeのようなクライアントが使うのと同じ経路です）。5つすべてのツールが有効なスキーマで登録されること、呼び出しがJSON-RPCを通じて往復することを確認します。これには、scan_piiがエンドツーエンドで形状のみを返すことの確認も含まれます。
• checksums — 外部公開されたABN／ACN／TFNの計算例（有効なものと破損したもの）を基準としており、生成器と検証器が互いに依存する循環性を排除しています。
• obsify / twin / redaction — プライバシーに関する不変条件をテストします。形状のみの出力、情報が漏れないツイン、fail-closed方式のセルフチェックです。
• precision — 誤検出抑制機能が数値台帳のノイズを除去しつつ、実際の氏名は維持されることを確認します。
• credentials — アンカー付きのシークレットパターンがクラウドキー／トークン／JWT／秘密鍵ブロック／接続文字列を検出し、キーワードをアンカーとする汎用パターンが、エントロピー判定を使わずに文章中でも高い精度を保つことを確認します。
• routing — ガードによるブロック／許可の分類と、obsify initが非破壊的であるという仕様を確認します。
• corpus — 合成PDF＋Excel＋DOCXコーパスをエンドツーエンドでテストします。形式ごとの検出、DOCXの段落と表の抽出、全形式での形状のみの出力を確認します。
• evaluation — スコア付き評価ハーネスを回帰テストのゲートとして実行します（再現率、抑制、誤検出の徹底検証、不足項目）。
• robustness — 不正、サイズ超過、空、ネストされた、未対応の入力をクラッシュさせず、常に注記として報告するグレースフルデグラデーションを確認します。
• model / variants — 初回実行時のモデル自動ダウンロード処理と、verify_value_freeの内部でのバリアント正規化を確認します。

対話形式での検証（MCP Inspector）と、実際のクライアントを使った最終段階の確認については、docs/verifying.mdを参照してください。

関連プロジェクト

obsify は、「AI が機密データを安全に扱えるようにする」という課題に取り組む複数の MCP サーバーの 1 つです。主に相互補完的なアプローチで、同じ課題を異なる側面から解決します。それぞれの用途を把握しておくとよいでしょう。

ツール	アプローチ	最適な用途
obsify	検出＋形状の分離：モデルに見えるのは形状、合成データの双子、マスク済み集計値のみで、実際の値も偽の値も見せません	PII を事前に列挙できない、形式の整っていないドキュメント（PDF/Excel/DOCX）。値の厳格な分離や、保護するタイミングの強制が必要な場合
cloakbox	ポリシーに基づく事前サニタイズ：データベースを非識別化したコピーにトークン化し、モデルが自由にクエリできるようにします	参照整合性を保ったクリーンなコピーに対して豊富な分析（結合／集計）を行いたい、既知の構造化スキーマ
redact-mcp	可逆的な難読化プロキシ：モデルは一貫性のある偽データで作業し、プロキシツールが実際の API 呼び出しを往復処理します	モデルが現実的なデータを使って動作し、後から実データに戻す必要がある、ペンテストのワークフローやシークレット
cms-ai	エンタープライズ向けの墨消しサービス：REST/MCP の背後で Presidio + spaCy を使用し、多言語対応でスケーラブルです	UI と水平スケーリングに対応した、ホスト型の多言語墨消し API

obsify の特徴：モデルに生の値も、完全なミラーも渡さず、形状＋マスク済み集計値だけを扱わせるのは、この中では obsify だけです。これに、チェックサムで検証された識別子、認証情報の検出、決定論的なルーティングガード、そしてネットワーク通信なし／LLM 使用なしの厳格な保証が加わります。機密性の高い財務ドキュメント向けに調整された、最も厳格な分離を実現します。

正直なトレードオフ：obsify は、データの有用性よりも、値の分離を優先します。クリーンなコピーで参照整合性を保った分析（cloakbox）、可逆的な往復処理（redact-mcp）、または多言語対応のホスト型サービス（cms-ai）が必要な場合は、そちらのほうが適しています。これらは obsify と競合するのではなく、組み合わせて活用できます。

貢献

PR を歓迎します。セットアップ、マージの基準、そして譲れない不変条件（ライブラリ内で LLM を呼び出さない、実行時にネットワーク通信を行わない、実データを使わない、内容ではなく形状を扱う）については、CONTRIBUTING.md をご覧ください。セキュリティ上の問題については、SECURITY.md をご覧ください（非公開で報告してください）。

ライセンス

MIT — LICENSE をご覧ください。