View a markdown version of this page

Des barrières dans les politiques - Substrat rocheux d'Amazon AgentCore

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Des barrières dans les politiques

Cette section explique comment placer des barrières de sécurité dans les politiques, de sorte que la décision d'une politique dépend de la question de savoir si le contenu de la demande ou de la réponse contient du contenu dangereux. La vérification du contenu elle-même est effectuée par un garde-corps, que Policy AgentCore appelle lors de l'évaluation. Aujourd'hui, les rambardes sont soutenues par Amazon Bedrock Guardrails.

Une condition de garde-corps désigne trois éléments : le type de garde-corps, les catégories que le type doit évaluer et le contenu à évaluer. Le garde-corps renvoie un score de confiance, et c'est votre police qui décide de ce qu'il faut en faire.

Si vous débutez dans le domaine des garde-corps dans les politiques, commencez par Commencer avec les glissières de sécurité, qui vous expliquera comment en créer un bout à bout. Pour des exemples de politiques couvrant le MCP, le runtime et chaque API d'inférence, consultez les exemples de politiques Guardrail.

Éléments constitutifs de l'état d'un garde-corps

Policy in AgentCore prend en charge trois types de garde-corps. Chacune utilise un ensemble de catégories pour être évaluée et renvoie son résultat différemment.

ContentFilter

Harmful-content catégories telles que VIOLENCE ouHATE. Renvoie un score de confiance pour chaque catégorie que vous nommez, que le contenu le présente ou non.

PromptAttack

Prompt-manipulation catégories telles que JAILBREAK ouPROMPT_INJECTION. Renvoie un score de confiance pour chaque catégorie que vous nommez.

SensitiveInformation

Entités sensibles telles que EMAIL ouUS_SOCIAL_SECURITY_NUMBER. Renvoie une détection par entité trouvée plutôt qu'un score par catégorie. Il n'y a donc aucun score par catégorie et nécessite une agrégation.

Pour les catégories acceptées par chaque type, voir Garde-corps pris en charge. Pour le contenu à évaluer, voir Transmettre le contexte à votre garde-fou.

Un score de confiance est un nombre décimal compris entre 0 et 1 qui indique dans quelle mesure le contenu présente la propriété évaluée. Vous décidez quoi faire de ce score, et la politique exprime votre décision sous forme de condition au résultat du garde-fou, le plus souvent une comparaison de seuils, telle que. .confidenceScore.greaterThan(decimal("0.4")) Pour les seuils et les opérateurs de comparaison, voir Seuils pour les glissières de sécurité.

Les scores peuvent également être réduits d'une catégorie à l'autre au lieu d'être comparés une par une. C'est ce que fait une agrégation : maxConfidenceScore() elle minConfidenceScore() count() renvoie un score, tout en renvoyant le nombre de détections et categories() en renvoyant l'ensemble des catégories détectées, de sorte que ces deux catégories n'ont pas besoin de seuil. Pour la liste complète, voir Agrégations.

Disponibilité régionale des rambardes

Le tableau suivant indique les AWS régions qui soutiennent les garde-fous dans les politiques.

Nom de la région Des barrières dans les politiques

USA Est (Virginie du Nord)

✓ Oui

USA Est (Ohio)

✓ Oui

USA Ouest (Californie du Nord)

Non

USA Ouest (Oregon)

✓ Oui

Asie-Pacifique (Hyderabad)

Non

Asie-Pacifique (Malaisie)

Non

Asie-Pacifique (Mumbai)

Non

Asie-Pacifique (Séoul)

Non

Asie-Pacifique (Singapour)

Non

Asie-Pacifique (Sydney)

✓ Oui

Asie-Pacifique (Thaïlande)

Non

Asie-Pacifique (Tokyo)

✓ Oui

Canada (Centre)

Non

Europe (Francfort)

Non

Europe (Irlande)

Non

Europe (Londres)

✓ Oui

Europe (Milan)

Non

Europe (Paris)

Non

Europe (Espagne)

Non

Europe (Stockholm)

✓ Oui

Amérique du Sud (São Paulo)

Non

AWS GovCloud (US-West)

Non

Avant de commencer

Avant de commencer, vous devez configurer correctement votre rôle IAM.

Permissions

