판정, 액션, 마스킹 용어집

firewall 이벤트나 guardrail match를 읽을 때, 행은 게이트웨이가 결정한 것을 알려줍니다 — deny, sanitize, [EMAIL]. 이 페이지는 그 단어들의 조회 테이블입니다: 각각이 무엇을 의미하고, 호출에 무엇을 하고, 전체 메커니즘을 위해 어디로 갈지. 규칙을 작성하거나 이벤트 피드를 트리아지하는 동안 열어 두세요. 두 제어 평면이 두 어휘를 생성합니다. Firewall은 툴 액션을 통제하고 판정을 방출합니다. Guardrails는 프롬프트와 응답 텍스트를 스크리닝하고 액션을, 그리고 마스킹 시 타입 지정 마스킹 태그를 방출합니다. 그들은 결코 단어를 공유하지 않습니다 — guardrail은 결코 deny라고 말하지 않고, firewall은 결코 mask라고 말하지 않습니다.

이것은 how-to가 아니라 레퍼런스 인덱스입니다. 각 컨트롤 뒤의 사용 사례는 Guardrails vs Firewall을; HTTP 본문은 보안 오류 코드를 참조하세요.

1. firewall 판정 용어집

firewall 규칙(또는 정책의 default_verdict)은 모든 툴 호출을 이 여섯 판정 중 정확히 하나로 해석합니다. 엔진은 규칙을 우선순위 순으로 순회하며, 첫 매치가 이기고, 아무것도 매치하지 않으면 기본값으로 폴백합니다.

allow — 호출을 통과시킨다

호출이 툴로 진행됩니다. 여전히 firewall 이벤트로 로깅되므로 Runs와 이벤트 피드에 나타납니다. 에이전트가 사용하도록 명시적으로 신뢰되는 툴에 대해 원하는 것입니다.

audit — 허용하되 검토를 위해 기록한다

allow와 동일한 트래픽이지만, 관찰하고 싶은 것으로 플래그됩니다. 권장 default_verdict입니다: 규칙이 튜닝될 때까지 모든 것을 관찰하고 아무것도 차단하지 않습니다. balanced 자율성 수준은 PII Shield guardrail을 flag-only(audit)로 제공하므로, 호출을 보류하지 않고 PII가 기록됩니다.

deny — 호출을 차단한다

호출이 결코 툴에 도달하지 않습니다. inbound 표면에서는 HTTP 400 firewall_blocked을 반환하고; MCP 게이트웨이를 통해서는 모델이 크래시 대신 반응할 수 있도록 툴 오류(firewall deny: <reason>)로 돌아옵니다. skip-retry로 표시됨. 모델 토큰을 소모하지 않음.

sanitize — 인자를 편집하고 정화된 호출을 전달한다

툴 호출 인자에서 매치된 부분 문자열(시크릿, PII)을 [redacted:<preset>] 토큰으로 대체한 뒤, 정화된 인자로 호출을 전달합니다. 인자만 편집합니다 — 툴이 반환하는 콘텐츠는 결코 아님. 아직 호출 시점 인자가 없는 inbound 표면에서는 sanitize가 deny로 격상됩니다.

pending_approval — 사람을 위해 보류한다

호출이 검토를 위해 큐에 들어가고 에이전트는 승인 id를 담은 held 응답을 받습니다(HTTP 400 firewall_approval_pending). 검토자가 콘솔에서나 HMAC 웹훅 콜백을 통해 해결합니다; 에이전트는 id를 폴링하고 일회용 승인 헤더와 함께 한 번 재제출합니다. Human approval 참조.

cap_cost — 실행이 초과 지출하면 거부한다

규칙별 센트 상한을 가진 규칙으로 작성됩니다. 에이전트 실행이 예산 아래에 있는 동안 allow로, 누적 지출이 상한을 넘으면 deny로 해석됩니다 — 그래서 이벤트는 리터럴 단어 cap_cost가 아니라 allow 또는 deny를 보여줍니다. 폭주 루프를 위한 회로 차단기.

shadow mode에서는 deny / sanitize / pending_approval이 모두 audit로 강등되고 이유에 [shadow] would …가 접두됩니다. 이벤트는 발동했을 판정을 기록하지만, 트래픽은 변경되지 않습니다 — 그것이 안전한 롤아웃의 핵심입니다.

