La pile de contrôle : clés → guardrails → firewall → audit

OrcaRouter applique quatre couches à chaque requête dans un ordre fixe. Chaque couche est indépendante, à portée d’espace de travail, et s’attache à une clé API sans changement de code. Cette page fait traverser une requête à travers les quatre couches en séquence, puis couvre l’ordre de résolution et le comportement fail-open/fail-closed. Pour une introduction plus large, voir Sécuriser les agents IA avec OrcaRouter.

​

1. Couche 1 — Clé API à portée limitée

La clé est la première barrière. Avant que tout contenu ne soit inspecté ou qu’un modèle ne soit appelé, la passerelle résout la clé appelante et décide si la requête est même autorisée. Ce que la clé transporte :

• model_limits — l’ensemble des modèles que la clé peut appeler. Une requête pour un modèle en dehors de la liste est rejetée immédiatement.
• allow_ips — liste blanche d’IP optionnelle. Une requête depuis une source non répertoriée est rejetée.
• credit_limit_usd — un plafond de dépenses strict. Une requête qui ferait dépasser ce plafond à la clé est rejetée.
• expiry — une date d’expiration stricte. Les clés expirées sont rejetées.
• environment — une étiquette (production, staging, dev, …) pour organiser et identifier la clé par environnement de déploiement.
• guardrail_id — la politique de guardrail liée à cette clé (voir Couche 2 et Couche 4).
• firewall_policy_id — la politique firewall liée à cette clé (voir Couche 3).
• is_firewall_gateway — marque la clé comme token scopé à la passerelle firewall ; requis pour les routes d’évaluation et de passerelle MCP.

Une requête qui échoue à la validation de la clé n’atteint jamais un modèle — et n’est jamais mesurée. Où configurer : Console → API Keys, ou l’API token. Nécessite Developer+ pour créer ou modifier ; is_firewall_gateway et les lectures de clés en texte clair nécessitent Admin. Pour le modèle complet des clés, voir Portée, clés, politiques et espaces de travail.

​

2. Couche 2 — Guardrails d’entrée

Une fois la clé validée, la passerelle exécute les règles de l’étape input du guardrail lié contre le texte de la requête — avant tout appel au modèle en amont. Ce qu’elle voit : Les messages de l’appelant tels que soumis. (Un prompt injecté depuis un registre de prompts est ajouté plus tard, à l’étape de routage ; les règles d’entrée ne le voient pas.) Types de règles disponibles : keyword, regex, pii, max_chars, external, llm_judge, grounding. Actions qu’une règle peut produire : Un block à cette étape signifie que le modèle n’est jamais appelé. Coût : zéro. L’appelant voit une erreur structurée nommant le guardrail et la règle qui s’est déclenchée. Où configurer : Console → Guardrails, ou l’API guardrail. Nécessite Developer+ pour créer ou modifier. Voir Guardrails pour la référence complète des règles.

​

3. Couche 3 — Le modèle s’exécute

Si la clé est valide et que les guardrails d’entrée passent, la passerelle transfère la requête au modèle en amont. C’est la seule couche sans application configurable — c’est simplement le modèle qui fait son travail. Le firewall opère sur les actions que le modèle produit (Couche 3 → Couche 4 ci-dessous), pas sur le modèle lui-même. Le routage, les fallbacks et l’équilibrage de charge se produisent ici de manière transparente.

​

4. Couche 4 — Agent Firewall (appels d’outils et egress)

Après que le modèle répond — ou en ligne, à mesure que les appels d’outils sont émis — l’Agent Firewall juge chaque action que le modèle demande. Quatre surfaces d’application : Verdicts qu’une règle (ou le défaut) peut produire : Un deny sur la surface inbound ne coûte aucun token de modèle — le block se déclenche avant l’appel en amont. Un pending_approval retourne HTTP 400 firewall_approval_pending avec un id d’approbation que le client interroge. Où configurer : Console → Firewall, ou l’API firewall. Nécessite Developer+ pour créer ou modifier des politiques et des règles. Voir Firewall et Règles firewall pour le langage de règles complet.

​

5. Couche 5 — Guardrails de sortie

Après que le modèle répond (et après la fin de tout cycle d’appels d’outils), la passerelle exécute les règles de l’étape output du guardrail lié contre le texte de la réponse avant qu’il n’atteigne l’appelant. Les mêmes types de règles et actions s’appliquent qu’en Couche 2. Un block de sortie retourne HTTP 400 guardrail_blocked et rembourse le quota pré-consommé — l’appelant ne paie rien.

​

6. Couche 6 — Audit

Chaque correspondance, verdict et décision d’approbation est écrit dans la piste d’audit, corrélé à l’exécution de l’agent et à la session qui l’a causé. Ce n’est pas une étape d’application séparée — elle s’exécute en parallèle avec les Couches 2–5 — mais c’est la couche qui rend les autres responsables. Ce qui est journalisé :

• Correspondances guardrail : type de règle, action, étape, chaîne de détail, et (si Log raw content est activé) la sous-chaîne correspondante.
• Événements firewall : surface, nom d’outil, verdict, règle correspondante, code de raison, facteurs de risque, et l’exécution/session à laquelle l’appel appartient.
• Décisions d’approbation : qui a approuvé ou rejeté, quand, et si la règle sous-jacente a changé entre la mise en attente et la décision.
• Changements de politique : chaque création, mise à jour, suppression et changement de niveau d’autonomie écrit une ligne d’audit versionnée.

Où consulter : Console → Guardrails → Matches ; Console → Firewall → Events, Runs & Sessions, Audit. Le flux Matches des guardrails est ouvert à tout Member de l’espace de travail ; les flux Events et Runs & Sessions du firewall nécessitent Developer+.

​

7. Tableau récapitulatif

​

8. Ordre de résolution des politiques

Pour toute requête, le guardrail actif et la politique firewall sont résolus indépendamment :

1. Attachement de clé — si la clé porte un guardrail_id ou un firewall_policy_id explicite, cette politique s’applique (lorsqu’elle existe et est activée).
2. Défaut de l’espace de travail — si la clé n’a pas d’attachement, le guardrail ou la politique is_default activé de l’espace de travail s’applique.
3. Ni l’un ni l’autre — aucune application. La requête est byte-identique à un espace de travail qui n’a jamais activé la fonctionnalité.

Les deux plans diffèrent lorsqu’une politique attachée est désactivée : un attachement de guardrail désactivé désactive les guardrails pour cette clé (sans fallback), tandis qu’un attachement de firewall désactivé revient à la politique firewall par défaut de l’espace de travail. Au plus un guardrail et une politique firewall par espace de travail peuvent être le défaut. Promouvoir un nouveau défaut rétrograde l’ancien dans la même transaction.

​

9. Fail-open et fail-closed

Voir Modes d’application pour l’arbre de décision complet, et Comment OrcaRouter inspecte les requêtes pour les mécaniques du chemin de relais.

​

10. Approfondissements

Chaque appel à travers OrcaRouter passe par les quatre couches d’application dans l’ordre — validation de clé, filtrage d’entrée, jugement firewall, filtrage de sortie — avec une piste d’audit complète écrite à travers toutes.