Le rôle d'exécution de la passerelle a besoin bedrock:InvokeGuardrailChecks en plus des AgentCore autorisations qu'elle possède déjà. Pour ce dernier point, voir AgentCore Passerelle et politique dans les autorisations AgentCore IAM.

Policy in AgentCore utilise les informations d'identification de session d'accès direct (FAS) dérivées du rôle d'exécution de la passerelle pour appeler l'API Bedrock Guardrails en votre nom. C'est pourquoi l'autorisation appartient à ce rôle.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "bedrock:InvokeGuardrailChecks", "Resource": "arn:aws:bedrock:us-west-2:123456789012:guardrail/abc123" } ] }

Rambardes soutenues

Type de garde-corps Type d’entité Catégories

Filtre de contenu

ContentFilter

VIOLENCE, HATE, SEXUAL, MISCONDUCT, INSULTS

Détection rapide des attaques

PromptAttack

JAILBREAK, PROMPT_INJECTION, PROMPT_LEAKAGE

Informations sensibles

SensitiveInformation

Identité personnelle — ADDRESSAGE,NAME,EMAIL,PHONE,USERNAME,PASSWORD,PIN,DRIVER_ID,LICENSE_PLATE, VEHICLE_IDENTIFICATION_NUMBER

Financier — CREDIT_DEBIT_CARD_NUMBERCREDIT_DEBIT_CARD_CVV,CREDIT_DEBIT_CARD_EXPIRY,US_BANK_ACCOUNT_NUMBER,US_BANK_ROUTING_NUMBER,INTERNATIONAL_BANK_ACCOUNT_NUMBER, SWIFT_CODE

Identifiants gouvernementaux et sanitaires —US_SOCIAL_SECURITY_NUMBER,US_PASSPORT_NUMBER,US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER,CA_SOCIAL_INSURANCE_NUMBER,CA_HEALTH_NUMBER,UK_NATIONAL_INSURANCE_NUMBER, UK_NATIONAL_HEALTH_SERVICE_NUMBER UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER

Identifiants et réseau — AWS_ACCESS_KEYAWS_SECRET_KEY,IP_ADDRESS,MAC_ADDRESS, URL

Note

Ce tableau présente la liste actuelle des barrières de sécurité et des catégories prises en charge par Policy in AgentCore . Une catégorie en dehors de cette catégorie échoue à la validation lorsque vous créez la politique. En particulier, il n'y a pas de ACCOUNT_NUMBER catégorie : utilisation US_BANK_ACCOUNT_NUMBER ouINTERNATIONAL_BANK_ACCOUNT_NUMBER.

Écrire des garde-fous dans les politiques

Pour ajouter un garde-fou à une politique, vous pouvez créer la politique sous forme de code ou la décrire en langage naturel. Comme pour les autres politiques, spécifiez un effet, par exemple avec une condition (when guardrails). permit Dans cette condition, fournissez le garde-fou à activer, les catégories à évaluer, le contenu à évaluer et la comparaison des scores que vous souhaitez.

Exemple de définition de garde-corps

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___<METHOD>:<uri>", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"] .confidenceScore .greaterThan(decimal("0.2")) };
Note

suppressOutputs'exécute une fois que l'outil a produit un résultat et refuse de communiquer la réponse à l'appelant. L'outil est toujours en cours d'exécution ; seule la réponse est supprimée.

suppressOutputfonctionne uniquement dans des conditions de garde-corps. Son état doit consister uniquement en des contrôles de sécurité. Écrivez ces vérifications dans un when guardrails {…​} bloc ou dans un when {…​} bloc simple. suppressOutputne prend pas en charge le Cedar ou temporal {…​} les conditions standard.

Notez les trois traits de soulignement qui séparent le nom de la cible de la méthode et de l'URI. Pour des exemples par rapport à une passerelle de référence complète, consultez les exemples de politique Guardrail.

Création d'une politique avec des garde-fous

Pour créer la politique, placez la déclaration dans le policy champ de la definition propriété. Pour plus d'informations, consultez la section Création d'une politique. Sinon, elle est créée comme n'importe quelle autre politique.

Exemple
AgentCore CLI