기본 판정

default_verdict는 세 개의 비대화형 판정만 받아들입니다:

Value	어떤 규칙도 매치하지 않을 때의 의미
`allow`	커버되지 않은 툴 호출을 조용히 허용.
`audit`	허용하되 기록 — 기본값.
`deny`	어떤 규칙도 명시적으로 허용하지 않은 것을 차단(기본 거부 자세).

tight 자율성 수준은 default_verdict: deny를 설정합니다; balanced와 제공되는 기본값은 audit를 사용합니다.

2. Guardrail 액션

guardrail 규칙은 다섯 액션 중 하나를 발동합니다. 이들은 판정의 텍스트-평면 등가물이며 — guardrail 규칙은 결코 firewall 판정을 생성하지 않습니다.

Action	무엇을 하는가	쿼터
`block`	전체 요청을 HTTP 400 `guardrail_blocked`으로 거부.	없음 — 입력 차단은 미터링 전에 발동; 출력 차단은 환불.
`mask`	각 매치를 타입 지정 태그로 편집하고(§3 참조) 정화된 텍스트 전달.	정상 — 호출이 진행됨.
`flag`	로그만. 매치를 기록; 트래픽에 대해 아무것도 변경하지 않음.	정상.
`annotate`	비차단. 텍스트를 마스킹하거나 차단하지 않고 사람 판독 가능한 노트를 요청에 첨부(보안 공지로 업스트림 주입).	정상.
`spotlight`	비차단. 매치된(신뢰할 수 없는) 텍스트를 구분자로 감싸고 모델에게 구분된 영역을 지시가 아니라 데이터로 취급하라고 알림 — 프롬프트 인젝션 “spotlighting” 방어.	정상.

차단된 guardrail 요청은 skip-retry로 표시됩니다 — 동일한 프롬프트를 다른 채널에 대해 다시 실행하면 그저 다시 차단될 뿐입니다.

새 규칙을 block 또는 mask로 전환하기 전에 실제 트래픽에 대해 측정하려면 flag를 사용하세요. Matches 피드는 트래픽 영향 제로로 무엇이 잡혔을지를 보여줍니다 — firewall shadow mode의 guardrail 대응물.

단일 pii 규칙은 entity_actions로 서로 다른 엔티티에 서로 다른 액션을 적용할 수 있습니다 — 한 규칙에서 이메일과 전화는 마스킹하되 credit_card와 ssn은 차단. 키는 규칙에서 활성화된 엔티티여야 합니다; 값은 block / mask / flag / annotate여야 합니다.

3. 마스킹 태그 용어집

mask 액션에서, 매치된 모든 엔티티는 타입 지정 태그 — [<UPPERCASE_ENTITY_NAME>] — 로 인라인 대체되므로, 모델(입력 단계) 또는 호출자(출력 단계)는 값 없이 데이터의 형태를 봅니다. 마스킹은 스트리밍 응답을 포함해 양 단계에서 실행됩니다: 토큰 인식 스트림 스캐너가 청크 경계를 가로지르는 매치를 클라이언트에 도달하기 전에 마스킹합니다.

Entity	Tag
`email`	`[EMAIL]`
`phone`	`[PHONE]`
`credit_card`	`[CREDIT_CARD]`
`ssn`	`[SSN]`
`ip`	`[IP]`
`iban`	`[IBAN]`
`mac_address`	`[MAC_ADDRESS]`
`jwt`	`[JWT]`
`aws_access_key`	`[AWS_ACCESS_KEY]`
`api_key_openai`	`[API_KEY_OPENAI]`
`bitcoin_address`	`[BITCOIN_ADDRESS]`

세 개의 지역 식별자가 기본 세트 위에 제공됩니다:

Entity	Tag	Region
`jp_mynumber`	`[JP_MYNUMBER]`	일본
`kr_rrn`	`[KR_RRN]`	대한민국
`cn_resident_id`	`[CN_RESIDENT_ID]`	중국

