Audit-Log-API-Referenz

Jede folgenreiche Aktion der Plattform landet in einem hash-verketteten, signierten Log, das dein Compliance-Team — oder das deines Kunden — unabhängig prüfen kann. Zum Lesen und Versiegeln braucht es nichts Besonderes: denselben Bearer-API-Schlüssel wie überall sonst auf der v1-Oberfläche.

Kette und Siegel

Jeder Eintrag hasht seinen Vorgänger; ein Siegel signiert einen Bereich. Die Kette entlarvt einen geänderten oder entfernten Eintrag, das Siegel ein gekürztes Ende — beides ist nötig.

GET /v1/audit/log

Blättert das Log ab einer als `from` übergebenen Sequenznummer durch, 5000 Einträge je Seite, mit `nextFrom` als Zeiger auf die nächste.

Eintragsfelder

Name	Typ	Beschreibung
`kind`	string	Was geschah, aus dem Vokabular unten.
`at`	timestamp	Wann die Plattform es festhielt.
`summary`	string	Eine einzeilige, menschenlesbare Beschreibung.
`seq`	integer	Die Position des Eintrags in der Kette.
`prev`	string	Der Hash des vorherigen Eintrags.
`hash`	string	Der eigene Hash dieses Eintrags, berechnet über seine kanonische Kodierung.

Das kind-Vokabular

Zu den kinds gehören session.created und session.released, die Verben verb.observe, verb.act und verb.extract, credential.released und credential.denied, die Sicherheits-Verweigerungen gate.refused und destination.refused, task.started und task.finished, workflow.block, takeover.granted und takeover.released, trigger.fired sowie die Schlüsselereignisse key.rotated und secret.rotated.

GET /v1/audit/seals

Listet die Siegel und die Eintragsbereiche, die jedes einzelne abdeckt.

POST /v1/audit/seal

Signiert einen benannten Bereich mit Ed25519 und liefert `{sealId, seal, covers}` — oder 400, wenn nichts Neues zu versiegeln ist.

GET /v1/audit/export

Exportiert ein `browserberg-action-log-v1`-Bündel aus Einträgen und Siegeln, paginiert zu 50000 Einträgen.

Prüfen ohne uns

Das Bündel enthält howToVerify, und ein Verifizierer braucht nichts von uns: Spiele die Kette nach, prüfe dann jedes Siegel. Keiner der Mechanismen genügt allein — der eine übersieht ein gekürztes Ende, der andere einen editierten Eintrag —, behandle sie also als eine Prüfung mit zwei Hälften, nie als Alternativen.

Siegel benennen ihren Algorithmus. ed25519 ist der ursprüngliche; ecdsa-p256-sha256 (seit 1.4) ist der, mit dem der gehostete Dienst versiegelt, weil sein Signaturschlüssel in einem KMS liegt, das P-256 und nicht Ed25519 anbietet. Eine ECDSA-Signatur ist die 64-Byte-IEEE-P1363-Form r||s, base64, geprüft mit SHA-256 über denselben kanonischen Siegel-String. Ein Prüfer lehnt einen unbekannten Algorithmus ab, statt zu raten.

POST /v1/audit/verify

Führt die plattformeigene Prüfung aus — sie existiert für den Support; führe deinen eigenen Verifizierer aus, genau das ist der Punkt.

Was das Log nicht ist

Ehrlichkeit beim Umfang: Der Export ist keine Zeitstempel-Autorität und kein Beweis, dass der Browser sich wie beschrieben verhalten hat. Er ist eine manipulationsevidente Aufzeichnung dessen, was die Plattform nach eigener Aussage tat — stark genug, dass ein geänderter, entfernter oder gekürzter Bericht auffällt, und nicht stärker.

Spur hinterlassen, Spur lesen

Erzeugt eine Session, gibt sie frei und liest dann die ersten Ketteneinträge mit ihren Hashes.

Voraussetzungen: api-key

BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"

# Leave a trace to read back.
ID=$(curl -s -X POST "$BASE/v1/sessions" -H "$AUTH" -H "$JSON" -d '{"ttlSeconds": 60}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["session"]["id"])')
curl -s -X DELETE "$BASE/v1/sessions/$ID" -H "$AUTH" > /dev/null

# Every entry carries seq, prev and hash: a hash chain a verifier replays.
curl -s "$BASE/v1/audit/log?from=0" -H "$AUTH" \
  | python3 -c 'import json,sys; r = json.load(sys.stdin); print(json.dumps([
      { "seq": e["seq"], "kind": e["kind"], "summary": e["summary"] }
      for e in r["entries"][:4]], indent=2))'

[
  {
    "seq": 0,
    "kind": "session.created",
    "summary": "session Fi3VkukDoaZf3fQgFzHI6w ready (warm start)"
  },
  {
    "seq": 1,
    "kind": "verb.act",
    "summary": "1 pre-resolved step(s)"
  },
  {
    "seq": 2,
    "kind": "session.released",
    "summary": "session Fi3VkukDoaZf3fQgFzHI6w ended: client_released"
  },
  {
    "seq": 3,
    "kind": "session.created",
    "summary": "session I3Vb_fM3rAKTp_e8k2n5jg ready (warm start)"
  }
]

Kontext

Isolation und Souveränität Die Grenzen, die das Log bezeugt
Limits Seitengrößen für Log und Export
Anleitung zum Zugangsdaten-Tresor Die Momente, die credential.released festhält