Redact MCP

Redact MCP — Claude Code のための PII 自動難読化

Claude が目にする前に機密データを自動検出して難読化する MCP サーバー（および Claude Code プラグイン）です。正規表現パターンマッチングと**AI を活用した固有表現認識（NER）**を使用して、IP アドレス、ホスト名、メールアドレス、API キー、人物名、組織名、場所、秘密鍵、接続文字列などを検出します。

クライアントのデータを第三者に公開することなく、Claude の分析機能を活用したいペネトレーションテスター向けに構築されています。

仕組み

Raw data with real PII ──► Regex + NER detection ──► Claude sees only fake values
                                                              │
Final report for client ◄── Real values restored ◄── /redact:export

サーバーは双方向のマッピングテーブルを管理します。各機密値には、一貫性のある決定論的な偽の値が割り当てられ、セッション全体で維持されます。

実際の値	難読化後の値	検出方法
10.50.1.100	198.51.100.1	正規表現
api.clientcorp.com	target-1.example.com	正規表現
[email protected]	[email protected]	正規表現
AKIA3EXAMPLE...	[REDACTED_AWS_KEY_1]	正規表現
James Wilson	Person_A Person_B	NER
Microsoft	Org_A	NER
Seattle	City_A	NER
postgres://admin:pw@host/db	[REDACTED_CONN_STRING_1]	正規表現
-----BEGIN RSA PRIVATE KEY...	[REDACTED_PRIVATE_KEY_1]	正規表現

同じ実際の値には、常に同じ偽の値が割り当てられます。obfuscate(text) -> deobfuscate(result) === text が保証されます。

インストール

npx によるクイックインストール（推奨）

claude mcp add @mattzam/redact-mcp -- npx @mattzam/redact-mcp

これで完了です。Claude Code は各セッションで npx 経由でサーバーを起動します。NER モデル（約 110 MB）は初回使用時に自動ダウンロードされ、以降の実行に備えてキャッシュされます。

監査ログを有効にするには、次のようにします。

claude mcp add @mattzam/redact-mcp -e REDACT_AUDIT_LOG=true -- npx @mattzam/redact-mcp

Claude Code プラグインとしてインストール（フル機能：フック＋スキル）

git clone https://github.com/r3352/redact-mcp.git redact
cd redact/server
npm install
npm run build
cd ../..

# Load as a plugin (includes hooks for leak detection + slash commands)
claude --plugin-dir ./redact

プラグインモードでは、MCP サーバーに加えて、フック（ツールの生の出力を自動的に漏えい検出）とスキル（/redact:status、/redact:add、/redact:export）が追加されます。

MCP の手動設定

Claude Code の MCP 設定（~/.claude/mcp.json またはプロジェクトの .mcp.json）に追加します。

{
  "mcpServers": {
    "redact-server": {
      "command": "npx",
      "args": ["redact-mcp"],
      "env": {
        "REDACT_DATA_DIR": "/path/to/data/directory",
        "REDACT_AUDIT_LOG": "true"
      }
    }
  }
}

環境変数

変数	デフォルト	説明
REDACT_DATA_DIR	./data	マッピング状態と監査ログの保存ディレクトリ
REDACT_AUDIT_LOG	false	JSONL 監査ログを有効にするには true に設定します

検出対象

正規表現パターン（19 種類）

設定は不要です。次の項目が自動的に検出されます。

カテゴリ	種類
ネットワーク	IPv4（プライベート＋パブリック）、IPv6、有効な TLD を持つホスト名、MAC アドレス
ID 情報	メールアドレス、人物名（JSON コンテキスト内）、電話番号（米国＋国際）、SSN
シークレット	AWS アクセスキー、JWT、Bearer トークン、API キー（コンテキストを考慮）、一般的なシークレット（password=、secret=）、秘密鍵（PEM 形式）、接続文字列（postgres/mysql/redis/mongodb/amqp/mssql URI）
金融情報	クレジットカード番号（Luhn アルゴリズムで検証）
物理情報	住所（123 Main Street、456 Oak Ave など）

NER 検出（AI を活用）

@huggingface/transformers がインストールされている場合（デフォルトで含まれます）、サーバーは Xenova/bert-base-NER（約 110 MB の ONNX モデル。初回使用時にダウンロード）を読み込み、次の項目を検出します。

エンティティの種類	例	難読化後の値
人物名	James Wilson	Person_A Person_B
組織	Microsoft、Acme Corp	Org_A、Org_B
場所	Seattle、New York	City_A、City_B

