Vue d'ensemble de l'Agent Firewall

Un agent IA ne se contente pas de générer du texte — il agit. Il appelle shell.exec, interroge une base de données, récupère une URL, dispatche un outil à travers un serveur MCP. Chacun de ces actes est une action aux conséquences réelles que les guardrails au niveau du prompt ne peuvent pas voir. Le firewall agent est le plan de la couche action qui les gouverne : une politique nommée, à portée d’espace de travail, que la passerelle évalue à chaque appel d’outil, avant qu’il n’atteigne l’outil. Cette page est le hub de la section Firewall — le modèle de politique, les verdicts, les surfaces, et la façon dont une politique s’attache à une clé. Chaque branche va plus en profondeur, et la référence complète du moteur vit dans Firewall et Règles du Firewall.

1. Ce que fait le firewall agent

Vous rédigez une politique une fois dans la console de votre espace de travail, vous y attachez une clé API (ou en définissez une comme défaut de l’espace de travail), et dès lors chaque appel d’outil émis par cette clé est vérifié contre la politique à la passerelle. Aucun redéploiement, aucun changement de code d’agent — votre agent continue d’émettre des appels d’outils exactement comme auparavant, et la modification de la politique prend effet dès le prochain appel pour chaque clé qui y est attachée. Une politique est une liste ordonnée de règles. Chaque règle décide à quels appels d’outils elle s’applique et quoi en faire. Le moteur parcourt les règles dans l’ordre de priorité, la première correspondance gagne, et retombe sur le verdict par défaut de la politique si rien ne correspond.

La détection se produit à la passerelle, dès la première utilisation — pas au moment de l’installation. Un outil, un serveur MCP ou un skill qu’un agent s’auto-installe est attrapé la première fois que son appel franchit la passerelle. C’est l’unique point d’étranglement qui voit chaque fournisseur, chaque agent et chaque appel d’outil, peu importe comment la capacité est arrivée là.

2. Un exemple concret

Supposons que vous vouliez bloquer les commandes shell destructrices tout en laissant passer tout le reste sous audit. Dans la console, vous créez une politique avec default_verdict = audit et une règle :

{
  "label": "block rm -rf",
  "tool_name_glob": "*.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"}]}",
  "verdict": "deny"
}

args_match_json est une chaîne encodée en JSON (la passerelle la valide contre le schéma de clauses à l’enregistrement) : path est un JSONPath dans les arguments de l’appel, op est l’une des valeurs eq, contains, regex, in, cidr_match, gt, lt. Attachez une clé à la politique (définissez firewall_policy_id sur la clé). Désormais, quand un agent émet shell.exec avec command: "rm -rf /", la passerelle renvoie HTTP 400 avec le code d’erreur firewall_blocked et une raison nommant l’outil — et l’appel n’atteint jamais le shell. Tout autre appel d’outil est autorisé et enregistré pour revue.

Déployez d’abord une nouvelle politique sous le mode shadow : elle évalue et journalise exactement comme elle le ferait en production, mais chaque verdict appliquant est rétrogradé en audit et la raison est préfixée [shadow] would …. Surveillez le flux d’événements, puis désactivez le mode shadow pour appliquer.

3. Politique, règles et résolution

Une politique est nommée et à portée d’espace de travail, avec enabled, is_default, un default_verdict (allow / audit / deny, défaut audit) et un flag shadow_mode. Une règle est une vérification à l’intérieur — voir Créer une politique et Schéma de règle. Pour tout appel d’outil, la passerelle résout la politique active dans cet ordre :

Attachement de clé — le firewall_policy_id de la clé appelante, lorsque cette politique existe et est activée.
Défaut de l’espace de travail — sinon, la politique is_default activée.

Une politique firewall attachée mais désactivée retombe sur le défaut de l’espace de travail — cela diffère des guardrails, où un attachement désactivé se résout en aucun. L’interrupteur d’arrêt sur le firewall d’une clé signifie « utiliser le défaut », pas « aucune application ». Voir Gérer les politiques.

