# 政策中的护栏
<a name="policy-guardrails-in-policies"></a>

本节介绍如何在策略中定义 Bedrock Guardrails。Bedrock Guardrails 提供可配置的保护措施，可以在请求和响应上运行，以确保 AI 应用程序的安全。目前，您可以在策略中定义即时攻击、内容过滤器和敏感信息防护栏。每个护栏都必须配置一个类别和一个介于 0 和 1 之间的阈值。

当护栏评估上下文时，它会返回介于 0 和 1 之间的置信度分数，表示所评估的内容表现出定义属性的置信度（例如）。`PROMPT_INJECTION`

## 护栏的区域可用性
<a name="guardrails-regional-availability"></a>

下表显示了哪些 AWS 地区支持政策中的护栏：


|  | 美国东部（弗吉尼亚州北部） | 美国东部（俄亥俄州） | 美国西部（俄勒冈州） | 欧洲地区（法兰克福） | 欧洲地区（爱尔兰） | 欧洲地区（伦敦） | 欧洲地区（巴黎） | 欧洲地区（斯德哥尔摩） | 亚太地区（孟买） | 亚太地区（新加坡） | 亚太地区（悉尼） | 亚太地区（东京） | 亚太地区 (首尔) | 加拿大（中部） | 南美洲（圣保罗） |  AWS GovCloud (US-West) | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| 护栏 Support | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 

## 开始前的准备工作
<a name="policy-guardrails-before-you-begin"></a>

在开始之前，您需要正确配置您的 IAM 角色。

### Permissions
<a name="policy-guardrails-permissions"></a>

在与策略引擎关联的 AgentCore 网关上配置的网关执行角色必须同时具有 Bedrock AgentCore 操作和 Bedrock Guardrails 的权限。该`bedrock:InvokeGuardrailChecks`权限是必需的，因为策略数据平面使用从网关的执行角色派生的 FAS（正向访问会话）凭据代表您调用 Bedrock Guardrails API。

```
{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "*"
    }
  ]
}
```

### 支撑的护栏
<a name="supported-guardrails"></a>