L'assistant interactif est le moyen le plus simple d'ajouter un garde-corps, car il crée la déclaration à votre place.

  1. agentcore add policyCourez sans drapeau :

    agentcore add policy

    L'assistant vous invite à saisir le nom de la passerelle, de la cible, du moteur et de la politique. Choisissez le formulaire de garde-corps comme source, puis il vous demande l'effet, la catégorie de garde-corps, les filtres et le chemin de données, et vous montre l'instruction qu'il a créée avant de la créer.

  2. Déployez le projet :

    agentcore deploy --yes

    Pour écrire la même chose de manière non interactive, transmettez les indicateurs de formulaire —--form-category, --form-filters--form-effect, et. --form-data-path Fournir l'un d'entre eux permet d'éviter le magicien. Pour fournir une déclaration que vous avez écrite vous-même, enregistrez-la dans un fichier et transmettez-la --source :

    agentcore add policy --name BlockViolentReason \ --engine my_policy_engine \ --source block_violent_reason.dw \ --validation-mode IGNORE_ALL_FINDINGS

    Pour plus d'informations, voir Commencer à utiliser les glissières de sécurité.

AWS CLI
  1. Exécutez la commande AWS CLI suivante dans un terminal pour créer la politique :

    aws bedrock-agentcore-control create-policy \ --policy-engine-id my_policy_engine-a1b2c3d4e5 \ --name BlockViolentReason \ --validation-mode IGNORE_ALL_FINDINGS \ --definition '{ "policy": { "statement": "forbid (principal, action == AgentCore::Action::\"RefundTool___process_refund\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.reason])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.4\")) };" } }'
AWS Python SDK (Boto3)
  1. Exécutez le code Python suivant pour créer la politique à l'aide du AWS SDK pour Python :

    import boto3 client = boto3.client("bedrock-agentcore-control") GATEWAY_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5" statement = ( 'forbid (principal, ' 'action == AgentCore::Action::"RefundTool___process_refund", ' f'resource == AgentCore::Gateway::"{GATEWAY_ARN}") ' 'when guardrails { ' 'BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"]' '.confidenceScore.greaterThan(decimal("0.4")) };' ) response = client.create_policy( policyEngineId="my_policy_engine-a1b2c3d4e5", name="BlockViolentReason", validationMode="IGNORE_ALL_FINDINGS", definition={"policy": {"statement": statement}}, ) # CreatePolicy returns 202 - wait for the terminal status client.get_waiter("policy_active").wait( policyEngineId="my_policy_engine-a1b2c3d4e5", policyId=response["policyId"], ) print(response["policyId"])

Quelle que soit la surface que vous utilisez, préférez exprimer la règle sous la forme permit d'une comparaison inverse. L'évaluation des politiques est refusée par défaut. Ainsi, un single permit qui ne tient que lorsque le score reste faible autorise l'action et la bloque :

permit (principal, action == AgentCore::Action::"RefundTool___process_refund", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5") when guardrails { BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"] .confidenceScore.lessThanOrEqual(decimal("0.4")) };

À utiliser forbid lorsque vous souhaitez restreindre une autorisation qui existe déjà, c'est-à-dire une action autorisée par une autre politique, par exemple sur ses valeurs d'entrée. A forbid remplace toute autre subventionpermit, de sorte qu'elle est déduite de cette subvention existante. À elle seule, elle n'accorde rien : l'action reste refusée par défaut et le garde-fou n'est jamais consulté, de sorte qu'une personne seule forbid a besoin d'un compagnon permit pour la même action.

Important

La validation des politiques analyse l'ensemble des règles définies dans votre moteur et ne peut pas interpréter l'état d'un garde-corps. Un forbid dont la seule porte est un garde-corps semble donc inconditionnel, donc si rien d'autre dans le moteur n'autorise ce principe, cette action et cette ressource, l'ensemble est signalé comme trop restrictif :. Overly Restrictive: Policy Engine will deny every request for the specified principal (…​), action (…​) and resource (…​) combination if the policy is added or updated Par défaut, --validation-mode FAIL_ON_ANY_FINDINGS la politique est refusée. Passez quand même --validation-mode IGNORE_ALL_FINDINGS pour le créer.

Comme le résultat est une propriété de l'ensemble de règles plutôt que d'une seule instruction, son affichage dépend de ce que contient déjà le moteur.

