Sécuriser les mises à niveau de version d'API pour les agents IA

Une mise à niveau d'API peut élargir l'autorité d'un agent sans modifier une seule ligne de ses instructions. Les changements dangereux paraissent généralement anodins dans les notes de version : une valeur par défaut change, un point de terminaison apparaît, un ancien jeton bénéficie d'un chemin de compatibilité ou une réponse contient des enregistrements absents de l'ancienne version.

Les intégrations pilotées par des humains survivent parfois à cette ambiguïté, car une personne remarque un écran inhabituel ou s'arrête avant une requête étrange. Un agent de programmation autonome ne marque pas cette pause. S'il peut construire des requêtes à partir de la documentation, examiner les erreurs et réessayer d'autres options, toute opération nouvellement accessible fait partie de son autorité réelle.

Les numéros de version ne mesurent pas l'autorité

Un numéro de version décrit la promesse de compatibilité du fournisseur de l'API, pas la modification des permissions vécue par l'agent. Traitez toute mise à niveau d'API comme un examen de l'autorité jusqu'à ce que vous ayez comparé ce que l'identifiant pouvait faire avant et après.

La spécification Semantic Versioning indique qu'une version MAJOR change lorsqu'une modification incompatible de l'API publique intervient. Cette règle aide les responsables de bibliothèques à déterminer si les appelants risquent de ne plus fonctionner. Elle ne dit pas qu'une version MINOR ne peut pas ajouter un nouveau point de terminaison administratif, élargir un filtre par défaut ou accepter un jeton d'accès destiné à une autre audience. Ces trois changements peuvent préserver la compatibilité tout en augmentant ce qu'un agent peut accomplir.

Cette distinction compte, car les équipes posent souvent la mauvaise question : « Notre code continuera-t-il de fonctionner ? » La question qui protège le compte est : « Quelles opérations cet agent existant peut-il maintenant effectuer avec succès, sur quelles ressources et avec quel identifiant ? »

Une mise à niveau d'API comporte quatre surfaces distinctes :

• Compatibilité des requêtes : méthodes, chemins, paramètres et formats de charge utile.
• Portée des ressources : comptes, projets, dépôts, fichiers ou enregistrements qu'une requête peut cibler.
• Portée des actions : opérations de lecture, d'écriture, de suppression, de déploiement, de facturation et d'identité qui peuvent aboutir.
• Acceptation des identifiants : jetons, clés, signatures, audiences et étendues acceptés par le fournisseur.

Un test réussi de compatibilité des requêtes ne dit presque rien sur les trois autres surfaces. C'est pourquoi une modification peut réussir une suite de régression classique tout en donnant à un agent un nouveau chemin vers les données de production.

Ne supposez pas qu'une version d'API datée règle le problème. Un fournisseur peut conserver une surface datée stable tout en modifiant un service d'authentification partagé, en ajoutant des champs facultatifs qu'un agent découvre ou en modifiant des valeurs par défaut en dehors du chemin du point de terminaison. Épingler une version est utile. Considérer cette épingle comme une limite de permissions est imprudent.

Construisez la carte d'autorité avant et après

Vous ne pouvez pas examiner une mise à niveau à partir des seules notes de version. Construisez une carte concise des requêtes que l'agent peut émettre, puis comparez le comportement observé dans l'ancienne et la nouvelle version.

Commencez par le trafic réel, pas par la conception prévue. Les agents utilisent souvent plus de points de terminaison que ne le laisse penser la tâche initiale : appels de découverte, nouvelles tentatives après des erreurs de validation, pagination, points de terminaison qui convertissent des noms en identifiants et API pratiques suggérées par les messages d'erreur. Incluez ces appels, car ils peuvent révéler des identifiants de ressources ou ouvrir un chemin plus large que l'action prévue.

Pour chaque famille de requêtes, notez les éléments suivants :