| 安全名称 | 实体类型 | 安全保护类别 | 
| --- | --- | --- | 
| 内容过滤器 |  `ContentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | 
| 即时攻击检测 |  `PromptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | 
| 敏感信息 |  `SensitiveInformation`  |  `CREDIT_DEBIT_CARD_NUMBER`、`US_SOCIAL_SECURITY_NUMBER`、`EMAIL`、`PHONE`、、`ADDRESS`、`AWS_ACCESS_KEY`、`AWS_SECRET_KEY`、`PASSWORD`、`IP_ADDRESS`、`NAME`、`USERNAME`、和 [20 多个](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | 

## 在政策中定义护栏
<a name="defining-guardrails-in-policies"></a>

要在政策中定义护栏，您可以将策略写成代码，也可以用自然语言描述政策。与您可能已经创建的任何现有策略类似，您需要使用条件 (`permit`) 来指定效果（例如`when guardrails`）。在这种情况下，您需要提供要启用的特定护栏防护措施、要使用的防护类别、您希望护栏防护评估的背景以及置信度分数阈值。

 **护栏定义示例** 

```
suppressOutput (principal, action == AgentCore::Action::"<TARGET_NAME>_<METHOD>:<URI>", resource == AgentCore::Gateway::"<GATEWAY_ARN>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};
```

### 指定护栏防护装置
<a name="specifying-a-guardrail-safeguard"></a>

要选择特定的安全实体类型，请使用 BedrockGuardrails 命名空间：


| Safeguard | 护栏功能名称 | 
| --- | --- | 
| 内容过滤器 |  `BedrockGuardrails::ContentFilter`  | 
| 即时攻击 |  `BedrockGuardrails::PromptAttack`  | 
| 敏感信息 |  `BedrockGuardrails::SensitiveInformation`  | 

### 选择防护类别
<a name="selecting-a-safeguard-category"></a>

为给定的安全措施选择一个类别（请参阅[支撑的护栏](#supported-guardrails)）。

例如 `BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])` 

### 对护栏的影响
<a name="effects-for-guardrails"></a>

要创建用于授权请求的护栏，请使用`permit`和效果。`forbid`它们继续控制请求授权。

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

要创建用于抑制工具、代理或模型输出的护栏，请使用该效果。`suppressOutput` `suppressOutput`是一种对操作返回的数据进行操作的新效果。授权操作完成后，它会对照护栏评估输出，并在违反护栏时抑制输出。

```
suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])["US_SOCIAL_SECURITY_NUMBER"]
    .confidenceScore
    .greaterThan(decimal("0.5"))
};
```

### 将上下文传递给您的护栏
<a name="passing-context-to-your-guardrail"></a>

在策略中定义护栏时，必须指定数据路径（例如`context.input.message`），以标识要从操作的有效负载中提取的值。护栏对提取的值进行评估。您可以根据请求或响应架构指定一条或多条数据路径。

例如 `[context.input.message, context.input.systemPrompt]` 

### 护栏的阈值
<a name="thresholds-for-guardrails"></a>

通过内容过滤器和即时攻击检测，护栏会返回置信度分数，该分数是 [0, 1] 范围内的数值，其中 0 表示低置信度，1 表示高置信度。该分数表示护栏检测到违规行为的信心程度。当前可能的分数是离散值 {0、0.2、0.4、0.6、0.8 和 1.0}。

要设置阈值，您需要向比较运算符提供十进制值（例如`greaterThan(decimal("0.4"))`）。

 **分数比较运算符** 

您可以将以下比较运算符应用于`confidenceScore``maxConfidenceScore()`、或`minConfidenceScore()`：


| 运算符 | 用量 | 
| --- | --- | 
|  `.greaterThan(decimal("X.X"))`  | 分数 > 阈值 | 
|  `.greaterThanOrEqual(decimal("X.X"))`  | 分数 ≥ 阈值 | 
|  `.lessThan(decimal("X.X"))`  | 分数 < 阈值 | 
|  `.lessThanOrEqual(decimal("X.X"))`  | 分数 ≤ 阈值 | 

您可以在策略中使用聚合来提取和比较护栏返回的分数：

 **聚合** 


| 聚合 | 说明 | 示例 | 
| --- | --- | --- | 
|  `[<category>].confidenceScore`  | 访问特定类别的置信度分[数（十进制](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)） |  `["HATE"].confidenceScore`  | 
|  `maxConfidenceScore()`  | 所有扫描类别的最大可信度（[十进制](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)） |  `.maxConfidenceScore()`  | 
|  `minConfidenceScore()`  | 所有扫描类别的最低置信度（[十进制](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)） |  `.minConfidenceScore()`  | 
|  `count()`  | 检测到的发现数量（[长](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-long)） |  `.count()`  | 

#### 如何选择阈值
<a name="how-to-choose-a-threshold"></a>

如果在提示创作服务时未指定阈值，则 AgentCore 设置默认值。如果您在没有创作服务帮助的情况下编写策略，则必须提供阈值。

以下默认值经过校准，可为大多数工作负载提供广泛的覆盖范围和可接受的精度：


| Safeguard | 默认阈值 | 
| --- | --- | 
| 内容过滤器 | 0.2 | 
| 即时攻击检测 | 0.4 | 
| 敏感信息 | 0.2 | 

##### 选择自定义阈值
<a name="_choosing_a_custom_threshold"></a>

如果默认阈值不符合您的要求，则可以使用以下方法之一确定工作负载的最佳阈值。

 **选项 1：对照黄金测试集进行评估** 

当你有一组精心策划的测试输入并具有明确的预期结果时，请使用这种方法。

1. 创建您的策略并将策略引擎模式设置为 LOG\_ONLY。

1. 通过您的策略引擎所连接的网关运行您的测试集。

1. 查看每次评估的日志。每个日志条目都包括评估的内容和护栏返回的置信度分数。

1. 对于每个结果，标注护栏是应该标记内容还是什么都不做（分别为真和假）。

1. 使用这些标签，再加上日志中可用的置信度分数，可以在多个阈值下构建混淆矩阵。比较每个阈值的精度和召回率，选择与误报容忍度与错过检测的容忍度一致的值。

 **选项 2：根据生产流量进行评估** 

如果您没有预先构建的测试集，并且想要使用真实的流量模式进行校准，请使用此方法。

1. 创建您的策略并将策略引擎模式设置为 LOG\_ONLY。

1. 允许策略引擎评估生产流量。每个日志条目都包括评估的内容和护栏返回的置信度分数。

1. 使用 LLM-as-a-judge 将每个记录的结果标记为 true（护栏本应标记内容）或 false（护栏不应该标记内容）。

1. 使用这些标签，在多个阈值下构建混淆矩阵。比较每个阈值的精度和召回率，选择与误报容忍度与错过检测的容忍度一致的值。

### 测试政策中的护栏
<a name="_test_guardrails_in_policy"></a>

AgentCore 提供了多种机制，用于在生产流量上强制执行护栏策略之前对其进行测试。您可以在策略引擎级别、单个策略级别或两者兼而有之地控制强制执行，从而可以逐步验证护栏行为。有关更多信息[，请参阅测试策略](policy-test-a-policy.md)。

## 护栏如何与政策配合
<a name="how-guardrails-works-with-policy"></a>

护栏策略可以应用于任何网关目标。**护栏运行于：\* **MCP 目标 — `POST /mcp` (JSON-RPC `tools/call`) \* HTTP** **运行时目标 — \* HTTP 推`POST /<target>/invocations`理目标** —** `POST /inference` 

当呼叫到达您的网关时，策略评估器会执行以下操作：

1.  **匹配范围**-确定哪些护栏策略适用于此请求

1.  **提取内容** — 从请求正文中提取由`dataPath`（例如`context.input.message`）指定的字段

1.  **调用 Bedrock InvokeGuardrailChecks API** — 评估内容并将返回的置信度分数注入策略评估上下文中

1.  **使用护栏分数评估策略 — 将返回的置信度分数**与策略中定义的阈值进行比较

1.  **将决策**`ALLOW`或`DENY`带有策略注释的决策返回网关

注意：护栏是不确定的。相同的输入可能导致不同的输出。但是，策略是确定性的，相同的输入将始终产生相同的输出。

## 政策中护栏的局限性
<a name="guardrails-in-policy-limitations"></a>
+  **不支持正则表达式或模式匹配** — 护栏使用 ML 评分，而不是正则表达式
+  **你不能将标准的 Cedar 保单与护栏混**用——取而代之 `when guardrails {…​}` `when {…​}` 
+  方@@ **块中需要护栏——护栏`when guardrails {…​}`块里面必须至少定义一个**护栏