Regeln
Die Matching-Sprache — Tool-Globs, Argument-Klauseln, Egress-Listen,
Sanitizer und Sequenzen.
MCP-Server
Registrieren und steuern Sie Model-Context-Protocol-Server hinter einem
einzigen auditierten Gateway.
Skills
Scannen und risikobewerten Sie die Fähigkeiten, die Ihre Agenten
installieren, bevor sie laufen können.
1. Was ist die Firewall
Ein KI-Agent generiert nicht nur Text — er handelt. Er ruftshell.exec
auf, fragt db.query ab, holt eine URL, lädt einen Community-Skill oder
routet einen Tool-Call durch einen Drittanbieter-MCP-Server. Jedes davon ist
eine Aktion mit realen Konsequenzen, und Guardrails auf Prompt-Ebene können
sie nicht sehen.
Die Firewall ist eine workspace-bezogene, benannte Policy, die das
Gateway bei jedem Tool-Call auswertet. Sie verfassen eine Policy einmal,
hängen einen API-Key daran (oder setzen einen als Workspace-Default), und von
da an wird jeder Tool-Call, den dieser Key ausgibt, gegen die Policy geprüft
— bevor er das Tool erreicht.
Jede Policy ist eine geordnete Liste von Regeln. Eine Regel entscheidet
eine Sache — auf welche Tool-Calls sie zutrifft (ein Tool-Namen-Glob,
optional auf einen Skill und eine Enforcement-Surface gescoped) und was
damit zu tun ist (ein Verdikt: allow, audit, deny, sanitize, zur
Freigabe zurückhalten oder Kosten begrenzen). Die Engine durchläuft die
Regeln in Prioritätsreihenfolge, erster Treffer gewinnt, und fällt auf
das Default-Verdikt der Policy zurück, wenn nichts matcht.
Das Bearbeiten einer Policy wirkt sich auf jeden daran gebundenen Key
beim nächsten Aufruf aus. Kein Redeploy. Keine Änderung im Agenten-Code. Die
Policy wird im Gateway durchgesetzt — Ihr Agent gibt Tool-Calls weiterhin
genau wie zuvor aus.
Die Erkennung erfolgt am Gateway, bei der ersten Nutzung. Die Firewall
sitzt auf dem LLM-Relay-Pfad, nicht innerhalb des Paketmanagers oder
Dateisystems Ihres Agenten. Ein Tool, ein MCP-Server oder ein Skill, das ein
Agent selbst installiert, wird das erste Mal abgefangen, wenn sein Aufruf das
Gateway überquert — nicht zur Installationszeit. Das ist beabsichtigt: Es ist
der eine Engpass, der jeden Anbieter, jeden Agenten und jeden Tool-Call
sieht, ganz gleich, wie die Fähigkeit dorthin gelangt ist.
2. Die vier Enforcement-Surfaces
Jeder Tool-Call wird gegen genau eine Surface ausgewertet — den Punkt im Request-Lebenszyklus, an dem die Firewall ihn sieht:| Surface | Was sie sieht |
|---|---|
inbound | Die Tools, die ein Agent dem Modell auf dem Request anbietet (Tool-Definitionen). Lässt Sie ein gefährliches Tool blockieren, bevor das Modell es überhaupt wählen kann. |
response | Die tool_calls, die das Modell in seiner Antwort ausgibt. |
mcp | Ein tools/call, der durch das Firewall-MCP-Gateway dispatcht oder über den SDK-Hook ausgewertet wird. |
egress | Ein ausgehendes Netzwerkziel (Host / IP / CIDR), das von einem Tool gemeldet wird — die SSRF- und Datenexfiltrations-Surface. |
3. Kernkonzepte
| Konzept | Definition |
|---|---|
| Policy | Ein benannter, workspace-bezogener Regelsatz. Hat enabled, is_default, ein default_verdict und ein shadow_mode-Flag. |
| Regel | Eine Prüfung innerhalb einer Policy: eine Priorität, ein Tool-/Skill-Match, eine optionale Surface, ein optionales Argument-Prädikat und ein Verdikt. Siehe Regeln. |
| Verdikt | Die Aktion, die eine Regel (oder der Default) erzeugt — siehe §4. |
| Default-Verdikt | Wird angewendet, wenn keine Regel matcht. Einer der Werte allow, audit (Default) oder deny. |
| Shadow-Mode | Die Policy wertet aus und loggt, blockiert aber nie — jedes durchsetzende Verdikt wird auf audit herabgestuft und dem Grund wird [shadow] would … vorangestellt. Ihr Schalter für sicheres Ausrollen. |
| Observe-Mode | Eine Einstellung auf Workspace-Ebene. Wenn ein Request auf keine Policy aufgelöst wird und der Observe-Mode an ist, wird der Aufruf erlaubt, aber als Abdeckungs-Lücke geloggt — das ist es, was die Discovered-tools-Ansicht füllt. |
Scoping und Auflösung
Policies werden genau wie Guardrails und API-Keys aufgelöst — workspace-geteilt, wenn Sie einen aktiven Workspace haben. Für jeden Tool-Call löst das Gateway die Policy in dieser Reihenfolge auf:- Key-Bindung — wenn der aufrufende Key eine
firewall_policy_idhat, gilt diese Policy (sofern sie existiert und aktiviert ist). - Workspace-Default — andernfalls gilt die aktivierte
is_default-Policy des Workspaces. - Keines von beiden — keine Durchsetzung. Mit Observe-Mode an wird der Aufruf erlaubt und als Lücke geloggt; mit ihm aus wird der Aufruf stillschweigend erlaubt (byte-identisch zu einem Workspace, der das Feature nie aktiviert hat).
Fail-open beim Unbekannten, fail-closed beim Mehrdeutigen. Wenn die
Policy-Auflösung auf einen transienten Fehler stößt, degradiert das Gateway zu
observe/allow, anstatt den Traffic lahmzulegen. Aber dort, wo Nicht-Durchsetzen
die Regel aushebeln würde — ein Egress-Report ohne nutzbares Ziel, ein
Approval-Store, der unerreichbar ist, ein Skill, dessen Ownership nicht
aufgelöst werden kann — failt die Engine closed (deny oder hold). Die
Verfügbarkeit bleibt erhalten; die Sicherheit wird in den Fällen, die zählen,
nicht stillschweigend übersprungen.
4. Verdikte
Eine Regel (oder das Default-Verdikt) erzeugt eines der folgenden:| Verdikt | Was es tut |
|---|---|
allow | Den Aufruf durchlassen. Geloggt. |
audit | Erlauben, aber zur Überprüfung aufzeichnen. Das Default-default_verdict — alles beobachten, nichts blockieren, bis Sie bereit sind. |
deny | Den Aufruf blockieren. Der Agent sieht einen Tool-Fehler (oder HTTP 400 auf der inbound-Surface). |
sanitize | Gematchte Teilstrings aus den Tool-Argumenten redigieren (Secrets, PII) und den bereinigten Aufruf weiterleiten. Siehe Sanitizer. Auf der inbound-Surface — wo es noch keine Aufruf-Argumente gibt — eskaliert sanitize zu einem Block. |
pending_approval | Den Aufruf für einen Menschen zurückhalten. Der Agent erhält eine „held”-Antwort; ein Prüfer genehmigt oder lehnt out-of-band ab; der Agent reicht mit einem einmal nutzbaren Approval-Token erneut ein. Siehe §7. |
cap_cost | Ablehnen, sobald die kumulierten Ausgaben des Agentenlaufs eine Pro-Regel-Cent-Obergrenze überschreiten. Ein Schutzschalter für außer Kontrolle geratene Schleifen. |
deny / sanitize / pending_approval allesamt auf
audit herabgestuft, sodass Sie die Wirkung einer Policy messen können, bevor
sie den Traffic verändert.
5. Wie ein Tool-Call ausgewertet wird
- Ein Tool-Call erreicht das Gateway (inbound angeboten, in einer Antwort ausgegeben, durch das MCP-Gateway dispatcht oder als Egress gemeldet).
- Die Engine löst die aktive Policy auf (§3).
- Sie durchläuft die Regeln der Policy in Prioritätsreihenfolge (niedrigere Priorität zuerst; Gleichstände werden über die Regel-ID gebrochen). Eine Regel matcht, wenn ihre Surface, ihr Tool-Namen-Glob, ihr optionaler Skill-Namen-Glob, ihre optionalen Argument-Klauseln und ihr optionaler Egress-Scope alle matchen.
- Erster Treffer gewinnt → das Verdikt der Regel gilt. Wenn keine Regel
matcht → das
default_verdictder Policy. - Wenn der Aufruf einem gesteuerten Skill
gehört, wird der Enforcement-Mode des Skills obendrauf angewendet — ein
Skill im
block-Mode erzwingt ein deny; ein Skill imquarantine-Mode eskaliert alles unterhalb von deny zupending_approval. - Die Entscheidung wird als Firewall-Event geloggt (sofern es kein Dry-Run ist), korreliert mit dem Agentenlauf und der Session.
6. Wie ein Block aussieht
Ein abgelehnter Aufruf auf der inbound-Surface gibt HTTP 400 mit einem OpenAI-förmigen Fehler-Body zurück, mit dem Fehlercodefirewall_blocked und
einer Nachricht, die das Tool und den Grund benennt — z. B. tool "shell.exec" blocked by firewall: destructive shell command. Der Fehler trägt
strukturierte metadata (Reason-Code, Risikofaktoren, Score) und ist als
skip-retry markiert (das erneute Ausführen desselben Aufrufs würde einfach
wieder blockieren).
Ein durch das MCP-Gateway dispatchter Aufruf wird als Tool-Fehler
(firewall deny: <reason>) blockiert statt als Transportfehler, sodass das
Modell die Ablehnung sieht und reagieren kann — ein anderes Tool wählen, den
Nutzer fragen oder anhalten — statt abzustürzen.
Ein zurückgehaltener Aufruf (pending_approval) gibt HTTP 400 mit dem
Code firewall_approval_pending und einer Approval-ID zurück, auf die der
Client pollt.
7. Menschliche Freigabe (HITL)
Einpending_approval-Verdikt verwandelt einen Tool-Call in eine
Out-of-band-Prüfung:
- Die Engine reiht einen Approval-Datensatz ein und gibt eine „held”-Antwort zurück, die seine ID trägt; der Aufruf erreicht das Tool nicht.
- Ein Prüfer löst es auf — über die Konsole (Developer+) oder über einen HMAC-signierten Webhook-Callback an Ihr eigenes Approval-System.
- Ihr Agent (oder das MCP-SDK) pollt die Approval-ID; sobald genehmigt,
reicht er den ursprünglichen Aufruf mit einem einmal nutzbaren
X-OrcaRouter-Firewall-Approval-Header erneut ein, und das Gateway lässt ihn dieses eine Mal durch.
rule_changed, sodass Prüfer wissen, dass sich der Kontext verschoben hat.
8. Autonomie-Stufen — ein Schalter für Ihre gesamte Haltung
Policies Regel für Regel zu tunen ist der präzise Weg; Autonomie-Stufen sind der schnelle. Ein einziger Regler ersetzt die Firewall- und Guardrails-Haltung Ihres Workspaces atomar in einer Transaktion, mit Ein-Klick-Undo:| Stufe | Haltung |
|---|---|
tight | Destruktive Shell, Secrets in Argumenten und SSRF-Egress blockieren (Default deny); PII-Shield- + Secrets-Blocker-Guardrails an; Observe-Mode aus. |
balanced | Destruktive Shell auditieren, PII flaggen; Observe-Mode aus. Die empfohlene Ausgangshaltung. |
permissive | Keine durchsetzende Policy, keine Guardrails; Observe-Mode an, sodass Sie trotzdem alles sehen. |
9. Anomalieerkennung
Über statische Regeln hinaus lernt die Firewall die normale Tool-Nutzungsform jedes Workspaces und flaggt Abweichungen auf einem für Viewer lesbaren Feed:- Raten- / Kosten-Spikes — die Aktivität pro Tool wird gegen eine
gelernte Hour-of-week-Baseline (ein gleitender 14-Tage-Durchschnitt)
bewertet, sodass „100
db.query-Aufrufe um 3 Uhr morgens am Sonntag” herausstechen, selbst wenn jeder Aufruf einzeln erlaubt ist. retry_loop— ein Agent, der auf dasselbe fehlschlagende Tool einhämmert.novel_path— ein Tool-zu-Tool-Übergang, den dieser Workspace noch nie zuvor gemacht hat.
10. Observability
Die Firewall hinterlässt eine Spur, auf die Sie reagieren können, alles workspace-bezogen:| Surface | Was sie Ihnen gibt |
|---|---|
| Events | Jede Auswertung, filterbar nach Verdikt, Surface, Tool, Run und Session. Der Rohdatensatz hinter allem anderen. |
| Runs & Sessions | Events, aufgerollt nach Agentenlauf oder Konversation — Verdikt-Aufschlüsselung, distinkte Tools und Modelle, first/last seen. Die „was hat dieser Agent tatsächlich getan”-Ansicht. |
| Discovered tools | Jedes Tool, das der Workspace gesehen hat, geflaggt als covered (eine Regel trifft zu) oder gap (keine tut es). Treibt das Verfassen von Policies aus echtem Traffic. |
| Simulate | Vorschau, was eine Autonomie-Stufe ändern würde, bevor Sie sie anwenden. |
| Test | Eine Policy gegen einen Beispiel-Tool-Call dry-runnen und das Verdikt, die gematchte Regel und den Grund sehen — nichts wird persistiert, nichts wird dispatcht. |
| Audit | Jede Policy-, Regel- und Einstellungsänderung schreibt eine Audit-Zeile (Workspace + zentral), nachdem die Änderung committed ist. Secrets und Regel-Blobs werden nie geloggt. |
11. Verhältnis zum restlichen Gateway
| Surface | Wie komponiert sie mit der Firewall? |
|---|---|
| Guardrails | Komplementäre Ebenen. Guardrails screenen Prompt-/Response-Text; die Firewall steuert Tool-Aktionen. Beide können auf eine Anfrage zutreffen. Autonomie-Stufen setzen beide auf einmal. |
| Routing | Unabhängig. Das Routing wählt das Modell bzw. den Channel; die Firewall beurteilt die Tool-Calls unabhängig davon, welches Modell sie bedient hat. |
| API-Keys | Ein Key hängt sich via firewall_policy_id an eine Policy; die Bindung lebt am Key im Gateway. Keine Bindung fällt auf den Workspace-Default zurück. |
| MCP-Gateway | Die Firewall ist das MCP-Gateway — jeder Server, den Sie registrieren, dispatcht seinen tools/call durch die Engine. |
| Skills | Der Enforcement-Mode eines gesteuerten Skills reitet auf dem Regel-Verdikt obendrauf, sodass ein quarantänierter Skill zurückgehalten wird, selbst wenn keine Regel seine Tools benennt. |
12. Einen Agenten an das Firewall-Gateway anbinden
Es gibt zwei Wege, auf denen ein Tool-Call die Engine erreicht:- MCP-Gateway — richten Sie Ihren MCP-Client (Claude Desktop, Cursor, ein
Agenten-Framework) auf
https://api.orcarouter.ai/api/v1/firewall/mcp. Das Gateway exponiert die Tools jedes erreichbaren registrierten Servers, namespaced als<server>.<tool>, und wertet jedentools/callinline aus. Siehe MCP-Server. - Evaluate-Hook — rufen Sie
POST /api/v1/firewall/evaluateaus Ihrer eigenen Agenten-Schleife auf, bevor Sie einen Tool-Call dispatchen, und handeln Sie nach dem Verdikt.
403.
13. API-Referenz
Alle Konsolen-Routen sind über den Workspace-Kontext workspace-bezogen und setzen RBAC konsistent durch: Lesen und die Test-/Simulate-Sandboxes sind für jedes Mitglied offen; Schreiben erfordert Developer+.Policies & Einstellungen
| Methode & Pfad | Rolle | Zweck |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Workspace-Firewall-Einstellungen lesen (Observe-Mode, Defaults). |
PUT /api/workspace/firewall/settings | Developer+ | Einstellungen aktualisieren. |
GET /api/workspace/firewall/policies | Member | Policies auflisten (mit Regel- + angehängten-Key-Zählern). |
GET /api/workspace/firewall/policies/:id | Member | Detail einer einzelnen Policy. |
POST /api/workspace/firewall/policies | Developer+ | Eine Policy erstellen. |
PUT /api/workspace/firewall/policies | Developer+ | Eine Policy aktualisieren. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | Eine Policy löschen (409, wenn noch Keys angehängt sind). |
Haltung, Presets & Sandboxes
| Methode & Pfad | Rolle | Zweck |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Eingebaute Regel-Presets. |
POST /api/workspace/firewall/autonomy | Developer+ | Eine Autonomie-Stufe anwenden. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Eine Autonomie-Änderung rückgängig machen. |
GET /api/workspace/firewall/simulate | Member | Eine Autonomie-Stufe vorschauen (?level=). |
POST /api/workspace/firewall/test | Developer+ | Eine Policy gegen einen Beispiel-Tool-Call dry-runnen. |
Observability
| Methode & Pfad | Rolle | Zweck |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | Gesehene Tools, geflaggt als covered / gap. |
GET /api/workspace/firewall/events | Developer+ | Firewall-Events auflisten (filterbar). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | Events für einen Request. |
GET /api/workspace/firewall/events/aggregate | Developer+ | Runs- / Sessions-Rollup. |
GET /api/workspace/firewall/trace/by-run | Developer+ | Trace-Knoten für einen Run (?run_id=). |
GET /api/workspace/firewall/anomalies | Member | Anomalie-Feed (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Den Anomalie-Feed snoozen. |
Gateway (Maschine-zu-Maschine)
Diese laufen auf einem firewall-gateway-scoped Token, nicht auf der Konsolen-Session:| Methode & Pfad | Zweck |
|---|---|
POST /api/v1/firewall/evaluate | Pre-Dispatch-Verdikt für einen Tool-Call. |
POST /api/v1/firewall/evaluate_plan | Pre-Execution-Prüfung für einen mehrstufigen Plan. |
ANY /api/v1/firewall/mcp | Der vereinheitlichte MCP-Gateway-Endpunkt. |
GET /api/v1/firewall/approvals/:id | Den Approval-Zustand eines zurückgehaltenen Aufrufs pollen. |
POST /api/v1/firewall/approvals/:id/callback | HMAC-signierter Approval-Callback. |
14. FAQ
Was, wenn auf einem Tool-Call keine Policy aufgelöst wird?
Was, wenn auf einem Tool-Call keine Policy aufgelöst wird?
Mit Observe-Mode aus ist das Verhalten byte-identisch zu einem
Workspace, der das Feature nie aktiviert hat — nichts wird blockiert oder
geloggt. Mit Observe-Mode an wird der Aufruf erlaubt, aber als
Abdeckungslücke aufgezeichnet, sodass er in Discovered tools auftaucht.
Wie rolle ich eine Policy sicher aus?
Wie rolle ich eine Policy sicher aus?
Schalten Sie den Shadow-Mode ein. Die Policy wertet aus und loggt
genau so, wie sie es in Produktion täte, aber jedes durchsetzende Verdikt
wird auf
audit herabgestuft und dem Grund wird [shadow] would …
vorangestellt. Beobachten Sie die Events- und Runs-Ansichten, bestätigen
Sie, dass sie auf das feuert, was Sie erwarten, und auf nichts, was Sie
nicht erwarten, und schalten Sie dann den Shadow-Mode aus, um mit der
Durchsetzung zu beginnen.Kostet ein blockierter Tool-Call Kontingent?
Kostet ein blockierter Tool-Call Kontingent?
Ein inbound-Block feuert vor dem Upstream-Modellaufruf, sodass er keine
Modell-Tokens kostet. Audit- / allow-Verdikte ändern die Abrechnung
nicht. Eine
cap_cost-Regel ist selbst eine Abrechnungskontrolle — sie
lehnt ab, sobald die Ausgaben des Runs Ihre Cent-Obergrenze überschreiten.Firewall oder Guardrails — was verwende ich?
Firewall oder Guardrails — was verwende ich?
Beides, für verschiedene Ebenen. Guardrails screenen den Text in
Prompts und Antworten (PII, Secrets, Jailbreaks). Die Firewall steuert
die Aktionen, die ein Agent vornimmt (welche Tools, welche MCP-Server,
welche Hosts). Eine Anfrage kann durch beide laufen. Die
tight-Autonomie-Stufe konfiguriert sie zusammen.Ist die Durchsetzung für jedes Tool garantiert, das ein Agent ausführt?
Ist die Durchsetzung für jedes Tool garantiert, das ein Agent ausführt?
Die Firewall setzt auf Tool-Calls durch, die das Gateway überqueren — den
Relay-Pfad, das MCP-Gateway und den Evaluate-Hook. Ein Tool, das Ihr Agent
vollständig innerhalb seines eigenen Prozesses ausführt, ohne je das
Gateway zu berühren, liegt außerhalb des Sichtfelds der Firewall. Das
Designziel ist, das Gateway zum einzigen auditierten Pfad für die Aufrufe
zu machen, die zählen (modellvermittelte Tools, MCP-Dispatch,
Netzwerk-Egress); routen Sie diese durch es, und sie werden gesteuert.
Siehe auch
Sie möchten tiefer in die Agentensicherheit einsteigen? Die Leitfäden Secure Your Agents (Zero Trust) ordnen dieses Feature in einen Zero-Trust-Workflow ein.Sichern Sie Ihre Agenten (Zero Trust)
Das Zero-Trust-Playbook für die Agenten-Firewall — Tool-Allow-Lists, Argumentprüfungen und Egress-Kontrolle.
Secure-Agents-Baseline
Ein Schalter, der Ihre Firewall- und Guardrails-Haltung gemeinsam setzt.