La carte doit décrire la limite de ressource en langage clair. « Peut appeler l'API des déploiements » est trop vague. « Peut créer des déploiements uniquement dans le projet sandbox » peut être testé. Si le fournisseur n'expose pas assez de détails pour formuler cette limite, utilisez une identité de test distincte pour l'agent jusqu'à ce que vous puissiez l'établir.

Faites ensuite une comparaison en deux colonnes. Exécutez le même corpus de requêtes sur les anciennes et nouvelles versions avec un compte isolé contenant des ressources volontairement séparées : au moins un projet autorisé, un projet interdit, un enregistrement inactif et un compte appartenant à un autre locataire si le service prend en charge cette notion. Les données de test doivent avoir des noms reconnaissables afin de révéler toute fuite accidentelle dans les résultats.

Ne comparez pas uniquement les codes de statut. Une réponse 200 peut dissimuler la différence importante : deux fois plus d'enregistrements, un nouveau lien next_page qui franchit une limite, un champ d'identifiant supplémentaire ou un identifiant d'objet permettant ensuite à l'agent d'appeler un point de terminaison privilégié. Comparez la structure et les identifiants des réponses, puis examinez tout nouveau champ qui pourrait donner une autorité supplémentaire.

Les valeurs par défaut modifiées créent des chemins d'accès que personne n'a demandés

Un paramètre omis reste une décision d'autorisation lorsque le serveur en choisit l'interprétation. Les valeurs par défaut modifiées méritent le même examen qu'un nouveau point de terminaison d'écriture.

Le problème classique commence par une requête de liste apparemment inoffensive. La version un exige project_id et ne renvoie que les enregistrements actifs. La version deux autorise la requête sans project_id, et le fournisseur définit cette omission comme « tous les projets visibles par ce jeton ». Le code source de l'agent n'a pas changé s'il omettait déjà ce champ facultatif. Ses données accessibles, elles, ont changé.

D'autres valeurs par défaut produisent le même résultat :

• Un point de terminaison de liste commence à inclure les objets archivés, supprimés ou hérités.
• La pagination passe d'un petit ensemble fixe à un parcours par curseur avec une URL next.
• Un point de terminaison de création choisit l'espace de travail par défaut de l'appelant au lieu de refuser un identifiant d'espace absent.
• Un point de terminaison de mise à jour accepte les champs omis comme « conserver la valeur actuelle » au lieu d'exiger une version de concurrence explicite.
• Un point de terminaison de recherche commence à indexer le contenu de services connectés.

Les fournisseurs présentent ces changements comme des améliorations, car ils réduisent le travail côté client. Pour un agent, moins de travail côté client signifie souvent moins d'obstacles avant qu'une action n'atteigne une cible plus large.

Examinez les valeurs par défaut avec des requêtes volontairement incomplètes. Pour chaque paramètre facultatif, envoyez une requête sans ce paramètre, une requête avec une valeur vide si l'API l'autorise, puis une requête avec une valeur sûre explicite. Comparez l'ensemble ciblé et l'erreur du serveur. Un agent qui génère des requêtes essaiera naturellement d'omettre des champs, surtout après avoir vu un exemple de documentation qui les laisse de côté.

Ne comptez pas sur un texte d'invite tel que « utilisez uniquement le projet A » pour contenir ce risque. Les instructions influencent le choix de la requête, mais c'est l'API qui décide si une requête peut toucher le projet B. Inscrivez la limite de projet dans l'identifiant, la conception du point de terminaison ou une passerelle qui valide la requête avant qu'elle ne quitte la machine.

Les nouveaux points de terminaison élargissent les identifiants étendus

Un nouveau point de terminaison modifie l'autorité d'un identifiant existant si cet identifiant peut s'y authentifier. L'agent n'a pas besoin d'avoir appelé ce point de terminaison avant la mise à niveau pour que le risque existe.

