Übersicht Schnellstart Handshake-Ablauf Token-Format Tarpit-Gründe Issuer-Endpunkte Admin-API Zero-Trust-Prinzipien Glossar Quellen & Nachweise

Dokumentation

Referenz für Betreiber, die eigene Agenten an ein AgentWarden-geschütztes Zielsystem anbinden oder ECAP unabhängig davon implementieren wollen.

Übersicht

AgentWarden setzt vor ein Zielsystem einen Zero-Trust-Handshake nach dem ECAP-Protokoll (Ethical Crawler Agreement Protocol). Bevor ein Agent lesen oder schreiben darf, weist er einen kurzlebigen, ES256-signierten Token vor, der Betreiber-Identität, Ziel-System und erlaubten Scope kryptografisch bindet. Der Agenten-seitige Prüfpfad antwortet dabei immer mit HTTP 200, unabhängig davon, ob der Zugriff gewährt oder abgelehnt wird: die tatsächliche Entscheidung steht ausschließlich in Response-Headern, damit ein abgelehnter Agent keinen Fehlercode zur Erkennungs-Diagnose missbrauchen kann.

ECAP selbst ist ein offener Standard, siehe ECAP-Standard. Diese Seite dokumentiert die produktionsnahe Referenzimplementierung, die in AgentWarden läuft.

Schnellstart

Die folgenden Schritte registrieren einen Betreiber, stellen einen Token aus und prüfen ihn gegen den ECAP-Handshake-Dienst (ecap-authz, Standardport 9001).

Betreiber registrieren
Über die Issuer-Admin-API (Standardport 9000), authentifiziert mit dem Admin-Token der Instanz. AgentWarden generiert dabei ein frisches ECDSA-P256-Schlüsselpaar und verwaltet den privaten Schlüssel selbst.
bash
```
curl -X POST http://localhost:9000/admin/operators/managed \
  -H "Authorization: Bearer $ECAP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iss": "operator:mein-agent",
    "display_name": "Mein Agent",
    "scopes_allowed": ["read"]
  }'
```
Die Antwort enthält einen api_key, mit dem dieser Betreiber künftig eigene Tokens anfordert. Er wird nur einmal ausgegeben.

ECAP-Token anfordern

Mit dem eben erhaltenen Betreiber-API-Key, nicht dem Admin-Token.

bash

curl -X POST http://localhost:9000/ecap/v1/tokens \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sub": "agent:instanz-01",
    "aud": "target-system:beispiel-app",
    "scope": ["read"]
  }'

json

{
  "ecap_token": "eyJhbGciOiJFUzI1NiIs...",
  "key_id": "kid:2026-03-ecdsa-p256-a1b2c3",
  "expires_at": 1780000300
}

Handshake ausführen
Der Agent stellt seine eigentliche Anfrage an das Zielsystem, geroutet über den ECAP-Handshake-Dienst. Drei Header sind Pflicht.
bash
```
curl -i http://localhost:9001/beliebiger/pfad \
  -H "ecap-token: $ECAP_TOKEN" \
  -H "x-ecap-audience: target-system:beispiel-app" \
  -H "x-ecap-required-scope: read"
```
Die Antwort ist immer HTTP 200. Bei Erfolg trägt sie x-ecap-decision: allow plus x-ecap-identity und x-ecap-operator. In Produktion setzt Envoy anhand dieses Headers die Weiche zum echten Backend oder zur Täuschungsschicht.

Handshake-Ablauf

Der Prüfpfad wertet in dieser Reihenfolge aus:

Sind x-ecap-audience und x-ecap-required-scope gesetzt? Sonst route_not_configured.
Ist ecap-token vorhanden und als JWT dekodierbar?
Steht die Schlüssel-ID auf der Revocation-Liste?
Ist der Betreiber (Issuer) registriert und aktiv?
Ist die Signatur gültig, der Token nicht abgelaufen, Audience und Scope korrekt (ES256 gegen den hinterlegten Public Key des Betreibers)?
Erlaubt die Policy-Engine diese Kombination aus Betreiber, Scope und Identität, und ist die Identität nicht in der Trust Registry markiert?
Lässt sich der Zugriff im manipulationssicheren Audit-Log verbuchen?

Schlägt irgendein Schritt fehl, ist die Antwort trotzdem 200 mit x-ecap-decision: tarpit. Der Grund steht ausschließlich in x-ecap-tarpit-reason, siehe Tabelle unten.

Token-Format

ECAP-Tokens sind JWTs, signiert mit ES256 (ECDSA über die Kurve P-256). Die maximale Laufzeit ist protokollseitig auf 300 Sekunden begrenzt, unabhängig davon, was angefragt wird.

Claim	Typ	Bedeutung
`iss`	string	Betreiber-Identität
`sub`	string	Agenten-Instanz-ID
`aud`	string	Ziel-System, für das der Token gilt
`iat` / `exp`	number	Ausstellung / Ablauf, Unix-Zeitstempel, max. 300s Differenz
`scope`	string[]	erlaubte Aktionen, Teilmenge der Betreiber-Berechtigung
`key_id`	string	Schlüssel-ID des Betreibers, identisch zum JWT-Header `kid`
`purpose_note`	string \| null	optionaler, menschenlesbarer Verwendungszweck

Tarpit-Gründe

Werte von x-ecap-tarpit-reason, wenn x-ecap-decision gleich tarpit ist. Stabile, oeffentlich dokumentierte Bezeichner.

