Comment une carte d'approbation d'API révèle la véritable cible

Un évaluateur ne peut pas approuver une action HTTP à partir d'une chaîne qui ressemble vaguement à une destination. La carte doit afficher la cible que le transport utilisera réellement, après l'analyse et avant que les identifiants ne quittent la machine.

Cela semble évident, jusqu'à ce qu'un agent envoie HTTPS://API.EXAMPLE.TEST:443/%76%31/../admin, qu'un client l'accepte et que la personne voie une étiquette abrégée comme api.example.test. Une telle carte ne demande pas un consentement éclairé. Elle demande à la personne de faire confiance à un affichage qui peut être en désaccord avec la pile HTTP.

La solution n'est pas d'apprendre aux évaluateurs tous les cas particuliers de la syntaxe des URL. Il faut créer une description canonique de la requête, l'afficher clairement et faire en sorte que l'exécuteur utilise cette même description. Le schéma, l'hôte, le port effectif, la méthode et le chemin sont le minimum. Les paramètres de requête, les redirections, les en-têtes contrôlés par l'appelant et l'identité du corps doivent souvent apparaître à côté, car ils peuvent modifier l'action tout aussi fortement.

Comment une carte d'approbation obtient un oui

Une carte d'approbation obtient un oui seulement lorsqu'elle décrit l'action réseau dans des termes que l'évaluateur peut vérifier. Un nom d'hôte seul est une affirmation d'identité, pas une description de requête. POST https://billing.example.test/v1/invoices/481/refund en dit bien plus à une personne que billing API ou example.test.

Placez la ligne d'action en premier, dans un ordre fixe :

POST https://billing.example.test/v1/invoices/481/refund

Ajoutez ensuite, juste en dessous, les détails qui modifient le sens :

Authorization: injected from vault entry "billing-production"
Query: dry_run=false
Body: JSON, 214 bytes, sha256: 7b1f...c0a9

Ne placez pas la valeur de l'identifiant, un espace réservé d'autorisation ou le nom convivial d'une intégration à la place de la cible. Ces libellés peuvent aider à reconnaître le contexte, mais ils ne prouvent pas la destination.

La méthode doit figurer sur la première ligne, car elle modifie la conséquence du même chemin. GET /exports/481 et DELETE /exports/481 ne sont pas deux variantes d'une même action. Ce sont des actions différentes qui ne doivent jamais être réduites à une seule étiquette d'approbation.

Le chemin doit aussi figurer sur la première ligne, car le routage des API s'y trouve généralement. Une carte qui affiche seulement api.example.test oblige l'évaluateur à deviner si l'agent consulte un profil, crée un jeton d'accès ou supprime un projet. Une interruption d'approbation ne devrait pas servir à cela.

La canonisation est un contrat d'affichage, pas une règle d'autorisation

La canonisation répond à la question : « Que doit voir une personne pour cette requête analysée ? » Elle ne répond pas à la question : « Quelles destinations sont autorisées ? » Les équipes mélangent souvent ces deux rôles et créent une liste d'autorisation fragile, déguisée en mise en forme conviviale.

Pour une carte d'approbation, créez un enregistrement structuré de la cible après l'analyse :

{
  "method": "POST",
  "scheme": "https",
  "host": "api.example.test",
  "port": 443,
  "port_display": null,
  "path": "/v1/invoices/481/refund",
  "query": "dry_run=false",
  "raw_url": "HTTPS://API.EXAMPLE.TEST:443/v1/invoices/481/refund?dry_run=false"
}

L'exécuteur doit utiliser ces mêmes champs structurés, ou une URL sérialisée à partir de ceux-ci. N'analysez pas l'URL une première fois pour la carte, puis ne transmettez pas la chaîne d'origine à une autre bibliothèque. C'est ainsi qu'un écran de contrôle devient du théâtre.

La RFC 3986 distingue plusieurs catégories de normalisation sûres. Elle considère le schéma et l'hôte comme insensibles à la casse, recommande des chiffres hexadécimaux majuscules dans les échappements en pourcentage et décrit la suppression des segments . et ... Elle avertit aussi que le code doit analyser les composants d'une URI avant de décoder les octets encodés en pourcentage, car un décodage effectué au mauvais moment peut transformer des données en délimiteurs. Cet avertissement relève de l'ingénierie pratique, pas d'un détail théorique.

