Zugriffstests für Agenten-APIs vor dem Produktions-Rollout

Ein Agent verdient Produktionszugriff auf eine API nicht dadurch, dass er in einer Sandbox eine erfolgreiche Antwort liefert. Entscheidend ist, ob er sich korrekt verhält, wenn eine Anfrage abgelehnt, fehlerhaft, langsam oder gefährlich ist. Eine freundliche Demo verdeckt die Fehler, auf die es ankommt: eine Genehmigung für den falschen Prozess, ein Token im Protokoll des Agenten, eine Wiederholungsschleife, die ein Ratenlimit überlastet, oder ein Journal, das nicht erklären kann, wer einen destruktiven Aufruf genehmigt hat.

Testen Sie den gesamten Aktionsweg gegen ein Ziel außerhalb der Produktion, bevor Sie einem Agenten eine Produktionsfähigkeit geben. Dazu gehören die Anfrage des Agenten, die Autorisierung, die Injektion der Zugangsdaten, die Antwort der entfernten API, die Interpretation eines Fehlers durch den Agenten und eine Aufzeichnung jedes Aufrufs, die über die Sitzung hinaus erhalten bleibt. Fehlt ein Teil, haben Sie einen API-Client getestet, keinen autonomen Akteur.

Ein Nichtproduktions-Endpunkt muss auf eine Weise getrennt sein, die im Fehlerfall zählt

Ein brauchbarer Test-Endpunkt hat eigene Zugangsdaten, eigene Daten und eine Schadensgrenze, die Sie in einem Satz erklären können. Ein Produktions-Hostname mit einem Abfrageparameter, der angeblich den Testmodus aktiviert, reicht nicht aus, wenn dasselbe Token weiterhin Kundendaten lesen oder Geld ausgeben kann.

Nutzen Sie eine Sandbox des Anbieters, wenn sie ein isoliertes Konto und Testzugangsdaten bietet. Verwenden Sie einen eigenen Mandanten, wenn der Dienst keine Sandbox hat. Falls beides nicht möglich ist, stellen Sie einen kleinen Dienst unter Ihrer Kontrolle unter einem anderen Hostnamen bereit und verwenden Sie darin wegwerfbare Daten. Es geht nicht um eine Bezeichnung wie Staging. Entscheidend ist, dass eine versehentliche Anfrage weder Nutzer in der Produktion noch Produktionsguthaben oder Geheimnisse beeinflussen kann.

Der Endpunkt sollte beweisen, dass er außerhalb der Produktion liegt. Geben Sie in jeder erfolgreichen Antwort ein eindeutig erkennbares Umgebungsfeld zurück und lassen Sie destruktive Routen ausschließlich in ein Testbuch schreiben. Eine Antwort wie diese verhindert, dass ein Operator einen grünen Test mit einer Änderung in der Produktion verwechselt:

{
  "environment": "test",
  "request_id": "req_7f1a",
  "status": "accepted",
  "resource_id": "demo-order-184"
}

Die Testdaten sollten realistisch genug sein, um Seitennavigation, fehlende Felder, Berechtigungen und Konflikte zu prüfen. Ein einzelner perfekter Datensatz bringt einem Agenten schlechte Gewohnheiten bei. Legen Sie einige Datensätze an, die er lesen darf, einen, den er ändern darf, und einen, auf den er niemals zugreifen darf. Sie brauchen keine riesige Testsammlung. Es reichen genügend Unterschiede, um Code zu entlarven, der jede Antwort als vollständig und fehlerfrei voraussetzt.

Verwenden Sie aus Bequemlichkeit niemals ein Produktions-Bearer-Token in einer Testumgebung. Ich habe erlebt, dass Teams dies als vorübergehende Abkürzung bezeichneten und es dann beibehielten, weil jede Folgeaufgabe dringender erschien. Eine Testidentität sollte einen Namen, einen Verantwortlichen, ein Ablaufdatum und genau die Berechtigungen haben, die zu den konkreten Testfällen passen. Wenn niemand sagen kann, welcher Test eine Berechtigung benötigt, entfernen Sie sie.

Der erste Lauf sollte die Autorisierungsgrenze testen, nicht die API

