# LOG\_ONLY モードでポリシーをテストする ポリシーレベルのエンフォースメントモードを使用すると、 `ACTIVE`と を切り替える`LOG_ONLY`ことで、「このポリシーが適用されるとトラフィックにどのような影響がありますか？」という質問に答えることができます。ポリシー`LOG_ONLY`モードごとに、認可の決定に影響を与えることなく、実際のトラフィックでポリシーをテストできます。ポリシーは、すべてのリクエストを強制されたものとして評価しますが、結果をログに書き込むだけです。強制モードが であるポリシーの結果としてブロックまたは許可されるものはありません`LOG_ONLY`。結果を信頼したら、 に昇格します`ACTIVE`。 **Topics** + [LOG\_ONLY モードの仕組み](#how-log-only-mode-works) + [LOG\_ONLY ポリシーと LOG\_ONLY ポリシーエンジン](#log-only-policies-and-log-only-policy-engines) + [ポリシーの適用モードを設定する](#set-the-enforcement-mode-of-a-policy) + [LOG\_ONLY の結果を確認する](#observe-log-only-results) + [ポリシーを強制に昇格させる](#promote-a-policy-to-enforcement) + [LOG\_ONLY モードによるしきい値の選択](#choosing-a-threshold-with-log-only-mode) + [考慮事項と制限事項](#policy-log-only-considerations-and-limitations) ## LOG\_ONLY モードの仕組み ポリシーエンジンのすべてのポリシーには、 `ACTIVE`または のエンフォースメントモードがあります`LOG_ONLY`。デフォルトは `ACTIVE`であるため、既存のポリシー、および フィールドを指定せずに作成する新しいポリシーは、以前と同様に引き続き適用されます。ポリシーエンジンはリクエストを評価すると、`ACTIVE`ポリシーと`LOG_ONLY`ポリシーを並べて評価しますが、`ACTIVE`ポリシーにのみ適用します。 `ACTIVE` ポリシーは、AgentCore Gateway に返され、強制される決定を決定します。ポリシーエンジンは「default-deny」および「forbid-wins」セマンティクスを適用します。つまり、リクエストはポリシーが許可する場合にのみ許可され、アクティブなポリシーからの 1 つの禁止によって拒否されます。 `LOG_ONLY` ポリシーは同じリクエストに対して評価されますが、結果は別々に保持されます。トレースで報告され、Amazon CloudWatch メトリクスとして出力されます。これらは強制決定にまとめられることはありません。 | 強制モード | 各リクエストで評価されますか? | 返された決定に影響しますか? | | --- | --- | --- | | `ACTIVE` (デフォルト) | はい | はい | | `LOG_ONLY` | はい | いいえ | リクエストは 2 つの段階で評価されます。 1. ポリシーエンジンは決定を計算します。`ACTIVE` ポリシーのみがそれに寄与します。 `LOG_ONLY`ポリシーは個別に評価および報告されますが、考慮されることはありません。 1. エンジンが `ENFORCE`モードでゲートウェイに関連付けられている場合、ゲートウェイはポリシーエンジンの決定に従ってアクションを許可または拒否します。エンジンが `LOG_ONLY`モードでゲートウェイに関連付けられている場合、ゲートウェイはアクションを実行しません。決定は記録されますが、強制されません。 `ACTIVE` と `LOG_ONLY`は 2 つの独立したセットとして扱われます。1 つの`LOG_ONLY`ポリシーで発信者が経験する内容を変更することはできません。リクエストが受け取る決定は、`LOG_ONLY`ポリシーの影響を受けません。 リクエストで一致した`LOG_ONLY`ポリシーを記録するだけでなく、ポリシーエンジンは、これらのポリシーのうち、 であれば決定を変更したポリシーを報告します`ACTIVE`。これは、ポリシーの有効性と安全性 ( に昇格できるかどうか`ACTIVE`) を評価するときに使用する重要なシグナルです。たとえば、頻繁に一致し、決定フリップセットに表示される`LOG_ONLY`ポリシーは、監視ウィンドウ中にトラフィックをブロックします。各`LOG_ONLY`ポリシーは、他のすべての`LOG_ONLY`ポリシーとは独立して評価され、決定フリップポリシーのセットを決定します。ただし、各`LOG_ONLY`ポリシー評価では、現在のすべての`ACTIVE`ポリシーが考慮されます。 ## LOG\_ONLY ポリシーと LOG\_ONLY ポリシーエンジン AgentCore のポリシーには、LOG\_ONLY 値を使用する 2 つの個別のコントロールがあります。これらはさまざまなレイヤーで動作し、さまざまな質問に答えるため、設定しているレイヤーを理解することが重要です。 **ポリシーエンジンの適用モード:** エンジンの全体的な動作を制御します。に設定すると`LOG_ONLY`、個々のポリシーモードに関係なく、エンジン内のポリシーは適用されません。すべての決定がログに記録されます。これは、 `CreateGateway`または `UpdateGateway`オペレーションを使用してポリシーエンジンをゲートウェイに関連付ける`policyEngineConfiguration`ときに、 の `mode`フィールドを使用して設定されます。が`mode`受け入れる 2 つの値は`ENFORCE`、 (デフォルト) と です`LOG_ONLY`。 ポリシーモードは、強制エンジン内の単一のポリシーの動作を制御します。LOG\_ONLY に設定すると、そのポリシーは引き続き評価されますが、その決定は強制されるのではなくログに記録されます。エンジン内の他のすべての`ACTIVE`ポリシーは、引き続き通常どおり適用されます。が`enforcementMode`受け入れる 2 つの値は`ACTIVE`、 (デフォルト) と です`LOG_ONLY`。 ポリシーレベルの LOG\_ONLY を使用して、トラフィックに影響を与えずに本番環境で新しいガードレールをシャドウテストします。エンジンレベルの LOG\_ONLY を使用して、強制を有効にする前にすべてのポリシーの動作を確認します。
ポリシー適用モード
ACTIVE LOG_ONLY
ポリシーエンジンの強制モード ENFORCE 評価され、強制されます。リクエストをブロックまたは変更する場合があります。評価されましたが、強制されていません。決定はログに記録されますが、エンジン内の他のACTIVEポリシーは引き続き強制します。
LOG_ONLY 評価されましたが、強制されていません。決定はログに記録されます。評価されましたが、強制されていません。決定はログに記録されます。
**注記** ポリシーエンジンの適用モードが優先されます。ポリシーエンジンが LOG\_ONLY モードで関連付けられている場合、ゲートウェイはポリシーエンジンの決定にまったく対応しないため、`ACTIVE`強制モードのポリシーであっても、ゲートウェイアクションを拒否することはできません。エンジンは引き続き決定を計算し、`LOG_ONLY`テレメトリを受け取ります。決定は強制されません。 ## ポリシーの適用モードを設定する ポリシー ( `CreatePolicy`および ) を作成または更新するときに、ポリシーの `enforcementMode`フィールドを設定でき、 `UpdatePolicy``GetPolicy`および によって返されます`ListPolicies`。 **Create a policy in `LOG_ONLY` mode** `CreatePolicy`リクエスト`LOG_ONLY`で `enforcementMode`を に設定して、 `LOG_ONLY` モードでポリシーを作成します。次の例では、信頼度しきい値を超える暴力的なコンテンツを禁止するガードレールをポリシーに作成しますが、それのみを監視します。ポリシーのガードレールの詳細については、「 [ポリシーのガードレール](policy-guardrails-in-policies.md)」を参照してください。 ``` aws bedrock-agentcore-control create-policy \ --policy-engine-id my-policy-engine-id \ --name "LogOnlyViolenceFilter" \ --enforcement-mode LOG_ONLY \ --validation-mode IGNORE_ALL_FINDINGS \ --definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.7\")) };"}}' ``` レスポンスは、ポリシーを「enforcementMode」：「LOG\_ONLY」とエコーします。ポリシーはトラフィックに対して評価を開始し、その一致はトレースと CloudWatch メトリクスに表示され、決定には影響しません。 **ポリシーとその適用モードを一覧表示する** ListPolicies は各ポリシー概要`enforcementMode`で を返すため、どのポリシーが監視しているか、どのポリシーが強制しているかを一目で確認できます。 ``` aws bedrock-agentcore-control list-policies \ --policy-engine-id my-policy-engine-id \ --query 'policies[].{name:name,enforcementMode:enforcementMode,status:status}' ``` **レスポンス** ``` [ { "name": "LogOnlyViolenceFilter", "enforcementMode": "LOG_ONLY", "status": "ACTIVE" }, { "name": "RefundLimit", "enforcementMode": "ACTIVE", "status": "ACTIVE" } ] ``` ## LOG\_ONLY の結果を確認する 発信者が AgentCore Gateway を介してツール/コールリクエストを行うと、ゲートウェイは MCP レスポンスを発信者に返す前に、ポリシーを含むすべての`LOG_ONLY`ポリシーを評価します。発信者の応答は`LOG_ONLY`ポリシーの影響を受けません。これらの結果はオブザーバビリティによってのみ報告されます。 トレースと Amazon CloudWatch メトリクスを通じて`LOG_ONLY`ポリシーの動作を観察します。 **トレースとスパン:** ゲートウェイでトレースを有効にすると、ポリシー評価スパンに`LOG_ONLY`一致情報が含まれます。AgentCore Observability コンソールでこれらのスパンを調べて、特定のリクエストに対して実行された`LOG_ONLY`ポリシーと、決定を反転したかどうかを確認できます。詳細については、[「Amazon Bedrock AgentCore Observability でエージェントアプリケーションを監視する](observability.md)」を参照してください。 **CloudWatch メトリクス:** AgentCore のポリシーは、AWS/Bedrock-AgentCore 名前空間の下にメトリクスを出力します。以下のメトリクスは`LOG_ONLY`評価に固有です。 | メトリクス | その意味 | | --- | --- | | `ConfidenceScore` (PolicyEnforcementMode= の場合`LOG_ONLY`) | 一致する`LOG_ONLY`ポリシーに対してガードレールが返した信頼スコア。これを使用して、しきい値を選択するときにトラフィックのスコア分布を理解します。 | | `ConfidenceThreshold` (`PolicyEnforcementMode=LOG_ONLY` を含む) | `LOG_ONLY` ポリシーで設定されたしきい値。ポリシー間でスコアをしきい値と比較する場合に便利です。 | | `LogOnlyMatches` | `LOG_ONLY` ポリシーが発生したリクエストの数。ポリシーごとに発行され、エンジン上のすべての`LOG_ONLY`ポリシーにまたがるグループロールアップとして発行されます。 | | `LogOnlyDecisionFlips` | 昇格した場合に`LOG_ONLY`ポリシーが決定を変更したリクエストの数。これは重要な昇格シグナルです。ゼロが持続すると、ポリシーを昇格しても現在のトラフィックはブロックされません。 | | `LogOnlyEvalIncomplete` | `LOG_ONLY` 評価が部分的な場合に出力されます。これを使用して、不完全な評価の持続的な割合を警告します。 | すべてのメトリクスには、フィルタリング用の PolicyEngine ディメンションと OperationName ディメンションが含まれます。ポリシーごとのメトリクスには、ポリシー ID を持つポリシーディメンションも含まれます。 AgentCore リソースのメトリクスの表示の詳細については、[「Bedrock AgentCore generated observability data](observability.md)」を参照してください。 ## ポリシーを強制に昇格させる `LOG_ONLY` ポリシーに自信が持てたら、 を に設定して `UpdatePolicy`の適用に昇格`enforcementMode`させます`ACTIVE`。他の変更は必要なく、ポリシーはその ID、名前、および定義を保持します。 ``` aws bedrock-agentcore-control update-policy \ --policy-engine-id my-policy-engine-id \ --policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \ --enforcement-mode ACTIVE ``` その逆もサポートされています。`ACTIVE`ポリシーを に戻し`LOG_ONLY`、ポリシーを所定の位置に保持して監視し続けながら強制から除外できます。 したがって、一般的なライフサイクルは、 でポリシーを作成し`LOG_ONLY`、トラフィックとメトリクスを観察し、それを `ACTIVE` に昇格させることです。必要に応じて、ポリシーを削除して再作成`LOG_ONLY`することなく、 に降格します。 ## LOG\_ONLY モードによるしきい値の選択 `LOG_ONLY` モードは、セキュリティと正当なトラフィックの中断のバランスをとる信頼スコアしきい値を選択する必要があるガードレールポリシーに特に役立ちます。しきい値が低すぎると、正当なリクエストがブロックされます。しきい値が高すぎると、脅威が通過する可能性があります。 **推奨されるワークフロー:** 妥当なしきい値 (0.7 など) でガードレールを `LOG_ONLY`モードでデプロイします。このポリシーはすべてのリクエストを評価し、CloudWatch メトリクスに信頼スコアを発行しますが、トラフィックをブロックすることはありません。 実際の本番稼働トラフィックの数日または数週間という、代表的なウィンドウにデータを蓄積します。ConfidenceScore メトリクス (PolicyEnforcementMode=LOG\_ONLY を使用) は、トラフィックが生成するスコアの分布を提供します。 グラウンドトゥルースと照らし合わせてスコアを分析します。ラベル付きのテストセット (良性または悪意があるとマークされたプロンプト) がある場合は、各しきい値で精度と再現率を計算し、目標に最適なものを選択できます。ラベル付きデータがない場合は、高スコア範囲 (0.8～1.0 など）、低スコア範囲 (0～0.2)、あいまいな中間ゾーン (0.4～0.7) のサンプルプロンプトを分類し、しきい値の選択の信頼性を構築します。選択したしきい値でポリシーを更新し、 に昇格させます`ACTIVE`。 ``` aws bedrock-agentcore-control update-policy \ --policy-engine-id my-policy-engine-id \ --policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \ --enforcement-mode ACTIVE \ --definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.65\")) };"}}' ``` このワークフローにより、一般的なデフォルトではなく、実際のトラフィックパターンがしきい値に反映されます。 ## 考慮事項と制限事項 `LOG_ONLY` ポリシーが決定に影響することはありません。`LOG_ONLY` ポリシーでは、アクションを許可または拒否することはできません。リクエストが受け取る決定は、`LOG_ONLY`ポリシーが存在しない場合に受け取る決定と同じです。これは 機能の中核的な保証です。 変更は結果整合性があります。ポリシーの作成、更新、昇格は、数秒以内に評価パスに適用されます。即時スイッチを期待するのではなく、観察ウィンドウとプロモーションステップを計画します。 結果リストには制限があります。`LOG_ONLY`一致リストと決定フリップリストはそれぞれ、リクエストごとに 1,000 エントリに制限されます。`LOG_ONLY` ポリシーの数が非常に多いエンジンの場合、完全な集計数については CloudWatch メトリクスに依存します。 評価は部分的な場合があります。リクエスト`LOG_ONLY`の評価が不完全な場合、そのリクエストの`LOG_ONLY`シグナルにエントリがない可能性があります。強制決定は影響を受けません。