Conservez un second enregistrement pour l'entrée brute de l'agent. Il doit figurer dans l'activité et dans une vue détaillée lorsqu'une personne doit examiner une requête inhabituelle. Il ne doit pas détourner l'attention de la ligne d'action canonique.

Une règle utile est simple : la carte affiche une description normalisée, le journal conserve la description et l'entrée, et les décisions d'autorisation ne remplacent pas des règles de portée explicites. Ce sont des produits de données distincts.

Analysez d'abord et refusez les entrées que le transport ne peut pas expliquer

Un analyseur d'URL fait partie de la frontière de sécurité dès lors qu'une personne approuve son résultat. Choisissez un comportement d'analyse unique pour les schémas d'URL pris en charge et faites-en la source de vérité pour l'affichage comme pour l'exécution.

Pour les API HTTP ordinaires, refusez les entrées ambiguës au lieu d'essayer de les rendre acceptables. Les références relatives ont besoin d'une URL de base explicite avant d'avoir un hôte. Les fragments ne sont pas envoyés dans une requête HTTP et ne doivent pas donner l'impression d'influencer le serveur. Les informations utilisateur comme https://[email protected]/ sont presque toujours trompeuses dans un flux d'approbation d'API. Il faut les refuser, et non les masquer silencieusement.

Utilisez un pipeline d'analyse avec un point d'échec clair :

1. N'acceptez, pour le canal API sortant, qu'une URL absolue en http ou https.
2. Analysez-la avec l'implémentation d'URL choisie par l'exécuteur de l'action.
3. Refusez les informations utilisateur, l'absence d'hôte, les ports mal formés, les schémas non pris en charge et les échappements en pourcentage invalides.
4. Construisez la requête réelle à partir des composants analysés et des en-têtes approuvés.
5. Affichez la carte à partir de ces composants, puis envoyez exactement cette requête.

Ne faites pas cela avec des découpages de chaînes faits maison. Le premier @, :, /, ? et # n'a pas la même signification dans toutes les positions. Les autorités IPv6 ont besoin de crochets. Un deux-points après un crochet peut introduire un port, tandis que les deux-points à l'intérieur des crochets font partie de l'adresse. Un analyseur connaît cette distinction, contrairement à une courte expression régulière dans la plupart des cas.

Le WHATWG URL Standard définit le comportement d'analyse et de sérialisation des URL, des hôtes, des domaines et des adresses IP. Ses recommandations de sécurité signalent aussi la confusion que le texte bidirectionnel peut créer entre un hôte et un chemin, et conseillent d'afficher uniquement l'hôte dans cette situation. Un produit de sécurité devrait retenir la leçon la plus stricte : séparez visuellement l'autorité du chemin dans chaque carte, et pas seulement pour les chaînes inhabituelles.

Si la couche d'action possède un client personnalisé, vérifiez qu'il est d'accord avec l'analyseur sur un corpus de test. Ne supposez pas que deux bibliothèques éprouvées tolèrent de la même manière les espaces, les antislashs, les noms d'hôte Unicode ou les formes numériques inhabituelles d'adresses IP. Leur accord est une propriété à tester.

Décodez les échappements sans modifier la route

L'encodage en pourcentage crée le type d'URL trompeuse le plus dangereux : celle qui semble anodine après un décodage rapide, mais qui signifie autre chose pour le routeur, le proxy ou le service en amont.

Considérez ces chemins :

/v1/projects/%2E%2E/admin
/v1/projects/%252E%252E/admin
/v1/files/report%2Ffinal

Le premier contient des points encodés en pourcentage. Le deuxième contient un signe pourcentage encodé suivi de 2E, ce qui n'est pas la même entrée. Le troisième contient une barre oblique encodée dans un seul segment de chemin. Si la couche d'affichage décode les trois à répétition jusqu'à obtenir une ponctuation lisible, elle peut afficher une structure de chemin que le client n'a pas envoyée.

La RFC 3986 définit un cas sûr limité : les échappements correspondant à des caractères non réservés peuvent être décodés pendant la normalisation. Les caractères non réservés sont les lettres, les chiffres, le trait d'union, le point, le trait de soulignement et le tilde. Les caractères réservés comme /, ?, #, @ et : doivent rester encodés lorsque leur décodage modifierait les limites des composants ou les délimiteurs. La RFC précise aussi qu'une implémentation ne doit pas encoder ou décoder la même chaîne plus d'une fois.

