davidgin/web-bot-auth

Vérification Web Bot Auth

Cette compétence ajoute la vérification du trafic signé par un agent à un service existant. La partie difficile n'est pas la cryptographie ; ce sont les petits détails qui peuvent donner à une signature moins de valeur qu'il n'y paraît : des composants non signés, un nonce réutilisé, un en-tête qui déclenche un fetch, une URL reconstruite différemment de ce que le client a signé. Le code de référence et les tests ici encodent ces détails. Votre travail consiste à les intégrer dans la pile de l'utilisateur sans les affaiblir.

Statut de la spécification : cible draft-meunier-web-bot-auth-architecture-05 (un Internet-Draft IETF, pas une norme) et accepte l'en-tête Signature-Agent historique au format quoted-string que de nombreux agents déployés envoient encore. Dites à l'utilisateur qu'il s'agit d'un brouillon et qu'il peut changer.

Workflow

1. Trouvez le point d'entrée de la requête. Identifiez le framework et l'endroit où les requêtes entrent (middleware, gestionnaire en périphérie, hook de proxy inverse). Notez si le service se trouve derrière un proxy ou un CDN, car cela détermine comment reconstruire l'URL (voir references/adapters.md).

2. Définissez les décisions de politique avec l'utilisateur. Lisez references/policy-decisions.md et demandez tout ce que la conversation n'a pas encore tranché : quels opérateurs autoriser dans la liste blanche, s'il faut exiger la liaison de requête et les nonces, le stockage des nonces, et ce que chaque résultat doit faire. Ne choisissez pas silencieusement des paramètres stricts : les réglages stricts par défaut rejettent la plupart des agents déployés aujourd'hui. Ne choisissez pas non plus silencieusement des paramètres laxistes : dites ce qu'ils laissent ouverts.

3. Ajoutez le vérificateur.

   • Python : copiez scripts/web_bot_auth.py dans le projet sans modification (gardez son en-tête de licence), ajoutez cryptography aux dépendances, et écrivez un petit adaptateur qui construit un Request.
   • Autres langages : portez scripts/web_bot_auth.py, en utilisant la bibliothèque Ed25519 établie du langage (jamais une bibliothèque faite maison), et un analyseur de champs structurés RFC 8941 maintenu s'il en existe un. Le portage n'est pas terminé tant qu'il ne réussit pas tous les cas de assets/test-vectors.json.

4. Écrivez l'adaptateur avec soin. C'est là que la plupart des intégrations cassent. Le Request doit transporter la méthode telle qu'envoyée, l'URL absolue telle que demandée par le client, chaque occurrence d'en-tête, et les octets bruts du corps avant analyse ou décompression. Voir references/adapters.md pour les notes par framework.

5. Choisissez le stockage des nonces. En mémoire uniquement pour un processus unique. Tout ce qui a plus d'un worker ou d'un nœud a besoin d'un stockage partagé et fortement cohérent. Voir references/nonce-stores.md.

6. Mappez les résultats en actions. Utilisez le tableau ci-dessous sauf si l'utilisateur a décidé autrement.

7. Testez l'intégration de bout en bout. Écrivez des tests via le framework réel (son client de test) en utilisant sign_request pour produire des requêtes signées : une requête valide, un corps modifié, un rejeu, et une requête expirée. Exécutez aussi scripts/test_web_bot_auth.py si le fichier a été copié.

8. Recommandez un déploiement en mode log uniquement. Enregistrez outcome, reason, operator, keyid, binds_request et replay_protected pour chaque requête pendant une période avant d'appliquer quoi que ce soit.

Résultats