Bevor Sie das fachliche Verhalten prüfen, weisen Sie nach, dass ein unbekannter Agentenprozess nicht unbemerkt handeln kann. Starten Sie einen neuen Agentenprozess und lassen Sie ihn einen harmlosen Lesevorgang gegen den Test-Endpunkt versuchen. Erwartet wird ein Autorisierungsereignis, bevor die API-Anfrage abgesendet wird.

Dabei wird ein Unterschied sichtbar, den Teams oft verwischen: Die Genehmigung durch den Benutzer ist nicht dasselbe wie die Genehmigung des Prozesses. Ein Operator kann seinem eigenen Terminal vertrauen, aber einem Plugin, einem kopierten Skript oder einem Agenten aus einer anderen Anwendung misstrauen. Die Genehmigungsoberfläche sollte dem Operator zeigen, welches ausführbare Programm handeln möchte. Eine Schaltfläche mit der Aufschrift «Erlauben» ohne diesen Kontext fordert Menschen auf, einem unbekannten Prozess zu vertrauen.

Halten Sie bei diesem Test vier Beobachtungen fest:

• Der neue Prozess erhält vor dem externen Aufruf eine Genehmigungsanfrage.
• Die Genehmigung identifiziert den Prozess so, dass ein Operator ihn erkennen kann.
• Die Genehmigung gilt nur für den vorgesehenen Lauf, nicht für jeden späteren Prozess.
• Beim Beenden des Prozesses wird die Sitzungsautorisierung entfernt.

Lehnen Sie die Anfrage einmal ab, bevor Sie sie genehmigen. Die Ablehnung muss dem Agenten ein brauchbares Fehlersignal geben, nicht einen erfundenen Erfolg. Gute Anweisungen für Agenten legen fest, was nach einer Ablehnung zu tun ist: Vorgang stoppen, melden, dass die Genehmigung verweigert wurde, und keinen zweiten Weg zum selben Endpunkt suchen.

Starten Sie den Agenten anschließend neu und wiederholen Sie den harmlosen Lesevorgang. Wenn der zweite Prozess die Berechtigung des ersten übernimmt, klären Sie den Grund. Eine zwischengespeicherte Autorisierung wirkt in einer Demo oft effizient. Nach einem Update des Agenten oder wenn ein anderer Starter denselben Befehl ausführt, wird sie jedoch zu einer stillen Berechtigungsvergabe.

Sallyport aktiviert die Genehmigung für Sitzungen standardmäßig und zeigt beim ersten Aufruf eines neuen Agentenprozesses dessen Code-Signierungsautorität an. Genau hier sollten Sie die menschliche Entscheidung testen, bevor eine Anfrage mit Zugangsdaten den externen Dienst erreicht.

Für die Injektion von Zugangsdaten muss nachgewiesen werden, dass der Agent das Geheimnis nie besaß

Die Injektion von Zugangsdaten ist nur dann erfolgreich, wenn der Agent eine Aktion anfordern kann, ohne die dafür verwendeten Zugangsdaten abzurufen. Ein Token in der Konsolenausgabe zu maskieren ist kein Schutz. Ein Token, das in eine Umgebungsvariable, eine Tool-Antwort, einen Prompt, einen Shell-Verlauf oder eine lokale Datei gelangt ist, war für den Agenten verfügbar, auch wenn es niemand ausgegeben hat.

Richten Sie ein Testzugangsmittel ein, das der entfernte Dienst erkennen kann, ohne seinen Wert offenzulegen. Viele APIs bieten eine Tokenbezeichnung, eine Client-ID oder ein Audit-Feld. Falls Ihre API das nicht kann, erstellen Sie eine Testroute, die die vom Dienst erkannte Identität des Zugangsmittels zurückgibt, nicht das Zugangsmittel selbst. Das Ergebnis sollte zeigen, welche Testidentität den Aufruf authentifiziert hat.

Für eine API mit Bearer-Token hat die Anfrage auf Leitungsebene meist diese Form:

GET /v1/test/projects/demo HTTP/1.1
Host: api.test.example
Authorization: Bearer [injected outside the agent]
Accept: application/json

Der Text in eckigen Klammern dient der Dokumentation und ist kein Wert, den der Agent einsetzen soll. Ein Agent sollte Methode, Ziel und erlaubte Anfrageargumente liefern. Erst nach der Genehmigungsentscheidung fügt der Handler für Zugangsdaten den Authorization-Header hinzu. Für Basic Authentication und benutzerdefinierte Header-Schemata gilt derselbe Test, denn fehlerhafte Konfigurationen zeigen sich dort an unterschiedlichen Stellen.