Cela donne une bonne règle d'affichage :

Raw path:       /v1/%75sers/alice%7Eops/report%2Ffinal
Card path:      /v1/users/alice~ops/report%2Ffinal
Wire path:      /v1/users/alice~ops/report%2Ffinal

La carte rend %75 et %7E lisibles, car ils représentent des caractères non réservés. Elle conserve %2F, car une barre oblique modifierait la structure des segments du chemin. La forme affichée et la forme transmise peuvent différer sans danger, mais elles doivent garder le même sens de routage.

Ne supprimez pas les segments . et .. après avoir décodé le chemin sans distinction. Analysez le chemin selon sa structure encodée, appliquez une procédure de normalisation définie et conservez les échappements qui transportent des caractères réservés comme données. Si le service en aval applique un ordre de décodage différent, c'est un problème de compatibilité et de sécurité à exposer dans les tests, et non une raison de laisser la carte deviner.

Un nom d'hôte ne constitue pas toute l'autorité

L'autorité d'une cible HTTP comprend l'hôte et, lorsqu'il n'est pas celui par défaut, le port. Omettre le port fait mentir la carte par omission.

Traitez ces cibles comme distinctes :

https://api.example.test/v1/keys
https://api.example.test:8443/v1/keys
http://api.example.test/v1/keys

La première utilise normalement le port 443. La deuxième utilise le port 8443. La troisième utilise un autre schéma et normalement le port 80. Un évaluateur peut accepter un appel d'API de production en HTTPS et refuser une requête vers un écouteur de test sur un port personnalisé. La carte doit lui permettre de prendre cette décision.

Mettez le schéma et le nom d'hôte en minuscules. N'affichez pas le port uniquement lorsqu'il est celui par défaut du schéma analysé : 80 pour http, 443 pour https. Ne le masquez pas parce qu'un enregistrement DNS mène par hasard vers un endroit familier.

Les noms de domaine internationalisés demandent la même attention. Une forme Unicode lisible par une personne peut être plus facile à comprendre, tandis que la forme transmise par le DNS utilise des étiquettes ASCII. Si vous affichez l'Unicode, affichez aussi la forme ASCII dans les détails et utilisez un analyseur qui applique un algorithme défini de traitement des hôtes. N'inventez pas votre propre conversion Punycode et ne comparez pas des chaînes d'affichage pour décider de leur équivalence.

Les littéraux IP méritent un traitement spécifique. Affichez les adresses IPv6 entre crochets, conservez les ports non standard et indiquez qu'il s'agit d'une adresse IP littérale. Une requête vers https://[2001:db8::9]/v1/keys ne doit pas ressembler à un service de production nommé simplement parce qu'un agent a fourni un alias agréable dans un champ de note.

Les alias posent un autre problème. api.internal, api et 10.0.0.9 peuvent aboutir aujourd'hui au même serveur, puis diverger après une modification DNS. Ne réécrivez pas silencieusement l'un en l'autre pour l'approbation. Affichez l'autorité analysée que le client a demandée. Si le système résout le DNS avant d'ouvrir la connexion, affichez l'adresse choisie comme contexte de connexion et enregistrez-la dans la piste d'audit. L'autorité reste l'élément nommé par la requête HTTP.

HTTP rend cette distinction explicite. La RFC 9110 indique que le champ Host fournit les informations d'hôte et de port de l'URI cible, tandis que HTTP/2 et HTTP/3 peuvent transporter ces informations dans :authority. La RFC 9113 précise qu'un intermédiaire qui génère Host à partir de l'autorité HTTP/2 doit utiliser :authority, sauf s'il modifie la cible de la requête. Une carte doit donc traiter un champ d'autorité fourni par l'appelant comme une donnée de routage, et non comme une métadonnée décorative.

La méthode et le chemin méritent une importance visuelle propre

Placez la méthode HTTP, l'autorité et le chemin ensemble, car les évaluateurs lisent l'action comme une phrase. Donnez ensuite à la méthode et aux segments de chemin dangereux suffisamment de contraste pour qu'un coup d'œil ne les réduise pas à une longue URL.

Cette disposition fonctionne parce qu'elle conserve un ordre stable :

DELETE
https://api.example.test/v1/projects/acme/production

