Governance hooks: configurable policies, threat detection, and audit trails

Proposal: Governance Hooks for Codex CLI

Summary

Add configurable governance hooks that allow organizations to enforce tool policies, detect threats, and generate audit trails when Codex executes code and commands.

Motivation

Codex is a powerful terminal coding agent that executes shell commands, writes files, and modifies codebases. For enterprise adoption, organizations need:

1. Command policies — Allowlist/blocklist shell commands, restrict file paths, limit network access
2. Threat detection — Flag data exfiltration patterns (curl | base64, env var access, credential harvesting), privilege escalation (sudo, chmod 777), and destructive operations (rm -rf /, DROP TABLE)
3. Audit trails — Immutable log of every command executed, file modified, and policy decision made
4. Configurable governance levels — From permissive (log only) to strict (block + require approval)

Proposed Design

A .codex/governance.yaml file in the project root:

governance:
  level: moderate  # permissive | moderate | strict | paranoid
  
  commands:
    allowed: ["git", "npm", "python", "node", "cat", "ls", "grep"]
    blocked: ["rm -rf /", "curl * | bash", "eval"]
    require_approval: ["sudo", "docker", "kubectl"]
  
  files:
    writable_paths: ["src/", "tests/", "docs/"]
    protected_paths: [".env", "*.key", "*.pem", ".git/"]
    
  network:
    allowed_hosts: ["registry.npmjs.org", "pypi.org"]
    block_outbound: false
    
  audit:
    enabled: true
    log_path: ".codex/audit.jsonl"
    include_command_output: false  # For compliance
    
  limits:
    max_commands_per_session: 200
    max_file_modifications: 50
    max_lines_changed: 5000

Hook Points

1. pre-command — Before executing any shell command, validate against policy
2. pre-file-write — Before modifying any file, check path restrictions
3. post-command — Audit the result, check for sensitive output
4. on-violation — Block execution, log violation, optionally request human approval

Use Cases

• Enterprise SOC: Security teams configure governance levels per-repo
• CI/CD Safety: Codex in CI pipelines with strict policies (no network, no secrets)
• Compliance: JSONL audit trail for SOX/SOC2 reporting
• Developer Safety: Prevent accidental destructive commands in production repos

Context

We maintain Agent-OS governance framework and have proposed similar patterns across the agent ecosystem:

• anthropics/claude-agent-sdk-python #587 — Governance hooks
• google/adk-python #4543 — GovernancePlugin
• openai/openai-agents-python — Already built trust integration