Firewall

Les guardrails filtrent le texte qui circule à travers un modèle. Le Firewall gouverne les actions qu’un agent entreprend — les outils qu’il appelle, les serveurs MCP qu’il atteint, les skills qu’il charge et les hôtes auxquels il parle. C’est le pendant côté action des Guardrails : même portée d’espace de travail, même modèle attach-once, même promesse « la politique vit dans la passerelle, pas dans votre application ». Cette page est la vue d’ensemble conceptuelle et la référence opérationnelle. Trois pages compagnes couvrent les rouages en profondeur :

​

1. Qu’est-ce que le Firewall

Un agent IA ne se contente pas de générer du texte — il agit. Il appelle shell.exec, interroge db.query, récupère une URL, charge un skill communautaire ou route un appel d’outil à travers un serveur MCP tiers. Chacun de ces actes est une action aux conséquences réelles, et les guardrails au niveau du prompt ne peuvent pas les voir. Le Firewall est une politique nommée, à portée d’espace de travail que la passerelle évalue à chaque appel d’outil. Vous rédigez une politique une fois, attachez-y 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 — avant qu’il n’atteigne l’outil. Chaque politique est une liste ordonnée de règles. Une règle décide d’une seule chose — à quels appels d’outils elle s’applique (un glob de nom d’outil, optionnellement scopé à un skill et à une surface d’application) et quoi en faire (un verdict : allow, audit, deny, sanitize, hold for approval, ou cap cost). 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 modification d’une politique prend effet sur chaque clé qui y est attachée dès le prochain appel. Aucun redéploiement. Aucun changement de code d’agent. La politique est appliquée dans la passerelle — votre agent continue d’émettre des appels d’outils exactement comme auparavant.

​

2. Les quatre surfaces d’application

Chaque appel d’outil est évalué contre exactement une surface — le point du cycle de vie de la requête où le firewall le voit : Une règle sans stage s’applique à toutes les surfaces ; épinglez une règle à une surface lorsqu’un verdict n’a de sens que là (par exemple une allowlist d’egress).

​

3. Concepts fondamentaux

​

Portée et résolution

Les politiques se résolvent exactement comme les Guardrails et les clés API — partagées dans l’espace de travail lorsque vous avez un espace de travail actif. Pour tout appel d’outil, la passerelle résout la politique dans cet ordre :

1. Attachement de clé — si la clé appelante a un firewall_policy_id, cette politique s’applique (lorsqu’elle existe et est activée).
2. Défaut de l’espace de travail — sinon, la politique is_default activée de l’espace de travail s’applique.
3. Ni l’un ni l’autre — aucune application. Avec le mode observe activé, l’appel est autorisé et journalisé comme une lacune ; avec lui désactivé, l’appel est autorisé silencieusement (identique octet pour octet à un espace de travail qui n’a jamais activé la fonctionnalité).

Au plus une politique par espace de travail peut être le défaut ; promouvoir un nouveau défaut rétrograde l’ancien dans la même transaction.

​

4. Verdicts

Une règle (ou le verdict par défaut) produit l’une des valeurs : En mode shadow, deny / sanitize / pending_approval sont tous rétrogradés en audit afin que vous puissiez mesurer l’impact d’une politique avant qu’elle ne change le trafic.

​

5. Comment un appel d’outil est évalué

1. Un appel d’outil atteint la passerelle (annoncé en inbound, émis dans une réponse, dispatché à travers la passerelle MCP, ou rapporté comme egress).
2. Le moteur résout la politique active (§3).
3. Il parcourt les règles de la politique dans l’ordre de priorité (priorité plus basse d’abord ; égalités tranchées par l’id de règle). Une règle correspond lorsque sa surface, son glob de nom d’outil, son glob de nom de skill optionnel, ses clauses d’arguments optionnelles et sa portée d’egress optionnelle correspondent toutes.
4. La première correspondance gagne → le verdict de la règle s’applique. Si aucune règle ne correspond → le default_verdict de la politique.
5. Si l’appel appartient à un skill gouverné, le mode d’application du skill est appliqué par-dessus — un skill en mode block force un deny ; un skill en mode quarantine escalade tout ce qui est en-deçà d’un deny vers pending_approval.
6. La décision est journalisée comme un événement firewall (sauf s’il s’agit d’un dry run), corrélée à l’exécution et à la session de l’agent.

​

6. À quoi ressemble un block

