Cette page porte sur les contrôles de passerelle qui limitent le rayon d’impact.
Le contexte du modèle de menace en amont — pourquoi les agents sont des cibles
de haute valeur et comment fonctionne l’injection — se trouve dans
Modèle de menace. Pour le contrôle
correspondant qui gouverne les appels d’outils individuels dangereux, voir
Appels d’outils dangereux.
1. Ce qui rend un agent excessivement capable
Quand chaque agent dans un espace de travail partage une clé, ou quand une clé est émise une fois et jamais revisitée, la capacité dérive vers le haut :- Modèles non restreints — l’agent peut appeler n’importe quel modèle dans l’espace de travail, y compris les coûteux ou très capables qu’il n’a jamais besoin.
- Pas de plafond de dépenses — une boucle incontrôlée, une injection déclenchée ou une attaque de facturation peut épuiser le solde de l’espace de travail avant que vous ne le remarquiez.
- Pas d’expiration — une clé émise pendant un sprint est encore valide un an plus tard, longtemps après que l’agent pour lequel elle a été créée est retraité.
- Pas de contrainte IP — l’identifiant fonctionne depuis n’importe où, donc une clé divulguée n’a pas de limite géographique.
- Pas de liste blanche d’outils — l’agent peut invoquer n’importe quel outil, même ceux sans rapport avec sa fonction.
2. Le pattern du député confus
Le député confus est une spécialisation de l’agence excessive. L’agent n’est pas piraté ; il est convaincu. Une charge utile d’injection de prompt dans une page web récupérée, un document ou un résultat d’outil dit à l’agent de prendre une action qu’il est légitimement autorisé à effectuer — transférer de l’argent, supprimer un enregistrement, envoyer un message — au nom de l’attaquant. L’agent agit. Il était autorisé à faire exactement cela. La vérification d’autorisation passe. Le dommage est fait. La défense nécessite deux choses travaillant ensemble :- Portée étroite — l’agent ne peut pas être trompé pour faire quelque chose que sa tâche n’avait jamais voulu, parce qu’il n’est pas autorisé à le faire du tout.
- Approbation humaine pour les actions irréversibles — même dans le cadre autorisé, un appel à enjeux élevés nécessite qu’un humain confirme avant qu’il ne s’exécute.
3. Défense en profondeur : les quatre couches
OrcaRouter applique la moindre agence à travers quatre contrôles indépendants qui se composent sur une seule clé API. Aucun ne nécessite un changement de code dans votre agent.Couche 1 — Clé à portée limitée (identité + limites strictes)
Chaque agent devrait avoir sa propre clé API. La clé porte des limites strictes que la passerelle applique peu importe ce que l’agent demande :| Champ | Ce qu’il restreint |
|---|---|
model_limits | L’ensemble exact de modèles que cette clé peut appeler. Une requête pour tout autre modèle est rejetée avant de quitter la passerelle. |
allow_ips | Les requêtes depuis toute adresse non sur cette liste sont rejetées à la couche d’authentification. Vide signifie pas de restriction IP. |
credit_limit_usd | Plafond de dépenses à vie en USD. 0 signifie illimité. La passerelle l’applique contre les dépenses cumulées sur la clé. |
expired_time | Horodatage d’expiration absolu. -1 signifie que la clé n’expire jamais. Définissez ceci au cycle de vie de déploiement de l’agent. |
environment | Une étiquette (prod, staging, dev) pour organiser les clés et filtrer les journaux d’audit. |
Couche 2 — Politique firewall (liste blanche d’outils)
Attachez une politique firewall à la clé viafirewall_policy_id. La politique gouverne chaque appel d’outil que cette clé
émet :
- Rédigez des règles qui autorisent les noms d’outils que l’agent utilise
légitimement (les globs de noms d’outils sont supportés — ex.
db.query*). - Définissez le
default_verdictde la politique surdenyafin que tout ce qui n’est pas explicitement listé soit bloqué. - Ajoutez des prédicats d’arguments pour restreindre même les outils autorisés
— ex. autoriser
db.queryuniquement quand l’argumentdatabasecorrespond à un schéma spécifique.
Couche 3 — Approbation humaine pour les actions à enjeux élevés (pending_approval)
Pour les appels d’outils irréversibles ou de haute valeur — un dispatch de
paiement, une suppression d’enregistrement, un envoi d’email — ajoutez une règle
pending_approval. Le flux :
- L’agent émet l’appel d’outil. Le firewall le met en attente et retourne une réponse « held » portant un id d’approbation. L’appel n’atteint pas l’outil.
- Un relecteur approuve ou rejette hors-bande — depuis la console (Developer+) ou via un webhook HMAC-signé vers votre propre système d’approbation.
- Votre agent interroge l’id d’approbation. Une fois approuvé, il re-soumet
l’appel original avec un header
X-OrcaRouter-Firewall-Approvalà usage unique. La passerelle le laisse passer exactement une fois.
Couche 4 — Plafond de coût par exécution (cap_cost)
Une règle cap_cost refuse tout appel d’outil une fois que la dépense accumulée
de l’exécution de l’agent dépasse un plafond par règle (en centimes). C’est le
disjoncteur pour :
- Les boucles incontrôlées déclenchées par injection.
- Les attaques de facturation qui font monter les dépenses avant qu’un humain ne remarque.
- La récursion accidentelle dans des plans multi-étapes.
cap_cost opère au niveau de l’exécution, pas au niveau de la vie de la
clé — donc il se réinitialise par invocation d’agent, et une seule exécution
défaillante ne peut pas épuiser le plafond credit_limit_usd de la clé.
4. Une clé d’agent bien scopée — exemple
Un agent qui résume des tickets clients en utilisantgpt-4o-mini et interroge
un réplica en lecture seule devrait ressembler à ceci :
model_limits:["openai/gpt-4o-mini"]— ne peut pas escalader vers un modèle plus capable ou plus cher.allow_ips: le CIDR d’egress du pool de travailleurs — la clé est inerte partout ailleurs.credit_limit_usd: un plafond hebdomadaire correspondant au coût attendu de la tâche, avec une marge — ex.5.00.expired_time: la fin du sprint ou de la période de déploiement — la clé s’auto-expire sans nettoyage manuel.environment:"prod"— apparaît dans les filtres de journaux et les vues d’anomalies.guardrail_id: un guardrail scopé à la sensibilité des données de cet agent (masquage PII, pas de secrets en sortie).firewall_policy_id: une politique qui autorise uniquementdb.query*etticket.read*, verdict par défautdeny.
is_firewall_gateway marque une clé comme token scopé passerelle pour les routes
de dispatch MCP et de hook d’évaluation. Créez celles-ci uniquement pour les
agents qui pilotent le firewall de manière programmatique — jamais pour le trafic
d’inférence général. Une clé de passerelle sur le chemin d’inférence expose des
routes que les clés à usage général ne devraient jamais atteindre. Activer
is_firewall_gateway nécessite Admin+.5. Rôles requis
| Action | Rôle minimum |
|---|---|
| Lire toute clé, politique ou événement firewall | Member |
| Créer ou modifier des clés, politiques firewall, règles | Developer |
| Approuver un appel d’outil mis en attente depuis la console | Developer |
Activer is_firewall_gateway sur une clé | Admin |
6. Relation avec les autres menaces
L’agence excessive est l’activateur pour presque toute autre menace d’agent :- Appels d’outils dangereux — une clé avec une liste blanche d’outils stricte ne peut pas être forcée d’appeler un outil qu’elle ne liste pas, même si l’injection réussit.
- Injection de prompt — les limites de portée bornent les dommages que l’injection peut faire ; les barrières d’approbation bloquent les actions irréversibles que l’injection tente de déclencher.
- Modèle de menace — la carte complète de la surface d’attaque, montrant où l’agence excessive se situe par rapport aux autres vecteurs.
Clés à portée limitée & politiques
La référence complète des champs de clé, l’ordre de résolution et le
modèle de frontière de l’espace de travail.
Firewall
Rédaction de politiques, verdicts, flux d’approbation HITL et la
référence API complète.
