§ DOCUMENTATION

Enforcement-Bypässe

Kann ein SDK keine Enforcement-Entscheidung erhalten, kann es die Aktion trotzdem ausführen lassen. Execlave hält jeden solchen ungeprüften Zeitraum in Ihrem Audit-Log fest und führt ihn im signierten Compliance-Bericht — damit „kein Eintrag“ nie als „vollständig kontrolliert“ gelesen wird.

§ 01

Was ein Bypass ist

Richtlinien werden von der Plattform ausgewertet. Das SDK ist eine eigene Fehlerdomäne: Kann enforcePolicy() (JavaScript) bzw. enforce_policy() (Python) keine Entscheidung erhalten, entscheiden die eigenen Einstellungen des SDK — nicht der failureMode einer Richtlinie. Standardmäßig (fail_open) wird die Aktion ausgeführt. Das ist ein Bypass: ein Aufruf, der ohne serverseitige Enforcement-Entscheidung lief.

Situation	Einstellung	Standard	Was passiert
Netzwerkfehler, 5xx oder offener Circuit Breaker	`enforcementOnOutage`	`fail_open`	Der Aufruf liefert allowed: true mit einer source von fail_open_network_error, fail_open_server_error oder fail_open_circuit_breaker. Unter fail_closed wirft er EnforcementUnavailableError.
Plan-Kontingent erschöpft (HTTP 402)	`planLimitBehavior`	`fail_open`	Der Aufruf liefert allowed: true mit einer source von fail_open_plan_limit. Unter fail_closed wirft er PlanLimitExceededError.

Ein Kontingent-Bypass ist eine Governance-Lücke, auch wenn die Ursache kommerziell statt ein Ausfall ist — und er tritt im Normalbetrieb am wahrscheinlichsten auf. Er wird genau wie die anderen festgehalten.

§ 02

Wie Bypässe festgehalten werden

Ab SDK 1.8.0 melden das JavaScript- und das Python-SDK Bypässe an Execlave. Dort wird jeder als enforcement.bypassed in das nur anfügbare (append-only), hashverkettete Audit-Log Ihrer Organisation geschrieben.

Ein Eintrag deckt ein Zeitfenster ab, nicht einen einzelnen Aufruf: aufeinanderfolgende Bypässe desselben Agenten mit demselben Grund werden zusammengefasst. Ein Fenster schließt sich, wenn der Agent wieder eine geprüfte Entscheidung erhält, nach 60 Sekunden ohne Bypass oder nach 15 Minuten. Ein zweistündiger Ausfall ergibt daher eine Handvoll Einträge statt Tausender, und ein geschriebener Eintrag ändert sich nie mehr.

Meldungen werden über einen Hintergrund-Timer mit Wiederholung und Backoff zugestellt. Sie laufen nie innerhalb eines Enforcement-Aufrufs, und der Endpunkt unterliegt nicht Ihrem Plan-Limit — ein durch erschöpftes Kontingent verursachter Bypass lässt sich also weiterhin melden.

§ 03

Den Eintrag lesen

Listen Sie sie aus dem Audit-Log mit dem Filter action auf, eingegrenzt durch startDate und endDate:

curl "https://api.execlave.com/api/v1/audit-logs?action=enforcement.bypassed&startDate=2026-09-01&endDate=2026-09-30" \  -H "Authorization: Bearer $EXECLAVE_API_KEY"

Jeder Eintrag hat den Ressourcentyp enforcement_window und die ID des Fensters als Ressourcen-ID:

{  "action": "enforcement.bypassed",  "resourceType": "enforcement_window",  "resourceId": "6f1c2a9e-3b7d-4c55-9a1e-0d2f8b6c7e41",  "metadata": {    "agentId": "support-bot",    "agentResolved": true,    "resolvedAgentId": "0b8e7c1a-…",    "reason": "network_error",    "source": "fail_open_network_error",    "count": 412,    "message": "connect ECONNREFUSED",    "clientReported": {      "firstAt": "2026-09-10T12:00:03.114Z",      "lastAt": "2026-09-10T12:41:57.902Z",      "sentAt": "2026-09-10T12:43:02.771Z"    },    "serverObserved": {      "receivedAt": "2026-09-10T12:43:02.845Z",      "skewMs": 74,      "clockSkewSuspect": false    },    "sdk": { "name": "@execlave/sdk", "language": "js", "version": "1.8.0" }  }}

Feld	Bedeutung
`agentId`	Die Agenten-ID genau so, wie das SDK sie gemeldet hat. agentResolved gibt an, ob sie einem Agenten Ihrer Organisation zugeordnet werden kann; eine unbekannte ID wird trotzdem festgehalten.
`reason`	network_error, server_error, circuit_breaker_open oder plan_limit_exceeded. source ist der passende fail_open_*-String, der an den Aufrufer zurückgegeben wurde.
`count`	Wie viele Aufrufe das Fenster abdeckt — Aufrufe, die ohne serverseitige Enforcement-Entscheidung liefen.
`clientReported`	Wann das Fenster begann und endete und wann es gesendet wurde — so, wie es die Uhr des SDK behauptet. Vom API-Schlüssel bestätigt, nicht von der Plattform gemessen.
`serverObserved`	Wann die Plattform die Meldung erhielt (receivedAt), die Abweichung zur Uhr des SDK (skewMs) und clockSkewSuspect, das true ist, wenn beide mehr als fünf Minuten auseinanderliegen. Eine abweichende Uhr führt nie zur Ablehnung einer Meldung.
`sdk`	Name, Sprache und Version des meldenden SDK.

