Cyber Strategy Institute

AI SAFE² Framework

v3.0.0 Released April 2026

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.

48 / 48
Tests passing
HeartbeatMonitor · ImmutableAuditLog · RiskScorer · HITLCircuitBreaker · ResponseScanner · RateLimiter · ProviderAdapters · NEXUS Compatibility

Bug Fixes

Critical — Heartbeat GENESIS_HASH regex mismatch

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.

ComponentSeverityStatus
HeartbeatMonitor.GENESIS_HASH — regex mismatch on first-run initCriticalFixed
REQUEST_LOG shared list race condition under threaded=TrueCriticalFixed
Rate limiting defined in config but not enforced in codeCriticalFixed
Mutable plain-file audit log — no HMAC chain, no tamper detectionCriticalFixed
No heartbeat validation at all (Bug #11766)CriticalFixed
HITL binary block — single threshold, no 4-tier specHighFixed
Risk scoring 2-vector only — missing target sensitivity + historical contextHighFixed
No A2A impersonation detectionHighFixed
No outbound response scanning for exfil / tool_use injectionHighFixed
main.py — stub only, version tagged 2.1.0, zero enforcementHighFixed

New in v3.0

ComponentDescription
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.

Repository Files

Upgrading from v2.1

Breaking change: v2.1 configs and audit logs are not forward-compatible. Complete the steps below before going live.

  1. Generate and export AUDIT_CHAIN_KEY and OPERATOR_DEACTIVATION_KEY before starting.
  2. Place provider_adapters.py in the same directory as gateway.py (or main.py). Without it the gateway falls back to Anthropic-only mode.
  3. Run python3 gateway.py --init-heartbeat once to create HEARTBEAT.md.
  4. Replace config.yaml entirely. New required sections: provider, providers, hitl_thresholds, risk_weights, heartbeat, audit_governance, nexus.
  5. Archive existing audit logs — plain-format entries do not pass HMAC chain verification. Start a fresh log file.
  6. Set provider.active to your chosen provider. Set the corresponding API key environment variable.
  7. Review HITL tier thresholds before going live. Default: AUTO ≤ 3.0 / MEDIUM ≤ 6.0 / HIGH ≤ 8.0 / CRITICAL > 8.0.