Production enforcement gateway with multi-provider support. Full 3-vector risk scoring, 4-tier HITL circuit breaker, HMAC-chained immutable audit, heartbeat-gated safe mode, outbound response scanning, and NEXUS-A2A v0.2 compatibility hooks. 48 tests. All passing.
GENESIS_HASH was initialized as the string literal
"GENESIS:SAFE2:v3.0:OPENCLAW". The HeartbeatMonitor
regex requires [a-f0-9]{16} for the hash field. The colon-delimited
sentinel failed validation on every first-run heartbeat, causing the gateway to
reject its own initialized file as malformed.
Fix: GENESIS_HASH is now derived as
sha256(b"GENESIS:SAFE2:v3.0:OPENCLAW").hexdigest()[:16]
— always valid hex, always 16 characters, regex-safe.
Resolved value: e9c2244761019e50.
| Component | Severity | Status |
|---|---|---|
HeartbeatMonitor.GENESIS_HASH — regex mismatch on first-run init | Critical | Fixed |
REQUEST_LOG shared list race condition under threaded=True | Critical | Fixed |
| Rate limiting defined in config but not enforced in code | Critical | Fixed |
| Mutable plain-file audit log — no HMAC chain, no tamper detection | Critical | Fixed |
| No heartbeat validation at all (Bug #11766) | Critical | Fixed |
| HITL binary block — single threshold, no 4-tier spec | High | Fixed |
| Risk scoring 2-vector only — missing target sensitivity + historical context | High | Fixed |
| No A2A impersonation detection | High | Fixed |
| No outbound response scanning for exfil / tool_use injection | High | Fixed |
main.py — stub only, version tagged 2.1.0, zero enforcement | High | Fixed |
| Component | Description |
|---|---|
New HeartbeatMonitor |
Validates HEARTBEAT.md before every proxied request. Regex-validated format with ISO-8601 timestamp and hex hash chain. Missing / empty / stale → safe mode. Never auto-creates; --init-heartbeat for first run only. |
New ImmutableAuditLog |
HMAC-SHA256 chained JSONL. Each entry: HMAC(AUDIT_CHAIN_KEY, "{prev_hash}|{entry_json_sorted}"). Atomic write with fsync(). Chain verified on startup — break activates safe mode. /audit/verify-chain route for on-demand integrity check. |
| New 3-vector risk scoring | Action type (0.40) × target sensitivity (0.35) × historical context (0.25). Injection modifier +5.0, A2A modifier +3.0. Composite capped at 10.0. Per-user fingerprint history persisted across restarts. |
| New 4-tier HITL circuit breaker | AUTO (0–3) / MEDIUM (4–6, X-HITL-Token) / HIGH (7–8, token + X-HITL-Reason ≥ 20 chars) / CRITICAL (>8, out-of-band HMAC-SHA256 2FA challenge-response). Tokens TTL-scoped to 300s, consumed on use. |
| New Multi-provider support | Pass-through adapter architecture supporting Anthropic, OpenAI/Codex, Gemini, Ollama (local models), and OpenRouter. Switch providers with one config value. All enforcement controls operate identically across providers. Response scanning normalizes each provider's wire format to a unified inspection model. |
New provider_adapters.py |
Standalone adapter module. Per-provider classes handle auth headers, request normalization for enforcement, and response content extraction for scanning. Adding a new provider requires only a new adapter class — no core enforcement logic changes. |
| NEXUS NEXUS-A2A v0.2 compatibility | Header detection, identity field passthrough, and delegation chain logging for NEXUS-A2A v0.2. A2A detection upgraded to NEXUS-aware indicator set. NEXUS identity fields written to every audit log entry when present. No NEXUS runtime required — enforcement mode activates via single config flag when NEXUS ships. |
| New Response scanner | Inspects every upstream response before returning to client. Flags exfiltration patterns in text blocks and injection payloads in tool_use input fields. Provider-aware: each adapter normalizes its response format for unified scanning. |
New SafeMode |
Event-based hard stop. Activated by heartbeat failure or audit chain break. Deactivated only by operator key via POST /emergency/deactivate-safe-mode. Agents cannot self-recover. |
New scanner.py |
Nightly external auditor. Checks: HMAC chain integrity, heartbeat validity, config security, secret sprawl, environment completeness, log permissions, drill calendar (90-day red-team, 180-day A2A). Exit 0/1/2 with --json for CI integration. |
New start.sh v3 |
9-step pre-flight: Python version, pip deps, env var validation, YAML syntax, network security, scanner pre-flight, heartbeat validation, log permissions, exec into Flask. Hard-aborts on any critical failure. Python YAML parsing throughout — no grep/awk. |
| New Per-user rate limiting | Dual sliding window: requests/minute + requests/hour. Per-identity enforcement with no cross-user bleed. Configured via config.yaml and enforced in code. |
NEXUS-A2A v0.2 — forward-compatible from day one.
When NEXUS-A2A ships, update nexus.enforcement in config.yaml
from "passthrough" to "verify" or "enforce".
No gateway code changes required.
Breaking change: v2.1 configs and audit logs are not forward-compatible. Complete the steps below before going live.
AUDIT_CHAIN_KEY and OPERATOR_DEACTIVATION_KEY before starting.provider_adapters.py in the same directory as gateway.py (or main.py). Without it the gateway falls back to Anthropic-only mode.python3 gateway.py --init-heartbeat once to create HEARTBEAT.md.config.yaml entirely. New required sections: provider, providers, hitl_thresholds, risk_weights, heartbeat, audit_governance, nexus.provider.active to your chosen provider. Set the corresponding API key environment variable.