Le refus est asynchrone. L'appel renvoie 202 avecCREATING, et la politique s'installe ensuite CREATE_FAILED avec la raisonstatusReasons, donc demandez l'état du terminal plutôt que de considérer le 202 comme un succès.

Pour une procédure pas à pas de bout en bout utilisant plutôt la AgentCore CLI, voir Getting started with guardrails. Pour les déclarations relatives à chaque type de cible, consultez les exemples de politique Guardrail.

Spécification d'un type de garde-corps

Pour choisir un type de garde-corps spécifique, utilisez l' BedrockGuardrails espace de noms :

Type de garde-corps Nom de la fonction de garde-corps

Filtre de contenu

BedrockGuardrails::ContentFilter

Attaque rapide

BedrockGuardrails::PromptAttack

Informations sensibles

BedrockGuardrails::SensitiveInformation

Sélection d'une catégorie de garde-corps

Sélectionnez une catégorie pour le type de garde-corps choisi (voirRambardes soutenues).

Par exemple : BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Effets pour les rambardes

Pour bloquer une demande d'autorisation sur un garde-corps, utilisez les effets permit etforbid. Elles continuent de régir l'autorisation des demandes.

forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6")) };

Pour supprimer les sorties des outils, des agents ou des modèles, utilisez l'suppressOutputeffet. suppressOutputagit sur les données renvoyées par une action. Une fois qu'une action autorisée est terminée, il évalue les sorties par rapport au garde-corps et supprime la sortie lorsque le garde-corps est violé.

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text]) .count() > 0 };
Important

Deux règles limitent le côté de la demande qu'un garde-corps peut lire, et les deux sont appliquées lorsque vous créez la politique.

  • Un effet d'autorisation (permitouforbid) peut lire uniquement context.input.* les chemins. L'suppressOutputeffet peut lire uniquement context.output.* les chemins. L'utilisation context.output avec permit ou forbid est rejetée avecGuardrail '<name>' references 'context.output' but the policy has an authorization effect.

  • Un seul appel de garde-corps ne peut pas mélanger context.input.* plusieurs context.output.* chemins ; tous les chemins d'un appel doivent se trouver du même côté. Pour filtrer à la fois une demande et sa réponse, rédigez deux appels de sécurité dans la même suppressOutput politique, un de chaque côté. La restriction s'applique par appel et non par politique.

Dans la mesure où une politique nomme une action spécifique, elle doit également nommer un ARN de passerelle spécifique avecresource ==. Le fait de laisser la ressource sans contrainte est refusé. Pour plus d'informations, consultez la section Exigences relatives à la spécificité des ressources.

Transmettre le contexte à votre garde-corps

Dans un état de garde-corps, spécifiez des chemins de donnéescontext.input.message, tels que ceux qui identifient les valeurs à extraire de la charge utile de l'action. Le garde-corps évalue les valeurs extraites. Vous pouvez spécifier un ou plusieurs chemins en fonction de votre schéma de demande ou de réponse.

Par exemple : [context.input.message, context.input.systemPrompt]

Vous pouvez fournir un chemin de données de deux manières :

Un chemin de terrain — context.input.<field> ou context.output.<field>

Utilisez-le lorsque la valeur souhaitée est une chaîne unique, telle qu'un argument d'outil ou un champ scalaire du corps d'une demande. Le chemin d'un champ doit se transformer en chaîne ; le fait de pointer un chemin vers un objet ou une liste est refusé lorsque vous créez la politique.

Un JSONPath — une chaîne littérale commençant par $

Utilisez-le lorsque le texte se trouve dans une liste ou un objet auquel le chemin d'un champ ne peut pas accéder, qu'il s'agisse d'une conversation ou d'une liste de blocs de contenu. Écrivez-le enraciné dans la charge utile, sans context.input. préfixe : par exemple. "$.messages[*].content" Un JSONPath étant évalué comme une requête, un caractère générique peut correspondre à de nombreuses valeurs, y compris des valeurs imbriquées à différentes profondeurs. Ces correspondances sont aplaties en une seule séquence de texte plutôt que conservées sous forme de liste.

Vous pouvez attribuer plusieurs chemins de données à chaque appel. Chaque chemin est extrait indépendamment et envoyé au garde-corps en tant que bloc de contenu distinct. Pour qu'une liste soit évaluée comme des éléments distincts, nommez les éléments avec des chemins séparés plutôt qu'un chemin générique.

