# 정책의 가드레일
<a name="policy-guardrails-in-policies"></a>

이 섹션에서는 정책에서 Bedrock 가드레일을 정의하는 방법을 설명합니다. Bedrock Guardrails는 AI 애플리케이션을 안전하게 유지하기 위해 요청과 응답 모두에서 실행할 수 있는 구성 가능한 보호 기능을 제공합니다. 현재 정책에서 프롬프트 공격, 콘텐츠 필터 및 민감한 정보 가드레일을 정의할 수 있습니다. 각 가드레일은 범주와 0에서 1 사이의 임계값으로 구성되어야 합니다.

가드레일이 컨텍스트를 평가할 때 0에서 1 사이의 신뢰도 점수를 반환하여 평가된 콘텐츠가 정의된 속성(예: `PROMPT_INJECTION`)을 나타낸다는 신뢰도를 나타냅니다.

## 가드레일 리전 가용성
<a name="guardrails-regional-availability"></a>

다음 표에는 정책에서 가드레일을 지원하는 AWS 리전이 나와 있습니다.


|  | 미국 동부(버지니아 북부) | 미국 동부(오하이오) | 미국 서부(오리건) | 유럽(프랑크푸르트) | 유럽(아일랜드) | 유럽(런던) | 유럽(파리) | 유럽(스톡홀름) | 아시아 태평양(뭄바이) | 아시아 태평양(싱가포르) | 아시아 태평양(시드니) | 아시아 태평양(도쿄) | 아시아 태평양(서울) | 캐나다(중부) | 남아메리카(상파울루) |  AWS GovCloud(미국 서부) | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| 가드레일 지원 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 

## 시작하기 전 준비 사항
<a name="policy-guardrails-before-you-begin"></a>

시작하기 전에 IAM 역할을 올바르게 구성해야 합니다.

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

정책 엔진과 연결된 게이트웨이에 구성된 AgentCore 게이트웨이 실행 역할에는 Bedrock AgentCore 작업과 Bedrock 가드레일 모두에 대한 권한이 있어야 합니다. 정책 데이터 영역은 게이트웨이의 실행 역할에서 파생된 FAS(Forward Access Session) 자격 증명을 사용하여 사용자를 대신하여 Bedrock Guardrails API를 호출하기 때문에 `bedrock:InvokeGuardrailChecks` 권한이 필요합니다.

```
{
  "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"))`)에 10진수 값을 제공해야 합니다.

 **점수 비교 연산자** 

`minConfidenceScore()`아래 비교 연산자를 `confidenceScore`, `maxConfidenceScore()`또는에 적용할 수 있습니다.


| 연산자 | 용도 | 
| --- | --- | 
|  `.greaterThan(decimal("X.X"))`  | 점수 > 임계값 | 
|  `.greaterThanOrEqual(decimal("X.X"))`  | 점수 ≥ 임계값 | 
|  `.lessThan(decimal("X.X"))`  | 점수 < 임계값 | 
|  `.lessThanOrEqual(decimal("X.X"))`  | 점수 ≤ 임계값 | 

정책의 집계를 사용하여 가드레일이 반환한 점수를 추출하고 비교할 수 있습니다.

 **집계** 


| 집계 | 설명 | 예제 | 
| --- | --- | --- | 
|  `[<category>].confidenceScore`  | 특정 범주의 신뢰도 점수에 액세스([10진수](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `["HATE"].confidenceScore`  | 
|  `maxConfidenceScore()`  | 스캔한 모든 범주에 대한 최대 신뢰도([10진수](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `.maxConfidenceScore()`  | 
|  `minConfidenceScore()`  | 스캔한 모든 범주에 대한 최소 신뢰도([10진수](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. 각 결과에 대해 가드레일이 콘텐츠에 플래그를 지정했는지 아니면 아무 작업도 수행하지 않았는지(각각 true 및 false) 레이블을 지정합니다.

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 런타임 대상** - `POST /<target>/invocations` \* **HTTP 추론 대상** - `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 {…​}` 블록에는 가드레일이 필요합니다**. 가드레일 블록에는 내부에 정의된 가드레일이 하나 이상 있어야 합니다.