Prüfen Sie das Protokoll des Agenten, den Verlauf der Tool-Anfragen, die dem Agenten zugängliche Shell-Umgebung und alle während des Laufs erstellten Dateien. Suchen Sie sowohl nach dem wörtlichen Token als auch nach indirekten Leaks, etwa einem Anfrageobjekt mit Authorization-Header. Eine nachträgliche Schwärzung repariert kein Design, das dem Prozess das Geheimnis bereits übergeben hat.

Rotieren Sie anschließend das Testzugangsmittel und führen Sie dieselbe Anfrage erneut aus. Ein erfolgreicher zweiter Lauf zeigt, dass der Aktionsweg das aktuell gespeicherte Zugangsmittel verwendet und keinen veralteten Wert aus einer Agentenkonfiguration. Ein fehlgeschlagener Lauf kann ebenfalls hilfreich sein, wenn der Fehler eine Authentifizierungsstörung nennt, ohne das abgelehnte Geheimnis auszugeben.

Testen Sie nicht mit einem Token, das mehr kann als für das Szenario nötig. Schreibgeschützte Zugangsdaten reichen aus, um die Injektion nachzuweisen. Fügen Sie für Mutationstests später eine eng begrenzte, reversible Schreibberechtigung hinzu. Die Person, die den Test prüft, sollte niemals Zugriff auf das echte Token benötigen, um über den Erfolg zu entscheiden.

Die Genehmigungshürde sollte zum Schaden des Aufrufs passen

Eine Genehmigung für eine Sitzung und eine Genehmigung für jede einzelne Nutzung lösen unterschiedliche Probleme. Die Sitzungsfreigabe bestätigt, dass ein bestimmter Agentenlauf eine begrenzte Fähigkeit nutzen darf. Eine Genehmigung für jede Nutzung zwingt eine Person, jede Anfrage mit einem vertraulichen Zugangsmittel zu prüfen. Wer beide Mechanismen gleichsetzt, erhält entweder eine unbrauchbare Flut von Abfragen oder einen unbeaufsichtigten Weg zu teuren Fehlern.

Verwenden Sie ein Zugangsmittel mit geringem Risiko, um die Sitzungsgrenze zu testen. Verlangen Sie für ein Zugangsmittel, das Daten erstellen, löschen, übertragen, veröffentlichen oder Berechtigungen ändern kann, eine Genehmigung bei jeder Nutzung. Lassen Sie den Agenten mit diesem Zugangsmittel zwei verschiedene Testaufrufe ausführen. Sie sollten zwei Entscheidungen sehen, und die zweite Anfrage darf nicht von der Genehmigung für die erste profitieren.

Der Test muss eine Ablehnung enthalten. Genehmigen Sie die erste Testaktion und lehnen Sie die zweite ab. Bestätigen Sie diese Punkte im Bericht des Agenten und in der Aktionsaufzeichnung:

1. Die erste Aktion erreichte den Testdienst und gab dessen Anfragekennung zurück.
2. Die abgelehnte Aktion erreichte den Testdienst nie.
3. Der Agent behauptete nicht, die Änderung vorgenommen zu haben.
4. Die Sitzung blieb für Vorgänge nutzbar, die das abgelehnte Zugangsmittel nicht benötigten.

Der vierte Punkt deckt einen besonders unangenehmen Fehler auf. Manche Integrationen behandeln eine abgelehnte vertrauliche Anfrage als Grund, alle späteren Vorgänge zu beenden. Andere ignorieren die Ablehnung und versuchen es so lange erneut, bis jemand versehentlich genehmigt. Beides erschwert die menschliche Kontrolle unnötig.

Genehmigungsmüdigkeit ist ein Designfehler, aber die Abschaffung von Genehmigungen ist normalerweise nicht die richtige Lösung. Verringern Sie die Belastung, indem Sie Aufgaben in einer kurzlebigen Sitzung bündeln, die Zahl vertraulicher Aufrufe reduzieren oder dem Agenten eine sicherere Sammelaktion geben. Lösen Sie störende Abfragen nicht durch ein dauerhaftes, weitreichendes Token für einen Prozess, dessen Plan sich während der Aufgabe ändern kann.

