api.orcarouter.ai의 에이전트를 위한 툴 허용 목록
패턴입니다: deny 기본 판정에
tool_name_glob에 키가 지정된 하나
이상의 allow 규칙을 더합니다. 그 규칙들 뒤의 전체 매칭 언어는
Firewall Rules를 참조하세요.
허용 목록은 콘솔의 Security → Firewall에서, 또는
/api/workspace/firewall/* 관리 라우트(세션 / 액세스 토큰 — 릴레이
sk-orca-… 키가 아님)를 통해 작성됩니다. 에이전트의 /v1/* 호출만
릴레이 키를 사용합니다. 정책을 생성하거나 편집하는 것은 Developer+
액션입니다.1. 왜 에이전트에게 기본 거부인가
차단 목록(“shell.exec 거부, db.delete 거부, …”)은 생각해낸 마지막
위협만큼만 완전합니다. 허용 목록은 입증 책임을 뒤집습니다: 게이트웨이는
정책이 명시적으로 허용하지 않는 모든 것을 거부하므로, 알 수 없는 툴은
구성상 닫혀 있습니다.
기본 판정 = deny
정책의 바닥. 어떤 규칙도 매치하지 않으면 모든 툴 호출이 차단됩니다.
allow 규칙이 툴을 다시 옵트인
각
allow 규칙은 실제로 사용하는 툴을 명명합니다 — 정확한 이름 또는
glob로.default_verdict로 떨어집니다. 그래서
허용 목록은 그저: 실제 툴을 위한 높은 우선순위 allow 규칙에, 그 외 모든
것을 잡는 deny 바닥입니다.
2. 한 예: 리서치 에이전트의 툴 허용 목록 만들기
에이전트가 오직 웹을 검색하고 지식 베이스에서 읽기만 하면 된다고 합시다 —web.search와 kb.read라는 이름의 툴. 그 외 모든 것(셸, 파일 쓰기,
데이터베이스 변경, 프롬프트 인젝션이 불러낼 수 있는 모든 툴)은 거부되어야
합니다.
정책을 기본 deny + 두 allow 규칙으로 구축합니다:
deny 기본값으로 정책 생성
Security → Firewall → Policies → New policy. 이름을 짓고,
Enabled를 켠 채로 두고, 기본 판정을
deny로 설정합니다. 이것이
닫힌 바닥입니다 — 정책 생성 참조.툴 패밀리별로 allow 규칙 추가
규칙 편집기에 둘 다
verdict = allow인 두 규칙을 추가합니다:priority | tool_name_glob | verdict |
|---|---|---|
10 | web.search | allow |
20 | kb.* | allow |
web.search는 정확한 매치입니다; kb.*는 정책을 다시 편집하지 않고도
kb.read, kb.search, 그리고 미래의 모든 kb.* 툴을 허용하는
접두사 glob입니다.web.search와 kb.read는 통과합니다; shell.exec 호출은 어떤
allow 규칙에도 매치하지 않고, deny 바닥에 부딪혀, inbound 표면에서 코드
firewall_blocked와 함께 HTTP 400으로 돌아옵니다 —
block은 어떻게 보이는가 참조.
3. 한 화면으로 보는 glob
tool_name_glob은 작고, 대소문자 구분 문법입니다 — regex 없음, 선형
시간. 허용 목록에 중요한 형태:
| 패턴 | 허용하는 것 |
|---|---|
web.search | 정확히 그 툴. |
kb.* | 접두사 — kb.read, kb.search(맨 kb은 아님). |
*.search | 접미사 — web.search, kb.search, 그리고 맨 search. |
*.tools.* | 중위 — byo.tools.fetch 및 유사한 것. |
4. 에이전트를 깨뜨리지 않고 롤아웃하기
기본 거부는 필요한 것을 잊은 툴을 차단할 가능성이 가장 높은 자세입니다. 단계적으로 진행하세요:먼저 shadow하기
먼저 shadow하기
shadow mode를 켜세요. 정책은
라이브에서와 정확히 동일하게 평가하고 로깅하지만, 모든 deny를 이유에
[shadow] would …가 접두된 audit로 강등합니다. 실제 트래픽을 실행한
다음, 이벤트 피드를 읽으세요.실제로 호출하는 툴 찾기
실제로 호출하는 툴 찾기
Discovered tools는 워크스페이스가 본
모든 툴을 covered 또는 gap으로 플래그하여 나열합니다. shadow
mode “would-deny” 이벤트에 갭을 더하면 아직 필요한 allow 규칙이 정확히
어떤 것인지 알려줍니다.
강제하기 전에 테스트
강제하기 전에 테스트
Test 샌드박스는 샘플 툴 호출에 대해
정책을 dry-run하고 판정, 매치된 규칙, 이유를 반환합니다 — 아무것도
디스패치되지 않고, 아무것도 영속화되지 않습니다.
web.search가
허용되고 shell.exec가 거부됨을 확인한 다음, shadow를 끄세요.거부된 inbound 호출은 모델 토큰을 들이지 않습니다 — 업스트림 모델이
실행되기 전에 차단됩니다 — 그리고 skip-retry로 표시되므로, 차단된
툴은 다시 차단하느라 재시도 예산을 태우지 않습니다.
Verdicts 참조.
5. 다음으로 갈 곳
특정 툴 차단
역 — 기본 허용 바닥을 유지하고 명명된 툴을 거부합니다.
인자 검증
툴을 허용하되 안전한 인자로만(
db.query은 되지만 DROP TABLE은 안
됨).규칙 우선순위
첫 매치 승리가 allow 규칙을 deny 바닥 위에 어떻게 정렬하는가.
Verdicts
allow, audit, deny, sanitize, pending_approval, cap_cost.