Auch Meldeverlust wird festgehalten. Übersteigt ein Ausfall den In-Memory-Puffer eines SDK (500 geschlossene Fenster), werden die ältesten Fenster verworfen, und die nächste erfolgreiche Meldung fügt einen Eintrag enforcement.bypass_reports_dropped mit droppedWindows und droppedBypasses hinzu. Der Eintrag sagt „N Bypässe wurden nicht gemeldet“, statt zu schweigen.

§ 04

Im signierten Compliance-Bericht

Ein Bericht, der Enforcement-Zahlen nennt, aber nichts über die Aufrufe sagt, die nie das Enforcement erreichten, lädt dazu ein, anzunehmen, jeder Aufruf sei geprüft gewesen. Compliance-Berichte enthalten daher einen Abschnitt enforcementBypasses innerhalb des signierten Teils: Wer ihn ändert, macht die Signatur ungültig. Er wird außerdem im HTML- und PDF-Export als „Enforcement Bypasses (Ungoverned Execution)“ dargestellt, und die Monitoring-Kontrolle zitiert ihn neben der Enforcement-Zahl, die er einordnet.

"enforcementBypasses": {  "windows": 3,  "bypassedCalls": 461,  "agents": 2,  "byReason": {    "circuit_breaker_open": { "windows": 0, "bypassedCalls": 0 },    "network_error":        { "windows": 2, "bypassedCalls": 452 },    "server_error":         { "windows": 0, "bypassedCalls": 0 },    "plan_limit_exceeded":  { "windows": 1, "bypassedCalls": 9 }  },  "clockSkewSuspectWindows": 0,  "unresolvedAgentWindows": 0,  "reportingLoss": { "notices": 0, "droppedWindows": 0, "droppedBypasses": 0 },  "items": [ /* die größten Zeitfenster, bis zu 200 */ ],  "itemsTruncated": false,  "scope": "organization",  "windowFrom": "2026-09-01T00:00:00.000Z",  "windowTo": "2026-09-30T23:59:59.999Z",  "limitations": [ /* warum eine leere Zahl kein Beleg für vollständige Kontrolle ist */ ]}

Gleicher Zeitraum und gleicher Umfang wie der übrige Bericht. Fenster werden dem Zeitraum zugeordnet, in dem die Plattform sie erhalten hat, nicht der Uhr des SDK. Ein auf Agenten eingegrenzter Bericht enthält nur Fenster, die diesen Agenten zugeordnet wurden; Fenster, deren Agenten-ID nicht zugeordnet werden konnte, werden ausgeschlossen und in unresolvedAgentWindows gezählt, statt stillschweigend zu fehlen. Meldeverlust wird immer vollständig gezeigt, weil er jede Zahl einschränkt.
Kein Urteil. Der Status der Monitoring-Kontrolle (erfüllt / teilweise / nicht erfüllt) ändert sich durch Bypässe nicht. Aus einer Zahl einen Status zu machen, braucht einen Schwellenwert, den Sie festlegen.
Eine leere Zahl wird nie als sauber dargestellt. Ohne Fenster schreibt der Bericht „None reported“ und erklärt, dass das nicht „nichts ist aufgetreten“ bedeutet. Ein Bericht, der vor diesem Abschnitt gespeichert wurde, sagt, der Abschnitt sei nicht enthalten — nie „none“.
Ein fehlgeschlagenes Lesen lässt den Bericht scheitern. Lassen sich die Bypass-Einträge nicht lesen, schlägt die Erstellung fehl, statt den Abschnitt wegzulassen.

§ 05

Konfiguration

Die Meldung ist standardmäßig aktiv, weil der Nachweis der Zweck ist. Um nur den lokalen Callback zu behalten und nichts an Execlave zu senden, setzen Sie reportBypassesToPlatform: false (JavaScript) bzw. report_bypasses_to_platform=False (Python). Der Callback wird in beiden Fällen einmal pro umgangenem Aufruf ausgelöst.

// JavaScriptconst exe = new Execlave({  apiKey: process.env.EXECLAVE_API_KEY!,  enforcementOnOutage: 'fail_open',       // oder 'fail_closed' — ablehnen statt fortfahren  planLimitBehavior: 'fail_open',  onEnforcementBypassed: (e) => alert(e), // lokal, einmal pro umgangenem Aufruf  reportBypassesToPlatform: true,         // Standard (ab 1.8.0): zusätzlich im Audit-Log festhalten}); # Pythonexe = Execlave(    api_key=os.environ["EXECLAVE_API_KEY"],    enforcement_on_outage="fail_open",    plan_limit_behavior="fail_open",    on_enforcement_bypassed=alert,    report_bypasses_to_platform=True,    # Standard (ab 1.8.0))

