Nachweise in der CI-Pipeline prüfen mit kya-verify

Das Wichtigste in Kürze

• kya-verify prüft Nachweise in jeder CI-Pipeline mit klaren Exit-Codes.
• Jeder Code ausser 0 sollte den Lauf scheitern lassen.
• Öffentliche Schlüssel und Statuslisten gehören ins Repository, private Schlüssel nie.

Kommandozeile kennenlernen

Das Paket bringt die Kommandozeile kya-verify mit. Sie nimmt eine Datei oder die Standardeingabe, optional Schlüssel, Statuslisten, Zeitstempel-Anker und einen Prüfzeitpunkt, und gibt das Urteil als Text oder mit --json als vollständigen Bericht aus:

npx kya-verify evidence.json --keys issuer-jwks.json --lists status-list.jwt --json > report.json
echo "exit code: $?"

Exit-Codes verwenden

kya-verify endet mit 0 bei VALID, 1 bei INVALID, 2 bei INDETERMINATE und 64 bei falschem Aufruf. In einer Pipeline sollte jeder Code ausser 0 den Lauf scheitern lassen, denn auch ein unbestimmtes Urteil heisst, dass ein Nachweis fehlt.

Vertrauen im Repository ablegen

Legen Sie die öffentlichen Schlüssel der Aussteller und die Statuslisten in einem eigenen Verzeichnis ab, etwa trust/. Private Schlüssel gehören nie ins Repository. Aktualisieren Sie die Statuslisten regelmässig, damit Widerrufe in der Prüfung ankommen.

Workflow anlegen

Ein Workflow für GitHub Actions installiert das Paket und prüft alle Nachweise im Verzeichnis evidence/:

name: Verify agent evidence
on: [push, pull_request]
jobs:
  kya:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install --no-save https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz
      - name: Verify all evidence files
        run: |
          for f in evidence/*.json; do
            npx kya-verify "$f" --keys trust/issuer-jwks.json --lists trust/status-list.jwt || exit 1
          done

Dasselbe Muster funktioniert in GitLab CI, Jenkins oder jeder anderen Pipeline mit Node.js.

Berichte aufbewahren

Speichern Sie mit --json den vollständigen Bericht als Artefakt des Laufs. Der reportDigest macht jeden Bericht später nachrechenbar; Begründungscodes erklärt die Fehlerreferenz.

Fehler beheben

Scheitert ein Lauf, zeigt die Ausgabe von kya-verify das Urteil und mit --json alle Prüfschritte. Häufige Ursachen sind eine veraltete Statusliste im Verzeichnis trust/, ein gewechselter Schlüssel des Ausstellers, der noch nicht hinterlegt ist, und Nachweise, deren Gültigkeit abgelaufen ist. Für reproduzierbare Tests mit festen Testdaten setzen Sie --now auf einen festen Zeitpunkt.

Häufige Fragen

Warum scheitert der Lauf bei einem unbestimmten Urteil?

Weil INDETERMINATE heisst, dass ein Nachweis fehlt. Wer das zulassen will, kann den Exit-Code 2 gezielt behandeln, sollte das aber bewusst entscheiden.

Kann ich nur geänderte Nachweise prüfen?

Ja, etwa indem Sie die Liste der geänderten Dateien aus dem Versionsverwaltungssystem an die Schleife übergeben.

Wie halte ich Testdaten stabil, wenn Mandate ablaufen?

Mit der Option --now auf einen festen Zeitpunkt. So bleiben Testergebnisse gleich, auch wenn die Gültigkeit der Testdaten in der Wirklichkeit abläuft.

Wie lange dauert die Prüfung in der Pipeline?

Die Prüfung selbst dauert pro Nachweis Millisekunden. Den grössten Teil der Laufzeit macht die Installation des Pakets aus, die sich zwischenspeichern lässt.

Funktioniert kya-verify auch ohne Internet?

Ja. Nach der Installation braucht die Kommandozeile keinen Netzwerkzugriff; Schlüssel und Statuslisten kommen aus dem Repository.

Kann ich die Berichte im Pull Request anzeigen?

Ja. Die Ausgabe mit --json lässt sich auswerten und als Kommentar oder Zusammenfassung des Laufs darstellen.

Kann ich die Pipeline auch für eigene Testvektoren nutzen?

Ja. Legen Sie Nachweise mit bekanntem Ergebnis ab und vergleichen Sie Urteil und Begründungscodes aus dem JSON-Bericht mit den erwarteten Werten.

Wie sichere ich die Installation ab?

Prüfen Sie die Prüfsumme des Pakets im Workflow, bevor Sie es installieren, und legen Sie die erwartete Prüfsumme im Repository ab.

Quellen

1. @knowyouragent/verify-core (Paket): https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz
2. GitHub Actions: Dokumentation: https://docs.github.com/actions