davidgin/web-bot-auth

Web-Bot-Auth-Verifikation

Diese Fähigkeit fügt die Verifikation von signiertem Agentenverkehr zu einem bestehenden Dienst hinzu. Der schwierige Teil ist nicht die Kryptographie; es sind die kleinen Details, die eine Signatur weniger bedeutend erscheinen lassen, als sie ist: unsignierte Komponenten, ein wiederverwendeter Nonce, ein Header, der einen Fetch auslöst, eine URL, die anders wiederhergestellt wird als vom Client signiert. Der Referenzcode und die Tests hier kodieren diese Details. Deine Aufgabe ist es, sie in den Stack des Benutzers einzubinden, ohne sie zu schwächen.

Spezifikationsstatus: Ziel ist draft-meunier-web-bot-auth-architecture-05 (ein IETF-Internet-Entwurf, kein Standard) und akzeptiert den veralteten quoted-string Signature-Agent, den viele bereitgestellte Agenten immer noch senden. Sage dem Benutzer, dass es ein Entwurf ist und sich ändern kann.

Arbeitsablauf

1. Finde den Anfrage-Einstiegspunkt. Identifiziere das Framework und wo Anfragen eintreten (Middleware, Edge-Handler, Reverse-Proxy-Hook). Beachte, ob der Dienst hinter einem Proxy oder CDN sitzt, denn das bestimmt, wie die URL wiederhergestellt wird (siehe references/adapters.md).

2. Klärung der Richtlinienentscheidungen mit dem Benutzer. Lese references/policy-decisions.md und frage nach allem, was das Gespräch noch nicht geklärt hat: welche Operatoren auf die Whitelist gesetzt werden sollen, ob Request-Binding und Nonces erforderlich sind, der Nonce-Speicher und was jedes Ergebnis tun soll. Wähle nicht stillschweigend strenge Einstellungen: strenge Standards lehnen die meisten heute bereitgestellten Agenten ab. Wähle auch nicht stillschweigend lockere Einstellungen: sage, was sie offen lassen.

3. Füge den Verifikator hinzu.

   • Python: Kopiere scripts/web_bot_auth.py unverändert in das Projekt (behalte seinen Lizenzheader), füge cryptography zu den Abhängigkeiten hinzu und schreibe einen kleinen Adapter, der eine Request erstellt.
   • Andere Sprachen: Portiere scripts/web_bot_auth.py unter Verwendung der etablierten Ed25519-Bibliothek der Sprache (niemals eine selbstgebaute) und eines gepflegten RFC-8941-Structured-Field-Parsers, falls vorhanden. Der Port ist erst fertig, wenn er jeden Fall in assets/test-vectors.json besteht.

4. Schreibe den Adapter sorgfältig. Hier brechen die meisten Integrationen. Die Request muss die gesendete Methode, die absolute URL, wie vom Client angefordert, jedes Header-Vorkommen und die rohen Körper-Bytes vor dem Parsen oder Dekomprimieren enthalten. Siehe references/adapters.md für frameworkspezifische Hinweise.

5. Wähle den Nonce-Speicher. Nur im Arbeitsspeicher für einen einzelnen Prozess. Alles mit mehr als einem Worker oder Knoten benötigt einen gemeinsamen, stark konsistenten Speicher. Siehe references/nonce-stores.md.

6. Ordne Ergebnisse Aktionen zu. Verwende die folgende Tabelle, es sei denn, der Benutzer hat etwas anderes entschieden.

7. Teste die Integration End-to-End. Schreibe Tests mit dem echten Framework (seinem Test-Client), die sign_request verwenden, um signierte Anfragen zu erzeugen: eine gültige Anfrage, einen manipulierten Körper, einen Replay und eine abgelaufene Anfrage. Führe auch scripts/test_web_bot_auth.py aus, wenn die Datei kopiert wurde.

8. Empfehle einen reinen Log-Rollout. Protokolliere outcome, reason, operator, keyid, binds_request und replay_protected für jede Anfrage für einen Zeitraum, bevor du etwas durchsetzt.

Ergebnisse