Wert	Auslöser
`route_not_configured`	Audience/Scope-Header wurden von der Gateway-Konfiguration nicht gesetzt
`missing_token`	Header `ecap-token` fehlt
`malformed_token`	Token lässt sich nicht einmal unverifiziert als JWT dekodieren
`revoked_key`	`key_id` steht auf der Revocation-Liste
`unknown_issuer`	`iss`-Claim ist nicht registriert
`suspended_issuer`	Betreiber registriert, aber nicht aktiv
`token_expired`	`exp`-Claim liegt in der Vergangenheit
`token_signature_invalid`	Signatur passt nicht zum hinterlegten Public Key des Betreibers
`token_malformed`	Claims fehlen, falscher Typ, oder unzulässiger Algorithmus (z.B. `alg: none`)
`token_scope_denied`	angeforderter Scope ist nicht im Token enthalten
`token_audience_mismatch`	`aud`-Claim passt nicht zur angefragten Route
`guardrails_unreachable`	Policy-Engine antwortet nicht
`guardrails_denied`	Policy lehnt ab: Scope nicht erlaubt oder Identität markiert
`audit_unavailable`	Audit-Dienst nicht erreichbar, siehe Zero-Trust-Prinzipien unten
`internal_error`	jeder unerwartete Fehler, als Catch-all abgefangen statt durchgereicht

Issuer-Endpunkte

Betreiber-seitige Endpunkte des Issuer-Dienstes (Standardport 9000).

`POST /ecap/v1/tokens`

Token anfordern. Authentifizierung über den Betreiber-API-Key.

`GET /.well-known/ecap-keys/{iss}`

Öffentlicher Schlüssel eines aktiven Betreibers als JWK, für externe Verifizierer, die Tokens unabhängig von AgentWarden prüfen wollen.

`POST /ecap/v1/revoke`

Eigene Schlüssel-ID sofort widerrufen. Wirkt auf alle noch gültigen Tokens mit dieser key_id, unabhängig von deren exp.

Admin-API

Betreiber-Verwaltung, Trust Registry, Laufzeit-Konfiguration und Honeypots laufen über admin-geschützte REST-Endpunkte auf allen vier Diensten, abgesichert durch ein gemeinsames Admin-Token mit Brute-Force-Sperre (Lockout nach mehreren Fehlversuchen, 429 mit Retry-After). Für den täglichen Betrieb ist das die Operator Console, nicht direkte API-Aufrufe.

Zero-Trust-Prinzipien

Immer HTTP 200 auf dem Agenten-Pfad. Ein abgelehnter Agent bekommt keinen Fehlercode, an dem er seine Erkennung diagnostizieren könnte. Die Entscheidung steht ausschließlich in Response-Headern.

Fail-closed statt Fehler-Leak. Ist der Audit-Dienst beim Verbuchen eines gewährten Zugriffs nicht erreichbar, wird der Zugriff nicht durchgelassen, aber die Antwort bleibt ein normal aussehendes tarpit mit Grund audit_unavailable, nie ein 5xx-Fehlercode.

Manipulationssichere Beweiskette. Jeder Audit-Eintrag ist per SHA-256 an seinen Vorgänger gekettet und signiert. Eine nachträgliche Veränderung eines einzigen Bytes lässt die Kette bei der nächsten Verifikation nachweisbar reißen.

Glossar

ECAP (Ethical Crawler Agreement Protocol): Ein offenes, kryptografisches Zero-Trust-Handshake-Protokoll, das von einem KI-Agenten einen signierten, kurzlebigen Token verlangt, bevor er ein Zielsystem lesen oder beschreiben darf.
Zero-Trust-Handshake: Ein Prüfschritt, der standardmäßig keinen Zugriff gewährt: Identität, Geltungsbereich und Berechtigung werden bei jeder Anfrage kryptografisch geprüft, nicht aus einer vorherigen Sitzung angenommen.
Tarpit: Eine Täuschungsantwort, die wie eine normale, erfolgreiche Interaktion aussieht (HTTP 200), einen abgelehnten oder verdächtigen Agenten aber unbemerkt in eine isolierte, synthetische Umgebung statt zum echten System umleitet.
Behavioral Intent Engine: Die AgentWarden-Schicht, die Agentenverhalten über Zeit bewertet, Schreibfrequenz, Syntax und identitätsübergreifende Koordination, statt eine einzelne Anfrage isoliert zu beurteilen.
Deception Infrastructure: Die AgentWarden-Schicht, die verdächtigen Traffic in eine synthetische Kopie des Zielsystems umleitet und dabei Forensik-Daten erfasst, ohne je echte Daten preiszugeben.
Semantic Guardrails: Eine deterministische Policy-Schicht, die Inhalt und Herkunft gegen Regeln prüft, die vor dem Scharfschalten formal auf Widerspruchsfreiheit verifiziert wurden.
Trust Registry: Ein Verzeichnis markierter Agenten-Identitäten, heute pro Kunde isoliert; eine föderierte, organisationsübergreifende Fassung ist Roadmap, noch nicht ausgeliefert.

Quellen & Nachweise

Der ECAP-Kern ist offen archiviert, unabhängig von AgentWarden als Unternehmen.

GitHub-Repository ↗Zenodo-Archiv, DOI: 10.5281/zenodo.17420277 ↗