Codex Preflight Guardian

A local-first Codex guard that detects risky repository commands, binds repairs to exact approval, and verifies safety before execution.

Comment

Inspiration

Coding agents routinely need to run dependency installs, build scripts, Docker commands, and repository-provided tooling. In an unfamiliar repository, one command can trigger hidden lifecycle scripts or a longer execution chain. I wanted Codex to have a local, evidence-based checkpoint before that happens.

What it does

Codex Preflight Guardian is a local-first Codex plugin workflow that statically analyzes both a repository and the command Codex is considering. It builds a bounded execution graph, detects dangerous capabilities and uncertainty, and returns a deterministic ALLOW, WARN, ASK_USER, or BLOCK decision.

The Guardian workflow adds bounded evidence for GPT-5.6 to explain, a closed remediation-plan schema, a stable content-derived planId, separate time-bound approval, single-use approval consumption, target-drift protection, isolated repair, and deterministic same-command verification. The scanner remains authoritative: GPT-5.6 can explain evidence and propose a plan, but it cannot change the policy decision, create approval, or authorize execution.

The plugin also reports its real protection mode. It claims Hook coverage only after a harmless live capability probe succeeds on the exact Codex version, operating system, surface, trust state, and tool path. Otherwise it reports skill-only or another bounded fallback instead of implying protection that was not verified.

Build Week contribution

The released v0.3.7 scanner was the baseline. During Build Week I added:

  • bounded and redacted guardian-context/v1 evidence;
  • explicit separation between deterministic findings and GPT advisory explanation;
  • closed guardian-remediation-plan/v1 plans with complete intended postimages;
  • stable planId identity and separate expiring, single-use approval records;
  • replay rejection, preimage validation, and target-drift checks;
  • capability-gated repair modes and verified-isolated-repair fallback;
  • deterministic before/after verification using the unchanged planned command;
  • self-contained Windows x64 and Linux x64 plugin runtimes;
  • a clean-install, zero-execution judge path using a synthetic fixture.

How it works

  1. Codex identifies a repository-dependent command.
  2. The local scanner treats the command as data and statically analyzes reachable files and capabilities.
  3. The deterministic engine returns a decision and bounded evidence.
  4. GPT-5.6 explains only that evidence and may propose an exact remediation plan.
  5. Local validation canonicalizes the plan and derives its planId.
  6. A separate human approval is bound to that exact plan, target, session, nonce, and expiry.
  7. Repair occurs only in a verified mode; unsupported edit surfaces use an isolated target with complete postimage comparison.
  8. Approval replay is rejected and the same command identity is rescanned.
  9. Real command execution still requires a separate final decision.

Demo and safety result

The submitted video shows the conservative Windows skill-only path. Codex scans a public synthetic npm postinstall fixture, returns BLOCK / 50 for NODE_LIFECYCLE_REMOTE_EXEC, explains the evidence, and refuses an informal repair approval because the installed v0.3.7 workflow does not expose the required digest-bound remediation authority. No package manager, lifecycle script, remote content, or repository command is executed.

The repository's completed Guardian conformance evidence separately records the full bounded path: one approval record, one consumption, replay rejected, only package.json changed inside an isolated target, the approved postimage matched, and the unchanged command rescanned from BLOCK / 50 to ALLOW / 0. Planned-command, package-manager, fixture, and test-network execution counters remained zero.

How I used Codex and GPT-5.6

Codex was the working interface throughout the Build Week implementation: it helped inspect the existing safety boundaries, implement and test the Guardian contracts, package the cross-platform plugin runtimes, run exact-head validation, and prepare the demonstration. GPT-5.6 was also used inside the product workflow for advisory explanation and remediation-plan proposal, always constrained by deterministic evidence and local validation.

Challenges

The hardest problem was being honest about capability boundaries. A shell may use Bash while the model-visible tool is still exec_command, so a ^Bash$ Hook matcher must not be described as active without a real event probe. The same issue applies to edit enforcement. The solution was to make protection and repair modes explicit, fail closed on incomplete authority, and preserve a safe isolated fallback.

Accomplishments

  • Deterministic policy remains the sole authority.
  • Exact plan identity is separate from approval.
  • Approval is expiring, target-bound, and single-use.
  • Replay and target drift fail closed.
  • The completed flow verifies BLOCK / 50 -> ALLOW / 0 without executing the planned command.
  • Judges can install a self-contained plugin without rebuilding it or configuring another API key.

What I learned

Security claims need runtime evidence, not configuration inference. Tool identity, platform, trust state, and actual interception behavior matter more than the name of the underlying shell. Separating deterministic policy from model explanation made the system both safer and easier to explain.

What's next

Expand live Hook coverage only where exact-surface probes prove it, add more supported packaged platforms, and continue growing the synthetic corpus and execution-chain coverage without weakening the local-first trust boundary.

Judge installation and testing

Supported packaged platforms: Windows x64 and Linux x64. The standalone source workflow requires Python 3.12 or newer.

  1. Add https://github.com/Gengetau/codex-preflight.git as a Codex marketplace using ref codex/v0.4.0-build-week-guardian and sparse paths .agents/plugins and plugins/codex-preflight.
  2. Install codex-preflight@codex-preflight and restart Codex so the Skill, MCP definition, Hook definition, and bundled runtime reload.
  3. Follow BUILD_WEEK.md in the public branch. It includes the exact capability boundary, installation path, synthetic fixture, expected decisions, completed conformance evidence, and zero-execution safety counters.
  4. No credentials, external API key, cloud backend, or local web server are required.
  5. Report Hook coverage only if the harmless live probe succeeds on the exact judge surface; otherwise use the documented skill-only read-only path.

Built With

  • codex
  • fastmcp
  • github-actions
  • gpt-5.6
  • json-schema
  • node.js
  • pyinstaller
  • python
Share this project:

Updates