Firewall-API-Referenz

Die Agent-Firewall wird auf zwei Wegen konfiguriert: über die Konsole (Ihre Session, derselbe Login, den Sie für das Dashboard nutzen) und über das Gateway (ein dedizierter firewall-scoped API-Key, den Ihr Agent zur Laufzeit präsentiert). Die zwei Familien leben unter verschiedenen Pfad-Präfixen, nehmen verschiedene Auth und beantworten verschiedene Fragen — „die Policy bearbeiten” versus „diesen Tool-Call auswerten”. Diese Seite ist die Route-für-Route-Karte beider. Was die Policy bedeutet — Verdikte, Surfaces, Regeln, Auflösung — beginnt bei Firewall und Firewall-Regeln. Diese Seite ist nur die API-Surface.

1. Die zwei Routenfamilien

Konsole — konfigurieren

/api/workspace/firewall/*. Authentifiziert durch Ihr Session- / Access-Token (UserAuth), gescoped auf Ihren aktiven Workspace. Policies verfassen, Events lesen, MCP-Server registrieren, Freigaben auflösen. Jede Aktion ist rollengegated.

Gateway — durchsetzen

/api/v1/firewall/*. Authentifiziert durch einen firewall-gateway-scoped Key (ein Key mit gesetztem is_firewall_gateway). Die Maschine-zu-Maschine-Surface, die Ihr Agent oder MCP-Client zur Laufzeit aufruft. Ein regulärer Relay-Key erhält hier 403.

Konsolen-Routen nehmen nie einen sk-orca-…-Relay-Key, und Gateway-Routen nehmen nie ein Session-Token. Sie zu verwechseln ist der häufigste 401/403, wenn man die Firewall das erste Mal verdrahtet. Der einzige sk-orca-…-Key, der auf einen /v1/firewall/*-Aufruf gehört, ist einer, der mit eingeschaltetem is_firewall_gateway geprägt wurde — siehe Scope, Keys & Policies.

2. Rollen auf einen Blick

Konsolen-Routen lösen Ihre Workspace-Rolle auf und gaten entsprechend. Lesevorgänge, die keine Tool-Call-Herkunft tragen, sind für jedes Mitglied offen; Schreibvorgänge und alles, was Tool-Call-Argumente exponiert, erfordern Developer+.

Rolle	Kann tun
Viewer / Mitglied	Einstellungen, Policies, Presets, Discovered tools, Simulate, Anomalien lesen.
Developer+	Alles davon, plus jeden Schreibvorgang, die `events`/`runs`/`trace`-Surface und den `test`-Dry-Run.
Admin+	Zusätzlich das `is_firewall_gateway`-Flag auf einem Key setzen und das Klartext eines Gateway-Keys lesen.

Die Aufteilung ist beabsichtigt: Ein Viewer kann sehen, dass eine Policy existiert und was sie blockieren würde, aber nicht die rohen Tool-Call-Argumente hinter einem Event. Wenn Sie Dashboards für Nicht-Entwickler bauen, sind die read-open Routen das sichere Set.

3. Eine Policy aus der Konsole konfigurieren

Die Konsolen-Routen sind, wie Sie Policy verfassen und inspizieren. Sie konfigurieren alles in der Dashboard-UI — dies sind dieselben Endpunkte, die sie aufruft.

Policies & Einstellungen

Methode & Pfad	Rolle	Zweck
`GET /api/workspace/firewall/settings`	Member	Observe-Mode + Zähler.
`PUT /api/workspace/firewall/settings`	Developer+	Workspace-Firewall-Einstellungen aktualisieren.
`GET /api/workspace/firewall/policies`	Member	Policies auflisten.
`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.
`POST /api/workspace/firewall/rules`	Developer+	Eine Regel hinzufügen.
`PUT /api/workspace/firewall/rules`	Developer+	Eine Regel aktualisieren.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	Eine Regel löschen.

Haltung, Presets & Sandboxes

Methode & Pfad	Rolle	Zweck
`GET /api/workspace/firewall/presets`	Member	Eingebaute Regel-Presets.
`GET /api/workspace/firewall/templates`	Member	Use-Case-Template-Galerie.
`POST /api/workspace/firewall/templates/apply`	Developer+	Ein Template anwenden → eine Policy + ihre Regeln.
`POST /api/workspace/firewall/autonomy`	Developer+	Eine Autonomie-Stufe anwenden (`tight` / `balanced` / `permissive`).
`POST /api/workspace/firewall/autonomy/undo/:audit_id`	Developer+	Ein-Klick-Undo aus dem Audit-Snapshot.
`GET /api/workspace/firewall/simulate`	Member	Was eine Stufe blockieren würde (`?level=`).
`POST /api/workspace/firewall/test`	Developer+	Eine Policy gegen einen Beispielaufruf 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.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	Den Feed snoozen (≤ 7 Tage).

MCP-Server

Registrieren Sie die Model-Context-Protocol-Server, die Ihre Agenten erreichen, hinter einem einzigen auditierten Gateway. Credentials werden verschlüsselt gespeichert und beim Lesen maskiert.

Methode & Pfad	Rolle	Zweck
`GET /api/workspace/firewall/mcp_servers`	Member	Registrierte Server auflisten.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Server-Detail.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Einen Server registrieren (`409` bei doppeltem `name`).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Einen Server aktualisieren.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Einen Server entfernen.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Erreichbarkeit + `tools/list`-Handshake.

Ein Server trägt einen eindeutigen name, einen endpoint, einen auth_mode (none / bearer / oauth / basic) und einen Health-status (ok / degraded / down). Siehe Firewall-MCP für den vollständigen Lebenszyklus und die Skill-Quarantäne.

4. Am Gateway durchsetzen

Diese laufen auf einem firewall-gateway-scoped Key, nicht auf Ihrer Session. Sie sind das, was Ihre Agenten-Schleife oder Ihr MCP-Client zur Laufzeit aufruft.

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/mcp_servers`	Die registrierten Server des Workspaces aufzählen.
`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.

Ein konkretes Beispiel: einen Tool-Call auswerten

Bevor Ihr Agent ein Tool dispatcht, bitten Sie das Gateway um ein Verdikt. Geben Sie den firewall-gateway-scoped Key weiter — nicht Ihren sk-orca-…-Relay-Key:

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

Die Antwort trägt das Verdikt — allow, audit, deny, sanitize oder pending_approval. Bei deny überspringen Sie den Aufruf und bringen den Grund dem Modell zur Kenntnis; bei sanitize leiten Sie die bereinigten Argumente weiter, die das Gateway zurückgibt (sanitize redigiert nur Tool-Call-Argumente — nie den Inhalt, den ein Tool zurückgibt); bei pending_approval treten Sie in die Approval-Schleife unten ein.

Das Gateway wertet die Aufrufe aus, die es überqueren — den Evaluate-Hook, das MCP-Gateway und den Relay-Pfad. Ein Tool, das Ihr Agent vollständig im eigenen Prozess ausführt, ohne je OrcaRouter zu berühren, liegt außerhalb seines Sichtfelds. Routen Sie die Aufrufe, die zählen (modellvermittelte Tools, MCP-Dispatch, Netzwerk-Egress), durch das Gateway, und sie werden gesteuert.

5. Der Approval-Handshake (HITL)

Ein pending_approval-Verdikt hält den Aufruf für einen Menschen zurück. Der HTTP-Fehler, während er zurückgehalten ist, ist firewall_approval_pending. Ihn freizugeben ist eine dreistufige Schleife, aufgeteilt über beide Routenfamilien:

Ein Prüfer löst den Hold auf

Über die Konsole (PATCH /api/workspace/firewall/approvals/:id, Developer+), oder Ihr eigenes System postet einen HMAC-signierten Callback an POST /api/v1/firewall/approvals/:id/callback. Der Callback verifiziert den HMAC inline — keine andere Auth wird akzeptiert.

Ihr Agent pollt die Freigabe

GET /api/v1/firewall/approvals/:id mit dem Gateway-Key, bis der Zustand auf approved oder rejected umkippt.

Reichen Sie mit dem einmal nutzbaren Token erneut ein

Sobald genehmigt, geben Sie den ursprünglichen Aufruf mit dem X-OrcaRouter-Firewall-Approval-Header und der Approval-ID erneut aus. Das Gateway erkennt ihn und lässt diesen einen Aufruf durch. Der Header ist einmal nutzbar.

Entscheidungen sind first-writer-wins und idempotent — eine zweite Auflösung desselben Holds ist ein No-op. Siehe Firewall — Menschliche Freigabe für den End-to-End-Flow und Warum wurde das blockiert? zum Lesen eines Verdikts.

6. Wie ein Block aussieht

Ergebnis	HTTP	Code
Abgelehnter Tool-Call (inbound-Surface)	`400`	`firewall_blocked`
Abgelehnt über MCP-Gateway	Tool-Fehler	`firewall deny: <reason>`
Für Freigabe zurückgehalten	`400`	`firewall_approval_pending`

firewall_blocked ist als skip-retry markiert — denselben Aufruf identisch erneut auszuführen würde einfach wieder blockieren, sodass ein wiederholender Client zurückweicht, statt zu hämmern. Die vollständige Code-Liste steht in Fehlercodes.

7. Verwandte Referenzen

Guardrail-API

Das Inhaltspolicy-Pendant — /api/guardrail/*-Routen für die Text-Plane.

Verdikt-Glossar

Jedes Verdikt und was es mit einem Aufruf macht.

Glob & JSONPath

Die Matching-Grammatik hinter tool_name_glob und args_match.

Compliance-API

Packs, signierte Reports, Residency und Erasure.

8. FAQ

Warum erhält mein Relay-Key einen 403 auf /api/v1/firewall/evaluate?

Die Gateway-Routen erfordern einen firewall-gateway-scoped Key — einen, der mit gesetztem is_firewall_gateway geprägt wurde (eine Admin+-Aktion). Ein regulärer Relay-Key, selbst ein gültiger, erhält 403. Prägen Sie einen dedizierten Gateway-Key für Ihre Agenten-Laufzeit.

Kann ein Viewer Firewall-Events lesen?

Nein. Die events-, events/aggregate- und trace-Routen sind Developer+, weil die Datensätze Tool-Call-Argument-Herkunft tragen. Viewer können Einstellungen, Policies, Presets, Discovered tools, Simulate und den Anomalie-Feed lesen.

Wo löse ich eine zurückgehaltene Freigabe auf — Konsole oder Gateway?

Beides. Ein Mensch löst sie in der Konsole über PATCH /api/workspace/firewall/approvals/:id (Developer+) auf, oder Ihr eigenes System postet eine HMAC-signierte Entscheidung an POST /api/v1/firewall/approvals/:id/callback. Der Agent pollt GET /api/v1/firewall/approvals/:id, unabhängig davon, welcher Pfad sie aufgelöst hat.

Bereinigt sanitize, was ein Tool zurückgibt?

Nein. Ein sanitize-Verdikt redigiert nur die Tool-Call-Argumente — nie den Inhalt, den ein Tool zurückgibt. Auf der inbound-Surface, wo es noch keine Aufruf-Argumente gibt, eskaliert sanitize zu einem Block. Siehe Firewall-Regeln.

Wie diese Kontrollen mit Guardrails und dem Rest des Gateways komponieren, siehe KI-Agenten absichern und Guardrails vs. Firewall.

​1. Die zwei Routenfamilien

Konsole — konfigurieren

Gateway — durchsetzen

​2. Rollen auf einen Blick

​3. Eine Policy aus der Konsole konfigurieren

​Policies & Einstellungen

​Haltung, Presets & Sandboxes

​Observability

​MCP-Server

​4. Am Gateway durchsetzen

​Ein konkretes Beispiel: einen Tool-Call auswerten

​5. Der Approval-Handshake (HITL)

​6. Wie ein Block aussieht

​7. Verwandte Referenzen

Guardrail-API

Verdikt-Glossar

Glob & JSONPath

Compliance-API

​8. FAQ

1. Die zwei Routenfamilien

2. Rollen auf einen Blick

3. Eine Policy aus der Konsole konfigurieren

Policies & Einstellungen

Haltung, Presets & Sandboxes

Observability

MCP-Server

4. Am Gateway durchsetzen

Ein konkretes Beispiel: einen Tool-Call auswerten

5. Der Approval-Handshake (HITL)

6. Wie ein Block aussieht

7. Verwandte Referenzen

8. FAQ