Pour une requête qui modifie un objet, incluez son identifiant dans le chemin visible. Tronquer la fin de /v1/projects/acme/production pour faire tenir la carte revient à faire l'inverse de ce qu'il faut. Si l'espace manque, tronquez d'abord les longues valeurs de requête ou les aperçus du corps, jamais le dernier segment du chemin qui identifie la cible.

La casse doit être conservée dans le chemin. La RFC 3986 indique que la syntaxe URI générique traite les composants autres que le schéma et l'hôte comme sensibles à la casse, sauf indication contraire du schéma. De nombreux frameworks acheminent les chemins en respectant la casse, même lorsqu'une API donnée ne le fait pas. Transformer /Admin/DeleteUser en /admin/deleteuser revient à décrire une requête qui n'a jamais été envoyée.

Un chemin peut aussi sembler anodin alors que sa requête modifie l'effet :

POST https://api.example.test/v1/invoices/481/refund?dry_run=false
POST https://api.example.test/v1/invoices/481/refund?dry_run=true

Affichez un résumé court de la requête sous la ligne d'action lorsque ses paramètres modifient la portée, le comportement ou l'identité. Pour les requêtes non structurées ou très longues, affichez la requête encodée complète dans une zone de détails dépliable, ainsi qu'un résumé décodé et expurgé dans la carte principale. Ne décodez jamais un jeton en secret lisible uniquement parce que la carte veut être conviviale.

Le corps de la requête peut être encore plus important que le chemin. Une approbation pour PATCH /v1/users/alice dit peu de choses si le corps peut accorder un rôle d'administrateur. Affichez au minimum le type de contenu, la longueur en octets et une empreinte stable. Pour les formats structurés comme JSON, un petit aperçu des champs modifiés peut aider, à condition qu'il provienne des mêmes octets que ceux envoyés sur le réseau. Réencoder un objet pour l'affichage après avoir signé ou haché une autre séquence d'octets crée le même problème de divergence que la réanalyse des URL.

Les en-têtes et les redirections peuvent modifier la destination

Une URL canonique ne suffit pas si un autre champ de la requête peut orienter la connexion. La carte doit soit limiter ces champs, soit afficher leur effet.

Commencez par Host et :authority. Un client HTTP les dérive normalement de l'URL cible. Si une interface d'action permet à l'appelant de les remplacer, refusez cette modification, sauf si le transport a une raison documentée de la prendre en charge. Si vous la prenez en charge, la ligne d'approbation doit afficher à la fois la destination de connexion et l'autorité demandée, dans des termes que la personne peut comparer.

La configuration du proxy mérite le même traitement. Un proxy modifie le pair immédiat, mais pas nécessairement la cible d'origine. Ne remplacez pas l'origine par l'adresse du proxy sur la carte. Affichez l'origine comme l'action approuvée et le proxy comme contexte de transport. Si le proxy peut réécrire les champs de destination, traitez-le comme un composant de l'exécuteur, avec des tests, une journalisation et une décision de confiance distincte.

Les redirections sont de nouvelles actions lorsque leur cible change. Un POST peut devenir un GET selon le comportement de redirection, ou être renvoyé vers une nouvelle autorité. L'approbation d'origine ne doit couvrir que la cible d'origine. Avant de suivre une redirection, analysez la valeur Location`, construisez la prochaine requête proposée, comparez son schéma, son autorité, sa méthode, son chemin, sa requête et le comportement de son corps, puis demandez une nouvelle approbation si un changement important apparaît.

Évitez le raccourci courant qui consiste à approuver un « site » pour la durée d'une exécution et à considérer toutes les redirections en dessous comme inoffensives. C'est moins intrusif, mais cela transforme l'analyse des URL et la politique de redirection en extension invisible des privilèges. Si l'exécution a besoin d'une autorisation large, indiquez explicitement cette portée dans le texte de l'approbation, au lieu de laisser les redirections l'introduire discrètement.

Placez l'entrée brute dans le journal, pas dans la ligne de décision

Une piste d'audit doit permettre de répondre à deux questions distinctes : qu'a demandé l'agent et qu'a tenté l'exécuteur ? Une seule chaîne URL ne peut pas toujours répondre aux deux.

Enregistrez exactement la chaîne URL brute reçue, sous réserve des règles de masquage des secrets. Enregistrez séparément la cible canonique. Ajoutez l'autorité finale de connexion et l'adresse résolue si l'exécuteur a effectué une résolution. Pour HTTP/2 ou HTTP/3, enregistrez la valeur effective de :authority ; pour HTTP/1.1, enregistrez la valeur effective de Host. Enregistrez chaque étape de redirection comme une requête tentée distincte, et non comme une note en bas de la première.