Einstellung (JS / Python)	Werte	Standard
`enforcementOnOutage`	fail_open \| fail_closed	`fail_open`
`planLimitBehavior`	fail_open \| fail_closed	`fail_open`
`reportBypassesToPlatform`	true \| false	`true`

§ 06

Was das nicht abdeckt

Ein Absturz während eines Ausfalls verliert den ungesendeten Puffer. Es wird nichts auf die Festplatte geschrieben; was noch nicht zugestellt war, wird nicht gemeldet.
Ein Fenster wird erst nach seinem Schließen gemeldet. Ein noch offener Zeitraum ist noch nicht sichtbar. Beim sauberen Herunterfahren werden offene Fenster geschlossen und ein begrenzter Versuch unternommen, sie zu senden.
Die Zustellung braucht eine wieder erreichbare Plattform. Während eines Ausfalls werden Einträge im Speicher gehalten und gesendet, sobald der Kontakt wiederhergestellt ist.
fail_closed erzeugt keine Einträge. Es wurde nichts umgangen; der Aufruf wurde abgelehnt.
SDKs vor 1.8.0 melden nichts. Sie lösen nur den lokalen Callback aus; ein fehlender Eintrag eines älteren SDK ist daher kein Beleg dafür, dass seine Aufrufe geprüft waren.
Zeitstempel in clientReported sind die Behauptung des SDK. Vergleichen Sie mit serverObserved.
Die Meldung kann einen internen Hostnamen oder eine Adresse enthalten, die aus dem zugrunde liegenden Netzwerkfehler stammt. Sie ist auf 500 Zeichen gekürzt und bleibt im Audit-Log Ihrer eigenen Organisation.

§ 07

Häufig gestellte Fragen

Waren alle meine Aufrufe geprüft, wenn ein Bericht keine Bypass-Zeitfenster zeigt?

Nicht zwingend. Bypass-Einträge werden vom SDK gemeldet; ein leeres Ergebnis bedeutet daher „keine gemeldet“ — nicht „keine aufgetreten“. Nur SDK-Versionen ab 1.8.0 melden, die Meldung lässt sich pro Client abschalten, und ein Prozess, der vor der Zustellung seines Puffers abgestürzt ist, meldet für diesen Zeitraum nichts. Der Bericht sagt das in seinem eigenen Text und trägt dieselben Einschränkungen im signierten JSON, sodass eine leere Zahl nie als saubere Zahl dargestellt wird.

Bedeutet ein Bypass, dass die Aktion unsicher war?

Er bedeutet, dass die Aktion ohne serverseitige Enforcement-Entscheidung lief: Richtlinien wurden für diesen Aufruf nicht ausgewertet. Ob sie sicher war, hängt davon ab, was der Agent getan hat. Genau deshalb wird der Zeitraum festgehalten — damit Sie nachsehen können, was der Agent währenddessen getan hat. Muss eine Aktion niemals ungeprüft laufen, setzen Sie enforcementOnOutage für diesen Client auf fail_closed; der Aufruf wird dann abgelehnt.

Kann die Meldung meinen Agenten verlangsamen oder beeinträchtigen?

Nein. Das Erfassen eines Bypasses ist eine reine In-Memory-Operation. Die Zustellung erfolgt über einen Hintergrund-Timer bzw. -Thread mit Wiederholung und Backoff und nie innerhalb eines Enforcement-Aufrufs; ein langsamer oder nicht erreichbarer Meldeendpunkt kann daher keinen Aufruf verzögern oder scheitern lassen. Beim Herunterfahren unternimmt das SDK einen einzigen Versuch, der auf etwa drei Sekunden begrenzt ist.

Kann ich die Meldung abschalten?

Ja. Setzen Sie im JavaScript-SDK reportBypassesToPlatform: false bzw. im Python-SDK report_bypasses_to_platform=False. Der lokale Callback onEnforcementBypassed / on_enforcement_bypassed bleibt unberührt und wird weiterhin einmal pro umgangenem Aufruf ausgelöst. Bei abgeschalteter Meldung enthalten Ihr Audit-Log und Ihre Compliance-Berichte keinen Eintrag zu den ungeprüften Zeiträumen dieses Clients.

Warum markiert der Compliance-Bericht die Monitoring-Kontrolle bei Bypässen nicht als nicht erfüllt?

Weil die Umwandlung einer Zahl in ein Urteil einen Schwellenwert braucht — und der richtige Schwellenwert (ein umgangener Aufruf, ein Prozent des Traffics, jeder Bypass bei einem regulierten Agenten) ist Ihre Entscheidung, nicht die des Berichts. Der Bericht nennt die Zahlen neben den Enforcement-Zahlen, die sie einordnen — im signierten Teil und im lesbaren Export — und lässt den Kontrollstatus unverändert.