Ergebnis	Bedeutung	Standardaktion
unsigned	Keine web-bot-auth-Signatur	Vorhandene Bot-Behandlung / Risikobewertung
verified	Gültige Signatur, erlaubter Operator	Als diesen Agenten zulassen; dennoch benutzerspezifische Authentifizierung und Ratenbegrenzungen anwenden
signed_untrusted	Gültige Signatur, bekannter, aber nicht erlaubter Operator	Als unsigned behandeln, optional mit geringerem Risiko
unknown_operator	Wohlgeformt, aber kein Schlüssel verfügbar	Als unsigned behandeln; optional einen Hintergrund-Verzeichnisabruf in die Warteschlange stellen
invalid	Vorhanden und falsch	Blockieren. Legitime Clients senden keine kaputten Signaturen
expired	Außerhalb seines Zeitfensters	Blockieren
replay	Nonce bereits verwendet	Blockieren

Result.hostile ist für die letzten drei wahr. Überprüfe für verified auch zwei Flags. Wenn binds_request falsch ist, deckt die Signatur nicht die Methode, den Pfad, die Abfrage und den Körper ab. Wenn replay_protected falsch ist, gab es keinen Nonce oder der Speicher war nicht verfügbar. Eine sinnvolle Voreinstellung ist, verifizierte Anfragen mit einem der beiden Flags auf false nur für sichere Methoden (GET, HEAD) zuzulassen.

Regeln, die leicht zu brechen sind

Diese existieren, weil hinter jeder ein konkreter Angriff steckt. Wenn die Einschränkungen des Benutzers zu erfordern scheinen, eine zu brechen, erkläre das Risiko und lass ihn entscheiden.

• Rufe niemals ein Schlüsselverzeichnis inline für einen Operator ab, der nicht auf der Whitelist steht. Signature-Agent wird vom Angreifer kontrolliert, daher ist das Abrufen dessen, was es benennt, SSRF und kann jedem erlauben, deinen Anforderungspfad zu blockieren. Rufe unbekannte Operatoren in einem Hintergrundjob mit safe_fetch_directory ab, oder gar nicht.
• Überprüfe Content-Digest gegen den Körper, wann immer er abgedeckt ist. Das Signieren des Headers ist bedeutungslos, wenn niemand überprüft, ob er mit den empfangenen Bytes übereinstimmt.
• Zeichne den Nonce erst auf, nachdem die Signatur verifiziert wurde. Sonst kann jeder den Speicher füllen oder die Nonces eines legitimen Agenten im Voraus verbrauchen.
• Verwende einen gemeinsamen, atomaren Nonce-Speicher über Instanzen hinweg. Ein prozessspezifischer Cache erlaubt es, dass ein Replay auf einem anderen Worker landet.
• Begrenze die Aktualität durch created, nicht nur durch expires. Agenten können mit langen Ablaufzeiten signieren; Policy.max_age hält das Replay-Fenster und den Nonce-Cache unabhängig davon klein.
• Stelle die URL wieder her, die der Client tatsächlich angefordert hat. Hinter einem Proxy verwende das weitergeleitete Schema und den Host nur von Proxys, denen du vertraust. Wenn du es falsch machst, schlagen gültige Signaturen bei der Verifikation fehl, oder ein gefälschter Host-Header wird vertrauenswürdig.
• Eine verifizierte Signatur identifiziert den Operator, nicht den Benutzer. Behalte die normale Authentifizierung und benutzerspezifische Autorisierung und Ratenbegrenzungen dahinter. Lasse niemals zu, dass eine Signatur für die Benutzereinwilligung bei sensiblen Aktionen steht.
• Wende keine menschlichen Verhaltensprüfungen auf verifizierte Agenten an. Sie sind von Natur aus Automatisierung.

Dateien

• scripts/web_bot_auth.py: der Verifikator, Schlüsselauflöser, Nonce-Speicher und sign_request. Einzelne Datei; hängt nur von cryptography ab.
• scripts/test_web_bot_auth.py: Angriffsfalltests plus der RFC-9421-Anhang-B.2.6-Konformitätsvektor. Ausführen mit python -m unittest -v test_web_bot_auth aus scripts/.
• scripts/generate_vectors.py: Generiert assets/test-vectors.json neu.
• assets/test-vectors.json: Sprachneutrale Vektoren für Portierungen (nur Testschlüssel).
• references/policy-decisions.md: Die Entscheidungen, die mit dem Benutzer zu treffen sind, mit Kompromissen. Lesen in Schritt 2.
• references/adapters.md: Korrektes Erstellen einer Request in gängigen Frameworks und hinter Proxys. Lesen in Schritt 4.
• references/nonce-stores.md: Welche Speicher sicher sind und wie man sie dimensioniert. Lesen in Schritt 5.