HTTP-Statuscodes sollten das Verhalten des Agenten steuern

Ein Agent braucht ein klares Verhalten für Fehlerklassen, denn ein HTTP-Erfolg und ein erfolgreicher Vorgang sind nicht dasselbe. RFC 9110 definiert die Bedeutung von HTTP-Statuscodes. Eine 401-Antwort zeigt unter anderem, dass Authentifizierungsdaten fehlen oder ungültig sind, während eine 403-Antwort bedeutet, dass der Server die Anfrage verstanden hat, ihre Ausführung aber verweigert. Behandeln Sie diese Antworten unterschiedlich. Eine Wiederholung derselben Anfrage bringt bei beiden normalerweise keinen Fortschritt, sondern nur mehr Rauschen.

Erstellen Sie vor dem Rollout eine Fehlertabelle und testen Sie jede Zeile gegen den Test-Endpunkt. Die erforderlichen Aktionen sollten so eng gefasst sein, dass ein Prüfer erkennen kann, ob der Agent ihnen gefolgt ist.

Eine 400-Antwort verdient mehr Aufmerksamkeit, als sie oft bekommt. Sie zeigt häufig eine Abweichung zwischen dem Tool-Schema des Agenten und dem tatsächlichen Vertrag der entfernten API. Lassen Sie den Testserver feldbezogene Validierungsfehler zurückgeben und prüfen Sie dann, ob der Agent das fehlerhafte Argument meldet, ohne einen Ersatzwert zu erfinden. Ein Agent, der Felder errät, kann aus einem harmlosen Validierungsfehler eine Anfrage an das falsche Konto machen.

Testen Sie einen Transportfehler getrennt von einem HTTP-503. Trennen Sie den Testdienst oder richten Sie eine kontrollierte Testanfrage an eine nicht erreichbare Adresse. Der Agent sollte keine Antwort von einer Serverantwort unterscheiden können. Das ist wichtig, wenn die Aktion den Dienst möglicherweise erreicht hat, die Antwort aber verloren ging. Nach einem unklaren Timeout einen Erstellungsaufruf zu wiederholen, kann Duplikate erzeugen.

Verwenden Sie Idempotenzkennungen, wenn die API sie unterstützt. Falls nicht, sollte der Agent vor einer potenziell verändernden Anfrage nach einem vorhandenen Ergebnis suchen. «Dreimal wiederholen» ist kein Wiederherstellungsplan, wenn jeder Versuch eine Karte belasten, einen Benutzer anlegen oder eine Nachricht senden kann.

Ein fehlgeschlagener Rollout beginnt oft mit einer harmlosen Wiederholungsschleife

Ein typischer Fehler beginnt damit, dass ein Agent eine Testressource erstellen und anschließend überprüfen soll. Die Erstellung gelingt beim Dienst, aber eine Netzwerkunterbrechung verbirgt die Antwort. Der Agent sieht einen Fehler, wiederholt den Erstellungsaufruf und erhält ein zweites erfolgreiches Ergebnis. Anschließend ruft er eine Ressource über einen geratenen Namen ab und meldet Erfolg. Der Operator hat nun doppelte Änderungen und keine klare Zuordnung, welche Anfrage welche Änderung ausgelöst hat.

Sie können dies ohne Risiko für die Produktion nachstellen. Lassen Sie eine Testroute eine Erstellungsanfrage annehmen, das Testobjekt speichern und anschließend die Verbindung absichtlich schließen, bevor die Antwort zurückgegeben wird. Führen Sie den Agenten mit einer festen Anfragekennung aus. Das erwartete sichere Verhalten besteht darin, dass er den Testdienst anhand dieser Kennung abfragt, bevor er die Erstellung wiederholt. Kann der Agent das nicht, sollte er stoppen und ein unklar gebliebenes Ergebnis melden.

Ein minimaler Vertrag für den Testdienst macht die Prüfung konkret:

POST /v1/test/jobs
{
  "request_id": "rollout-042",
  "name": "reconcile-demo"
}

GET /v1/test/jobs?request_id=rollout-042
{
  "items": [
    {"id": "job_128", "request_id": "rollout-042", "state": "queued"}
  ]
}