NER は、正規表現では検出されないエンティティ（JSON コンテキスト外の人物名や組織名、任意の地名など）を検出します。正規表現と NER の両方が同じ範囲を検出した場合は、常に正規表現の結果が優先されます（構造化パターンの検出精度は正規表現の方が高いためです）。

問題発生時のフォールバック： モデルの読み込みに失敗した場合やパッケージが見つからない場合、サーバーはエラーを出さずに正規表現のみのモードで動作を続けます。

スマートパススルー

以下の値は難読化されません。

• ループバック／予約済み： localhost、127.0.0.1、::1、0.0.0.0
• RFC のドキュメント用範囲： 192.0.2.x（TEST-NET-1）、198.51.100.x（TEST-NET-2）、203.0.113.x（TEST-NET-3）、2001:db8::（IPv6 のドキュメント用）
• サンプルドメイン： example.com、example.org、example.net
• 開発用ドメイン： github.com、npmjs.com、nodejs.org、googleapis.com など
• セキュリティテスト： burpcollaborator.net、oastify.com
• コードパターン： console.log、process.env、package.json、webpack.config、jest.config、tailwind.config、およびその他 30 種類以上の一般的な誤検知
• ブロードキャスト MAC アドレス： FF:FF:FF:FF:FF:FF、00:00:00:00:00:00

MCP ツール

このサーバーは、MCP 経由で 8 個のツールを登録します。

ツール	説明
redact_obfuscate	テキスト内のすべての PII を自動検出して置換します（正規表現＋NER）
redact_deobfuscate	すべての置換を元に戻し、実際の値に戻します
redact_proxy_request	HTTP プロキシ — リクエストを難読化解除し、実際の呼び出しを行い、レスポンスを難読化します
redact_read_file	ファイルを読み取り、難読化された内容を返します
redact_add_mapping	実際の値から偽の値へのマッピングを手動で追加します
redact_remove_mapping	マッピングを削除します（誤検知を修正）
redact_show_mappings	現在のすべてのマッピングを種類別にまとめて表示します
redact_audit_log	最近の監査ログエントリを表示します（REDACT_AUDIT_LOG=true が必要です）

redact_proxy_request — 主要なツール

ペンテストのワークフローでは、これが重要なツールです。Claude は curl/fetch の代わりにこれを呼び出します。

1. Claude が URL／ヘッダー／本文を指定します（すでに難読化された値が含まれている場合があります）
2. サーバーがリクエストを難読化解除します（実際のホスト名／IP／トークンを復元します）
3. ターゲットに対して実際の HTTP リクエストを行います
4. レスポンス全体（ヘッダー＋本文）を難読化します
5. サニタイズされたレスポンスを Claude に返します

Claude が実際のレスポンスデータを見ることはありません。難読化解除と難読化のすべての手順は監査ログに記録されます。

redact_audit_log — コンプライアンス監査証跡

REDACT_AUDIT_LOG=true の場合、すべての難読化および難読化解除の操作が ${REDACT_DATA_DIR}/audit.jsonl に記録されます。各エントリには次の情報が記録されます。

• タイムスタンプと操作の種類（obfuscate、deobfuscate、proxy_request、file_read）
• 入力テキスト全体（変換前の生データ）
• 種類、実際の値、偽の置換値、ソース（regex または ner）を含むすべての検出結果
• 出力テキスト全体（変換後の結果）

これにより、何が入力され、何が変更され、何が出力されたかを完全に記録した監査証跡を提供します。

redact_audit_log ツールを使ってエントリを表示するか、audit.jsonl を直接読み取ってください。

# Last 5 entries, pretty-printed
tail -5 data/audit.jsonl | python3 -m json.tool

セキュリティに関する注意： 監査ログには、設計上、実際の機密データが含まれます（何が秘匿化されたかを証明することが目的です）。適切に保護してください。

スキル（スラッシュコマンド）

コマンド	説明
/redact:status	現在の秘匿化マッピングを種類別にまとめて表示します
/redact:add <real> <fake>	マッピングを手動で追加します（例：/redact:add clientcorp.com target.example.com）
/redact:export <file> [output]	クライアントへの納品用にファイルの難読化を解除します（デフォルトは ~/Desktop/）

フック

このプラグインは、2 つのフックを使用します（自動で実行され、ユーザーの操作は不要です）。

• SessionStart — すべてのデータを redact ツール経由で処理するよう Claude に指示を挿入します
• PostToolUse — Claude が生の Bash／Read／Grep／WebFetch を使用し、出力に既知の機密値が含まれている場合に警告します（漏えい検出）

パイプラインの仕組み

検出