Une entrée de journal peut avoir cette forme :

{
  "request_id": "req_01J...",
  "agent_input_url": "HTTPS://API.EXAMPLE.TEST:443/v1/%75sers/alice%7Eops",
  "approved_target": "GET https://api.example.test/v1/users/alice~ops",
  "effective_authority": "api.example.test",
  "effective_port": 443,
  "connection_ip": "203.0.113.42",
  "result": "200"
}

L'exemple utilise une plage d'adresses réservée à la documentation pour l'adresse IP de connexion. Dans un journal réel, protégez les secrets de requête, les données d'autorisation et les corps sensibles avant qu'ils n'atteignent un enregistrement conservé longtemps. Une empreinte permet de relier le contenu approuvé au contenu exécuté sans recopier les charges privées dans chaque écran.

La distinction entre entrée brute et cible canonique est précieuse pendant une enquête. Si une carte affichait un chemin normal, mais que l'entrée brute contenait plusieurs couches d'encodage, vous pouvez déterminer si l'analyseur, l'affichage ou le client HTTP était en désaccord. Si vous n'avez conservé qu'une URL embellie, vous avez supprimé les éléments nécessaires pour trouver le défaut.

Le journal Activity et le journal Sessions de Sallyport sont générés à partir d'un journal d'audit chiffré et chaîné par hachage. La représentation d'une cible doit donc être écrite une seule fois dans l'enregistrement de l'action, et non reconstruite plus tard à partir de chaînes de l'interface. Sa vérification hors ligne avec sp audit verify n'est utile que si les champs de l'action enregistrés étaient exacts au moment de l'exécution.

Testez les désaccords que les URL ordinaires ne révèlent jamais

Les tests unitaires importants ne sont pas dix exemples ordinaires de https://api.example.test/v1/users. Ce sont les cas où une chaîne brute, un affichage et une bibliothèque de transport pourraient diverger.

Construisez un corpus piloté par table qui vérifie les champs analysés, la cible visible, la cible transmise et la décision. Incluez au moins les familles suivantes :

• variations de casse du schéma et de l'hôte, avec des ports par défaut et non standard ;
• segments . et .. et échappements en pourcentage pour les caractères réservés et non réservés ;
• signes pourcentage et barres obliques encodés, ainsi que séquences d'échappement mal formées ;
• littéraux IPv6, hôtes Unicode et informations utilisateur qui doivent être refusées ;
• paramètres de requête qui modifient le comportement de l'action, ainsi que des redirections vers une autre autorité.

Un cas de test doit rendre la représentation attendue explicite :

{
  "input": "HTTPS://API.EXAMPLE.TEST:443/v1/%75sers/alice%7Eops?role=viewer",
  "decision": "approve",
  "card": "GET https://api.example.test/v1/users/alice~ops?role=viewer",
  "wire_url": "https://api.example.test/v1/users/alice~ops?role=viewer"
}

Ajoutez ensuite les cas négatifs qui doivent échouer avant l'approbation :

{
  "input": "https://[email protected]/v1/users",
  "decision": "reject",
  "reason": "userinfo is not supported for outbound API actions"
}

Faites passer le corpus dans le code client exact qui ouvre la connexion. Une suite de tests limitée à l'analyseur détecte les erreurs d'affichage, mais pas les comportements du transport, comme une bibliothèque qui normalise un chemin vide, injecte une autorité par défaut ou applique ses propres règles de redirection.

Enfin, testez l'interface comme l'utilise un évaluateur. Vérifiez que la méthode complète, l'hôte, le port lorsqu'il est présent et le dernier segment du chemin restent visibles dans des fenêtres de taille courante. Le texte de sécurité échoue lorsque la personne doit survoler, développer ou faire défiler l'écran pour découvrir qu'une requête supprime des données de production. La carte doit rendre la différence importante visible avant que le bouton d'approbation ne reçoive le focus.

Une approbation humaine peut être un contrôle solide, mais elle ne sera jamais plus fiable que la description de la requête présentée à la personne. Construisez cette description à partir de composants analysés, exécutez ces composants, conservez l'entrée brute pour un examen ultérieur et refusez l'ambiguïté au lieu de la décorer.