Un appel refusé sur la surface inbound renvoie une HTTP 400 avec un corps d’erreur de forme OpenAI, le code d’erreur firewall_blocked, et un message nommant l’outil et la raison — par exemple tool "shell.exec" blocked by firewall: destructive shell command. L’erreur porte des metadata structurées (code de raison, facteurs de risque, score) et est marquée skip-retry (ré-exécuter le même appel ne ferait que bloquer à nouveau). Un appel dispatché à travers la passerelle MCP est bloqué comme une erreur d’outil (firewall deny: <reason>) plutôt qu’une défaillance de transport, de sorte que le modèle voit le rejet et peut réagir — choisir un autre outil, demander à l’utilisateur, ou s’arrêter — au lieu de planter. Un appel mis en attente (pending_approval) renvoie une HTTP 400 avec le code firewall_approval_pending et un id d’approbation sur lequel le client interroge.

​

7. Approbation humaine (HITL)

Un verdict pending_approval transforme un appel d’outil en une revue hors-bande :

1. Le moteur met en file d’attente un enregistrement d’approbation et renvoie une réponse « held » portant son id ; l’appel n’atteint pas l’outil.
2. Un relecteur le résout — depuis la console (Developer+), ou via un callback webhook signé HMAC vers votre propre système d’approbation.
3. Votre agent (ou le SDK MCP) interroge l’id d’approbation ; une fois approuvé, il re-soumet l’appel d’origine avec un en-tête X-OrcaRouter-Firewall-Approval à usage unique, et la passerelle le laisse passer cette fois-là.

Les décisions sont first-writer-wins et idempotentes. Si la règle sous-jacente a été modifiée après la mise en attente, l’enrichissement note rule_changed afin que les relecteurs sachent que le contexte a changé.

​

8. Niveaux d’autonomie — un seul interrupteur pour toute votre posture

Ajuster les politiques règle par règle est le chemin précis ; les niveaux d’autonomie sont le chemin rapide. Un unique contrôle remplace atomiquement la posture Firewall et Guardrails de votre espace de travail en une seule transaction, avec annulation en un clic : L’annulation restaure l’état antérieur exact à partir du snapshot d’audit.

​

9. Détection d’anomalies

Au-delà des règles statiques, le Firewall apprend la forme normale d’utilisation des outils de chaque espace de travail et signale les écarts sur un flux lisible par un viewer :

• Pics de débit / coût — l’activité par outil est scorée contre une baseline heure-de-la-semaine apprise (une moyenne glissante sur 14 jours), de sorte que « 100 appels db.query à 3h du matin un dimanche » ressort même si chaque appel est individuellement autorisé.
• retry_loop — un agent qui martèle le même outil défaillant.
• novel_path — une transition d’outil à outil que cet espace de travail n’a jamais faite auparavant.

Le flux ne rapporte que des noms d’outils, des ids de tokens redactés et des comptes. Vous pouvez mettre en sourdine une anomalie jusqu’à 7 jours pendant que vous enquêtez.

​

10. Observabilité

Le Firewall laisse une trace sur laquelle vous pouvez agir, le tout à portée d’espace de travail :

​

11. Relation avec le reste de la passerelle

​

12. Connecter un agent à la passerelle Firewall

Il y a deux façons pour un appel d’outil d’atteindre le moteur :

• Passerelle MCP — pointez votre client MCP (Claude Desktop, Cursor, un framework d’agent) vers https://api.orcarouter.ai/api/v1/firewall/mcp. La passerelle expose les outils de chaque serveur enregistré joignable, sous le namespace <server>.<tool>, et évalue chaque tools/call en ligne. Voir Serveurs MCP.
• Hook d’évaluation — appelez POST /api/v1/firewall/evaluate depuis votre propre boucle d’agent avant de dispatcher un appel d’outil, et agissez sur le verdict.

Les deux requièrent un token scopé à la passerelle firewall — une clé API dédiée frappée à cet effet. Une clé ordinaire reçoit un 403 sur ces routes.

​

13. Référence API

Toutes les routes de console sont à portée d’espace de travail via le contexte d’espace de travail et appliquent RBAC de manière cohérente : les lectures et les sandboxes de test/simulation sont ouvertes à chaque membre ; les écritures nécessitent Developer+.

​

Politiques & réglages

​

Posture, presets & sandboxes

​

Observabilité

Les règles, les serveurs MCP et les skills ont chacun leurs propres endpoints — voir Règles, Serveurs MCP, et Skills.

​

Passerelle (machine-à-machine)

Celles-ci s’exécutent sur un token scopé à la passerelle firewall, pas sur la session de console :

​

14. FAQ

​

Voir aussi

Vous souhaitez approfondir la sécurité des agents ? Les guides Sécurisez vos agents (Zero Trust) replacent cette fonctionnalité dans un workflow zero-trust.