1. 正規表現パス — コンパイル済みの RegExp を使用して、19 種類のパターンを同期的にスキャンします
2. NER パス — Xenova/bert-base-NER を並行して（非同期で）実行し、人名／組織／場所のエンティティを検出します
3. マージ — 結果を統合します。重複する範囲では正規表現の一致を優先します（構造化データの検出精度が高いため）
4. 重複排除 — 正規表現の一致と同じ範囲をカバーする、重複した NER の結果を除外します

マッピング

1. 一意な実値ごとに、カウンターベースの生成で決定論的な偽値を割り当てます
2. 偽値には安全な範囲を使用します：IPv4 は TEST-NET-2、IPv6 は RFC 3849、ドメインは example.com、電話番号は 555 プレフィックス、MAC アドレスはローカル管理範囲です
3. マッピングは ${REDACT_DATA_DIR}/mappings.json に保存され、書き込みはデバウンスされます（500ms）
4. 長い値から順に置換することで、部分一致による破損を防ぎます（例：10.50.1.10 より先に 10.50.1.100 を処理）

ラウンドトリップ保証

すべての入力で deobfuscate(obfuscate(text)) === text が成立します。双方向マッピングテーブルにより、損失のない復元が可能です。

アーキテクチャ

redact/
├── .claude-plugin/plugin.json     # Plugin manifest
├── .mcp.json                      # MCP server config (stdio transport)
├── hooks/
│   ├── hooks.json                 # Hook definitions
│   └── scripts/
│       ├── session-start.sh       # Injects redaction context on session start
│       └── post-tool-scan.py      # Leak detection on raw tool output
├── skills/
│   ├── status/SKILL.md            # /redact:status
│   ├── add/SKILL.md               # /redact:add
│   └── export/SKILL.md            # /redact:export
└── server/
    ├── package.json               # v2.0.0, deps: @modelcontextprotocol/sdk, @huggingface/transformers
    ├── tsconfig.json              # ES2022, Node16 modules, strict
    └── src/
        ├── index.ts               # MCP server — 8 tools, server instructions
        ├── mapping-engine.ts      # Bidirectional mapping, async obfuscate/deobfuscate, audit integration
        ├── pattern-detector.ts    # 19 regex patterns + async NER merge
        ├── fake-generator.ts      # Deterministic counter-based fake value generation
        ├── ner-detector.ts        # Lazy-loaded HuggingFace NER with graceful fallback
        ├── audit-logger.ts        # JSONL append logger, serialized write queue
        └── persistence.ts         # JSON state file with debounced writes

ランタイムフロー

Claude Code ──stdio──► MCP Server (index.ts)
                            │
                     CallToolRequest
                            │
                    ┌───────┴───────┐
                    │ MappingEngine │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
        detectPatterns   NER detect   AuditLogger
        (regex, sync)   (async)      (JSONL, async)
              │             │             │
              └─────────────┼─────────────┘
                            │
                     merge + dedupe
                            │
                     apply mappings
                     (longest-first)
                            │
                     return to Claude

開発

cd server

# Install dependencies (~110MB for NER model on first run)
npm install

# Build TypeScript
npm run build

# Test MCP server starts and lists tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

# Quick obfuscation test
node -e '
const { MappingEngine } = await import("./dist/mapping-engine.js");
const engine = new MappingEngine("/tmp/redact-dev");
await engine.init();
console.log(await engine.obfuscate("Email [email protected] from 10.0.0.1"));
'

変更履歴

v2.0.0

• NER 検出 — @huggingface/transformers と Xenova/bert-base-NER を利用した AI によるエンティティ認識です。構造化 JSON のコンテキスト外にある人名、組織、場所を検出します。
• 監査ログ — オプトインの JSONL 監査証跡（REDACT_AUDIT_LOG=true）により、すべての難読化および難読化解除操作について、入力／出力テキスト全体、検出元を含むすべての検出結果、タイムスタンプを記録します。
• 7 種類の新しいパターンタイプ — organization、location、private_key、connection_string、generic_secret、mac_address、street_address
• 8 番目のツール — 監査ログの確認に使用する redact_audit_log
• 電話番号検出の改善 — 国際形式（+CC-XXXX-XXXX）に対応しました
• 誤検出リストの拡充 — webpack.config、jest.config、tailwind.config と、その他 9 種類の設定ファイルパターンを追加しました

v1.0.0

• 正規表現のみの検出（12 種類のパターンタイプ）、7 つの MCP ツール、双方向マッピング、永続化、フック、スキルを備えた初回リリースです。

ライセンス

MIT