Important

Un JSONPath ne comporte aucun marqueur de direction, de sorte que l'effet de la politique détermine sa direction : suppressOutput lit la réponse et tout autre effet lit la demande. Un garde-corps de sortie utilisant un JSONPath doit donc être unsuppressOutput, tandis qu'un garde-corps d'entrée peut être un forbid ou un a permit — les deux lisent la requête. Ne mélangez pas un JSONPath et un context.input.* champ vide dans le même appel ci-dessous suppressOutput : les deux impliquent des directions opposées et la demande est rejetée en raison d'un conflit secondaire.

Toutes les correspondances d'un seul JSONPath sont concaténées en une seule chaîne, sans aucun caractère de séparation entre elles. C'est délibéré : un modèle divisé en deux blocs de contenu, tel que le numéro de sécurité sociale 123- suivi de45-6789, reste contigu et ne peut pas passer inaperçu par un détecteur qui recherche le schéma complet. Cela signifie également que le texte provenant de correspondances adjacentes s'exécute ensemble, de sorte qu'un chemin qui balaie des champs non liés peut produire une valeur qu'aucun champ ne contient.

Un chemin qui ne correspond à rien n'apporte rien, tant qu'au moins un autre chemin configuré est résolu. Cela vous permet de nommer plusieurs formes candidates en un seul appel, pour des charges utiles dont la structure varie, et de faire en sorte que celle qui existe soit le chemin utilisé.

Avertissement

Un JSONPath n'est pas validé lorsque vous créez la politique. Contrairement à un chemin de champ, il ne AgentCore vérifie ni sa syntaxe ni son adaptation à votre schéma. Un chemin mal formé, ou un nom de champ que votre charge utile n'envoie jamais, arrive toujours. ACTIVE Ce qui se passe au moment de l'évaluation dépend de la résolution des autres problèmes.

Si aucun chemin de données configuré n'est résolu dans le périmètre, l'évaluation échoue et se termine. Aucun garde-fou ne pouvant fonctionner, la demande est refuséeAuthorization denied: request missing field(s) required for guardrail evaluation, en indiquant les chemins qu'elle n'a pas pu résoudre. Le trafic qui fonctionnait s'arrête. Vérifiez d'abord le JSONPath lorsque vous rencontrez cette erreur.

Si au moins un chemin configuré est résolu, les rambardes contenant du contenu s'exécutent et décident normalement, et seule la vérification dont le chemin n'a pas été résolu est ignorée. Cette vérification n'apporte rien et ne permet pas de trouver un résultat, de sorte qu'un seul chemin mal orthographié parmi plusieurs chemins actifs échoue silencieusement plutôt que bruyamment.

Testez chaque garde-corps JSONPath par rapport au contenu qu'il doit capter, et empruntez les chemins de Reaching text inside arrays with a JSONPath plutôt que de les adapter à partir d'une autre API.

Pour des exemples de chaque chemin d'API d'inférence, voir Atteindre du texte dans des tableaux avec un JSONPath.

Seuils pour les rambardes

Avec les filtres de contenu et la détection rapide des attaques, le garde-corps renvoie un score de confiance, qui est une valeur numérique comprise dans la plage [0, 1], où 0 correspond à un niveau de confiance faible et 1 à un niveau de confiance élevé. Le score représente le degré de confiance avec lequel le garde-corps a détecté une violation. Les scores possibles actuels sont les valeurs discrètes {0,0, 0,2, 0,4, 0,6, 0,8, 1,0}.

Pour définir un seuil, fournissez la valeur décimale à l'opérateur de comparaison, par exemplegreaterThan(decimal("0.4")).

Opérateurs de comparaison de scores

Vous pouvez appliquer les opérateurs de comparaison suivants à confidenceScoremaxConfidenceScore(), ou minConfidenceScore() :

Opérateur Usage

.greaterThan(decimal("X.X"))

Score > seuil

.greaterThanOrEqual(decimal("X.X"))

Score ≥ seuil

.lessThan(decimal("X.X"))

Score inférieur au seuil

.lessThanOrEqual(decimal("X.X"))

Score ≤ seuil