Lorsqu’aucune politique ne se résout, le comportement dépend du réglage firewall_observe_mode de l’espace de travail : avec le mode observe activé, l’appel est autorisé mais journalisé comme une lacune de couverture (il apparaît dans Discovered Tools) ; avec lui désactivé, l’appel est autorisé silencieusement.

4. Verdicts

Une règle — ou le défaut — produit l’une des valeurs :

Verdict	Ce qu’il fait
`allow`	Laisse passer, journalisé.
`audit`	Autorise + enregistre pour revue. Le défaut habituel.
`deny`	Bloque. HTTP 400 `firewall_blocked` en inbound ; erreur d’outil en MCP.
`sanitize`	Redacte les sous-chaînes correspondantes des arguments de l’outil et transmet.
`pending_approval`	Met en attente d’un humain ; HTTP 400 `firewall_approval_pending`.
`cap_cost`	Refuse dès que la dépense de l’exécution franchit un plafond par règle.

Un verdict sanitize redacte les arguments de l’appel seulement — jamais le contenu qu’un outil renvoie. Sur la surface inbound, où il n’y a pas encore d’arguments au moment de l’appel, sanitize escalade en un block. Voir Verdicts et Assainir les réponses.

5. Les quatre surfaces d’application

Chaque appel d’outil est évalué contre exactement une surface — épinglez une règle à l’une d’elles avec le champ stage, ou laissez-le vide pour s’appliquer à toutes.

inbound

Les outils qu’un agent annonce au modèle sur la requête. Bloquez un outil dangereux avant même que le modèle puisse le choisir.

response

Les tool_calls que le modèle émet dans sa réponse.

mcp

Un tools/call dispatché à travers la passerelle MCP. Voir Serveurs MCP.

egress

Un host / IP / CIDR sortant qu’un outil atteint — la surface de SSRF et d’exfiltration de données.

6. Correspondance

Les règles expriment à quels appels d’outils elles s’appliquent avec un vocabulaire petit et déterministe, sûr sur le chemin critique :

Globs de nom d'outil et de skill

Un glob sensible à la casse sur le nom d’outil (shell.*, *.delete), optionnellement combiné par AND avec un glob sur le skill propriétaire. Voir Syntaxe glob et Liste blanche d’outils.

Clauses d'arguments

Des prédicats JSONPath sur les arguments de l’appel avec les opérateurs eq, contains, regex, in, cidr_match, gt, lt — la différence entre « bloquer shell.exec » et « le bloquer uniquement quand la commande est rm -rf ». Les clauses fail closed (la règle, pas la requête). Voir Valider les arguments.

Listes d'egress

Listes d’autorisation et de refus host / IP / CIDR sur la surface egress. Vous pouvez rédiger votre propre règle de refus pour les plages cloud-metadata ou RFC-1918. Voir Contrôle d’egress.

Séquences et plafonds de coût

Une règle sequence correspond à une chaîne ordonnée d’appels sur une fenêtre (appliquée réactivement) ; une règle cap_cost refuse dès que la dépense accumulée d’une exécution d’agent franchit un plafond en centimes. Voir Règles de séquence et Plafonner le coût.

7. Approbation humaine, autonomie et anomalies

Human-in-the-loop. Un verdict pending_approval met l’appel en attente et renvoie son id d’approbation. Un relecteur le résout dans la console (Developer+) ou via un callback webhook signé HMAC ; l’agent interroge et re-soumet avec un en-tête X-OrcaRouter-Firewall-Approval à usage unique. Voir Approbations et Webhook d’approbation.
Niveaux d’autonomie. Un seul interrupteur définit toute votre posture : tight (default-deny + refus du shell destructeur + refus des outils de forme fetch (http_fetch/web_search/fetch_url/request, le vecteur SSRF) + PII Shield + Secrets Blocker appliqués), balanced (audit par défaut, refus du shell destructeur, PII Shield en audit seulement) ou permissive (observe seulement). Chacun écrit des lignes de politique et de guardrail réelles et éditables, avec annulation en un clic à partir du snapshot d’audit.
Détection d’anomalies. Au-delà des règles statiques, le firewall score l’usage des outils contre une baseline heure-de-la-semaine apprise (sur 14 jours) et signale les pics de débit/coût, retry_loop et novel_path sur un flux lisible par un Member que vous pouvez mettre en sourdine jusqu’à 7 jours.