Hier finden Sie auch Prompts, die den Agenten auffordern, es so lange zu versuchen, bis es funktioniert. Für jemanden, der einen menschlichen Operator beobachtet, klingt diese Anweisung vernünftig. Für einen Akteur, der schneller Aufrufe ausführt, als jemand sie bemerkt, ist sie unsicher. Ersetzen Sie sie durch eine begrenzte Wiederholungsregel, eine Duplikatprüfung und eine Bedingung, die eine menschliche Prüfung verlangt.

OWASP nennt in den API Security Top 10 sowohl den uneingeschränkten Ressourcenverbrauch als auch eine fehlerhafte Autorisierung auf Objektebene. Beim Rollout von Agenten zeigen sich beide Probleme als gewöhnliche Verhaltensfehler: eine Schleife, die ein Limit ignoriert, und ein Agent, der nach dem Fehlschlagen der angeforderten Kennung eine ähnliche Objektkennung einsetzt. Ihr Test braucht ein verbotenes Objekt und eine Route mit Ratenbegrenzung, denn eine reine Erfolgsumgebung würde keine dieser Gewohnheiten sichtbar machen.

Aufzeichnungen müssen Entscheidung und externe Wirkung erklären

Eine Aufzeichnung eines Aufrufs muss jemandem ermöglichen, den Ablauf nachzuvollziehen, ohne die gesamte private Denkweise des Agenten zu rekonstruieren. Speichern Sie die Fakten, die Autorität und Wirkung belegen: welche Sitzung gehandelt hat, welcher Prozess die Aktion angefordert hat, welches Ziel und welche Methode verwendet wurden, welche Referenz auf das Zugangsmittel galt, ob eine Person genehmigt hat, wann der Aufruf stattfand und welches Ergebnis zurückkam.

Speichern Sie nicht reflexartig den vollständigen Anfragekörper in jeder Aufzeichnung. Manche Nutzdaten enthalten Kundendaten, Tokens Dritter oder Inhalte, die der Agent verarbeiten sollte. Eine sichere Zusammenfassung oder ausgewählte Felder reichen oft für die Untersuchung. Besonders nützlich ist die Anfragekennung des entfernten Dienstes, weil sie Ihre lokale Aufzeichnung mit dem eigenen Audit-Trail des Dienstes verbindet.

Trennen Sie die Aufzeichnung des Laufs von der Aufzeichnung des Aufrufs. Der Laufdatensatz beantwortet, ob ein bestimmter Agentenprozess arbeiten durfte und ob jemand diese Erlaubnis später widerrufen hat. Der Aufrufdatensatz beantwortet, was bei jeder externen Aktion geschah. Wenn Sie beides in ein Chat-Protokoll packen, verlieren Sie die Struktur, die Sie bei einem Lauf mit vielen Anfragen brauchen.

Sallyport führt Sitzungs- und Aktivitätsjournale aus einem verschlüsselten, hashverketteten Audit-Log. Mit dem Befehl sp audit verify lässt sich diese Kette offline über dem Chiffretext prüfen, ohne einen Tresorschlüssel zu benötigen. So kann die Integrität der Aufzeichnungen getrennt vom Zugriff auf Geheimnisse getestet werden.

Führen Sie nach einem normalen Test die Prüfung aus. Kopieren Sie anschließend die verschlüsselte Audit-Datei an einen Testort und verändern Sie Bytes in der Kopie. Der Befehl sollte für die veränderte Kopie einen Fehler melden, während die Originaldatei weiterhin erfolgreich geprüft wird. Verwenden Sie dafür ausschließlich eine wegwerfbare Kopie. So lernt das Prüferteam, wie ein gültiger Bericht aussieht, bevor es ihn bei einer Untersuchung in der Produktion benötigt.

Manipulationserkennung bedeutet nicht, dass jeder Operator jedes Detail lesen kann. Sie ersetzt auch nicht die Protokolle der entfernten API. Sie beantwortet eine engere Frage: Ist die lokale Folge der Aufzeichnungen unverändert geblieben? Bewahren Sie die Anfragekennungen und Zeitstempel des Test-Endpunkts auf, damit ein Ermittler beide Seiten vergleichen kann.

Ein Widerruf muss den nächsten Aufruf stoppen, nicht nur ein Fenster schließen

