diff --git a/examples/codex-sovereign-runtime/EVALUATION.md b/examples/codex-sovereign-runtime/EVALUATION.md new file mode 100644 index 0000000..286522c --- /dev/null +++ b/examples/codex-sovereign-runtime/EVALUATION.md @@ -0,0 +1,96 @@ +# Codex Sovereign Runtime v2 Evaluation + +## Purpose + +This file defines how to verify the Codex sovereign runtime in practice. + +## Verification Targets + +### 1. Launch Control + +Expected: + +- wrapper blocks dangerous bypass startup +- wrapper launches Codex with explicit approval and sandbox settings +- Codex executable resolution does not depend on `PATH` alone + +Manual checks: + +```powershell +& "C:\Users\CyberStrategy1\AppData\Local\OpenAI\Codex\bin\codex.exe" --version +powershell -ExecutionPolicy Bypass -File .\scripts\codex-jit-wrapper.ps1 -Profile sovereign +``` + +### 2. External Logging + +Expected: + +- `wrapper-sessions.log` created +- `notify.log` created when Codex emits notifications +- session summary written + +Check: + +- `C:\Users\\.codex\logs` +- fallback `.codex-runtime-logs` in the workspace + +### 3. Config Safety + +Expected: + +- scanner flags risky sandbox or approval settings +- audit script identifies binary drift and shell alias risk + +Manual checks: + +```powershell +powershell -ExecutionPolicy Bypass -File .\scripts\audit-codex-install.ps1 +powershell -ExecutionPolicy Bypass -File .\scripts\scan-dangerous-config.ps1 -SearchRoot "C:\path\to\repos" +``` + +### 4. Governance File Presence + +Expected in protected repos: + +- `IDENTITY.md` +- `SOUL.md` +- `AGENTS.md` +- `USER.md` +- `TOOLS.md` +- `SUBAGENT-POLICY.md` + +### 5. CI Enforcement + +Expected: + +- Codex invoked under explicit sandbox/approval settings +- no reliance on unsafe workstation defaults + +## Known Platform Caveats + +Observed during Windows validation: + +1. `codex` may not resolve from `PATH` in all PowerShell sessions. +2. writes to `~/.codex/logs` may fail in constrained contexts. +3. global `~/.codex/config.toml` mutation is less reliable than wrapper-scoped controls. +4. `Start-Process` can fail because of duplicate `Path` / `PATH` environment handling. + +These are design constraints for the package, not user mistakes. + +## Maturity Levels + +- `Level 1`: governance files present, audits runnable +- `Level 2`: wrapper launch working with external logs +- `Level 3`: CI enforcement active +- `Level 4`: optional post-run alignment scoring / drift review + +## Next Optimization Layer + +The next layer should borrow from `love_equation`: + +- event schema for cooperative vs defective runtime behavior +- Green/Yellow/Red session trust bands +- drift scoring over repeated sessions +- escalation thresholds for high-risk actions + +That should be implemented as a separate evaluation module, not merged into first-run workstation setup. diff --git a/examples/codex-sovereign-runtime/QUICKSTART.md b/examples/codex-sovereign-runtime/QUICKSTART.md index 1f91b4e..2859574 100644 --- a/examples/codex-sovereign-runtime/QUICKSTART.md +++ b/examples/codex-sovereign-runtime/QUICKSTART.md @@ -1,7 +1,11 @@ -# QUICKSTART -- 15-Minute Codex Sovereign Runtime Setup +# QUICKSTART -- 15-Minute Codex Sovereign Runtime v2 Setup This guide deploys the highest-priority AI SAFE2 controls for Codex with the current Codex runtime surface. +Default deployment mode: **wrapper-first**. + +Do **not** start by replacing your live global `~/.codex/config.toml` unless you are explicitly testing global integration on a non-production machine. + --- ## Step 0: Check Your Installed Codex Version @@ -16,29 +20,45 @@ If `codex` resolves from more than one location, treat that as inventory drift a --- -## Step 1: Install The Managed Codex Config +## Step 1: Install Monitoring And Governance Files -Back up your current user config, then copy a hardened baseline: +Install the external monitoring sink: ```powershell New-Item -ItemType Directory -Force -Path "$HOME\\.codex" | Out-Null -Copy-Item "$HOME\\.codex\\config.toml" "$HOME\\.codex\\config.toml.bak" -ErrorAction SilentlyContinue -Copy-Item ".\\managed-settings\\config.strict.toml" "$HOME\\.codex\\config.toml" -Force +New-Item -ItemType Directory -Force -Path "$HOME\\.codex\\monitoring" | Out-Null +Copy-Item ".\\monitoring\\codex-notify.ps1" "$HOME\\.codex\\monitoring\\codex-notify.ps1" -Force +``` + +Install the project governance files into the repo you want to protect: + +```powershell +Copy-Item ".\\AGENTS.md" "C:\\path\\to\\your-project\\AGENTS.md" -Force +Copy-Item ".\\IDENTITY.md" "C:\\path\\to\\your-project\\IDENTITY.md" -Force +Copy-Item ".\\SOUL.md" "C:\\path\\to\\your-project\\SOUL.md" -Force +Copy-Item ".\\USER.md" "C:\\path\\to\\your-project\\USER.md" -Force +Copy-Item ".\\TOOLS.md" "C:\\path\\to\\your-project\\TOOLS.md" -Force +Copy-Item ".\\SUBAGENT-POLICY.md" "C:\\path\\to\\your-project\\SUBAGENT-POLICY.md" -Force +Copy-Item ".\\EVALUATION.md" "C:\\path\\to\\your-project\\EVALUATION.md" -Force ``` -If you need team MCP servers, start from `managed-settings/config.team.toml` instead of weakening `config.strict.toml` ad hoc. +This is the project-local governance layer. It does not replace sandboxing or approvals; it shapes behavior and gives reviewers concrete artifacts to inspect. --- -## Step 2: Install The Hardened Project Policy +## Step 2: Confirm The Codex Binary Path -Copy the Codex-focused `AGENTS.md` into the project you want to protect: +On Windows, do not assume `codex` resolves from `PATH`. ```powershell -Copy-Item ".\\AGENTS.md" "C:\\path\\to\\your-project\\AGENTS.md" -Force +& "C:\Users\CyberStrategy1\AppData\Local\OpenAI\Codex\bin\codex.exe" --version ``` -This is the project-local behavioral policy layer. It does not replace sandboxing or approvals; it constrains the reasoning layer above them. +If that path differs on your machine, update the wrapper or use the detected path from: + +```powershell +Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\bin" +``` --- @@ -60,6 +80,8 @@ Optional: The wrapper blocks dangerous startup flags, creates session logs, enforces a timeout, and injects a notification sink for external evidence. +Current Windows note: timeout enforcement may be disabled in favor of stable launch behavior. Use session review and CI gates as the stronger enforcement layer for now. + --- ## Step 4: Audit Existing Codex Installations And Configs @@ -92,6 +114,7 @@ Expected outputs: - a session log under `%USERPROFILE%\\.codex\\logs` - a notification log entry - a summary file you can retain as audit evidence +- if home-directory logging is blocked, fallback logs under `.codex-runtime-logs` in the workspace --- @@ -99,12 +122,12 @@ Expected outputs: | Control | What It Does | |---|---| -| `config.strict.toml` | Keeps Codex in `workspace-write` with `on-request` approvals and minimal MCP exposure | -| `AGENTS.md` | Hardens the reasoning layer against prompt injection and unsafe execution norms | -| `codex-jit-wrapper.ps1` | Blocks dangerous launch flags, adds timeout, injects notification logging | +| Governance files (`IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `USER.md`, `TOOLS.md`, `SUBAGENT-POLICY.md`) | Define identity, constraints, tool surface, user data handling, and delegation rules | +| `codex-jit-wrapper.ps1` | Blocks dangerous launch flags, enforces approval/sandbox mode, injects notification logging | | `audit-codex-install.ps1` | Inventories binaries, aliases, configs, and MCP surfaces | | `scan-dangerous-config.ps1` | Flags unsafe approvals, sandbox modes, and config overrides | | `codex-notify.ps1` | Captures external completion metadata for audit evidence | +| `EVALUATION.md` | Defines the verification model and known platform caveats | --- @@ -127,4 +150,8 @@ Then: --- -*This quickstart is intentionally stricter than convenience defaults.* +## Optional: Global Config Integration + +If you explicitly want to test global Codex config integration, use files in `managed-settings/`, but treat that as advanced deployment. Validate on a non-production machine first. + +*This quickstart documents the v2 wrapper-first deployment model.* diff --git a/examples/codex-sovereign-runtime/README.md b/examples/codex-sovereign-runtime/README.md index c234761..d395fb2 100644 --- a/examples/codex-sovereign-runtime/README.md +++ b/examples/codex-sovereign-runtime/README.md @@ -1,8 +1,10 @@ -# Codex Sovereign Runtime +# Codex Sovereign Runtime v2 **Framework:** AI SAFE2 / AISM Level 4 (Sovereign Runtime Governance) -**Source Pattern:** Adapted from the Claude Code sovereign runtime example in the AI SAFE2 framework. +**Version:** 2.0 + +**Source Pattern:** Adapted from the Claude Code sovereign runtime example in the AI SAFE2 framework and optimized using the OpenClaw v2.0 governance model. **Audience:** Individual developers, SMBs, enterprise engineering teams using OpenAI Codex CLI or the Codex desktop app. @@ -46,16 +48,30 @@ Net: the Claude package is the correct **control philosophy**, but not the corre --- +## What Changed After Real-World Validation + +This package was tested against a live Windows Codex installation. That validation changed the design: + +- global `~/.codex/config.toml` mutation is now **optional**, not the default +- wrapper-scoped enforcement is the primary deployment mode +- Codex executable discovery must not rely on `PATH` alone +- logs and summaries must fail over to a local workspace directory +- profile-based launch controls are less reliable than explicit launch flags + +This is the same design lesson the OpenClaw example encodes at a higher maturity level: governance files help, but the strongest controls are the ones enforced at the execution boundary. + +--- + ## What This Package Implements ### The Five AI SAFE2 Pillars Applied To Codex ```text -Pillar 1: Sanitize & Isolate -> scripts/codex-jit-wrapper.ps1 + managed-settings/config.strict.toml -Pillar 2: Audit & Inventory -> scripts/audit-codex-install.ps1 + scripts/scan-dangerous-config.ps1 -Pillar 3: Fail-Safe & Recovery -> managed-settings/ + ci-cd/github-actions-codex-safe.yml -Pillar 4: Engage & Monitor -> monitoring/codex-notify.ps1 + monitoring/summarize-session.ps1 -Pillar 5: Evolve & Educate -> QUICKSTART.md + ARTICLE.md + AGENTS.md +Pillar 1: Sanitize & Isolate -> scripts/codex-jit-wrapper.ps1 + IDENTITY.md + TOOLS.md +Pillar 2: Audit & Inventory -> scripts/audit-codex-install.ps1 + scripts/scan-dangerous-config.ps1 + EVALUATION.md +Pillar 3: Fail-Safe & Recovery -> wrapper-scoped launch controls + ci-cd/github-actions-codex-safe.yml +Pillar 4: Engage & Monitor -> monitoring/codex-notify.ps1 + monitoring/summarize-session.ps1 + HEARTBEAT guidance in EVALUATION.md +Pillar 5: Evolve & Educate -> QUICKSTART.md + ARTICLE.md + SOUL.md + AGENTS.md ``` ### Controls Implemented @@ -63,15 +79,20 @@ Pillar 5: Evolve & Educate -> QUICKSTART.md + ARTICLE.md + AGENTS.md | Control | File | Risk Addressed | |---|---|---| | Deny dangerous bypass startup | `scripts/codex-jit-wrapper.ps1` | `--dangerously-bypass-approvals-and-sandbox` | -| Enforce approval + sandbox baseline | `managed-settings/config.strict.toml` | Overly broad execution | -| Narrow MCP inventory | `managed-settings/config.team.toml` | Adversarial or excess MCP exposure | +| Enforce approval + sandbox baseline | `scripts/codex-jit-wrapper.ps1` | Overly broad execution | +| Narrow MCP inventory | `managed-settings/config.team.toml` + `TOOLS.md` | Adversarial or excess MCP exposure | | Audit Codex installs and versions | `scripts/audit-codex-install.ps1` | Unknown runtime surface | | Scan risky config settings | `scripts/scan-dangerous-config.ps1` | Unsafe local overrides | | Notification-based external logging | `monitoring/codex-notify.ps1` | Invisible session outcomes | | Session summary and alert rollup | `monitoring/summarize-session.ps1` | Missing audit evidence | +| Identity anchoring | `IDENTITY.md` | Identity replacement and prompt role drift | +| User data classification | `USER.md` | Context-insensitive handling of sensitive user data | +| Subagent governance | `SUBAGENT-POLICY.md` | ACT-4 delegation drift and privilege sprawl | | Hardened project policy | `AGENTS.md` | Prompt injection and unsafe operator behavior | +| Operating constitution | `SOUL.md` | Value drift and inconsistent decision-making | | Fail-closed CI template | `ci-cd/github-actions-codex-safe.yml` | Unreviewed autonomous CI execution | | MCP review checklist | `integrations/mcp-allowlist.md` | Unvalidated external tools | +| Runtime validation checklist | `EVALUATION.md` | Unverified claims about what is actually enforced | --- @@ -82,7 +103,7 @@ WITHOUT this package: User Intent -> Codex internal policies -> Your workstation / repo / network WITH this package: - User Intent -> [Wrapper + Managed Config + AGENTS.md] -> Codex -> [External Notifications + Audits] -> Your infrastructure + User Intent -> [Wrapper + Core Governance Files + Audits] -> Codex -> [External Notifications + Evaluation] -> Your infrastructure ^ ^ | controls you own | logs Codex cannot retroactively rewrite ``` @@ -102,7 +123,7 @@ Codex's internal controls are still useful, but AI SAFE2 requires the runtime go | Codex with MCP servers | Yes | | Codex multi-agent workflows | Yes, with tighter governance | -**Desktop app note:** the app honors project `AGENTS.md` and Codex config behavior, but wrapper-enforced launch controls are strongest when you launch via CLI or CI. +**Desktop app note:** the app honors project governance files and Codex config behavior, but wrapper-enforced launch controls are strongest when you launch via CLI or CI. --- @@ -121,6 +142,7 @@ This pattern assumes **ACT-3** by default and **ACT-4** if you enable multi-agen | I am... | Start here | |---|---| | Individual developer hardening a workstation | [QUICKSTART.md](./QUICKSTART.md) | +| Security reviewer validating real enforcement | [EVALUATION.md](./EVALUATION.md) | | Team lead standardizing Codex configs | [managed-settings](./managed-settings/) | | Security engineer auditing developer setups | [scripts](./scripts/) + [monitoring](./monitoring/) | | CI owner protecting non-interactive runs | [ci-cd](./ci-cd/) | @@ -135,8 +157,24 @@ This pattern assumes **ACT-3** by default and **ACT-4** if you enable multi-agen - Notification logging is coarser than per-tool auditing. - Desktop app launches are harder to mediate than wrapper-launched CLI sessions. -These are platform constraints, not design omissions. The mitigation is to tighten launch controls, minimize MCP scope, keep `approval_policy = "on-request"` or stricter, and use CI for high-consequence actions. +These are platform constraints, not design omissions. The mitigation is to tighten launch controls, minimize MCP scope, keep launch-time approval/sandbox flags explicit, and use CI for high-consequence actions. + +--- + +## Core Governance Files + +Inspired by the OpenClaw v2.0 approach, this package now includes a minimal Codex core-file standard: + +- [IDENTITY.md](./IDENTITY.md): short identity anchor +- [SOUL.md](./SOUL.md): operating constitution +- [AGENTS.md](./AGENTS.md): primary operating manual +- [USER.md](./USER.md): data classification and trust handling +- [TOOLS.md](./TOOLS.md): environment and approved tool surface +- [SUBAGENT-POLICY.md](./SUBAGENT-POLICY.md): delegation rules for ACT-4 usage +- [EVALUATION.md](./EVALUATION.md): verification, drift checks, and known platform caveats + +This is deliberately smaller than the OpenClaw 11-file standard because Codex does not expose the same runtime surfaces. The goal is not file count parity. The goal is a tighter governance surface with real operational effect. --- -*Cyber Strategy Institute -- AI SAFE2 Framework adaptation for Codex* +*Cyber Strategy Institute -- AI SAFE2 Framework adaptation for Codex, v2* diff --git a/examples/codex-sovereign-runtime/scripts/codex-jit-wrapper.ps1 b/examples/codex-sovereign-runtime/scripts/codex-jit-wrapper.ps1 index cd142eb..4146210 100644 --- a/examples/codex-sovereign-runtime/scripts/codex-jit-wrapper.ps1 +++ b/examples/codex-sovereign-runtime/scripts/codex-jit-wrapper.ps1 @@ -19,6 +19,31 @@ function Resolve-LogRoot { } } +function Resolve-CodexPath { + $candidates = @() + + try { + $cmd = Get-Command codex -ErrorAction Stop + if ($cmd.Source) { + $candidates += $cmd.Source + } + } catch { + } + + $candidates += @( + (Join-Path $env:LOCALAPPDATA "OpenAI\Codex\bin\codex.exe"), + "C:\Program Files\WindowsApps\OpenAI.Codex_26.422.3464.0_x64__2p2nqsd0c76g0\app\resources\codex.exe" + ) + + foreach ($candidate in $candidates | Select-Object -Unique) { + if ($candidate -and (Test-Path -LiteralPath $candidate)) { + return $candidate + } + } + + return $null +} + function Write-Log { param( [string]$Path, @@ -26,7 +51,14 @@ function Write-Log { ) $timestamp = (Get-Date).ToUniversalTime().ToString("o") - Add-Content -LiteralPath $Path -Value "$timestamp | $Message" + try { + Add-Content -LiteralPath $Path -Value "$timestamp | $Message" + } catch { + $fallbackDir = Join-Path (Get-Location) ".codex-runtime-logs" + New-Item -ItemType Directory -Force -Path $fallbackDir | Out-Null + $fallbackPath = Join-Path $fallbackDir (Split-Path -Leaf $Path) + Add-Content -LiteralPath $fallbackPath -Value "$timestamp | $Message" + } } $logRoot = Resolve-LogRoot @@ -38,8 +70,22 @@ $sessionLog = Join-Path $logRoot "wrapper-sessions.log" $summaryPath = Join-Path $logRoot "$sessionId.summary.txt" $notifyScript = Join-Path $monitoringRoot "codex-notify.ps1" -if (-not (Get-Command codex -ErrorAction SilentlyContinue)) { - throw "codex is not available in PATH." +function Write-Summary { + param([string]$Content) + + try { + Set-Content -LiteralPath $summaryPath -Value $Content + } catch { + $fallbackDir = Join-Path (Get-Location) ".codex-runtime-logs" + New-Item -ItemType Directory -Force -Path $fallbackDir | Out-Null + $fallbackSummary = Join-Path $fallbackDir (Split-Path -Leaf $summaryPath) + Set-Content -LiteralPath $fallbackSummary -Value $Content + } +} + +$codexPath = Resolve-CodexPath +if (-not $codexPath) { + throw "Unable to locate codex.exe. Use the local OpenAI Codex install path or refresh PATH in a new shell." } $joinedArgs = ($AdditionalArgs -join " ") @@ -56,8 +102,13 @@ $configOverride = @( ) $codexArgs = @() -if ($Profile) { - $codexArgs += @("-p", $Profile) +switch ($Profile) { + "sovereign_strict" { + $codexArgs += @("-a", "untrusted", "-s", "read-only") + } + default { + $codexArgs += @("-a", "on-request", "-s", "workspace-write") + } } $codexArgs += $configOverride $codexArgs += $AdditionalArgs @@ -69,21 +120,11 @@ $env:CODEX_SOVEREIGN_LOG_ROOT = $logRoot Write-Log -Path $sessionLog -Message "SESSION_START | id=$sessionId | profile=$Profile | timeout=$SessionTimeoutSeconds | args=$joinedArgs" try { - $process = Start-Process -FilePath "codex" -ArgumentList $codexArgs -NoNewWindow -PassThru - $completed = $process.WaitForExit($SessionTimeoutSeconds * 1000) - - if (-not $completed) { - try { - Stop-Process -Id $process.Id -ErrorAction Stop - } catch { - } - Write-Log -Path $sessionLog -Message "SESSION_TIMEOUT | id=$sessionId | pid=$($process.Id)" - throw "Blocked by AI SAFE2: Codex session exceeded timeout of $SessionTimeoutSeconds seconds." - } - - $exitCode = $process.ExitCode - Write-Log -Path $sessionLog -Message "SESSION_END | id=$sessionId | exit_code=$exitCode" - "SessionId=$sessionId`nExitCode=$exitCode`nProfile=$Profile" | Set-Content -LiteralPath $summaryPath + Write-Log -Path $sessionLog -Message "SESSION_EXEC | id=$sessionId | codex_path=$codexPath | timeout_enforcement=disabled | mode=wrapper-first-v2" + & $codexPath @codexArgs + $exitCode = $LASTEXITCODE + Write-Log -Path $sessionLog -Message "SESSION_END | id=$sessionId | codex_path=$codexPath | exit_code=$exitCode" + Write-Summary -Content "SessionId=$sessionId`nExitCode=$exitCode`nProfile=$Profile" exit $exitCode } finally { } diff --git a/examples/codex-sovereign-runtime/setup-codex-safe.ps1 b/examples/codex-sovereign-runtime/setup-codex-safe.ps1 index c2240c6..b8c67e4 100644 --- a/examples/codex-sovereign-runtime/setup-codex-safe.ps1 +++ b/examples/codex-sovereign-runtime/setup-codex-safe.ps1 @@ -4,8 +4,10 @@ $targetRoot = Join-Path $HOME ".codex" $monitoringRoot = Join-Path $targetRoot "monitoring" New-Item -ItemType Directory -Force -Path $targetRoot, $monitoringRoot | Out-Null -Copy-Item ".\managed-settings\config.strict.toml" (Join-Path $targetRoot "config.toml") -Force Copy-Item ".\monitoring\codex-notify.ps1" (Join-Path $monitoringRoot "codex-notify.ps1") -Force -Write-Output "AI SAFE2 Codex setup complete." +Write-Output "AI SAFE2 Codex Sovereign Runtime v2 setup complete." +Write-Output "Installed: $HOME\.codex\monitoring\codex-notify.ps1" +Write-Output "Default deployment mode: wrapper-first." +Write-Output "Optional governance files should be copied into the target project root." Write-Output "Next step: launch .\scripts\codex-jit-wrapper.ps1" diff --git a/examples/codex-sovereign-runtime/setup-codex-safe.sh b/examples/codex-sovereign-runtime/setup-codex-safe.sh index f3114fc..01e3509 100644 --- a/examples/codex-sovereign-runtime/setup-codex-safe.sh +++ b/examples/codex-sovereign-runtime/setup-codex-safe.sh @@ -5,8 +5,10 @@ TARGET_ROOT="${HOME}/.codex" MONITORING_ROOT="${TARGET_ROOT}/monitoring" mkdir -p "$TARGET_ROOT" "$MONITORING_ROOT" -cp "./managed-settings/config.strict.toml" "${TARGET_ROOT}/config.toml" cp "./monitoring/codex-notify.ps1" "${MONITORING_ROOT}/codex-notify.ps1" -echo "AI SAFE2 Codex setup complete." +echo "AI SAFE2 Codex Sovereign Runtime v2 setup complete." +echo "Installed: ${HOME}/.codex/monitoring/codex-notify.ps1" +echo "Default deployment mode: wrapper-first." +echo "Optional governance files should be copied into the target project root." echo "Next step: run ./scripts/codex-jit-wrapper.sh"