Les équipes excluent souvent les nouveaux points de terminaison de l'examen en les qualifiant de « nouvelles fonctionnalités ». Ce raisonnement fonctionne lorsqu'un utilisateur humain reçoit un nouveau contrôle dans l'interface et qu'un administrateur accorde séparément l'accès. Il échoue lorsqu'un jeton bearer doté d'une étendue large fonctionne automatiquement sur la nouvelle route.

Supposons qu'un agent possède un jeton décrit comme projects:write. Dans la version un, ce jeton peut créer et modifier les métadonnées d'un projet. La version deux ajoute POST /projects/{id}/exports, qui crée une exportation téléchargeable et utilise la même étendue. La chaîne d'étendue n'a pas changé, mais l'effet de sa possession, lui, a changé. L'agent peut découvrir ce point de terminaison dans un schéma d'API, un client généré, une indication d'erreur ou la documentation.

Classez les nouveaux points de terminaison par effet plutôt que par verbe HTTP. Les points de terminaison GET peuvent exposer du code source, des secrets, un historique d'audit, des données personnelles ou des URL de téléchargement signées. Les points de terminaison POST peuvent créer des coûts irréversibles ou déclencher des flux de travail externes. Une route DELETE peut être moins dangereuse qu'une route GET qui révèle un identifiant utilisable ailleurs.

Examinez chaque nouvelle route avec quatre questions :

1. Un identifiant d'agent existant peut-il s'y authentifier avec succès ?
2. Quelles étendues, quels rôles ou quelles classes de clés API existants l'autorisent ?
3. Sa sortie peut-elle fournir des identifiants, des URL ou des jetons pour une autre opération ?
4. L'agent peut-il l'atteindre par la bibliothèque cliente, le document de découverte ou la documentation fournie ?

La dernière question permet d'écarter une mauvaise recommandation fréquente : « Nous ne parlerons pas du nouveau point de terminaison à l'agent. » Cette restriction semble pratique, car les agents suivent la plupart du temps leur contexte de travail. Ce n'est pas un contrôle. Les agents peuvent examiner des schémas, déduire des chemins conventionnels ou recevoir une instruction dans une tâche ultérieure. Le serveur doit refuser une opération non approuvée même lorsque le client connaît son URL exacte.

Si le fournisseur ne peut pas séparer la nouvelle route d'une ancienne étendue large, créez une identité d'intégration plus limitée avant la mise à niveau. Un jeton destiné à un flux de travail précis ne doit pas hériter de toutes les significations futures qu'un fournisseur attribuera à un nom d'étendue convivial.

Les modifications d'authentification sont des modifications de permissions

Le comportement d'authentification doit figurer dans l'examen de la mise à niveau, car accepter un identifiant d'une autre manière modifie qui peut agir. Les équipes testent souvent la connexion réussie et négligent les refus, alors que c'est là que la mise à niveau peut causer des dommages.

OAuth 2.0 définit les jetons d'accès comme des identifiants représentant une autorisation, tandis que la RFC 9700, OAuth 2.0 Security Best Current Practice, recommande une correspondance exacte des URI de redirection et décrit des protections contre la réutilisation des jetons ainsi que des jetons liés à l'émetteur. La leçon pratique dépasse OAuth : le format d'un jeton n'établit pas à lui seul son destinataire, son émetteur ou son étendue prévue. Le serveur de ressources doit appliquer ces propriétés à chaque requête acceptée.

Les changements de version touchent souvent cette application indirectement. Un fournisseur peut introduire un nouvel émetteur, accepter des jetons destinés à une API voisine, ajouter une route d'échange de jetons, modifier la rotation des jetons de renouvellement ou autoriser une ancienne clé API en parallèle d'un jeton limité. La pression de compatibilité rend ces changements tentants. Elle crée aussi des chemins alternatifs que les ingénieurs oublient de tester.

