LOG_ONLY モードでポリシーをテストする

ポリシーレベルのエンフォースメントモードを使用すると、 ACTIVEと を切り替えるLOG_ONLYことで、「このポリシーが適用されるとトラフィックにどのような影響がありますか？」という質問に答えることができます。ポリシーLOG_ONLYモードごとに、認可の決定に影響を与えることなく、実際のトラフィックでポリシーをテストできます。ポリシーは、すべてのリクエストを強制されたものとして評価しますが、結果をログに書き込むだけです。強制モードが であるポリシーの結果としてブロックまたは許可されるものはありませんLOG_ONLY。結果を信頼したら、 に昇格しますACTIVE。

LOG_ONLY モードの仕組み

ポリシーエンジンのすべてのポリシーには、 ACTIVEまたは のエンフォースメントモードがありますLOG_ONLY。デフォルトは ACTIVEであるため、既存のポリシー、および フィールドを指定せずに作成する新しいポリシーは、以前と同様に引き続き適用されます。ポリシーエンジンはリクエストを評価すると、ACTIVEポリシーとLOG_ONLYポリシーを並べて評価しますが、ACTIVEポリシーにのみ適用します。

ACTIVE ポリシーは、AgentCore Gateway に返され、強制される決定を決定します。ポリシーエンジンは「default-deny」および「forbid-wins」セマンティクスを適用します。つまり、リクエストはポリシーが許可する場合にのみ許可され、アクティブなポリシーからの 1 つの禁止によって拒否されます。

LOG_ONLY ポリシーは同じリクエストに対して評価されますが、結果は別々に保持されます。トレースで報告され、Amazon CloudWatch メトリクスとして出力されます。これらは強制決定にまとめられることはありません。

リクエストは 2 つの段階で評価されます。

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 を使用して、強制を有効にする前にすべてのポリシーの動作を確認します。

ポリシーの適用モードを設定する

ポリシー ( CreatePolicyおよび ) を作成または更新するときに、ポリシーの enforcementModeフィールドを設定でき、 UpdatePolicyGetPolicyおよび によって返されますListPolicies。

Create a policy in LOG_ONLY mode CreatePolicyリクエストLOG_ONLYで enforcementModeを に設定して、 LOG_ONLY モードでポリシーを作成します。次の例では、信頼度しきい値を超える暴力的なコンテンツを禁止するガードレールをポリシーに作成しますが、それのみを監視します。ポリシーのガードレールの詳細については、「 ポリシーのガードレール」を参照してください。

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 でエージェントアプリケーションを監視する」を参照してください。

CloudWatch メトリクス: AgentCore のポリシーは、AWS/Bedrock-AgentCore 名前空間の下にメトリクスを出力します。以下のメトリクスはLOG_ONLY評価に固有です。

すべてのメトリクスには、フィルタリング用の PolicyEngine ディメンションと OperationName ディメンションが含まれます。ポリシーごとのメトリクスには、ポリシー ID を持つポリシーディメンションも含まれます。

AgentCore リソースのメトリクスの表示の詳細については、「Bedrock AgentCore generated observability data」を参照してください。

ポリシーを強制に昇格させる

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シグナルにエントリがない可能性があります。強制決定は影響を受けません。