Vous pouvez utiliser une agrégation dans votre politique pour extraire et comparer les scores renvoyés par les garde-fous :

Agrégations

Agrégation Description Exemple

[<category>].confidenceScore

Accédez au score de confiance pour une catégorie spécifique (décimal). Non disponible pourSensitiveInformation.

["HATE"].confidenceScore

maxConfidenceScore()

Confiance maximale dans toutes les catégories numérisées (décimal)

.maxConfidenceScore()

minConfidenceScore()

Confiance minimale pour toutes les catégories numérisées (décimal)

.minConfidenceScore()

count()

Nombre de résultats détectés (long). Comparez-le avec un opérateur entier, pas avec une decimal méthode.

.count() > 0

categories()

L'ensemble de catégories détectées par le garde-corps (ensemble de chaînes)

.categories().contains("HATE")

Important

SensitiveInformationnécessite l'une des méthodes d'agrégation et ne prend pas en charge l'indexation par catégorie. Une déclaration telle que celle BedrockGuardrails::SensitiveInformation(["EMAIL"], [context.input.text])["EMAIL"].confidenceScore qui est rejetée lorsque vous créez la politique, avecPer-category indexing is not supported for SensitiveInformation. Utilisezcount(), categories()maxConfidenceScore(), ou à la minConfidenceScore() place. ContentFilteret PromptAttack soutenez les deux formes.

Comment choisir un seuil

Si vous ne spécifiez pas de seuil lorsque vous demandez au service de création, AgentCore définit une valeur par défaut. Si vous rédigez vos politiques sans l'aide du service de création, vous devez fournir la valeur de seuil.

Les valeurs par défaut suivantes sont calibrées pour fournir une couverture étendue avec une précision acceptable pour la plupart des charges de travail :

Type de garde-corps Seuil par défaut

Filtre de contenu

0.2

Détection rapide des attaques

0.4

Informations sensibles

0.2

Choix d'un seuil personnalisé

Si les seuils par défaut ne répondent pas à vos exigences, vous pouvez déterminer le seuil optimal pour votre charge de travail en utilisant l'une des approches suivantes.

Option 1 : évaluer par rapport à un ensemble de tests de référence

Utilisez cette approche lorsque vous disposez d'un ensemble de tests sélectionnés avec des résultats attendus clairs.

  1. Créez vos politiques et définissez le mode de votre moteur de politiques sur LOG_ONLY.

  2. Exécutez votre ensemble de tests via la passerelle à laquelle votre moteur de politiques est connecté.

  3. Consultez les journaux de chaque évaluation. Chaque entrée du journal inclut le contenu évalué et le score de confiance renvoyé par le garde-corps.

  4. Pour chaque résultat, indiquez si le garde-corps aurait dû signaler le contenu ou ne rien faire (vrai et faux respectivement).

  5. À l'aide de ces étiquettes, combinées aux scores de confiance disponibles dans vos journaux, créez une matrice de confusion à plusieurs valeurs de seuil. Comparez la précision et le rappel à chaque seuil pour sélectionner la valeur correspondant à votre tolérance aux faux positifs par rapport aux détections manquées.

Option 2 : évaluation par rapport au trafic de production

