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 paraACTIVE.

Como funciona o modo LOG_ONLY

Cada política em um mecanismo de política tem um modo de imposição de ACTIVE ouLOG_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

ACTIVEas 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_ONLYas 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.

Uma solicitação é avaliada em duas etapas:

ACTIVEe 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 fossemACTIVE. 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 comoLOG_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.

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 eUpdatePolicy), 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 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.

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:

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.

Promova uma política para aplicação

Quando você estiver confiante em uma LOG_ONLY política, promova-a para aplicação comUpdatePolicy, definindo enforcementMode comoACTIVE. 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íticaLOG_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_ONLYo 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 paraACTIVE:

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_ONLYas 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_ONLYCada 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.