Testez l'acceptation et le refus. Pour chaque classe d'identifiants, essayez l'opération autorisée, la même opération sur une ressource interdite, un identifiant expiré, un jeton dont l'audience est incorrecte, un jeton auquel il manque une étendue et un identifiant révoqué. Si le fournisseur prend en charge les jetons de renouvellement, vérifiez si le renouvellement conserve l'autorisation précédente, modifie son audience ou gagne silencieusement les étendues accordées lors d'un consentement ultérieur.

Un relevé utile ressemble à ceci :

credential: build-agent-sandbox
request: POST /v3/projects/prod-42/deployments
expected: 403 forbidden
old version: 403 {"error":"insufficient_scope"}
new version: 201 {"id":"dep_...","environment":"production"}
review result: block upgrade and revoke credential

Le corps de la réponse compte. Un 403 qui devient 404 peut correspondre à une modification intentionnelle destinée à masquer l'information. Un 403 qui devient 201 est une hausse d'autorité, même si les notes de version la présentent comme une amélioration de compatibilité.

Examinez aussi le comportement des en-têtes. Des en-têtes personnalisés peuvent sélectionner une version d'API, une organisation ou un utilisateur usurpé. Si la nouvelle API traite un en-tête absent comme l'organisation par défaut, une nouvelle tentative de l'agent après une erreur de formatage peut arriver au mauvais endroit. Enregistrez les en-têtes exacts dans les tests, en masquant les secrets, et testez séparément leur omission.

Le comportement d'un agent transforme de petits écarts en flux de travail complets

Un agent peut enchaîner des appels ordinaires pris séparément pour obtenir un résultat que le concepteur de l'API n'a jamais examiné comme une seule permission. L'examen d'une version doit suivre ces chaînes.

Un nouveau champ de liste peut révéler l'identifiant d'un dépôt. Cet identifiant peut alimenter un point de terminaison de téléchargement. La réponse du téléchargement peut contenir une URL signée. Cette URL peut exposer un artefact dont la configuration contient le point de terminaison d'un autre service. Chaque appel peut sembler autorisé isolément. La séquence complète peut dépasser la tâche confiée à l'agent.

C'est pourquoi l'examen de l'autorisation point par point est nécessaire mais incomplet. Ajoutez des tests de flux pour les actions que vous voulez autoriser et pour les actions proches que vous voulez exclure. Suivez le passage des identifiants entre les appels : identifiants, curseurs de pagination, emplacements, URL présignées, identifiants de tâches et messages d'erreur qui révèlent des noms de ressources valides.

Restez concret. Si l'agent doit mettre à jour un ticket dans un dépôt, vérifiez qu'il peut :

• Lire le ticket prévu et modifier ses champs autorisés.
• Échouer lorsqu'il essaie l'identifiant d'un ticket d'un autre dépôt.
• Échouer lorsqu'il tente de modifier les paramètres ou les webhooks du dépôt.
• Échouer lorsqu'il suit un lien vers une exportation, une liste de membres ou une route de gestion des jetons.

Le chemin d'échec compte autant que le chemin de réussite. Un agent traite les erreurs comme des informations. Un refus détaillé qui indique un autre point de terminaison peut rendre une route non prévue plus facile à trouver. Vous pouvez accepter ce compromis pour des développeurs humains, mais vous devez le connaître avant d'exposer l'intégration à un processus autonome.

Limitez les nouvelles tentatives pendant les tests de mise à niveau. Une stratégie de nouvelle tentative qui était inoffensive lorsqu'une requête était idempotente peut créer des actions en double si la nouvelle version modifie la gestion de l'idempotence ou renvoie un délai d'attente après avoir terminé le travail. Vérifiez si l'API utilise une clé d'idempotence, combien de temps elle la conserve et si la mise à niveau modifie le nom de l'en-tête ou les règles de hachage de la requête.

Un diff de capacités détecte les changements que les tests classiques manquent

Un diff de capacités est un test reproductible qui demande quelles requêtes un identifiant peut mener à bien, et non si votre application reçoit encore les données attendues. Gardez-le assez petit pour l'exécuter avec chaque version candidate.

