ocultar-pii

Ocultar

Ocultar は、AI ワークフロー向けのオープンソースのローカル PII／PHI マスキングエンジンです。

ローカル HTTP サイドカーとして動作します。テキストがクラウド LLM に届く前に送信すると、個人データを決定論的で復元可能なトークン（[EMAIL_9c8f7a1b]、[PERSON_3a12b4cd] など）に置き換えた同じテキストを返します。元のデータは暗号化され、ローカルのボールトに保存されます。監査者トークンを持つ呼び出し元は、元のデータを復元できます。

PII がアップストリームのモデルに届くことはありません。

---

クイックスタート — Docker

export OCU_MASTER_KEY=$(openssl rand -hex 32)
export OCU_SALT=$(openssl rand -hex 16)
export OCU_AUDITOR_TOKEN=$(openssl rand -hex 24)

docker run --rm -p 4141:4141 \
  -e OCU_MASTER_KEY \
  -e OCU_SALT \
  -e OCU_AUDITOR_TOKEN \
  ghcr.io/ocultar-dev/ocultar:latest -serve 4141

クイックスタート — ソースからビルド

CGO_ENABLED=1 go build -o ocultar ./services/refinery/cmd/

OCU_MASTER_KEY=$(openssl rand -hex 32) \
OCU_SALT=$(openssl rand -hex 16) \
OCU_AUDITOR_TOKEN=$(openssl rand -hex 24) \
./ocultar -serve 4141

---

API リファレンス

GET /api/health

エンジンのステータスを返します。認証は不要です。

{
  "status": "healthy",
  "version": "1.14",
  "vault": { "status": "online" },
  "slm":   { "status": "online", "circuit": "closed" }
}

---

POST /api/refine

テキストまたは JSON 内の PII をマスキングします。認証は不要です。

リクエストボディ：生テキスト文字列または任意の JSON 値。

レスポンス：

{
  "refined": "{\"message\":\"Hello [PERSON_3a12b4cd], your order [EMAIL_9c8f7a1b] is ready.\"}",
  "report": {
    "hits": 2,
    "types": ["PERSON", "EMAIL"]
  }
}

refined は JSON エンコードされた文字列です。マスキングされたペイロードを取得するには、一度パースしてください。

---

POST /api/reveal

ボールト内のトークンを元のデータに戻します。

認証：Authorization: Bearer <OCU_AUDITOR_TOKEN> ヘッダーが必要です。 サーバーで OCU_AUDITOR_TOKEN が設定されていない場合は、403 を返します。

リクエストボディ：

{ "tokens": ["[PERSON_3a12b4cd]", "[EMAIL_9c8f7a1b]"] }

レスポンス：

{
  "results": {
    "[PERSON_3a12b4cd]": "Alice Martin",
    "[EMAIL_9c8f7a1b]": "[email protected]"
  }
}

---

GET /api/entities · POST /api/entities · POST /api/entities/seed

永続的なエンティティレジストリを管理します（正規名を事前登録すると、すべてのバリエーションが同じトークンに対応します）。Authorization: Bearer <OCU_AUDITOR_TOKEN> が必要です。

---

アーキテクチャ

Ocultar は、テキストがマシンの外に出る前に、2 段階の検出を実行します。

第 1 段階 — 決定論的な正規表現／ヒューリスティック（高速、外部送信なし）

サブ段階	シールド	検出対象
0	辞書	VIP の名前、configs/protected_entities.json に登録された組織名
0.5	パターン＋エントロピー	シャノン値によるスコアリングで検出する高エントロピー文字列（API キー、シークレット）
1	ルールエンジン	EMAIL、SSN、IBAN、クレジットカード、50 種類以上の国別 ID 形式
1.1	電話番号シールド	libphonenumber による検証
1.2	住所シールド	ヒューリスティックによる住所パーサー（EN／FR／ES／DE）
1.5	コンテキスト	挨拶、署名、疑問文に含まれる名前

第 2 段階 — SLM ベースの NER（再現率向上、エンドポイントを設定可能）

固有表現認識のために、テキストをローカル AI サイドカーに送信します。スキャナーは常に初期化されますが、互換性のあるサイドカーが SLM_SIDECAR_URL で稼働していない場合、結果は出力されません。NER を有効にするには、privacy-filter または llama.cpp のインスタンスを指定します。

SLM_SIDECAR_URL=http://localhost:8085 ./ocultar -serve 4141

llama.cpp／Qwen エンドポイントには SLM_ADAPTER=openai-chat を使用します。privacy-filter プロトコルを使用する場合は、設定せずにおきます（デフォルト）。

---

プライバシーモデル

• 外部送信ゼロの設計。 上流モデルに転送されるデータは、マスクされたトークン（[EMAIL_9c8f7a1b]、…）のみです。生テキストは送信されません。
• ローカルの保管庫のみ。 各トークンを元の値に戻すための対応関係は、AES-256-GCMとHKDF-SHA256を使用して暗号化されたDuckDBの保管庫（vault.db）に、ローカルファイルシステム上で保存されます。保管庫ファイルが送信されることはありません。
• 生のプロンプトの保持。 リファイナリーは監査差分ビューをサポートするため、マスクされていない生のプロンプトをすべてローカルの保管庫に記録します。このデータはトークンの対応関係とともに保存時に暗号化され、どこにも送信されません。プロンプトを保持しない場合は、OCU_AUDITOR_TOKENを設定しないでください。監査トークンがない場合、表示エンドポイントは403を返し、差分ビューにはアクセスできません。
• フェイルクローズ設計。 リファイナリーでエラーが発生した場合、または利用できない場合、ゲートウェイは5xxエラーを返して処理を停止します。フォールバックとして生テキストを転送することはありません。

---

設定

変数	必須	デフォルト	用途
OCU_MASTER_KEY	はい（本番環境）	安全でない開発用キー	HKDF用の32バイト以上のAESキーマテリアル
OCU_SALT	はい（本番環境）	組み込みのデフォルト値	デプロイごとのHKDFソルト
OCU_AUDITOR_TOKEN	はい	—	/api/revealおよび/api/entities用のベアラートークン
OCU_VAULT_PATH	いいえ	vault.db	DuckDB保管庫のファイルパス
SLM_SIDECAR_URL	いいえ	http://localhost:8085	Tier 2 NERサイドカーのエンドポイント
SLM_ADAPTER	いいえ	privacy-filter	サイドカープロトコル：privacy-filterまたはopenai-chat

---

ソースからのビルド

Go 1.24以降が必要です。CGOを有効にしてください（DuckDBとlibphonenumberにはCコンパイラーが必要です）。

git clone https://github.com/ocultar-dev/ocultar.git
cd ocultar
make build

テストを実行します：

CGO_ENABLED=1 go test ./...

---

ライセンス

Apache 2.0 — LICENSEを参照してください。