Reguły
Język dopasowania — globy narzędzi, klauzule argumentów, listy egress,
sanityzatory i sekwencje.
Serwery MCP
Rejestruj i zarządzaj serwerami Model Context Protocol za jedną
audytowaną bramą.
Skille
Skanuj i oceniaj ryzyko zdolności, które instalują twoje agenty, zanim
będą mogły się uruchomić.
1. Czym jest Firewall
Agent AI nie tylko generuje tekst — on działa. Wywołujeshell.exec,
odpytuje db.query, pobiera URL, ładuje skill społecznościowy lub
kieruje wywołanie narzędzia przez serwer MCP innej firmy. Każda z tych
rzeczy to akcja o rzeczywistych konsekwencjach, a guardrails na poziomie
promptu ich nie widzą.
Firewall to nazwana polityka w zakresie przestrzeni roboczej,
którą brama ewaluuje przy każdym wywołaniu narzędzia. Zapisujesz politykę
raz, wiążesz z nią klucz API (lub ustawiasz jeden jako domyślny dla
przestrzeni roboczej), a od tej chwili każde wywołanie narzędzia, które
ten klucz wystawia, jest sprawdzane wobec polityki — zanim dotrze do
narzędzia.
Każda polityka to uporządkowana lista reguł. Reguła decyduje o jednej
rzeczy — których wywołań narzędzi dotyczy (glob nazwy narzędzia,
opcjonalnie zawężony do skilla i do powierzchni egzekwowania) oraz co z
nimi zrobić (werdykt: allow, audit, deny, sanitize, wstrzymaj do
zatwierdzenia lub ogranicz koszt). Silnik przechodzi reguły w kolejności
priorytetów, wygrywa pierwsze dopasowanie, a jeśli nic nie pasuje,
wraca do domyślnego werdyktu polityki.
Edycja polityki wchodzi w życie na każdym powiązanym z nią kluczu
przy następnym wywołaniu. Bez ponownego wdrożenia. Bez zmian w kodzie
agenta. Polityka jest egzekwowana w bramie — twój agent dalej wystawia
wywołania narzędzi dokładnie jak wcześniej.
Wykrywanie odbywa się w bramie, przy pierwszym użyciu. Firewall siedzi
na ścieżce relay LLM, nie wewnątrz menedżera pakietów ani systemu plików
twojego agenta. Narzędzie, serwer MCP lub skill, który agent
samodzielnie instaluje, jest wychwycony przy pierwszym przekroczeniu
bramy przez jego wywołanie — nie w momencie instalacji. To celowe: to
jeden punkt zwężenia, który widzi każdego dostawcę, każdego agenta i
każde wywołanie narzędzia niezależnie od tego, skąd zdolność się wzięła.
2. Cztery powierzchnie egzekwowania
Każde wywołanie narzędzia jest ewaluowane wobec dokładnie jednej powierzchni — punktu w cyklu życia żądania, w którym firewall je widzi:| Powierzchnia | Co widzi |
|---|---|
inbound | Narzędzia, które agent ogłasza modelowi w żądaniu (definicje narzędzi). Pozwala zablokować niebezpieczne narzędzie, zanim model w ogóle będzie mógł je wybrać. |
response | tool_calls, które model emituje w swojej odpowiedzi. |
mcp | tools/call dyspozytowane przez bramę Firewall MCP lub ewaluowane przez hook SDK. |
egress | Wychodzący cel sieciowy (host / IP / CIDR) zgłoszony przez narzędzie — powierzchnia SSRF i eksfiltracji danych. |
3. Pojęcia podstawowe
| Pojęcie | Definicja |
|---|---|
| Polityka | Nazwany zestaw reguł w zakresie przestrzeni roboczej. Ma enabled, is_default, default_verdict oraz flagę shadow_mode. |
| Reguła | Jedno sprawdzenie wewnątrz polityki: priorytet, dopasowanie narzędzia/skilla, opcjonalna powierzchnia, opcjonalny predykat argumentu oraz werdykt. Zobacz Reguły. |
| Werdykt | Akcja, którą produkuje reguła (lub wartość domyślna) — zobacz §4. |
| Domyślny werdykt | Stosowany, gdy żadna reguła nie pasuje. Jeden z allow, audit (domyślny) lub deny. |
| Tryb cienia (shadow) | Polityka ewaluuje i loguje, ale nigdy nie blokuje — każdy egzekwujący werdykt jest degradowany do audit, a powód jest poprzedzony przedrostkiem [shadow] would …. Twój przełącznik bezpiecznego wdrożenia. |
| Tryb obserwacji (observe) | Ustawienie na poziomie przestrzeni roboczej. Gdy żądanie rozwiązuje się do braku polityki, a tryb obserwacji jest włączony, wywołanie jest dozwolone, ale logowane jako luka w pokryciu — to właśnie zasila widok Discovered-tools. |
Zakres i rozwiązywanie
Polityki rozwiązują się dokładnie jak Guardrails i klucze API — współdzielone w przestrzeni roboczej, gdy masz aktywną przestrzeń. Dla dowolnego wywołania narzędzia brama rozwiązuje politykę w tej kolejności:- Powiązanie klucza — jeśli wywołujący klucz ma
firewall_policy_id, ta polityka ma zastosowanie (gdy istnieje i jest włączona). - Domyślny przestrzeni roboczej — w przeciwnym razie stosuje się
włączona polityka
is_defaultprzestrzeni roboczej. - Żadna — brak egzekwowania. Przy włączonym trybie obserwacji wywołanie jest dozwolone i logowane jako luka; przy wyłączonym wywołanie jest po cichu dozwolone (bajt-identycznie z przestrzenią roboczą, która nigdy nie włączyła tej funkcji).
Fail-open na nieznanym, fail-closed na niejednoznacznym. Jeśli
rozwiązywanie polityki trafi na przejściowy błąd, brama degraduje się do
observe/allow zamiast wyłączać ruch. Ale tam, gdzie brak egzekwowania
zniweczyłby regułę — raport egress bez użytecznego celu, magazyn
zatwierdzeń, który jest nieosiągalny, skill, którego własności nie da się
rozwiązać — silnik fail closed (deny lub hold). Dostępność jest
zachowana; bezpieczeństwo nie jest po cichu pomijane w przypadkach, które
mają znaczenie.
4. Werdykty
Reguła (lub domyślny werdykt) produkuje jeden z:| Werdykt | Co robi |
|---|---|
allow | Przepuść wywołanie. Zalogowane. |
audit | Przepuść, ale zarejestruj do przeglądu. Domyślny default_verdict — obserwuj wszystko, nie blokuj nic, dopóki nie jesteś gotów. |
deny | Zablokuj wywołanie. Agent widzi błąd narzędzia (lub HTTP 400 na powierzchni inbound). |
sanitize | Zredaguj dopasowane podłańcuchy z argumentów narzędzia (sekrety, PII) i prześlij oczyszczone wywołanie. Zobacz sanityzatory. Na powierzchni inbound — gdzie nie ma jeszcze argumentów czasu wywołania — sanitize eskaluje do bloku. |
pending_approval | Wstrzymaj wywołanie dla człowieka. Agent dostaje odpowiedź „wstrzymane”; recenzent zatwierdza lub odrzuca poza pasmem; agent ponownie wysyła z jednorazowym tokenem zatwierdzenia. Zobacz §7. |
cap_cost | Odrzuć, gdy zakumulowane wydatki uruchomienia agenta przekroczą limit w centach per reguła. Bezpiecznik dla rozbieganych pętli. |
deny / sanitize / pending_approval są degradowane do
audit, abyś mógł zmierzyć wpływ polityki, zanim zmieni ona ruch.
5. Jak ewaluowane jest wywołanie narzędzia
- Wywołanie narzędzia dociera do bramy (ogłoszone inbound, wyemitowane w odpowiedzi, dyspozytowane przez bramę MCP lub zgłoszone jako egress).
- Silnik rozwiązuje aktywną politykę (§3).
- Przechodzi reguły polityki w kolejności priorytetów (niższy priorytet pierwszy; remisy rozstrzyga id reguły). Reguła pasuje, gdy jej powierzchnia, glob nazwy narzędzia, opcjonalny glob nazwy skilla, opcjonalne klauzule argumentów i opcjonalny zakres egress wszystkie pasują.
- Wygrywa pierwsze dopasowanie → stosuje się werdykt reguły. Jeśli
żadna reguła nie pasuje →
default_verdictpolityki. - Jeśli wywołanie jest własnością zarządzanego
skilla, na wierzch stosuje się tryb
egzekwowania skilla — skill w trybie
blockwymusza deny; skill w trybiequarantineeskaluje wszystko poniżej deny dopending_approval. - Decyzja jest logowana jako zdarzenie firewalla (chyba że to dry run), skorelowana z uruchomieniem i sesją agenta.
6. Jak wygląda block
Odrzucone wywołanie na powierzchni inbound zwraca HTTP 400 z ciałem błędu w kształcie OpenAI, kodem błędufirewall_blocked oraz
komunikatem nazywającym narzędzie i powód — np. tool "shell.exec" blocked by firewall: destructive shell command. Błąd niesie ustrukturyzowane
metadata (kod powodu, czynniki ryzyka, wynik) i jest oznaczony jako
skip-retry (ponowne uruchomienie tego samego wywołania po prostu znów
by zablokowało).
Wywołanie dyspozytowane przez bramę MCP jest blokowane jako błąd
narzędzia (firewall deny: <reason>) zamiast jako awaria transportu,
więc model widzi odrzucenie i może zareagować — wybrać inne narzędzie,
zapytać użytkownika lub zatrzymać się — zamiast się wysypać.
Wstrzymane wywołanie (pending_approval) zwraca HTTP 400 z kodem
firewall_approval_pending oraz id zatwierdzenia, na którym odpytuje
klient.
7. Zatwierdzenie przez człowieka (HITL)
Werdyktpending_approval zamienia wywołanie narzędzia w przegląd poza
pasmem:
- Silnik kolejkuje rekord zatwierdzenia i zwraca odpowiedź „wstrzymane” niosącą jego id; wywołanie nie dociera do narzędzia.
- Recenzent je rozstrzyga — z konsoli (Developer+) lub przez podpisany HMAC webhook callback do twojego własnego systemu zatwierdzeń.
- Twój agent (lub MCP SDK) odpytuje id zatwierdzenia; po zatwierdzeniu
ponownie wysyła oryginalne wywołanie z jednorazowym nagłówkiem
X-OrcaRouter-Firewall-Approval, a brama przepuszcza je ten jeden raz.
rule_changed,
aby recenzenci wiedzieli, że kontekst się zmienił.
8. Poziomy autonomii — jeden przełącznik dla całej postawy
Strojenie polityk reguła po regule to droga precyzyjna; poziomy autonomii to ta szybka. Pojedyncza kontrolka atomowo zastępuje postawę Firewall oraz Guardrails twojej przestrzeni roboczej w jednej transakcji, z cofnięciem jednym kliknięciem:| Poziom | Postawa |
|---|---|
tight | Blokuj destrukcyjny shell, sekrety w argumentach i egress SSRF (domyślnie deny); guardrails PII Shield + Secrets Blocker włączone; tryb obserwacji wyłączony. |
balanced | Audytuj destrukcyjny shell, flaguj PII; tryb obserwacji wyłączony. Rekomendowana postawa początkowa. |
permissive | Brak egzekwującej polityki, brak guardrails; tryb obserwacji włączony, więc i tak wszystko widzisz. |
9. Wykrywanie anomalii
Poza statycznymi regułami Firewall uczy się normalnego kształtu użycia narzędzi każdej przestrzeni roboczej i flaguje odchylenia na strumieniu czytelnym dla obserwującego:- Skoki tempa / kosztu — aktywność per narzędzie jest oceniana wobec
wyuczonej bazowej linii godziny-tygodnia (14-dniowa średnia
krocząca), więc „100 wywołań
db.queryo 3 w nocy w niedzielę” wyróżnia się, nawet jeśli każde wywołanie z osobna jest dozwolone. retry_loop— agent waląc w to samo zawodzące narzędzie.novel_path— przejście narzędzie-do-narzędzia, którego ta przestrzeń robocza nigdy wcześniej nie wykonała.
10. Obserwowalność
Firewall pozostawia ślad, na który możesz reagować, cały w zakresie przestrzeni roboczej:| Powierzchnia | Co ci daje |
|---|---|
| Events | Każda ewaluacja, filtrowalna po werdykcie, powierzchni, narzędziu, uruchomieniu i sesji. Surowy rekord stojący za wszystkim innym. |
| Runs & sessions | Zdarzenia zwinięte po uruchomieniu agenta lub konwersacji — rozbicie werdyktów, odrębne narzędzia i modele, pierwsze/ostatnie zaobserwowanie. Widok „co ten agent faktycznie zrobił”. |
| Discovered tools | Każde narzędzie, które przestrzeń robocza widziała, oznaczone covered (reguła ma zastosowanie) lub gap (żadna nie ma). Napędza autorowanie polityki z prawdziwego ruchu. |
| Simulate | Podejrzyj, co poziom autonomii zmieniłby, zanim go zastosujesz. |
| Test | Dry-run polityki wobec przykładowego wywołania narzędzia i zobacz werdykt, dopasowaną regułę oraz powód — nic nie jest persystowane, nic nie jest dyspozytowane. |
| Audit | Każda zmiana polityki, reguły i ustawień zapisuje wiersz audytu (przestrzeń robocza + centralny) po zatwierdzeniu zmiany. Sekrety i bloby reguł nigdy nie są logowane. |
11. Relacja z resztą bramy
| Powierzchnia | Jak komponuje się z Firewallem? |
|---|---|
| Guardrails | Komplementarne płaszczyzny. Guardrails prześwietlają tekst promptu/odpowiedzi; Firewall zarządza akcjami narzędzi. Oba mogą dotyczyć jednego żądania. Poziomy autonomii ustawiają oba naraz. |
| Routing | Niezależne. Routing wybiera model/kanał; firewall ocenia wywołania narzędzi niezależnie od tego, który model je obsłużył. |
| API keys | Klucz wiąże się z polityką przez firewall_policy_id; powiązanie żyje na kluczu w bramie. Brak powiązania wraca do domyślnego przestrzeni roboczej. |
| Brama MCP | Firewall jest bramą MCP — każdy serwer, który zarejestrujesz, dyspozytuje swoje tools/call przez silnik. |
| Skille | Tryb egzekwowania zarządzanego skilla jedzie na wierzchu werdyktu reguły, więc skill poddany kwarantannie jest wstrzymany, nawet jeśli żadna reguła nie nazywa jego narzędzi. |
12. Łączenie agenta z bramą Firewall
Są dwa sposoby, by wywołanie narzędzia dotarło do silnika:- Brama MCP — skieruj swojego klienta MCP (Claude Desktop, Cursor,
framework agentowy) na
https://api.orcarouter.ai/api/v1/firewall/mcp. Brama wystawia narzędzia każdego osiągalnego zarejestrowanego serwera, w przestrzeni nazw<server>.<tool>, i ewaluuje każdetools/callinline. Zobacz Serwery MCP. - Hook evaluate — wywołaj
POST /api/v1/firewall/evaluatez własnej pętli agenta przed dyspozycją wywołania narzędzia i działaj wedle werdyktu.
403 na tych trasach.
13. Referencja API
Wszystkie trasy konsoli są w zakresie przestrzeni roboczej przez kontekst przestrzeni roboczej i egzekwują RBAC konsekwentnie: odczyty oraz piaskownice test/simulate są otwarte dla każdego członka; zapisy wymagają Developer+.Polityki i ustawienia
| Metoda i ścieżka | Rola | Cel |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Odczytaj ustawienia firewalla przestrzeni roboczej (tryb obserwacji, domyślne). |
PUT /api/workspace/firewall/settings | Developer+ | Zaktualizuj ustawienia. |
GET /api/workspace/firewall/policies | Member | Lista polityk (z licznikami reguł + powiązanych kluczy). |
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ę (409, jeśli klucze są wciąż powiązane). |
Postawa, presety i piaskownice
| Metoda i ścieżka | Rola | Cel |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Wbudowane presety reguł. |
POST /api/workspace/firewall/autonomy | Developer+ | Zastosuj poziom autonomii. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Cofnij zmianę autonomii. |
GET /api/workspace/firewall/simulate | Member | Podejrzyj poziom autonomii (?level=). |
POST /api/workspace/firewall/test | Developer+ | Dry-run polityki wobec przykładowego wywołania narzędzia. |
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 (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Uśpij strumień anomalii. |
Brama (maszyna-do-maszyny)
Te działają na tokenie w zakresie firewall-gateway, nie na sesji konsoli:| 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/approvals/:id | Odpytaj stan zatwierdzenia wstrzymanego wywołania. |
POST /api/v1/firewall/approvals/:id/callback | Podpisany HMAC callback zatwierdzenia. |
14. FAQ
Co jeśli żadna polityka nie rozwiąże się na wywołaniu narzędzia?
Co jeśli żadna polityka nie rozwiąże się na wywołaniu narzędzia?
Przy wyłączonym trybie obserwacji zachowanie jest bajt-identyczne z
przestrzenią roboczą, która nigdy nie włączyła tej funkcji — nic nie
jest blokowane ani logowane. Przy włączonym trybie obserwacji
wywołanie jest dozwolone, ale rejestrowane jako luka w pokryciu, więc
pojawia się w Discovered tools.
Jak bezpiecznie wdrożyć politykę?
Jak bezpiecznie wdrożyć politykę?
Włącz tryb cienia. Polityka ewaluuje i loguje dokładnie tak, jak
robiłaby to na produkcji, ale każdy egzekwujący werdykt jest degradowany
do
audit, a powód jest poprzedzony przedrostkiem [shadow] would ….
Obserwuj widoki events i runs, potwierdź, że odpala na tym, czego
oczekujesz, i niczym, czego nie chcesz, a potem wyłącz tryb cienia, aby
zacząć egzekwować.Czy zablokowane wywołanie narzędzia kosztuje kwotę?
Czy zablokowane wywołanie narzędzia kosztuje kwotę?
Block inbound odpala przed wywołaniem modelu nadrzędnego, więc nie
kosztuje tokenów modelu. Werdykty audit / allow nie zmieniają
rozliczeń. Reguła
cap_cost jest sama w sobie kontrolą rozliczeń —
odrzuca, gdy wydatki uruchomienia przekroczą twój limit w centach.Firewall czy Guardrails — którego użyć?
Firewall czy Guardrails — którego użyć?
Obu, do różnych warstw. Guardrails prześwietlają tekst w promptach
i odpowiedziach (PII, sekrety, jailbreaki). Firewall zarządza
akcjami, które podejmuje agent (które narzędzia, które serwery MCP,
które hosty). Żądanie może przejść przez oba. Poziom autonomii
tight
konfiguruje je razem.Czy egzekwowanie jest gwarantowane dla każdego narzędzia, które agent uruchamia?
Czy egzekwowanie jest gwarantowane dla każdego narzędzia, które agent uruchamia?
Firewall egzekwuje na wywołaniach narzędzi, które przekraczają bramę —
ścieżce relay, bramie MCP i hooku evaluate. Narzędzie, które twój agent
wykonuje całkowicie wewnątrz własnego procesu, nigdy nie dotykając
bramy, jest poza polem widzenia firewalla. Celem projektowym jest
uczynienie bramy jedyną audytowaną ścieżką dla wywołań, które mają
znaczenie (narzędzia mediowane przez model, dyspozycja MCP, egress
sieciowy); poprowadź je przez nią, a będą zarządzane.
Zobacz także
Chcesz głębiej wejść w bezpieczeństwo agentów? Przewodniki Secure Your Agents (Zero Trust) osadzają tę funkcję w przepływie pracy zero-trust.Zabezpiecz swoje agenty (Zero Trust)
Podręcznik firewalla agentów zero-trust — listy dozwolonych narzędzi, kontrole argumentów i zarządzanie egress.
Baza Secure Agents
Jeden przełącznik, który ustawia jednocześnie postawę Firewalla i Guardrails.