Créez un corpus de requêtes dans un dépôt sans secrets de production. Utilisez des variables d'environnement pour les jetons de test et ciblez uniquement un compte jetable. Le modèle shell suivant enregistre les éléments qui révèlent une autorité modifiée sans afficher les identifiants :

curl -sS -D headers.txt -o body.json \\
  -H "Authorization: Bearer $TEST_TOKEN" \\
  -H "X-API-Version: 2025-01-01" \\
  "https://api.example.test/v1/projects?limit=2"

printf 'status: ' && head -n 1 headers.txt
printf 'headers:\n' && grep -Ei '^(link|location|x-request-id|www-authenticate):' headers.txt
printf 'identifiers:\n' && jq -r '.. | objects | (.id? // empty)' body.json | sort -u

Exécutez le corpus une fois pour chaque version, puis comparez le statut, certains en-têtes et les identifiants normalisés. Ne comparez pas aveuglément l'intégralité du JSON. Les horodatages, identifiants de requête et ordres variables créent du bruit et habituent les réviseurs à ignorer les différences. Normalisez d'abord ces champs, mais conservez les liens de pagination, les identifiants de ressources, les noms de rôles et tout champ pouvant diriger une requête ultérieure.

Votre corpus doit inclure des requêtes réussies, des refus attendus, des paramètres facultatifs omis, ainsi que la première page et une requête de pagination suivante. Ajoutez une requête pour chaque nouvelle route documentée qui semble liée à une étendue existante de l'agent. Le but n'est pas d'énumérer tout le fournisseur, mais de couvrir chaque opération que l'agent peut raisonnablement découvrir ou combiner.

Un fichier de résultats simple rend les décisions vérifiables :

{
  "case": "forbidden-production-deploy",
  "credential": "build-agent-sandbox",
  "request": "POST /v3/projects/prod-42/deployments",
  "expected_status": 403,
  "observed_status": 403,
  "observed_resource_ids": [],
  "version": "2025-01-01"
}

Exigez une décision explicite du réviseur pour chaque différence. « C'est attendu, le fournisseur l'a modifié » n'est pas une décision. Le réviseur doit préciser si le nouveau comportement reste dans l'autorité approuvée de l'agent et, dans l'affirmative, où cette autorité est appliquée.

Les journaux prouvent ce qui s'est passé, pas ce qui aurait dû se passer

Les journaux de requêtes aident à examiner une mise à niveau, mais ne remplacent pas un examen préalable de l'autorité. Ils répondent à des questions différentes.

Avant la mise à niveau, le diff de capacités vous indique si le fournisseur acceptera une requête indésirable. Après la mise à niveau, les journaux indiquent si l'agent a réellement tenté cette requête, quel processus l'a émise et si vous devez contenir le compte. Vous avez besoin des deux, car une requête refusée aujourd'hui peut être acceptée demain après une modification du comportement du fournisseur.

Enregistrez le sélecteur de version, l'opération normalisée, la limite ciblée, le libellé de l'identifiant, la décision, le statut et l'identifiant de corrélation. N'enregistrez pas les jetons bearer, les en-têtes d'autorisation bruts, les corps complets des requêtes ou les champs de réponse contenant des secrets. Un journal de sécurité qui conserve l'identifiant qu'il devait protéger ne fait que déplacer la compromission.

Séparez l'enregistrement de session de l'enregistrement d'action. La session indique quel processus d'agent a reçu l'autorisation d'agir pendant une exécution. L'action indique quelle requête individuelle il a effectuée. Cette distinction devient pénible lorsqu'un agent de longue durée démarre avec une version examinée, puis reçoit une modification d'environnement ou une bibliothèque cliente régénérée.

