# Teste uma política no modo LOG\_ONLY Usando o modo de fiscalização em nível de política, você pode alternar entre `ACTIVE` e responder `LOG_ONLY` à pergunta: “O que essa política faria com meu tráfego se fosse aplicada?” O `LOG_ONLY` modo por política permite testar uma política no tráfego real sem afetar as decisões de autorização. A política avalia cada solicitação como se ela fosse aplicada, mas só grava os resultados nos registros. Nada é bloqueado ou permitido como resultado de uma política cujo modo de aplicação é`LOG_ONLY`. Depois de confiar nos resultados, promova-os para`ACTIVE`. **Topics** + [Como funciona o modo LOG\_ONLY](#how-log-only-mode-works) + [Políticas LOG\_ONLY e mecanismos de políticas LOG\_ONLY](#log-only-policies-and-log-only-policy-engines) + [Definir o modo de aplicação de uma política](#set-the-enforcement-mode-of-a-policy) + [Observe os resultados do LOG\_ONLY](#observe-log-only-results) + [Promova uma política para aplicação](#promote-a-policy-to-enforcement) + [Escolhendo um limite com o modo LOG\_ONLY](#choosing-a-threshold-with-log-only-mode) + [Considerações e limitações](#policy-log-only-considerations-and-limitations) ## Como funciona o modo LOG\_ONLY Cada política em um mecanismo de política tem um modo de imposição de `ACTIVE` ou`LOG_ONLY`. O padrão é `ACTIVE` que as políticas existentes e qualquer nova política que você criar sem especificar o campo continuem sendo aplicadas como antes. Quando o mecanismo de políticas avalia uma solicitação, ele avalia suas `ACTIVE` políticas e suas `LOG_ONLY` políticas lado a lado, mas só aplica suas políticas. `ACTIVE` `ACTIVE`as políticas determinam a decisão que é devolvida ao AgentCore Gateway e aplicada. O mecanismo de políticas aplica a semântica “negação padrão” e “proibi-vence”, o que significa que uma solicitação só é permitida se uma política permitir, e uma única proibição de qualquer política ativa a nega. `LOG_ONLY`as políticas são avaliadas em relação à mesma solicitação, mas seus resultados são mantidos separados. Eles são relatados em rastreamentos e emitidos como CloudWatch métricas da Amazon. Eles nunca são combinados na decisão forçada. | Modo de fiscalização | Avaliado em cada solicitação? | Afeta a decisão devolvida? | | --- | --- | --- | | `ACTIVE` (padrão) | Sim | Sim | | `LOG_ONLY` | Sim | Não | Uma solicitação é avaliada em duas etapas: 1. O mecanismo de política computa uma decisão. Somente `ACTIVE` políticas contribuem para isso. `LOG_ONLY`as políticas são avaliadas e relatadas separadamente, mas nunca são consideradas. 1. Se o mecanismo estiver associado a um gateway no `ENFORCE` modo, o Gateway permite ou nega a ação de acordo com a decisão do mecanismo de política. Se o mecanismo estiver associado a um gateway no `LOG_ONLY` modo, o Gateway não tomará nenhuma ação; a decisão será registrada, mas não aplicada. `ACTIVE`e `LOG_ONLY` são tratados como dois conjuntos isolados; uma `LOG_ONLY` política nunca pode mudar a experiência de seus chamadores. A decisão que uma solicitação recebe não é afetada por nenhuma `LOG_ONLY` política. Além de registrar as `LOG_ONLY` políticas que corresponderam a uma solicitação, o mecanismo de políticas relata quais dessas políticas teriam mudado a decisão se fossem`ACTIVE`. Esse é um sinal fundamental a ser usado ao avaliar a eficácia e a segurança de uma política (ou seja, se ela pode ser promovida). `ACTIVE` Por exemplo, uma `LOG_ONLY` política que corresponda com frequência e apareça no conjunto de inversão de decisões teria bloqueado seu tráfego durante a janela de observação. Cada `LOG_ONLY` política é avaliada independentemente de todas as outras `LOG_ONLY` políticas para determinar o conjunto de políticas de mudança de decisão. No entanto, cada avaliação de `LOG_ONLY` política considera todas as `ACTIVE` políticas atuais. ## Políticas LOG\_ONLY e mecanismos de políticas LOG\_ONLY A política em AgentCore tem dois controles separados que usam o valor LOG\_ONLY. Eles operam em camadas diferentes e respondem a perguntas diferentes, por isso é importante entender qual delas você está configurando. **Modo de aplicação do mecanismo de política:** controla o comportamento geral do mecanismo. Quando definido como`LOG_ONLY`, nenhuma política no mecanismo é aplicada, independentemente de seu modo de política individual. Todas as decisões são registradas. Isso é definido usando o `mode` campo de `policyEngineConfiguration` quando você associa um mecanismo de política a um gateway usando as `UpdateGateway` operações `CreateGateway` ou. Os dois valores que `mode` aceitam são `ENFORCE` (padrão) `LOG_ONLY` e. O modo de política controla o comportamento de uma única política em um mecanismo de fiscalização. Quando definida como LOG\_ONLY, essa política ainda é avaliada, mas sua decisão é registrada em vez de aplicada. Todas `ACTIVE` as outras políticas no mecanismo continuam sendo aplicadas normalmente. Os dois valores que `enforcementMode` aceitam são `ACTIVE` (padrão) `LOG_ONLY` e. Use LOG\_ONLY em nível de política para testar uma nova barreira de proteção na produção sem afetar o tráfego. Use LOG\_ONLY em nível de mecanismo para observar o comportamento de todas as políticas antes de ativar a fiscalização.
Modo de aplicação de políticas
ACTIVE LOG_ONLY
Modo de aplicação do Policy Engine ENFORCE Avaliado e aplicado. Pode bloquear ou modificar solicitações.Avaliado, mas não aplicado. A decisão é registrada somente; outras ACTIVE políticas no mecanismo ainda são aplicadas.
LOG_ONLY Avaliado, mas não aplicado. A decisão é registrada somente.Avaliado, mas não aplicado. A decisão é registrada somente.
**nota** O modo de imposição do mecanismo de política tem precedência. Quando um mecanismo de política é associado no modo LOG\_ONLY, nenhuma política pode negar uma ação do Gateway — nem mesmo uma política no modo de `ACTIVE` fiscalização — porque o Gateway não age de forma alguma sobre a decisão do mecanismo de política. O mecanismo ainda computa a decisão e você ainda recebe `LOG_ONLY` telemetria; a decisão simplesmente não é aplicada. ## Definir o modo de aplicação de uma política Você pode definir o `enforcementMode` campo em uma política ao criar ou atualizar a política (ou seja, `CreatePolicy` e`UpdatePolicy`), e ele será retornado por `GetPolicy` `ListPolicies` e. **Crie uma política no `LOG_ONLY` modo** Crie uma política no `LOG_ONLY` modo configurando `enforcementMode` como `LOG_ONLY` na `CreatePolicy` solicitação. O exemplo a seguir cria uma barreira na política que proíbe conteúdo violento acima de um limite de confiança, mas apenas o observa. Para obter mais informações sobre grades de proteção na política, consulte grades de [proteção](policy-guardrails-in-policies.md) nas políticas. ``` 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\")) };"}}' ``` A resposta ecoa a política com “EnforcementMode”: “LOG\_ONLY”. A política começa a ser avaliada em relação ao tráfego e, a partir desse ponto, suas correspondências aparecem em rastreamentos e CloudWatch métricas, sem afetar nenhuma decisão. **Listar políticas e seus modos de aplicação** ListPolicies retorna `enforcementMode` em cada resumo da política, para que você possa ver rapidamente quais políticas estão sendo observadas e quais estão sendo aplicadas. ``` aws bedrock-agentcore-control list-policies \ --policy-engine-id my-policy-engine-id \ --query 'policies[].{name:name,enforcementMode:enforcementMode,status:status}' ``` **resposta** ``` [ { "name": "LogOnlyViolenceFilter", "enforcementMode": "LOG_ONLY", "status": "ACTIVE" }, { "name": "RefundLimit", "enforcementMode": "ACTIVE", "status": "ACTIVE" } ] ``` ## Observe os resultados do LOG\_ONLY Quando um chamador faz uma tools/call solicitação por meio do AgentCore Gateway, o gateway avalia todas as políticas — incluindo `LOG_ONLY` políticas — antes de retornar a resposta do MCP ao chamador. A resposta do chamador nunca é afetada pelas `LOG_ONLY` políticas; esses resultados são relatados somente por meio da observabilidade. Você observa o comportamento `LOG_ONLY` da política por meio de rastreamentos e CloudWatch métricas da Amazon: **Rastreamentos e extensões:** quando você ativa o rastreamento em seu gateway, os períodos de avaliação da política incluem `LOG_ONLY` informações de correspondência. Você pode inspecionar esses períodos no console do AgentCore Observability para ver quais `LOG_ONLY` políticas foram acionadas em uma determinada solicitação e se elas teriam invertido a decisão. Para obter mais informações, consulte [Observe seus aplicativos de agente no Amazon Bedrock AgentCore Observability](observability.md). **CloudWatch métricas:** a política AgentCore emite métricas sob o AWS/Bedrock-AgentCore namespace. As métricas a seguir são específicas para `LOG_ONLY` avaliação: | Métrica | O que isso te diz | | --- | --- | | `ConfidenceScore`(com PolicyEnforcementMode =`LOG_ONLY`) | A pontuação de confiança que a grade de proteção retornou para uma política compatível`LOG_ONLY`. Use isso para entender a distribuição da pontuação do seu tráfego ao escolher um limite. | | `ConfidenceThreshold` (com `PolicyEnforcementMode=LOG_ONLY`) | O limite configurado na `LOG_ONLY` política. Útil ao comparar a pontuação com o limite entre as políticas. | | `LogOnlyMatches` | A contagem de solicitações em que uma `LOG_ONLY` política foi acionada. Emitido por política e como um conjunto de grupos em todas as `LOG_ONLY` políticas no mecanismo. | | `LogOnlyDecisionFlips` | A contagem de solicitações em que uma `LOG_ONLY` política teria mudado a decisão se promovida. Este é o principal sinal de promoção: um zero sustentado significa que promover a política não bloqueará o tráfego atual. | | `LogOnlyEvalIncomplete` | Emitido quando a `LOG_ONLY` avaliação era parcial. Use isso para alertar sobre uma taxa sustentada de avaliações incompletas. | Todas as métricas incluem PolicyEngine OperationName dimensões para filtragem. Per-policy Além disso, as métricas incluem uma dimensão de política com o ID da política. Para obter mais informações sobre a visualização de métricas para seus AgentCore recursos, consulte Dados de [observabilidade AgentCore gerados pelo Bedrock](observability.md). ## Promova uma política para aplicação Quando você estiver confiante em uma `LOG_ONLY` política, promova-a para aplicação com`UpdatePolicy`, definindo `enforcementMode` como`ACTIVE`. Nenhuma outra alteração é necessária, e a política mantém sua ID, nome e definição. ``` aws bedrock-agentcore-control update-policy \ --policy-engine-id my-policy-engine-id \ --policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \ --enforcement-mode ACTIVE ``` O inverso também é suportado: você pode mover uma `ACTIVE` política de volta `LOG_ONLY` para retirá-la da aplicação, mantendo-a em vigor e continuando a observá-la. Portanto, um ciclo de vida típico é criar uma política`LOG_ONLY`, observar o tráfego e as métricas e, em seguida, promovê-la `ACTIVE` e, se necessário, rebaixá-la `LOG_ONLY` sem excluir e recriar a política. ## Escolhendo um limite com o modo LOG\_ONLY `LOG_ONLY`o modo é particularmente útil para políticas de proteção, nas quais você precisa selecionar um limite de pontuação de confiança que equilibre a segurança contra a interrupção do tráfego legítimo. Um limite muito baixo bloqueia solicitações legítimas; um limite muito alto pode permitir a passagem de ameaças. **O fluxo de trabalho recomendado:** implante a grade de proteção no `LOG_ONLY` modo com um limite que você acredita ser razoável (por exemplo, 0,7). A política avalia cada solicitação e emite uma pontuação de confiança para CloudWatch as métricas, mas nunca bloqueia o tráfego. Acumule dados em uma janela representativa — dias ou semanas de tráfego real de produção. A ConfidenceScore métrica (com PolicyEnforcementMode =LOG\_ONLY) fornece a distribuição das pontuações que seu tráfego produz. Analise as pontuações em relação à verdade fundamental. Se você tiver um conjunto de testes rotulado (solicitações marcadas como benignas ou maliciosas), poderá calcular a precisão e a recuperação em cada valor limite e selecionar aquele que melhor atenda às suas metas. Se você não tiver dados rotulados, solicite amostras da faixa de pontuação alta (por exemplo, 0,8—1,0), da faixa de pontuação baixa (0—0,2) e da zona intermediária ambígua (0,4—0,7) e, em seguida, classifique cada amostra para aumentar a confiança em sua escolha de limite. Atualize a política com o limite escolhido e promova-a para`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\")) };"}}' ``` Esse fluxo de trabalho garante que o limite reflita seus padrões reais de tráfego, em vez de um padrão genérico. ## Considerações e limitações `LOG_ONLY`as políticas nunca afetam as decisões. Uma `LOG_ONLY` política não pode fazer com que uma ação seja permitida ou negada. A decisão que uma solicitação recebe é idêntica à decisão que receberia se a `LOG_ONLY` política não existisse. Essa é a principal garantia do recurso. Eventualmente, as mudanças são consistentes. A criação, atualização ou promoção de uma política é aplicada ao caminho de avaliação em alguns segundos. Planeje suas janelas de observação e etapas de promoção adequadamente, em vez de esperar uma mudança instantânea. As listas de resultados são limitadas. `LOG_ONLY`Cada uma das listas de partidas e de inversão de decisões tem um limite máximo de 1.000 entradas por solicitação. Para mecanismos com um número muito grande de `LOG_ONLY` políticas, confie nas CloudWatch métricas para obter contagens agregadas completas. A avaliação pode ser parcial. Quando a `LOG_ONLY` avaliação de uma solicitação está incompleta, os `LOG_ONLY` sinais dessa solicitação podem estar faltando entradas. A decisão imposta nunca é afetada.