Résultat	Signification	Action par défaut
unsigned	Aucune signature web-bot-auth	Gestion existante des bots / scoring des risques
verified	Signature valide, opérateur autorisé (liste blanche)	Admettre comme cet agent ; appliquer toujours l'authentification par utilisateur et les limites de taux
signed_untrusted	Signature valide, opérateur connu mais pas autorisé	Traiter comme non signé, éventuellement avec un risque moindre
unknown_operator	Bien formé, mais aucune clé disponible	Traiter comme non signé ; éventuellement mettre en file d'attente une récupération de répertoire en arrière-plan
invalid	Présent et incorrect	Bloquer. Les clients légitimes n'envoient pas de signatures cassées
expired	Hors de sa fenêtre temporelle	Bloquer
replay	Nonce déjà utilisé	Bloquer

Result.hostile est vrai pour les trois derniers. Pour verified, vérifiez aussi deux indicateurs. Si binds_request est faux, la signature ne couvre pas la méthode, le chemin, la requête et le corps. Si replay_protected est faux, il n'y avait pas de nonce ou le stockage était indisponible. Un défaut raisonnable est d'admettre les requêtes vérifiées avec l'un ou l'autre indicateur faux uniquement pour les méthodes sûres (GET, HEAD).

Règles faciles à enfreindre

Ces règles existent car chacune a une attaque concrète derrière elle. Si les contraintes de l'utilisateur semblent nécessiter d'en enfreindre une, expliquez le risque et laissez-les décider.

• Ne récupérez jamais un répertoire de clés en ligne pour un opérateur qui n'est pas sur la liste blanche. Signature-Agent est contrôlé par l'attaquant, donc récupérer ce qu'il nomme est une SSRF et permet à quiconque de bloquer votre chemin de requête. Récupérez les opérateurs inconnus dans un job d'arrière-plan avec safe_fetch_directory, ou pas du tout.
• Vérifiez Content-Digest par rapport au corps chaque fois qu'il est couvert. Signer l'en-tête ne sert à rien si personne ne vérifie qu'il correspond aux octets reçus.
• Enregistrez le nonce uniquement après que la signature est vérifiée. Sinon, n'importe qui peut remplir le stockage, ou brûler les nonces d'un agent légitime à l'avance.
• Utilisez un stockage de nonces atomique et partagé entre les instances. Un cache par processus permet à un rejeu d'atterrir sur un worker différent.
• Limitez la fraîcheur par created, pas seulement par expires. Les agents peuvent signer avec de longues expirations ; Policy.max_age garde la fenêtre de rejeu et le cache de nonces petits indépendamment.
• Reconstruisez l'URL que le client a réellement demandée. Derrière un proxy, utilisez le schéma et l'hôte transférés uniquement provenant de proxies de confiance. Si vous vous trompez, les signatures valides échouent à la vérification, ou un en-tête d'hôte usurpé est pris pour argent comptant.
• Une signature vérifiée identifie l'opérateur, pas l'utilisateur. Gardez l'authentification normale, l'autorisation par utilisateur et les limites de taux derrière elle. Ne laissez jamais une signature remplacer le consentement de l'utilisateur pour des actions sensibles.
• N'appliquez pas de vérifications de comportement humain aux agents vérifiés. Ils sont de l'automatisation par conception.

Fichiers

• scripts/web_bot_auth.py : le vérificateur, les résolveurs de clés, les stockages de nonces et sign_request. Un seul fichier ; dépend uniquement de cryptography.
• scripts/test_web_bot_auth.py : tests de cas d'attaque plus le vecteur de conformité RFC 9421 Annexe B.2.6. Lancez avec python -m unittest -v test_web_bot_auth depuis scripts/.
• scripts/generate_vectors.py : régénère assets/test-vectors.json.
• assets/test-vectors.json : vecteurs neutres en langage pour les portages (clés de test uniquement).
• references/policy-decisions.md : les choix à faire avec l'utilisateur, avec les compromis. Lire à l'étape 2.
• references/adapters.md : construction correcte de Request dans les frameworks courants et derrière les proxys. Lire à l'étape 4.
• references/nonce-stores.md : quels stockages sont sûrs et comment les dimensionner. Lire à l'étape 5.