규칙
매칭 언어 — 툴 glob, 인자 절, egress 목록, 새니타이저, 그리고
시퀀스.
MCP 서버
Model Context Protocol 서버를 단일 감사 게이트웨이 뒤에서 등록하고
통제합니다.
Skills
에이전트가 설치하는 기능을 실행되기 전에 스캔하고 위험 점수를
매깁니다.
1. Firewall이란
AI 에이전트는 텍스트를 생성하기만 하는 것이 아닙니다 — 행동합니다.shell.exec를 호출하고, db.query로 질의하고, URL을 가져오고, 커뮤니티
skill을 로드하거나, 서드파티 MCP 서버를 통해 툴 호출을 라우팅합니다. 이들
각각은 실제 세계에 결과를 미치는 액션이며, 프롬프트 수준의 guardrail은
이를 볼 수 없습니다.
Firewall은 게이트웨이가 모든 툴 호출에 대해 평가하는
워크스페이스 범위의, 이름이 지정된 정책입니다. 정책을 한 번 작성하고,
API 키를 그것에 연결하거나(또는 하나를 워크스페이스 기본값으로 설정),
그 후로는 그 키가 발행하는 모든 툴 호출이 정책에 대해 검사됩니다 —
툴에 도달하기 전에.
각 정책은 순서가 있는 규칙 목록입니다. 규칙은 한 가지를 결정합니다 —
어떤 툴 호출에 적용되는지(툴 이름 glob, 선택적으로 skill 및 강제 표면에
범위 지정됨)와 그것에 대해 무엇을 할지(판정: allow, audit, deny,
sanitize, 승인 대기, 또는 비용 상한). 엔진은 규칙을 우선순위 순으로
순회하며, 첫 매치가 이깁니다. 아무것도 매치하지 않으면 정책의 기본
판정으로 폴백합니다.
정책을 편집하면 그것에 연결된 모든 키에서 바로 다음 호출에
반영됩니다. 재배포 없음. 에이전트 코드 변경 없음. 정책은 게이트웨이에서
강제됩니다 — 에이전트는 이전과 정확히 동일하게 툴 호출을 계속 발행합니다.
탐지는 게이트웨이에서, 최초 사용 시 일어납니다. Firewall은
에이전트의 패키지 매니저나 파일시스템 내부가 아니라 LLM 릴레이 경로에
위치합니다. 에이전트가 자체 설치한 툴, MCP 서버, 또는 skill은 설치 시점이
아니라 그 호출이 게이트웨이를 처음 가로지를 때 포착됩니다. 이는
의도적입니다: 그것은 기능이 어떻게 거기에 도달했는지와 무관하게 모든
프로바이더, 모든 에이전트, 모든 툴 호출을 보는 단일 초크 포인트입니다.
2. 네 가지 강제 표면
모든 툴 호출은 정확히 하나의 표면에 대해 평가됩니다 — firewall이 그것을 보는 요청 수명 주기의 지점:| 표면 | 무엇을 보는가 |
|---|---|
inbound | 에이전트가 요청에서 모델에게 광고하는 툴(툴 정의). 위험한 툴을 모델이 선택조차 하기 전에 차단할 수 있게 합니다. |
response | 모델이 응답에서 발행하는 tool_calls. |
mcp | Firewall MCP 게이트웨이를 통해 디스패치되거나 SDK 훅을 통해 평가되는 tools/call. |
egress | 툴이 보고하는 아웃바운드 네트워크 목적지(호스트 / IP / CIDR) — SSRF 및 데이터 유출 표면. |
3. 핵심 개념
| 개념 | 정의 |
|---|---|
| Policy | 이름이 지정된, 워크스페이스 범위 규칙 세트. enabled, is_default, default_verdict, 그리고 shadow_mode 플래그를 가집니다. |
| Rule | 정책 내부의 한 검사: 우선순위, 툴/skill 매치, 선택적 표면, 선택적 인자 술어, 그리고 판정. 규칙 참조. |
| Verdict | 규칙(또는 기본값)이 생성하는 액션 — §4 참조. |
| Default verdict | 어떤 규칙도 매치하지 않을 때 적용됨. allow, audit(기본값), 또는 deny 중 하나. |
| Shadow mode | 정책이 평가하고 로깅하지만 결코 차단하지 않습니다 — 모든 강제 판정이 audit로 강등되고 이유에 [shadow] would …가 접두됩니다. 안전한 롤아웃 스위치. |
| Observe mode | 워크스페이스 수준 설정. 요청이 어떤 정책에도 해석되지 않고 observe mode가 켜져 있으면, 호출은 허용되지만 커버리지 갭으로 로깅됩니다 — 이것이 Discovered-tools 뷰를 채웁니다. |
범위 지정과 해석
정책은 Guardrails 및 API 키와 정확히 동일하게 해석됩니다 — 활성 워크스페이스가 있으면 워크스페이스 공유. 임의의 툴 호출에 대해 게이트웨이는 다음 순서로 정책을 해석합니다:- 키 연결 — 호출하는 키에
firewall_policy_id가 있으면 그 정책이 적용됩니다(존재하고 활성화된 경우). - 워크스페이스 기본값 — 그렇지 않으면 워크스페이스의 활성화된
is_default정책이 적용됩니다. - 둘 다 아님 — 강제 없음. observe mode가 켜져 있으면 호출이 허용되고 갭으로 로깅됩니다; 꺼져 있으면 호출이 조용히 허용됩니다 (기능을 한 번도 활성화하지 않은 워크스페이스와 바이트 단위로 동일).
알 수 없는 것에는 페일 오픈, 모호한 것에는 페일 클로즈. 정책 해석이
일시적 오류에 부딪히면 게이트웨이는 트래픽을 중단시키기보다
observe/allow로 저하됩니다. 그러나 강제하지 않는 것이 규칙을 무력화할
경우 — 사용 가능한 목적지가 없는 egress 보고, 도달 불가능한 승인 저장소,
소유권을 해석할 수 없는 skill — 엔진은 페일 클로즈합니다(deny 또는
hold). 가용성은 보존되며, 중요한 경우에 안전성이 조용히 건너뛰어지지
않습니다.
4. Verdicts
규칙(또는 기본 판정)은 다음 중 하나를 생성합니다:| Verdict | 무엇을 하는가 |
|---|---|
allow | 호출을 통과시킵니다. 로깅됨. |
audit | 허용하되 검토를 위해 기록합니다. 기본 default_verdict — 준비될 때까지 모든 것을 관찰하고 아무것도 차단하지 않습니다. |
deny | 호출을 차단합니다. 에이전트는 툴 오류를 봅니다(또는 inbound 표면에서는 HTTP 400). |
sanitize | 툴 인자에서 매치된 부분 문자열(시크릿, PII)을 마스킹하고 정화된 호출을 전달합니다. 새니타이저 참조. inbound 표면에서는 — 아직 호출 시점 인자가 없으므로 — sanitize가 block으로 격상됩니다. |
pending_approval | 호출을 사람을 위해 보류합니다. 에이전트는 “held” 응답을 받습니다; 검토자가 대역 외에서 승인 또는 거부합니다; 에이전트는 일회용 승인 토큰으로 재제출합니다. §7 참조. |
cap_cost | 에이전트 실행의 누적 지출이 규칙별 센트 상한을 초과하면 거부합니다. 폭주 루프를 위한 회로 차단기. |
deny / sanitize / pending_approval이 모두
audit로 강등되므로, 정책이 트래픽을 변경하기 전에 그 영향을 측정할 수
있습니다.
5. 툴 호출이 평가되는 방식
- 툴 호출이 게이트웨이에 도달합니다(inbound로 광고됨, 응답에서 발행됨, MCP 게이트웨이를 통해 디스패치됨, 또는 egress로 보고됨).
- 엔진이 활성 정책을 해석합니다(§3).
- 정책의 규칙을 우선순위 순으로 순회합니다(낮은 우선순위 먼저; 동점은 규칙 id로 깨짐). 규칙은 그 표면, 툴 이름 glob, 선택적 skill 이름 glob, 선택적 인자 절, 그리고 선택적 egress 범위가 모두 매치할 때 매치합니다.
- 첫 매치가 이깁니다 → 규칙의 판정이 적용됩니다. 어떤 규칙도
매치하지 않으면 → 정책의
default_verdict. - 호출이 통제되는 skill에 의해 소유되면,
skill의 강제 모드가 그 위에 적용됩니다 —
block모드의 skill은 deny를 강제하고;quarantine모드의 skill은 deny에 미치지 않는 모든 것을pending_approval로 격상시킵니다. - 결정은 firewall 이벤트로 로깅되며(dry run이 아닌 한), 에이전트 실행 및 세션과 상관 관계가 지어집니다.
6. block은 어떻게 보이는가
inbound 표면의 거부된 호출은 OpenAI 형태의 오류 본문, 오류 코드firewall_blocked, 그리고 툴과 이유를 명시하는 메시지와 함께
HTTP 400을 반환합니다 — 예: tool "shell.exec" blocked by firewall: destructive shell command. 오류는 구조화된 metadata(이유 코드, 위험
요인, 점수)를 담고 skip-retry로 표시됩니다(동일한 호출을 다시 실행해도
그저 다시 차단될 뿐입니다).
MCP 게이트웨이를 통해 디스패치된 호출은 전송 실패가 아니라 툴 오류
(firewall deny: <reason>)로 차단되므로, 모델이 거부를 보고 반응할 수
있습니다 — 다른 툴 선택, 사용자에게 질문, 또는 중단 — 크래시 대신.
held 호출(pending_approval)은 코드 firewall_approval_pending과
클라이언트가 폴링하는 승인 id와 함께 HTTP 400을 반환합니다.
7. Human approval (HITL)
pending_approval 판정은 툴 호출을 대역 외 검토로 전환합니다:
- 엔진이 승인 레코드를 큐에 넣고 그 id를 담은 “held” 응답을 반환합니다; 호출은 툴에 도달하지 않습니다.
- 검토자가 그것을 해결합니다 — 콘솔에서(Developer+), 또는 자체 승인 시스템에 대한 HMAC 서명 웹훅 콜백을 통해.
- 에이전트(또는 MCP SDK)가 승인 id를 폴링합니다; 일단 승인되면
일회용
X-OrcaRouter-Firewall-Approval헤더와 함께 원래 호출을 재제출하고, 게이트웨이는 그것을 그 한 번 통과시킵니다.
rule_changed가 기록되어 검토자가 컨텍스트가 변했음을 압니다.
8. 자율성 수준 — 전체 자세를 위한 단일 스위치
규칙별로 정책을 튜닝하는 것은 정밀한 경로입니다; 자율성 수준은 빠른 경로입니다. 단일 컨트롤이 워크스페이스의 Firewall 및 Guardrails 자세를 한 트랜잭션에서 원자적으로 교체하며, 원클릭 실행 취소를 제공합니다:| 수준 | 자세 |
|---|---|
tight | 파괴적 셸, 인자 내 시크릿, SSRF egress 차단(기본 거부); PII Shield + Secrets Blocker guardrails 켬; observe mode 끔. |
balanced | 파괴적 셸 감사, PII 플래그; observe mode 끔. 권장 시작 자세. |
permissive | 강제 정책 없음, guardrails 없음; observe mode 켬이라 여전히 모든 것을 볼 수 있음. |
9. 이상 탐지
정적 규칙을 넘어, Firewall은 각 워크스페이스의 정상적인 툴 사용 형태를 학습하고 뷰어 판독 가능한 피드에서 편차를 플래그합니다:- 속도 / 비용 급증 — 툴별 활동이 학습된 주중 시간대 베이스라인
(14일 롤링 평균)에 대해 채점되므로, “일요일 새벽 3시의
db.query호출 100건”은 각 호출이 개별적으로 허용되더라도 두드러집니다. retry_loop— 동일하게 실패하는 툴을 두드리는 에이전트.novel_path— 이 워크스페이스가 이전에 한 적 없는 툴 간 전이.
10. 관측성
Firewall은 당신이 활용할 수 있는 흔적을 남기며, 모두 워크스페이스 범위입니다:| 표면 | 무엇을 주는가 |
|---|---|
| Events | 모든 평가, 판정, 표면, 툴, 실행, 세션으로 필터링 가능. 다른 모든 것 뒤의 원시 레코드. |
| Runs & sessions | 에이전트 실행 또는 대화별로 롤업된 이벤트 — 판정 분류, 구별되는 툴과 모델, 처음/마지막 관측. “이 에이전트가 실제로 무엇을 했는가” 뷰. |
| Discovered tools | 워크스페이스가 본 모든 툴, covered(규칙이 적용됨) 또는 gap(아무것도 적용 안 됨)으로 플래그됨. 실제 트래픽으로부터 정책 작성을 구동합니다. |
| Simulate | 자율성 수준을 적용하기 전에 그것이 무엇을 변경할지 미리 봅니다. |
| Test | 샘플 툴 호출에 대해 정책을 dry-run하고 판정, 매치된 규칙, 이유를 봅니다 — 아무것도 영속화되지 않고, 아무것도 디스패치되지 않습니다. |
| Audit | 모든 정책, 규칙, 설정 변경은 변경이 커밋된 후 감사 행(워크스페이스 + 중앙)을 씁니다. 시크릿과 규칙 blob은 결코 로깅되지 않습니다. |
11. 게이트웨이 나머지 부분과의 관계
| 표면 | Firewall과 어떻게 결합되는가? |
|---|---|
| Guardrails | 상호 보완적 평면. Guardrails는 프롬프트/응답 텍스트를 검사합니다; Firewall은 툴 액션을 통제합니다. 둘 다 하나의 요청에 적용될 수 있습니다. 자율성 수준은 둘을 한 번에 설정합니다. |
| Routing | 독립적. 라우팅은 모델/채널을 선택합니다; firewall은 어떤 모델이 처리했는지와 무관하게 툴 호출을 판정합니다. |
| API keys | 키는 firewall_policy_id를 통해 정책에 연결됩니다; 바인딩은 게이트웨이의 키에 존재합니다. 연결이 없으면 워크스페이스 기본값으로 폴백합니다. |
| MCP 게이트웨이 | firewall이 바로 MCP 게이트웨이입니다 — 등록하는 모든 서버는 그 tools/call을 엔진을 통해 디스패치합니다. |
| Skills | 통제되는 skill의 강제 모드가 규칙 판정 위에 올라타므로, 격리된 skill은 어떤 규칙도 그 툴을 지명하지 않아도 보류됩니다. |
12. 에이전트를 Firewall 게이트웨이에 연결하기
툴 호출이 엔진에 도달하는 방법은 두 가지입니다:- MCP 게이트웨이 — MCP 클라이언트(Claude Desktop, Cursor, 에이전트
프레임워크)를
https://api.orcarouter.ai/api/v1/firewall/mcp로 가리킵니다. 게이트웨이는 도달 가능한 모든 등록된 서버의 툴을<server>.<tool>로 네임스페이스 처리하여 노출하고, 각tools/call을 인라인으로 평가합니다. MCP 서버 참조. - Evaluate 훅 — 툴 호출을 디스패치하기 전에 자체 에이전트 루프에서
POST /api/v1/firewall/evaluate를 호출하고, 판정에 따라 행동합니다.
403을 받습니다.
13. API 레퍼런스
모든 콘솔 라우트는 워크스페이스 컨텍스트를 통해 워크스페이스 범위이며 RBAC를 일관되게 강제합니다: 읽기와 test/simulate 샌드박스는 모든 멤버에게 개방; 쓰기는 **Developer+**를 요구합니다.정책 및 설정
| 메서드 및 경로 | 역할 | 목적 |
|---|---|---|
GET /api/workspace/firewall/settings | Member | 워크스페이스 firewall 설정 읽기(observe mode, 기본값). |
PUT /api/workspace/firewall/settings | Developer+ | 설정 업데이트. |
GET /api/workspace/firewall/policies | Member | 정책 목록(규칙 + 연결된 키 카운트 포함). |
GET /api/workspace/firewall/policies/:id | Member | 단일 정책 상세. |
POST /api/workspace/firewall/policies | Developer+ | 정책 생성. |
PUT /api/workspace/firewall/policies | Developer+ | 정책 업데이트. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | 정책 삭제(키가 여전히 연결되어 있으면 409). |
자세, 프리셋 및 샌드박스
| 메서드 및 경로 | 역할 | 목적 |
|---|---|---|
GET /api/workspace/firewall/presets | Member | 내장 규칙 프리셋. |
POST /api/workspace/firewall/autonomy | Developer+ | 자율성 수준 적용. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | 자율성 변경 실행 취소. |
GET /api/workspace/firewall/simulate | Member | 자율성 수준 미리 보기(?level=). |
POST /api/workspace/firewall/test | Developer+ | 샘플 툴 호출에 대해 정책 dry-run. |
관측성
| 메서드 및 경로 | 역할 | 목적 |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | 본 툴, covered / gap으로 플래그됨. |
GET /api/workspace/firewall/events | Developer+ | firewall 이벤트 목록(필터 가능). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | 한 요청에 대한 이벤트. |
GET /api/workspace/firewall/events/aggregate | Developer+ | 실행 / 세션 롤업. |
GET /api/workspace/firewall/trace/by-run | Developer+ | 한 실행에 대한 트레이스 노드(?run_id=). |
GET /api/workspace/firewall/anomalies | Member | 이상 피드(?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | 이상 피드 스누즈. |
게이트웨이 (machine-to-machine)
이들은 콘솔 세션이 아니라 firewall-gateway-scoped 토큰에서 실행됩니다:| 메서드 및 경로 | 목적 |
|---|---|
POST /api/v1/firewall/evaluate | 단일 툴 호출에 대한 디스패치 전 판정. |
POST /api/v1/firewall/evaluate_plan | 다단계 계획에 대한 실행 전 검사. |
ANY /api/v1/firewall/mcp | 통합 MCP 게이트웨이 엔드포인트. |
GET /api/v1/firewall/approvals/:id | held 호출의 승인 상태 폴링. |
POST /api/v1/firewall/approvals/:id/callback | HMAC 서명 승인 콜백. |
14. FAQ
툴 호출에서 어떤 정책도 해석되지 않으면 어떻게 되나요?
툴 호출에서 어떤 정책도 해석되지 않으면 어떻게 되나요?
observe mode 끔일 때 동작은 기능을 한 번도 활성화하지 않은
워크스페이스와 바이트 단위로 동일합니다 — 아무것도 차단되거나
로깅되지 않습니다. observe mode 켬일 때 호출은 허용되지만 커버리지
갭으로 기록되어 Discovered tools에 나타납니다.
정책을 안전하게 롤아웃하려면 어떻게 하나요?
정책을 안전하게 롤아웃하려면 어떻게 하나요?
shadow mode를 켜세요. 정책은 프로덕션에서와 정확히 동일하게
평가하고 로깅하지만, 모든 강제 판정이
audit로 강등되고 이유에
[shadow] would …가 접두됩니다. 이벤트와 실행 뷰를 보고, 예상한
것에는 발동하고 예상치 않은 것에는 발동하지 않음을 확인한 뒤, shadow
mode를 꺼서 강제를 시작하세요.차단된 툴 호출은 쿼터를 소모하나요?
차단된 툴 호출은 쿼터를 소모하나요?
inbound 차단은 업스트림 모델 호출 전에 발동하므로 모델 토큰을 소모하지
않습니다. Audit / allow 판정은 청구를 변경하지 않습니다.
cap_cost
규칙 자체가 청구 컨트롤입니다 — 실행의 지출이 센트 상한을 넘으면
거부합니다.Firewall 또는 Guardrails — 무엇을 사용하나요?
Firewall 또는 Guardrails — 무엇을 사용하나요?
둘 다, 서로 다른 계층을 위해. Guardrails는 프롬프트와 응답의
텍스트를 검사합니다(PII, 시크릿, 탈옥). Firewall은 에이전트가
취하는 액션을 통제합니다(어떤 툴, 어떤 MCP 서버, 어떤 호스트). 요청은
둘 다를 통과할 수 있습니다.
tight 자율성 수준은 그것들을 함께
구성합니다.에이전트가 실행하는 모든 툴에 강제가 보장되나요?
에이전트가 실행하는 모든 툴에 강제가 보장되나요?
Firewall은 게이트웨이를 가로지르는 툴 호출에 강제합니다 — 릴레이 경로,
MCP 게이트웨이, 그리고 evaluate 훅. 에이전트가 게이트웨이를 전혀 건드리지
않고 자체 프로세스 내부에서 전적으로 실행하는 툴은 firewall의 시야
밖입니다. 설계 목표는 게이트웨이를 중요한 호출(모델 매개 툴, MCP
디스패치, 네트워크 egress)을 위한 단일 감사 경로로 만드는 것입니다;
그것들을 그곳으로 라우팅하면 통제됩니다.
더 보기
에이전트 보안을 더 깊이 파고드시나요? 에이전트 보안 (제로 트러스트) 가이드는 이 기능을 제로 트러스트 워크플로 안에 배치합니다.에이전트 보호하기 (제로 트러스트)
제로 트러스트 에이전트 firewall 플레이북 — 툴 허용 목록, 인자 검사, egress 통제.
Secure Agents 베이스라인
Firewall과 Guardrails 자세를 함께 설정하는 단일 스위치.