Testen Sie den Widerruf, während der Agent noch läuft. Genehmigen Sie eine Sitzung, führen Sie eine harmlose Anfrage aus, widerrufen Sie die Sitzung und bitten Sie denselben Prozess um eine zweite harmlose Anfrage. Die zweite Anfrage muss scheitern, bevor sie den Nichtproduktions-Endpunkt erreicht. Wenn sie wegen einer bestehenden Verbindung oder eines zwischengespeicherten Zugangsmittels erfolgreich ist, blockiert das den Produktionsstart.

Testen Sie anschließend die Sperre des Tresors unabhängig davon. Sperren Sie den Speicher für Zugangsdaten und versuchen Sie die Anfrage erneut. Ein gesperrter Tresor muss jede Aktion ablehnen, auch eine Anfrage, die ein Operator zuvor für die Sitzung genehmigt hat. Das ist eine stärkere Kontrolle als der Widerruf eines einzelnen Laufs, weil sie alle vom Tresor abhängigen Aktionswege stoppt.

Beobachten Sie den Endpunkt während beider Tests. Akzeptieren Sie nicht die Meldung des Agenten, der Zugriff sei verweigert worden, als Beweis. Das serverseitige Anfrageprotokoll muss zeigen, dass keine zweite Anfrage eingegangen ist. Diese einfache Gegenprüfung deckt Integrationen auf, die nach dem bereits erfolgten Versand der HTTP-Anfrage noch einen Genehmigungsfehler melden.

Wenn Ihr Agent neben HTTP-Aufrufen auch mit SSH arbeiten kann, wiederholen Sie den Test gegen einen wegwerfbaren Host. Verwenden Sie ein nicht privilegiertes Konto und einen Befehl mit eindeutigem Ergebnis, etwa das Erstellen einer Datei in einem temporären Verzeichnis. Der Widerruf muss einen neuen SSH-Befehl ebenso verhindern wie eine API-Anfrage. Ein Gateway, das beide Kanäle unterschiedlich behandelt, schafft eine Lücke, in der Operatoren fälschlich von fortbestehender Kontrolle ausgehen.

Für die Freigabe braucht es ein Belegpaket, nicht das Vertrauen in eine Demo

Gehen Sie erst dann in die Produktion, wenn ein Prüfer anhand einer kompakten Testaufzeichnung feststellen kann, ob der Agent innerhalb seiner vorgesehenen Befugnisse geblieben ist. Das Paket sollte die Testidentität und ihre Berechtigungen, die Grenze des Endpunkts, das erwartete Genehmigungsverhalten, repräsentative Erfolgs- und Fehlerergebnisse, das Ergebnis der Aufzeichnungsprüfung und das beobachtete Widerrufsergebnis enthalten.

Übernehmen Sie nicht jede Testberechtigung mit dem Agenten in die Produktion. Erstellen Sie die Produktionszugangsdaten separat und beginnen Sie mit der kleinsten Operationsmenge, die die erste echte Aufgabe unterstützt. Bestimmen Sie einen Operator, der Läufe genehmigen oder widerrufen kann, und dokumentieren Sie, bei welchen Antwortzuständen der Agent stoppen muss. Wenn das Team diese Person nicht benennen kann, hat es die operative Kontrolle dem Zufall überlassen.

Führen Sie die erste Produktionsaufgabe mit aktivierten Genehmigungen aus und prüfen Sie die Aufzeichnungen unmittelbar danach. Vergleichen Sie die tatsächliche Zahl der Anfragen, die Ziele und die Ergebnisse mit dem Testlauf. Wenn der Agent einen ungeplanten Endpunkt kontaktiert, ein weiterreichendes Zugangsmittel anfordert oder sich bei Produktionsdaten anders verhält, stoppen Sie den Rollout und holen Sie dieses Verhalten zurück an den Nichtproduktions-Endpunkt.

Der richtige erste Produktions-Rollout ist bewusst unspektakulär. Der Agent führt wenige erwartete Aufrufe aus, eine Person kann ihn stoppen, das Zugangsmittel gelangt nie in seinen Kontext und jede externe Wirkung hat eine Aufzeichnung, deren Anfragekennung mit der des Dienstes übereinstimmt. Das reicht als Beleg für eine vorsichtige Erweiterung. Eine polierte Demo tut es nicht.