Referencja API Firewall

Agent Firewall jest konfigurowany na dwa sposoby: przez konsolę (twoja sesja, ten sam login, którego używasz do dashboardu) i przez bramę (dedykowany klucz API w zakresie firewall, który twój agent prezentuje w czasie wykonywania). Te dwie rodziny żyją na różnych prefiksach ścieżek, biorą różne uwierzytelnienie i odpowiadają na różne pytania — „edytuj politykę” kontra „oceń to wywołanie narzędzia”. Ta strona to mapa obu trasa po trasie. Po to, co polityka oznacza — werdykty, powierzchnie, reguły, rozwiązywanie — zacznij od Firewall i Reguł Firewall. Ta strona to wyłącznie powierzchnia API.

1. Dwie rodziny tras

Konsola — konfiguruj

/api/workspace/firewall/*. Uwierzytelniane twoją sesją / tokenem dostępu (UserAuth), w zakresie twojej aktywnej przestrzeni roboczej. Autoruj polityki, czytaj zdarzenia, rejestruj serwery MCP, rozstrzygaj zatwierdzenia. Każda akcja jest bramkowana rolą.

Brama — egzekwuj

/api/v1/firewall/*. Uwierzytelniane kluczem w zakresie firewall-gateway (klucz z ustawionym is_firewall_gateway). Powierzchnia maszyna-do-maszyny, którą twój agent lub klient MCP woła w czasie wykonywania. Zwykły klucz relay dostaje tu 403.

Trasy konsoli nigdy nie biorą klucza relay sk-orca-…, a trasy bramy nigdy nie biorą tokenu sesji. Pomylenie ich to najczęstsze 401/403 przy pierwszym podpinaniu firewalla. Jedyny klucz sk-orca-…, który należy na wywołanie /v1/firewall/*, to taki wybity z włączonym is_firewall_gateway — zobacz Zakres, klucze i polityki.

2. Role w skrócie

Trasy konsoli rozwiązują twoją rolę przestrzeni roboczej i bramkują odpowiednio. Odczyty, które nie niosą pochodzenia wywołania narzędzia, są otwarte dla każdego członka; zapisy i wszystko, co wystawia argumenty wywołania narzędzia, wymagają Developer+.

Rola	Może robić
Viewer / członek	Czytać ustawienia, polityki, presety, wykryte narzędzia, symulować, anomalie.
Developer+	Wszystko powyższe, plus każdy zapis, powierzchnia `events`/`runs`/`trace` oraz dry-run `test`.
Admin+	Dodatkowo, ustawić flagę `is_firewall_gateway` na kluczu i odczytać jawny tekst klucza bramy.

Podział jest celowy: viewer może widzieć, że polityka istnieje i co by zablokowała, ale nie surowe argumenty wywołania narzędzia stojące za zdarzeniem. Jeśli budujesz dashboardy dla nie-deweloperów, trasy otwarte do odczytu to bezpieczny zestaw.

3. Skonfiguruj politykę z konsoli

Trasy konsoli to sposób, w jaki autorujesz i inspekcjonujesz politykę. Konfigurujesz wszystko w UI dashboardu — to te same endpointy, które ono wywołuje.

Polityki i ustawienia

Metoda i ścieżka	Rola	Cel
`GET /api/workspace/firewall/settings`	Member	Tryb obserwacji + liczniki.
`PUT /api/workspace/firewall/settings`	Developer+	Zaktualizuj ustawienia firewalla przestrzeni roboczej.
`GET /api/workspace/firewall/policies`	Member	Lista polityk.
`GET /api/workspace/firewall/policies/:id`	Member	Szczegóły pojedynczej polityki.
`POST /api/workspace/firewall/policies`	Developer+	Utwórz politykę.
`PUT /api/workspace/firewall/policies`	Developer+	Zaktualizuj politykę.
`DELETE /api/workspace/firewall/policies/:id`	Developer+	Usuń politykę.
`POST /api/workspace/firewall/rules`	Developer+	Dodaj regułę.
`PUT /api/workspace/firewall/rules`	Developer+	Zaktualizuj regułę.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	Usuń regułę.

Postawa, presety i piaskownice

Metoda i ścieżka	Rola	Cel
`GET /api/workspace/firewall/presets`	Member	Wbudowane presety reguł.
`GET /api/workspace/firewall/templates`	Member	Galeria szablonów przypadków użycia.
`POST /api/workspace/firewall/templates/apply`	Developer+	Zastosuj szablon → jedna polityka + jej reguły.
`POST /api/workspace/firewall/autonomy`	Developer+	Zastosuj poziom autonomii (`tight` / `balanced` / `permissive`).
`POST /api/workspace/firewall/autonomy/undo/:audit_id`	Developer+	Cofnięcie jednym kliknięciem z migawki audytu.
`GET /api/workspace/firewall/simulate`	Member	Co poziom by zablokował (`?level=`).
`POST /api/workspace/firewall/test`	Developer+	Dry-run polityki wobec przykładowego wywołania.

Obserwowalność

Metoda i ścieżka	Rola	Cel
`GET /api/workspace/firewall/discovered-tools`	Member	Widziane narzędzia, oznaczone covered / gap.
`GET /api/workspace/firewall/events`	Developer+	Lista zdarzeń firewalla (filtrowalna).
`GET /api/workspace/firewall/events/by-request/:request_id`	Developer+	Zdarzenia dla jednego żądania.
`GET /api/workspace/firewall/events/aggregate`	Developer+	Zwinięcie runs / sessions.
`GET /api/workspace/firewall/trace/by-run`	Developer+	Węzły trace dla uruchomienia (`?run_id=`).
`GET /api/workspace/firewall/anomalies`	Member	Strumień anomalii.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	Uśpij strumień (≤ 7 dni).

Serwery MCP

Zarejestruj serwery Model Context Protocol, do których sięgają twoje agenty, za jedną audytowaną bramą. Poświadczenia są przechowywane zaszyfrowane i maskowane przy odczycie.

Metoda i ścieżka	Rola	Cel
`GET /api/workspace/firewall/mcp_servers`	Member	Lista zarejestrowanych serwerów.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Szczegóły serwera.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Zarejestruj serwer (`409` na zduplikowanej `name`).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Zaktualizuj serwer.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Usuń serwer.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Osiągalność + handshake `tools/list`.

Serwer niesie unikalną name, endpoint, auth_mode (none / bearer / oauth / basic) oraz status zdrowia (ok / degraded / down). Zobacz Firewall MCP po pełny cykl życia i kwarantannę skilli.

4. Egzekwuj na bramie

Te działają na kluczu w zakresie firewall-gateway, nie na twojej sesji. To, co twoja pętla agenta lub klient MCP woła w czasie wykonywania.

Metoda i ścieżka	Cel
`POST /api/v1/firewall/evaluate`	Werdykt przed-dyspozycją dla jednego wywołania narzędzia.
`POST /api/v1/firewall/evaluate_plan`	Sprawdzenie przed-wykonaniem dla wielokrokowego planu.
`ANY /api/v1/firewall/mcp`	Ujednolicony endpoint bramy MCP.
`GET /api/v1/firewall/mcp_servers`	Wylicz zarejestrowane serwery przestrzeni roboczej.
`GET /api/v1/firewall/approvals/:id`	Odpytaj stan zatwierdzenia wstrzymanego wywołania.
`POST /api/v1/firewall/approvals/:id/callback`	Podpisany HMAC callback zatwierdzenia.

Jeden konkretny przykład: oceń wywołanie narzędzia

Zanim twój agent dyspozytuje narzędzie, zapytaj bramę o werdykt. Przekaż klucz w zakresie firewall-gateway — nie swój klucz relay sk-orca-…:

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 /" }
  }'

Odpowiedź niesie werdykt — allow, audit, deny, sanitize lub pending_approval. Na deny pomijasz wywołanie i wystawiasz powód modelowi; na sanitize przesyłasz oczyszczone argumenty, które brama oddaje (sanitize redaguje argumenty wywołania narzędzia tylko — nigdy treści, którą narzędzie zwraca); na pending_approval wchodzisz w pętlę zatwierdzenia poniżej.

Brama ocenia wywołania, które ją przekraczają — hook evaluate, bramę MCP i ścieżkę relay. Narzędzie, które twój agent uruchamia całkowicie w procesie, nigdy nie dotykając OrcaRouter, jest poza jej polem widzenia. Poprowadź wywołania, które mają znaczenie (narzędzia mediowane przez model, dyspozycja MCP, egress sieciowy) przez bramę, a będą zarządzane.

5. Handshake zatwierdzenia (HITL)

Werdykt pending_approval wstrzymuje wywołanie dla człowieka. Błąd HTTP podczas wstrzymania to firewall_approval_pending. Przepuszczenie go to trzykrokowa pętla rozłożona na obie rodziny tras:

Recenzent rozstrzyga wstrzymanie

Z konsoli (PATCH /api/workspace/firewall/approvals/:id, Developer+) lub twój własny system wysyła podpisany HMAC callback do POST /api/v1/firewall/approvals/:id/callback. Callback weryfikuje HMAC inline — żadne inne uwierzytelnienie nie jest akceptowane.

Twój agent odpytuje zatwierdzenie

GET /api/v1/firewall/approvals/:id z kluczem bramy, dopóki stan nie przeskoczy na zatwierdzone lub odrzucone.

Wyślij ponownie z jednorazowym tokenem

Po zatwierdzeniu ponownie wystaw oryginalne wywołanie z nagłówkiem X-OrcaRouter-Firewall-Approval zawierającym id zatwierdzenia. Brama rozpoznaje je i przepuszcza to jedno wywołanie. Nagłówek jest jednorazowy.

Decyzje są first-writer-wins i idempotentne — drugie rozstrzygnięcie tego samego wstrzymania jest no-opem. Zobacz Firewall — Zatwierdzenie przez człowieka po przepływ od końca do końca oraz Dlaczego to zostało zablokowane? po odczytywanie werdyktu.

6. Jak wygląda block

Wynik	HTTP	Kod
Odrzucone wywołanie narzędzia (powierzchnia inbound)	`400`	`firewall_blocked`
Odrzucone przez bramę MCP	błąd narzędzia	`firewall deny: <reason>`
Wstrzymane do zatwierdzenia	`400`	`firewall_approval_pending`

firewall_blocked jest oznaczone skip-retry — ponowne uruchomienie identycznego wywołania po prostu znów by zablokowało, więc ponawiający klient wycofuje się zamiast walić. Pełna lista kodów żyje w Kodach błędów.

7. Powiązane referencje

API Guardrail

Odpowiednik polityki treści — trasy /api/guardrail/* dla płaszczyzny tekstu.

Słownik werdyktów

Każdy werdykt i co robi z wywołaniem.

Glob i JSONPath

Gramatyka dopasowania stojąca za tool_name_glob i args_match.

API Compliance

Packi, podpisane raporty, rezydencja i wymazanie.

8. FAQ

Dlaczego mój klucz relay dostaje 403 na /api/v1/firewall/evaluate?

Trasy bramy wymagają klucza w zakresie firewall-gateway — takiego wybitego z ustawionym is_firewall_gateway (akcja Admin+). Zwykły klucz relay, nawet poprawny, dostaje 403. Wybij dedykowany klucz bramy dla swojego środowiska wykonawczego agenta.

Czy viewer może czytać zdarzenia firewalla?

Nie. Trasy events, events/aggregate i trace są Developer+, ponieważ rekordy niosą pochodzenie argumentów wywołania narzędzia. Viewerzy mogą czytać ustawienia, polityki, presety, wykryte narzędzia, symulować oraz strumień anomalii.

Gdzie rozstrzygam wstrzymane zatwierdzenie — konsola czy brama?

W obu. Człowiek rozstrzyga je w konsoli przez PATCH /api/workspace/firewall/approvals/:id (Developer+) lub twój własny system wysyła podpisaną HMAC decyzję do POST /api/v1/firewall/approvals/:id/callback. Agent odpytuje GET /api/v1/firewall/approvals/:id niezależnie od tego, która ścieżka je rozstrzygnęła.

Czy sanitize czyści to, co narzędzie zwraca?

Nie. Werdykt sanitize redaguje argumenty wywołania narzędzia tylko — nigdy treści, którą narzędzie zwraca. Na powierzchni inbound, gdzie nie ma jeszcze argumentów czasu wywołania, sanitize eskaluje do bloku. Zobacz Reguły Firewall.

Po to, jak te kontrole komponują się z guardrails i resztą bramy, zobacz Zabezpieczanie agentów AI i Guardrails vs Firewall.

​1. Dwie rodziny tras

Konsola — konfiguruj

Brama — egzekwuj

​2. Role w skrócie

​3. Skonfiguruj politykę z konsoli

​Polityki i ustawienia

​Postawa, presety i piaskownice

​Obserwowalność

​Serwery MCP

​4. Egzekwuj na bramie

​Jeden konkretny przykład: oceń wywołanie narzędzia

​5. Handshake zatwierdzenia (HITL)

​6. Jak wygląda block

​7. Powiązane referencje

API Guardrail

Słownik werdyktów

Glob i JSONPath

API Compliance

​8. FAQ

1. Dwie rodziny tras

2. Role w skrócie

3. Skonfiguruj politykę z konsoli

Polityki i ustawienia

Postawa, presety i piaskownice

Obserwowalność

Serwery MCP

4. Egzekwuj na bramie

Jeden konkretny przykład: oceń wywołanie narzędzia

5. Handshake zatwierdzenia (HITL)

6. Jak wygląda block

7. Powiązane referencje

8. FAQ