8. Où s’insère le firewall

Le firewall est le pendant côté action de deux plans adjacents :

Plan	Gouverne	Quand y recourir
Guardrails	Le texte des prompts et réponses	PII, secrets, jailbreaks, intention d’injection
Firewall agent	Les actions d’outils	Quels outils, appels MCP, hôtes et coût
Conformité	Preuves et frameworks	Préparation SOC 2 / HIPAA / EU AI Act

Les plans contenu et action peuvent tous deux s’appliquer à une seule requête, et un niveau d’autonomie les configure ensemble. Voir Guardrails vs. Firewall et la pile de contrôle.

9. Attacher et connecter

Une politique se lie à une clé via firewall_policy_id (configuré dans la console ; la liaison vit sur la clé dans la passerelle). Deux façons pour un appel d’outil d’atteindre le moteur, toutes deux requérant une clé scopée à la passerelle firewall (is_firewall_gateway = true) — une clé de relais ordinaire reçoit un 403 sur ces routes :

Passerelle MCP — pointez votre client MCP vers l’endpoint unifié ANY /api/v1/firewall/mcp ; chaque tools/call est évalué en ligne. Voir Serveurs MCP.
Hook d’évaluation — appelez POST /api/v1/firewall/evaluate (ou /evaluate_plan pour un plan multi-étapes) depuis votre propre boucle d’agent avant de dispatcher, et agissez sur le verdict.

Toute la configuration de console s’exécute sous votre session via /api/workspace/firewall/*. Les lectures des politiques, des réglages, des outils découverts, le simulateur d’autonomie en lecture seule et le flux d’anomalies sont ouverts à chaque membre de l’espace de travail ; le sandbox de dry-run Test, le journal Events / Runs et toutes les écritures requièrent Developer+. Voir Clés de passerelle et Tester les règles.

10. Menaces que ce plan traite

Appels d'outils dangereux

Refusez le shell destructeur, les drops de BDD et les verbes risqués par glob + args.

Exfiltration de données

Listes d’egress et règles de séquence read-then-export.

Empoisonnement d'outils MCP

Évaluation par appel sur la surface mcp avant dispatch.

Agence excessive

Approbations, plafonds de coût et posture default-deny.

Étapes suivantes

Créer une politique

Rédigez votre première politique et règle.

Verdicts

Ce que fait chaque verdict sur le fil.

Journal d'événements

Lisez ce que le firewall a décidé et pourquoi.

​1. Ce que fait le firewall agent

​2. Un exemple concret

​3. Politique, règles et résolution

​4. Verdicts

​5. Les quatre surfaces d’application

inbound

response

mcp

egress

​6. Correspondance

​7. Approbation humaine, autonomie et anomalies

​8. Où s’insère le firewall

​9. Attacher et connecter

​10. Menaces que ce plan traite

Appels d'outils dangereux

Exfiltration de données

Empoisonnement d'outils MCP

Agence excessive

​Étapes suivantes

Créer une politique

Verdicts

Journal d'événements

1. Ce que fait le firewall agent

2. Un exemple concret

3. Politique, règles et résolution

4. Verdicts

5. Les quatre surfaces d’application

6. Correspondance

7. Approbation humaine, autonomie et anomalies

8. Où s’insère le firewall

9. Attacher et connecter

10. Menaces que ce plan traite

Étapes suivantes