Utilisez cette approche lorsque vous ne disposez pas d'un ensemble de tests prédéfini et que vous souhaitez effectuer un étalonnage en utilisant des modèles de trafic réels.

  1. Créez vos politiques et définissez le mode de votre moteur de politiques sur LOG_ONLY.

  2. Permettez au moteur de politiques d'évaluer le trafic de production. Chaque entrée du journal inclut le contenu évalué et le score de confiance renvoyé par le garde-corps.

  3. Utilisez an LLM-as-a-judge pour étiqueter chaque résultat enregistré comme vrai (le garde-corps aurait dû signaler le contenu) ou faux (le garde-corps n'aurait pas dû signaler le contenu).

  4. À l'aide de ces étiquettes, créez une matrice de confusion à plusieurs valeurs de seuil. Comparez la précision et le rappel à chaque seuil pour sélectionner la valeur correspondant à votre tolérance aux faux positifs par rapport aux détections manquées.

Tester les glissières de sécurité dans une politique

AgentCore fournit plusieurs mécanismes pour tester les garde-corps avant de les appliquer au trafic de production. Vous pouvez contrôler l'application au niveau du moteur de politiques, au niveau des politiques individuelles, ou les deux, ce qui vous permet de valider le comportement des garde-corps de manière incrémentielle. Pour plus d'informations, consultez Tester une politique en mode LOG_ONLY.

Comment fonctionnent les garde-corps dans une politique

Vous pouvez placer une barrière de sécurité dans une politique sur n'importe quelle cible de passerelle. Les rambardes fonctionnent sur :

  • Objectifs du MCP — action<TargetName>___<ToolName>, atteinte grâce à POST /mcp () JSON-RPC tools/call

  • AgentCore Objectifs d'exécution — action <TargetName>___POST:/invocations

  • Cibles d'inférence : une cible par forme d'API, donc une action par API :

    • <TargetName>___POST:/v1/chat/completions

    • <TargetName>___POST:/v1/responses

    • <TargetName>___POST:/v1/messages

    • <TargetName>___GET:/v1/models

  • Cibles de proxy HTTP — action <TargetName>___<METHOD>:<uri>

Lorsqu'un appel arrive à votre passerelle, l'évaluateur de politiques effectue les opérations suivantes :

  1. Correspond au champ d'application — Identifie les politiques avec garde-fous qui s'appliquent à cette demande

  2. Extrait le contenu — Extrait le champ spécifié par dataPath (par exemplecontext.input.message) du corps de la demande

  3. Appelle InvokeGuardrailChecks l'API Bedrock — Évalue le contenu et injecte les scores de confiance renvoyés dans le contexte de l'évaluation des politiques

  4. Évalue la politique à l'aide des scores de protection : compare les scores de confiance renvoyés par rapport au seuil défini dans la politique

  5. Renvoie une décision, ALLOW ou DENY avec des annotations de politique, à la passerelle

Remarque : les barrières de sécurité ne sont pas déterministes, de sorte qu'une même entrée peut entraîner des sorties différentes. Les politiques sont déterministes ; le même contexte d'évaluation aboutira toujours à la même décision politique.

Limitations

  • Aucune prise en charge des regex ou de la correspondance de modèles : les garde-fous utilisent le score ML, et non les expressions régulières

  • Un garde-corps est requis dans un when guardrails {…​} bloc ; les blocs de garde-corps doivent comporter au moins un garde-corps défini à l'intérieur

  • Un appel de garde-corps ne peut pas lire les deux côtés d'une demande ; tous les chemins de données d'un appel doivent être l'un ou context.input.* l'autre. context.output.* Une suppressOutput politique peut être lue des deux côtés, mais pas à partir du même appel

  • Les barrières de sécurité ne sont pas déterministes : le même contenu peut obtenir des scores différents lors d'appels distincts, de sorte qu'une demande proche de votre seuil peut être autorisée une fois et refusée la prochaine fois

  • suppressOutputexige l'état d'un garde-corps ; son état doit consister uniquement en des vérifications du garde-corps. Il ne prend pas en charge le cèdre standard ou temporal {…​} les conditions

  • Un chemin de données $ -JSONPath n'est pas validé lors de sa création. Ni sa syntaxe ni son ajustement à votre schéma ne sont vérifiés. S'il s'agit du seul chemin et qu'il n'aboutit à rien, la demande est refusée plutôt que filtrée, et le refus désigne le chemin non résolu. Si un autre chemin est résolu, la vérification non résolue est ignorée silencieusement. Voir Transmettre le contexte à votre garde-corps

Note

Dans le cadre d'un effet d'autorisation (permitouforbid), vous pouvez combiner un garde-corps aux conditions ordinaires de Cedar dans une seule police. when guardrails { E }est l'équivalent d'une plaine when { E } dont le corps fait office de garde-corps ; l'guardrailsétiquette documente l'intention au lieu de restreindre la politique. Entrez l'appel du garde-corps when et la demande ou les conditions principales. unless Une seule politique peut ainsi comporter un appel de garde-fou, une condition Cedar et une condition temporelle. Voir Combiner un garde-corps avec des conditions de demande et Combiner des conditions temporelles, de garde-corps et de demande.

suppressOutputest l'exception : son état doit consister uniquement en des contrôles de sécurité. Pour plus d'informations, consultez la section Rédaction de barrières de sécurité dans les politiques.