方針パイプライン (YPP)
Yabanin 方針パイプライン(YPP)は、ゲートウェイのトラフィック上で動く、プログラム可能な検査と変換のコンベアです。宣言的な YAML 方針、外部 HTTP スキャナ、LLM ジャッジ、コンテンツミューテータ、条件分岐を、ゲートウェイミドルウェアという一箇所で組み立てて実行します。デフォルトではオフです。YABANIN_POLICY_MODE が未設定のとき、パイプラインランタイムは構築されず、リクエスト処理はこの機能のない導入とビット単位で同一です。
方針は組織スコープのセキュリティオブジェクトです。適用が読むのは policystore だけです。リクエストごとの(SDK が供給する)方針設定はないため、クライアントが管理者の方針を回避することはできません。
1. アーキテクチャ
pkg/pipeline pure core: payload/finding/result types, the Step
contract, YAML compilation, the execution engine.
No DB/HTTP/LLM/logging side effects.
pkg/pipeline/builtins 20 deterministic steps (15 detectors + 5 mutators).
pkg/pipeline/callout external HTTP detector/mutator steps (SSRF-guarded).
pkg/pipeline/llmjudge LLM-judge step through the gateway's own upstream pool.
pkg/pipeline/script `when` condition engines: expr (default), lua, starlark.
pkg/pipeline/streaming SSE primitives: prefix gate, chunk carry, final check.
pkg/policystore versioned policy storage + attachments (migration 0008).
gateway middleware the single integration point: compiles org policies per
version, runs attached pipelines on each hook (OP-8).
ゲートウェイは、プロセスごとに完全なステップレジストリを持つエンジンを 1 つ構築します。組み込みステップ、callout(外部送信 の許可リストが設定されている場合のみ)、llm_judge、builtin/toolpolicy のツールガード、decide 判定ステップ、何もしない route_hint プレースホルダ、および 3 つの条件エンジン(expr、lua、starlark)すべてです。
2. 概念
フックとペイロード種別
方針は、実行するゲートウェイの面(hooks)を宣言します。フックが、ステップに渡されるペイロード種別を決めます。
| フック | ペイロード種別 | 発火 |
|---|---|---|
pre_upstream | request | アップストリーム呼び出しの前 |
post_upstream | response | アップストリーム応答の後 |
stream_prefix | stream_prefix | バッファしたストリーム接頭辞(§7 を参照) |
stream_final | stream_final | ストリーム全体の集約 |
tool_pre | tool_args | ツール/MCP 呼び出しの前 |
tool_post | tool_result | ツール/MCP 呼び出しの後 |
ペイロードは、メッセージ一覧、生のボディ(stream_* ではチャンクテキスト)、読み取り専用のリクエストメタデータ(org、key、model、provider、ラベル、タグ)を運び、リクエストペイロードではアップストリームのリクエストヘッダも運びます。
アクションと合成
すべての検出結果は、固定の厳格さの尺度 deny > mask > flag > allow 上のアクションを 1 つ持ちます。
deny— リクエスト / ツール呼び出し / ストリームをブロックします(実行を短絡します)。mask— 続行しますが、変換後のペイロードだけを使います。flag— 変更せずに続行し、観察を記録します。allow— 対処するものはありません。
アタッチされた複数の方針がリクエストに一致すると、すべてが実行されます(アタッチメントの優先度順。組織 → キー → モデル)。検出結果は和集合になり、判定は観察されたうち最も厳しいものになり、最初の deny が残りの処理を短絡します(スキップされたステップもトレースに現れます)。バグのあるステップからの未知のアクションは deny として順位付けされます。フェイルクローズです。検出器は常に、方針の境界をまたいでも、最新の変換済みテキストを観察します。
すべての実行について、コンパイル済みの各ステップはちょうど 1 回ト レースされます(ran、skipped、error、timeout。所要時間とエラー付き)。判定ログはこの完全性に依存します。
モードとキルスイッチ
mode: enforce— 検出結果が判定を引き上げます。ミューテータはペイロードを書き換えます。mode: shadow— 方針は決して変換せず、判定も決して引き上げません。検出結果は「何が起きていたか」の差分のために記録されます。これが推奨される展開経路です(shadow → 判定ログの確認 → enforce)。
プロセス全体のキルスイッチ YABANIN_POLICY_MODE(デフォルトは off):
| 値 | 動作 |
|---|---|
off | ランタイムは構築されません。すべてのフックは何もしません(デフォルト) |
shadow | すべての方針がコンパイル時に shadow へ格下げされます |
enforce | 方針は保存されたモードで実行されます |
未知の値は警告付きで off に解決されます。ゲートウェイ自身が行うジャッジ呼び出しは内部マーカーを持ちます(§6.2)。ジャッジヘッダを提示する受信トラフィックは免除されず、拒否されます(§6.2)。
3. 方針 YAML(apiVersion ypp/v1)
1 ドキュメントにつき方針は 1 つです。コードとして管理する場合、ファイル名は方針の name と等しくなければなりません(§8)。実際に動く例は deploy/policies/_example/pii-guard.yaml と deploy/policies/_pack/ のパックにあります。
apiVersion: ypp/v1
kind: Policy
name: pii-guard # required identity (metrics, decision log)
mode: shadow # shadow | enforce
hooks: [pre_upstream] # at least one, no duplicates
steps:
- id: scan # parallel group head: the detectors below
parallel: [pii, secrets] # run concurrently, join before the next step
- id: pii
detector: builtin/national-pii
- id: secrets
detector: builtin/secrets
- id: verdict
decide: |
deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise
検証は厳格です。未知の YAML フィールドは読み込みエラーです。apiVersion は ypp/v1、kind は Policy でなければならず、name と mode は必須です。ステップ id は一意であり、すべてのステップは種別フィールドをちょうど 1 つ持ちます(detector | mutator | callout | llm_judge | decide | route_hint)。
ステップごとのオプション:
| フィールド | 意味 |
|---|---|
when | 任意の条件ソース(§4)。方針の読み込み時に 1 回コンパイルされます |
when_engine | 条件エンジンを固定します(expr/lua/starlark)。エンジンが複数登録されると必須です |
timeout | ステップごとの予算。Go の duration 構文(50ms、2s)。タイムアウトは on_error に従います |
on_error | fail_closed(デフォルト。失敗は拒否して短絡します)| fail_open | fail_open+flag(合成された step_error の flag 検出結果を追加します) |
parallel | このステップと同時に実行し、1 つの結合グループとする、この方針のステップ id。参加者はすべて検出器でなければなりません(グループは読み取り専用です。グループ内のミューテータはコンパイルエラーです)。入れ子はできません |
params | ステップファクトリのパラメータ(§5)。種別で予約されたキー(url、model、prompt_ref、expr、target)は衝突するとコンパイルエラーになります |
アタッチメント(方針の適用対象)は YAML ではなく方針とともに保存されます。git で宣言する照合ブロックは §8、管理 API は §9 を参照してください。
4. 条件(when)
when ソースは実行時に、それまでの実行の読み取り専用コンテキストに対して評価されます。記録された検出結果、ステップトレース(所要時間/結果)、リクエストメタです。コンパイルは方針の読み込み時にステップごとに 1 回行われます。登録されたエンジンがない条件は読み込みエラーであり、黙ってスキップされることはありません。条件 のエラーはステップの on_error モードに従います(デフォルトはフェイルクローズです)。
3 つのエンジンが同梱され、ゲートウェイによって登録されます。expr(最小限でループなし。想定されるデフォルト)、lua(命令予算付きでサンドボックス化された gopher-lua)、starlark です。エンジンは 1 つのインタフェースの背後で交換できます。言語を切り替えても YAML の方針モデルは変わりません。
decide ステップ種別は、エンジンに依存しない別の判定 DSL です(行ベースで、最初に一致したルールが採用されます)。
deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise
フィールドは category、severity、action、step、span です。演算子は == と matches(末尾 * の前方一致)です。otherwise 行はフォールバックを設定します(デフォルトは allow)。decide ステップは判定を引き上げるだけであり、変換も検出結果の追加も行いません。
5. 組み込みステップ
レジストリ名は凍結されています。方針は文字列でそれらを参照します。すべてのステップに共通する任意パラメータ:
kinds— 検査するペイロード種別を制限します(デフォルトは 6 種別すべて。JSON スキーマステップのデフォルトは出力種別であり、リクエスト専用ステップはrequestに固定します)。action— ステップの検出結果が持つアクション。flag(デフォルト)、mask、またはdeny(allowは検出器のアクションではありません)。ファクトリ検証の失敗は方針の読み込みエラーです。
検出器
| ステップ | カテゴリ | パラメータ(共通以外) |
|---|---|---|
builtin/national-pii | innsnils、pan、ru_passport、ogrn + BR/IN/MY/AE/ZA/NG/KE/EG の識別番号 | —(固定の RU + 9 法域セット。チェックサム/Luhn 検証) |
builtin/secrets | secret(+ 資格情報をキーとする JSON 値) | —(プロバイダのキー形状、PEM ヘッダ、JWT の形状。証拠は引 用されません — [REDACTED_SECRET]) |
builtin/injection | injection | —(RU + EN のプロンプトインジェクション語句) |
builtin/word-count | word_count | min、max(少なくとも 1 つの境界が必要。max が 0 なら無制限) |
builtin/char-count | char_count | min、max(ルーンであり、バイトではありません) |
builtin/sentence-count | sentence_count | min、max(オフラインの終端ヒューリスティック) |
builtin/contains | contains | words(必須のリスト)、mode は any|all|none(デフォルトは any)、case_insensitive(デフォルトは true) |
builtin/regex | regex | pattern(必須、RE2。入れ子の量指定子と展開爆弾は読み込みエラー)、invert、case_insensitive、max_input(デフォルト 1 MiB、上限 64 MiB。超過するとステップは失敗します) |
builtin/json-schema | json_schema | schema(必須のインライン JSON Schema。読み込み時にコンパイル) |
builtin/json-keys | json_keys | keys(必須のドット区切りパス)、mode は any|all|none(デフォルトは all) |
builtin/url-check | url | schemes(デフォルトは ["https","http"])、allow_hosts、deny_hosts(*.suffix ワイルドカード)。完全にオフラインであり、取得は行いません |
builtin/code-detect | code.<lang> | languages(sql|python|typescript の部分集合。デフォルトはすべて) |
builtin/language | language | allowed(ru|en|other の空でない必須の部分集合。文字体系優勢のヒューリスティック) |
builtin/model-whitelist | model | models(必須の glob パターン。未知または空のモデルは違反) |
builtin/metadata-required | metadata | keys(メタフィールド/ラベル)および/または labels(label=value の組)。少なくとも 1 つが必須 |
ミューテータ
| ステップ | 効果 | パラメータ |
|---|---|---|
builtin/redact | 実行の検出結果にある機微な範囲(および/または自身のパターン)を [REDACTED:<category>:n] トークンに置き換えます | categories(正確な名前、または末尾の .*)、patterns({category, pattern} のリスト)、max_input |
builtin/pseudonymize | 可逆の仮名化。範囲は安定した {{YPP_n}} エイリアスになります。置換は外向きのみであり、応答への逆置換はありません | categories、patterns、carry は none(デフォルト)|session、max_input |
builtin/header-rewrite | アップストリームのリクエストヘッダを編集します(削除は設定より先に適用されます。CRLF/NUL インジェクションは読み込みエラーです) | set(マップ)、remove(リスト)。リクエスト専用 |
builtin/model-rewrite | リクエストのモデルを書き換えます(データ境界の継ぎ目。PII を含むリクエストをリージョン内のモデルへ経路します)。すべての書き換えは model_rewrite の flag 検出結果として記録されます | to(必須)、from(任意の事前条件)。リクエスト専用 |
builtin/partials-substitute | {{partials.NAME}} トークンを置換します(1 回限り。再スキャンしません) | on_missing は skip(デフォルト)|error。ソースストアはサーバ側で接続されます(プロンプトスタジオ、§6.1) |
carry: session を指定した builtin/pseudonymize は、セッションキャリアを通じてエイリアスマップを永続化し、同じ原文がターンをまたいで同じエイリアスに対応するようにします。キャリアは、アップストリームまたはクライアントへ送出する前に取り除かれます。
ゲートウェイはさらに 2 つのステップ種別を登録します。builtin/toolpolicy(ツール方針 のツール呼 び出しガードレールをパイプラインステップにしたもの)と、decide / route_hint の継ぎ目ステップ(§4)です。route_hint は現在、何もしないプレースホルダです。経路の意味論は後の決定事項です。
6. 外部ステップ
6.1 Callout(HTTP 検出器/ミューテータ)
callout: ステップは、ペイロードの射影を外部スキャナへ POST し、応答を検出結果へ対応付けます(モード detect)。または、変換後の内容を適用して戻します(モード mutate)。
- id: presidio
callout: http://presidio.internal:3000/analyze
params:
mode: detect # detect | mutate
expose: messages # messages (default) | body | fields:a,b,c
response: findings # findings (default) | boolean (JSON true/false)
finding_category: presidio # default category for boolean mode
max_response_bytes: 65536
timeout: 250ms
on_error: fail_open+flag
射影(expose)は、ゲートウェイの外に出るものを制限します。messages はメッセージ内容を送ります(detect では \n で結合し、mutate ではメッセージごとに配列要素 1 つです)。body は生のボディを送ります(文書化されたリスクです。同じデータ領域に契約上拘束されたスキャナに対してのみ有効にしてください)。fields:a,b は、JSON オブジェクトボディのそれらのトップレベルフィールドのみを送ります。組織/キー/モデルのメタデータは外に出ません。
応答契約。 detect/findings は {"findings":[{"category","severity","action","span","evidence"}]} を期待します。category は必須であり、未知のアクションは deny として順位付けされます。detect/boolean は JSON の true/false を期待します。mutate は、射影と正確に一致する {"content": ...} で応答しなければなりません。メッセージ数が同じであること、ボディ文字列であること、またはキー集合が射影されたフィールド集合と等しいオブジェクトであることです。スキャナの判定(有効な 2xx)はエラーではありません。ネットワーク障害、非 2xx、契約違反、ブレーカによる拒否は、on_error に従うステップエラーです。
外部送信のセキュリティ(交渉の余地はありません)。 ステップが構築されるのは、運用者が YABANIN_POLICY_CALLOUT_ALLOW_HOSTS(カンマ区切りの正確なドメイン、または *.suffix)を設定したときだけです。すべての URL は、方針のコンパイル時にそのリストと照合されます。ダイヤル時に、SSRF ガードが DNS の応答を固定し、予約済みアドレス(ループバック、RFC1918、リンクローカル/クラウドメタデータ)をすべて拒否して、DNS リバインディングの窓を閉じます。リダイレクトはなく、再試行もなく、URL ごとのサーキットブレーカ、同時の同一呼び出しに対する singleflight による重複排除、ステップごとのタイムアウトがあります。許可リストがないと、callout 方針は読み込み時に失敗します。外部送信が運用者のリストより広くなることはありません。