Firewall API 레퍼런스

Agent Firewall은 두 가지 방식으로 구성됩니다: 콘솔을 통해(여러분의 세션, 대시보드에 사용하는 것과 동일한 로그인)와 게이트웨이를 통해 (에이전트가 런타임에 제시하는 전용 firewall-scoped API 키). 두 패밀리는 서로 다른 경로 접두사에 존재하고, 서로 다른 인증을 받고, 서로 다른 질문에 답합니다 — “정책을 편집한다” 대 “이 툴 호출을 평가한다”. 이 페이지는 둘 다의 라우트별 지도입니다. 정책이 무엇을 의미하는지 — 판정, 표면, 규칙, 해석 — 은 Firewall과 Firewall 규칙에서 시작하세요. 이 페이지는 API 표면만 다룹니다.

1. 두 라우트 패밀리

콘솔 — 구성

/api/workspace/firewall/*. 여러분의 세션 / 액세스 토큰(UserAuth)으로 인증되며, 활성 워크스페이스로 범위 지정됩니다. 정책 작성, 이벤트 읽기, MCP 서버 등록, 승인 해결. 모든 액션은 역할 게이트 처리됩니다.

게이트웨이 — 강제

/api/v1/firewall/*. firewall-gateway-scoped 키(is_firewall_gateway가 설정된 키)로 인증됩니다. 에이전트 또는 MCP 클라이언트가 런타임에 호출하는 machine-to-machine 표면. 일반 릴레이 키는 여기서 403을 받습니다.

콘솔 라우트는 결코 sk-orca-… 릴레이 키를 받지 않고, 게이트웨이 라우트는 결코 세션 토큰을 받지 않습니다. 이를 혼동하는 것이 firewall을 처음 연결할 때 가장 흔한 401/403입니다. /v1/firewall/* 호출에 속하는 유일한 sk-orca-… 키는 is_firewall_gateway가 켜진 채로 발급된 것입니다 — Scope, keys & policies 참조.

2. 역할 한눈에 보기

콘솔 라우트는 여러분의 워크스페이스 역할을 해석하고 그에 따라 게이트 처리합니다. 툴 호출 출처를 담지 않는 읽기는 모든 멤버에게 개방됩니다; 쓰기와 툴 호출 인자를 노출하는 모든 것은 **Developer+**를 요구합니다.

Role	할 수 있는 것
Viewer / member	설정, 정책, 프리셋, 발견된 툴, simulate, 이상 읽기.
Developer+	위의 모든 것에 더해, 모든 쓰기, `events`/`runs`/`trace` 표면, 그리고 `test` dry-run.
Admin+	추가로, 키에 `is_firewall_gateway` 플래그 설정 및 게이트웨이 키의 평문 읽기.

이 분리는 의도적입니다: viewer는 정책이 존재한다는 사실과 그것이 무엇을 차단할지 볼 수 있지만, 이벤트 뒤의 원시 툴 호출 인자는 볼 수 없습니다. 비개발자를 위한 대시보드를 만든다면, 읽기 개방 라우트가 안전한 세트입니다.

3. 콘솔에서 정책 구성하기

콘솔 라우트는 정책을 작성하고 검사하는 방법입니다. 모든 것을 대시보드 UI에서 구성합니다 — 이들은 그것이 호출하는 것과 동일한 엔드포인트입니다.

정책 및 설정

메서드 및 경로	역할	목적
`GET /api/workspace/firewall/settings`	Member	Observe-mode + 카운트.
`PUT /api/workspace/firewall/settings`	Developer+	워크스페이스 firewall 설정 업데이트.
`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+	정책 삭제.
`POST /api/workspace/firewall/rules`	Developer+	규칙 추가.
`PUT /api/workspace/firewall/rules`	Developer+	규칙 업데이트.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	규칙 삭제.

자세, 프리셋 및 샌드박스

메서드 및 경로	역할	목적
`GET /api/workspace/firewall/presets`	Member	내장 규칙 프리셋.
`GET /api/workspace/firewall/templates`	Member	사용 사례 템플릿 갤러리.
`POST /api/workspace/firewall/templates/apply`	Developer+	템플릿 적용 → 하나의 정책 + 그 규칙들.
`POST /api/workspace/firewall/autonomy`	Developer+	자율성 수준 적용(`tight` / `balanced` / `permissive`).
`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	이상 피드.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	피드 스누즈(≤ 7일).

MCP 서버

에이전트가 도달하는 Model Context Protocol 서버를 단일 감사 게이트웨이 뒤에서 등록합니다. 자격 증명은 암호화되어 저장되고 읽을 때 마스킹됩니다.

메서드 및 경로	역할	목적
`GET /api/workspace/firewall/mcp_servers`	Member	등록된 서버 목록.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	서버 상세.
`POST /api/workspace/firewall/mcp_servers`	Developer+	서버 등록(중복 `name`에 `409`).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	서버 업데이트.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	서버 제거.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	도달성 + `tools/list` 핸드셰이크.

서버는 고유한 name, endpoint, auth_mode (none / bearer / oauth / basic), 그리고 health status (ok / degraded / down)를 담습니다. 전체 수명 주기와 skill 격리는 Firewall MCP를 참조하세요.

4. 게이트웨이에서 강제하기

이들은 여러분의 세션이 아니라 firewall-gateway-scoped 키에서 실행됩니다. 에이전트 루프나 MCP 클라이언트가 런타임에 호출하는 것입니다.

메서드 및 경로	목적
`POST /api/v1/firewall/evaluate`	단일 툴 호출에 대한 디스패치 전 판정.
`POST /api/v1/firewall/evaluate_plan`	다단계 계획에 대한 실행 전 검사.
`ANY /api/v1/firewall/mcp`	통합 MCP 게이트웨이 엔드포인트.
`GET /api/v1/firewall/mcp_servers`	워크스페이스의 등록된 서버 열거.
`GET /api/v1/firewall/approvals/:id`	held 호출의 승인 상태 폴링.
`POST /api/v1/firewall/approvals/:id/callback`	HMAC 서명 승인 콜백.

한 가지 구체적 예시: 툴 호출 평가

에이전트가 툴을 디스패치하기 전에, 게이트웨이에 판정을 요청하세요. 릴레이 sk-orca-… 키가 아니라 firewall-gateway-scoped 키를 전달하세요:

curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'

응답은 판정을 담습니다 — allow, audit, deny, sanitize, 또는 pending_approval. deny에서는 호출을 건너뛰고 이유를 모델에 표면화하고; sanitize에서는 게이트웨이가 돌려주는 정화된 인자를 전달하고(sanitize는 툴 호출 인자만 편집합니다 — 툴이 반환하는 콘텐츠는 결코 아님); pending_approval에서는 아래 승인 루프에 진입합니다.

게이트웨이는 그것을 가로지르는 호출을 평가합니다 — evaluate 훅, MCP 게이트웨이, 그리고 릴레이 경로. 에이전트가 OrcaRouter를 전혀 건드리지 않고 전적으로 프로세스 내부에서 실행하는 툴은 그 시야 밖입니다. 중요한 호출 (모델 매개 툴, MCP 디스패치, 네트워크 egress)을 게이트웨이를 통해 라우팅하면 통제됩니다.

5. 승인 핸드셰이크 (HITL)

pending_approval 판정은 호출을 사람을 위해 보류합니다. 보류 중의 HTTP 오류는 firewall_approval_pending입니다. 그것을 해제하는 것은 두 라우트 패밀리에 걸친 3단계 루프입니다:

검토자가 보류를 해결한다

콘솔에서(PATCH /api/workspace/firewall/approvals/:id, Developer+), 또는 여러분 자신의 시스템이 HMAC 서명 콜백을 POST /api/v1/firewall/approvals/:id/callback에 포스트합니다. 콜백은 HMAC을 인라인으로 검증합니다 — 다른 인증은 받아들여지지 않습니다.

에이전트가 승인을 폴링한다

상태가 approved 또는 rejected로 뒤집힐 때까지 게이트웨이 키로 GET /api/v1/firewall/approvals/:id.

일회용 토큰과 함께 재제출한다

일단 승인되면, 승인 id를 담은 X-OrcaRouter-Firewall-Approval 헤더와 함께 원래 호출을 재발행하세요. 게이트웨이가 그것을 인식하고 그 한 번의 호출을 통과시킵니다. 헤더는 일회용입니다.

결정은 first-writer-wins이며 멱등적입니다 — 동일한 보류의 두 번째 해결은 no-op입니다. 엔드투엔드 흐름은 Firewall — Human approval을, 판정을 읽는 것은 왜 차단되었나요?를 참조하세요.

6. 차단이 어떻게 보이는가

결과	HTTP	Code
거부된 툴 호출(inbound 표면)	`400`	`firewall_blocked`
MCP 게이트웨이를 통한 거부	툴 오류	`firewall deny: <reason>`
승인을 위해 보류됨	`400`	`firewall_approval_pending`

firewall_blocked는 skip-retry로 표시됩니다 — 동일한 호출을 다시 실행하면 그저 다시 차단될 뿐이므로, 재시도하는 클라이언트는 두드리는 대신 백오프합니다. 전체 코드 목록은 오류 코드에 있습니다.

7. 관련 레퍼런스

Guardrail API

콘텐츠 정책 동료 — 텍스트 평면을 위한 /api/guardrail/* 라우트.

판정 용어집

모든 판정과 그것이 호출에 무엇을 하는지.

Glob 및 JSONPath

tool_name_glob과 args_match 뒤의 매칭 문법.

Compliance API

팩, 서명 리포트, 거주지, 그리고 삭제.

8. FAQ

왜 내 릴레이 키가 /api/v1/firewall/evaluate에서 403을 받나요?

게이트웨이 라우트는 firewall-gateway-scoped 키를 요구합니다 — is_firewall_gateway가 설정된 채로 발급된 키(Admin+ 액션). 일반 릴레이 키는, 유효한 것이라도, 403을 받습니다. 에이전트 런타임을 위해 전용 게이트웨이 키를 발급하세요.

viewer가 firewall 이벤트를 읽을 수 있나요?

아니요. events, events/aggregate, 그리고 trace 라우트는 레코드가 툴 호출 인자 출처를 담기 때문에 Developer+입니다. Viewer는 설정, 정책, 프리셋, 발견된 툴, simulate, 그리고 이상 피드를 읽을 수 있습니다.

held된 승인을 어디서 해결하나요 — 콘솔 또는 게이트웨이?

둘 다 가능합니다. 사람이 콘솔에서 PATCH /api/workspace/firewall/approvals/:id(Developer+)를 통해 해결하거나, 여러분 자신의 시스템이 HMAC 서명 결정을 POST /api/v1/firewall/approvals/:id/callback에 포스트합니다. 어느 경로가 해결했든 에이전트는 GET /api/v1/firewall/approvals/:id를 폴링합니다.

sanitize가 툴이 반환하는 것을 정화하나요?

아니요. sanitize 판정은 툴 호출 인자만 편집합니다 — 툴이 반환하는 콘텐츠는 결코 아님. 아직 호출 시점 인자가 없는 inbound 표면에서는 sanitize가 차단으로 격상됩니다. Firewall 규칙 참조.

이 컨트롤들이 guardrail 및 게이트웨이 나머지 부분과 어떻게 조합되는지는 AI 에이전트 보안과 Guardrails vs Firewall을 참조하세요.

​1. 두 라우트 패밀리

콘솔 — 구성

게이트웨이 — 강제

​2. 역할 한눈에 보기

​3. 콘솔에서 정책 구성하기

​정책 및 설정

​자세, 프리셋 및 샌드박스

​관측성

​MCP 서버

​4. 게이트웨이에서 강제하기

​한 가지 구체적 예시: 툴 호출 평가

​5. 승인 핸드셰이크 (HITL)

​6. 차단이 어떻게 보이는가

​7. 관련 레퍼런스

Guardrail API

판정 용어집

Glob 및 JSONPath

Compliance API

​8. FAQ

1. 두 라우트 패밀리

2. 역할 한눈에 보기

3. 콘솔에서 정책 구성하기

정책 및 설정

자세, 프리셋 및 샌드박스

관측성

MCP 서버

4. 게이트웨이에서 강제하기

한 가지 구체적 예시: 툴 호출 평가

5. 승인 핸드셰이크 (HITL)

6. 차단이 어떻게 보이는가

7. 관련 레퍼런스

8. FAQ