# 在 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」語意，這表示只有在政策允許請求，且任何作用中政策的單一禁止拒絕請求時，才允許請求。 `LOG_ONLY` 政策會根據相同的請求進行評估，但其結果會保持個別。它們會以追蹤形式報告，並以 Amazon CloudWatch 指標的形式發出。它們永遠不會合併為強制執行的決策。 | 強制執行模式 | 在每個請求上評估？ | 影響傳回的決策？ | | --- | --- | --- | | `ACTIVE` (default) | 是 | 是 | | `LOG_ONLY` | 是 | 否 | 請求會以兩個階段評估： 1. 政策引擎會計算決策。只有`ACTIVE`政策會有所貢獻。 `LOG_ONLY` 政策會分別評估和報告，但絕不會納入考量。 1. 如果引擎與 `ENFORCE` 模式的閘道相關聯，閘道會根據政策引擎的決策允許或拒絕動作。如果引擎與 `LOG_ONLY` 模式中的閘道相關聯，閘道不會採取任何動作；系統會記錄決策，但不會強制執行。 `ACTIVE` 和 `LOG_ONLY` 被視為兩個隔離集；`LOG_ONLY`政策永遠無法變更來電者的體驗。請求收到的決策不受任何`LOG_ONLY`政策影響。 除了記錄與請求相符`LOG_ONLY`的政策之外，政策引擎還會報告哪些政策如果是 ，將會變更決策`ACTIVE`。這是評估政策的有效性和安全性 （即是否可以提升為 `ACTIVE`) 時要使用的關鍵訊號。例如，經常比對並出現在決策翻轉集中`LOG_ONLY`的政策，會在觀察時段期間封鎖您的流量。每個`LOG_ONLY`政策的評估都獨立於所有其他`LOG_ONLY`政策，以確定決策翻轉政策集。不過，每個`LOG_ONLY`政策評估都會考慮所有目前的`ACTIVE`政策。 ## LOG\_ONLY 政策和 LOG\_ONLY 政策引擎 AgentCore 中的政策有兩個不同的控制項，兩者都使用 LOG\_ONLY 值。它們在不同層級操作並回答不同的問題，因此請務必了解您要設定哪個層級。 **政策引擎強制執行模式：** 控制引擎的整體行為。設為 時`LOG_ONLY`，不會強制執行引擎中的政策，無論其個別政策模式為何。會記錄所有決策。當您使用 `CreateGateway`或 `UpdateGateway`操作將政策引擎與閘道建立關聯`policyEngineConfiguration`時，這會使用 的 `mode` 欄位設定。`mode` 接受的兩個值為 `ENFORCE`（預設） 和 `LOG_ONLY`。 政策模式控制強制引擎內單一政策的行為。設為 LOG\_ONLY 時，仍會評估該政策，但會記錄其決策而非強制執行。引擎中的所有其他`ACTIVE`政策會繼續正常強制執行。`enforcementMode` 接受的兩個值為 `ACTIVE`（預設） 和 `LOG_ONLY`。 使用政策層級 LOG\_ONLY 在生產環境中陰影測試新的護欄，而不會影響流量。在啟用強制執行之前，使用引擎層級 LOG\_ONLY 觀察所有政策的行為。
政策強制執行模式
ACTIVE LOG_ONLY
政策引擎強制執行模式 ENFORCE 已評估並強制執行。可能會封鎖或修改請求。已評估但未強制執行。只會記錄決策；引擎中的其他ACTIVE政策仍會強制執行。
LOG_ONLY 已評估但未強制執行。只會記錄決策。已評估但未強制執行。只會記錄決策。
**注意** 政策引擎強制執行模式優先。當政策引擎在 LOG\_ONLY 模式中建立關聯時，沒有任何政策可以拒絕閘道動作，甚至不能拒絕`ACTIVE`強制執行模式中的政策，因為閘道完全不會對政策引擎的決定採取行動。引擎仍會計算決策，而且您仍然會收到`LOG_ONLY`遙測；該決策只是不強制執行。 ## 設定政策的強制執行模式 您可以在建立或更新政策 （即 `CreatePolicy`和 `UpdatePolicy`) 時，在政策上設定 `enforcementMode` 欄位，並由 `GetPolicy`和 傳回。 `ListPolicies` **在 `LOG_ONLY` 請求中將 **`enforcementMode`設定為 ，以在 `LOG_ONLY` 模式下建立政策`LOG_ONLY``CreatePolicy`。下列範例會在政策中建立護欄，以禁止超過可信度閾值的暴力內容，但只會觀察到該內容。如需政策中護欄的詳細資訊，請參閱[政策中的護欄](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 可觀測性主控台中檢查這些範圍，以查看在特定請求上觸發哪些`LOG_ONLY`政策，以及它們是否會翻轉決策。如需詳細資訊，請參閱在 [Amazon Bedrock AgentCore 可觀測性上觀察您的代理程式應用程式](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 產生的可觀測性資料](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`訊號可能會遺失項目。強制執行的決策永遠不會受到影響。