Sallyport conserve un journal Sessions et un journal Activity projetés depuis un journal d'audit chiffré et chaîné par hachage. Un opérateur peut ainsi examiner à la fois l'exécution de l'agent et chaque action HTTP ou SSH. Sa vérification hors ligne sp audit verify peut vérifier la chaîne sans accès au coffre, ce qui est utile lorsqu'un examen de mise à niveau se transforme en analyse d'incident.

Ne confondez pas preuve d'intégrité et prévention. Une piste d'audit intacte peut établir qu'un nouveau point de terminaison a été utilisé. Elle ne peut pas récupérer des données exportées d'un service distant. Protégez les actions sensibles avec des identifiants et des approbations qui échouent avant que la requête ne quitte la machine.

L'approbation doit être liée à un processus, pas à une tâche vague

Une approbation humaine ne peut arrêter une mise à niveau non examinée que si elle indique à la personne quel exécutable demande l'autorité. « L'agent demande un accès API » ne fournit pas assez d'informations lorsque plusieurs processus locaux peuvent parler le même protocole.

Liez l'autorisation de session à l'autorité de signature du code du processus demandeur lorsque le système d'exploitation l'expose. Cela détecte un remplacement courant : un agent approuvé démarre une session, puis un assistant non approuvé ou un binaire copié tente de réutiliser le même chemin d'identification. L'identité d'un processus ne prouve pas que toutes ses futures requêtes seront judicieuses, mais elle fournit à l'opérateur un objet concret à approuver ou à révoquer.

Réservez l'approbation par appel aux identifiants dont l'effet est difficile à limiter, comme le déploiement en production, l'administration de comptes ou l'exportation de données. Demander à une personne d'approuver chaque lecture inoffensive l'entraîne simplement à cliquer machinalement sur les fiches. La fatigue liée aux approbations est une erreur de conception, pas un défaut de l'utilisateur.

Sallyport utilise une échelle de décision fixe à trois contrôles : le coffre verrouillé refuse toutes les actions, un nouveau processus d'agent demande par défaut une autorisation de session et un réglage par clé peut exiger une approbation distincte à chaque utilisation. Ce modèle limité n'exprime pas toutes les règles d'une organisation, mais il évite d'enfouir les changements d'autorité dans un ensemble de règles difficile à suivre.

Lorsqu'une mise à niveau d'API modifie l'étendue effective d'un identifiant, révoquez la session actuelle et exigez une nouvelle approbation après l'examen. Ne laissez pas une session approuvée pour les points de terminaison d'hier se poursuivre discrètement sur ceux, plus larges, de demain.

Faites de l'examen de l'autorité une condition de livraison

Une mise à niveau de version d'API doit échouer à la condition de livraison lorsqu'un identifiant actuel gagne une requête réussie inexpliquée, lorsqu'une requête refusée devient autorisée ou lorsqu'une réponse expose un nouvel identifiant permettant un flux de travail interdit.

Inscrivez l'examen dans le même dossier de modification que les mises à jour de dépendances et du client généré. Notez les anciens et nouveaux sélecteurs d'API, les notes de version du fournisseur, le résultat du diff de capacités, les classes d'identifiants testées et la personne qui a accepté chaque différence intentionnelle. Ce travail est banal, et c'est précisément pourquoi il est souvent ignoré jusqu'à la première entrée d'audit étrange.

N'attendez pas une version majeure de l'API. Déclenchez l'examen lorsque le fournisseur modifie une version d'API, un service d'authentification, les paramètres d'une application OAuth, un SDK généré, un schéma de découverte, un en-tête par défaut ou une définition d'étendue. Une modification en dehors de l'URL peut aussi changer la décision prise par le serveur distant.

Commencez par l'identifiant qui causerait le plus de dommages s'il gagnait une seule route supplémentaire. Donnez-lui un compte de test isolé, écrivez cinq requêtes autorisées et refusées, puis exécutez-les sur la version proposée. Si vous ne pouvez pas expliquer pourquoi chaque réussite correspond à la tâche de l'agent, l'intégration n'est pas prête pour un usage autonome.