커스텀 엔티티는 동일한 규칙을 따릅니다. employee_id라는 커스텀 엔티티는 명시적 mask_with 대체를 설정하지 않는 한 [EMPLOYEE_ID]로 마스킹됩니다. 규칙당 최대 25개 커스텀 엔티티, 각각 선택적 luhn 체크섬을 가진 RE2 정규식. PII 탐지 참조.

4. 한 가지 작동 예시

단일 db.query 툴 호출은, 위에서 아래로 읽으면, 두 어휘를 모두 건드립니다:

firewall verdict : sanitize        # secret stripped from the SQL argument
guardrail action : mask            # an email in the prompt redacted
masking tag      : [EMAIL]         # what the model actually receives

firewall sanitize가 툴 인자를 정화했고; guardrail mask가 프롬프트 텍스트를 정화했고; [EMAIL] 태그는 모델이 주소 대신 보는 것입니다. 동일한 요청, 세 개의 서로 다른 계층, 이 용어집에서 나온 세 단어.

5. 판정과 함께 보게 될 자세 단어

이들은 판정이나 액션이 아니지만, 판정이 강제될지 여부를 결정합니다 — 그래서 동일한 이벤트와 설정 뷰에 나타납니다.

Word	Plane	Meaning
Shadow mode	Firewall	정책별 플래그. 모든 강제 판정을 `audit`로 강등하고, 이유에 `[shadow] would …`를 접두.
Observe mode	Firewall	워크스페이스 설정. 어떤 정책도 해석되지 않을 때, 호출을 허용하되 커버리지 갭으로 로깅(Discovered tools).
Enforce	Firewall	Shadow 끔 + 정책 연결: 판정이 효력 발생.
Fail-open	Guardrails	고급 규칙(`llm_judge`, `grounding`, `external`)의 기본값 — 타임아웃이 관찰되고, 요청이 계속됨. 규칙별로 fail-closed로 전환.
Log raw content	Guardrails	기본 꺼짐. 꺼져 있으면, 매치는 규칙이 발동했다는 것을 기록하지만 매치된 부분 문자열은 아님.

deny-대-audit-대-shadow 구분의 심층은 강제 모드를 참조하세요.

6. 각 단어가 정의된 곳

Surface	Vocabulary	Home page
Firewall 정책	`allow` `audit` `deny` `sanitize` `pending_approval` `cap_cost`	Firewall
Firewall 규칙 매칭	`tool_name_glob`, `args_match`, egress, sequence	Firewall 규칙
Guardrail 규칙	`block` `mask` `flag` `annotate` `spotlight`	Guardrails
Guardrail PII	엔티티 이름 + 마스킹 태그	Guardrails
MCP & skills	skill 위험 밴드, `quarantine` / `block` 모드	Firewall MCP, Firewall skills
HTTP 오류 본문	`guardrail_blocked`, `firewall_blocked`, `firewall_approval_pending`	오류 코드

여기의 모든 용어는 신원, 범위, 위협 용어를 추가하는 더 넓은 개념 용어집에도 나타납니다. 이 페이지는 좁은, 결정 중심의 슬라이스입니다 — 판정, 액션, 마스킹 태그만.

7. 관련 읽을거리

왜 차단되었나요?

단일 거부된 호출을 그것을 멈춘 정확한 규칙과 판정으로 추적하세요.

강제 모드

audit, shadow, observe, enforce가 어떻게 관련되는지 — 그리고 안전하게 롤아웃하는 방법.

Guardrails vs Firewall

어느 평면이 어느 결정을 소유하는지, 그리고 왜 요청이 둘 다를 통과할 수 있는지.

위험한 툴 호출

deny와 sanitize 판정이 멈추기 위해 존재하는 위협.

​1. firewall 판정 용어집

​기본 판정

​2. Guardrail 액션

​3. 마스킹 태그 용어집

​4. 한 가지 작동 예시

​5. 판정과 함께 보게 될 자세 단어

​6. 각 단어가 정의된 곳

​7. 관련 읽을거리

왜 차단되었나요?

강제 모드

Guardrails vs Firewall

위험한 툴 호출

1. firewall 판정 용어집

기본 판정

2. Guardrail 액션

3. 마스킹 태그 용어집

4. 한 가지 작동 예시

5. 판정과 함께 보게 될 자세 단어

6. 각 단어가 정의된 곳

7. 관련 읽을거리