OpenAI Codex MCP security workflow for PR reviews

Current setup: follow the Codex integration guide with pinned @lyrashield/mcp@0.2.12 and authenticate local stdio separately using npx -y lyrashield@0.2.14 login --oauth. The Agent Plugin package 0.1.31 is published; its public listing and authenticated client runtime acceptance remain pending. Use pinned CLI commands for documented config or skill installs; marketplace plugins remain separately gated. Confirm client discovery, then make an authenticated read-only workspace call.

You can review AI generated pull requests in Codex with evidence-state AppSec findings by connecting LyraShield AI through MCP, running a targeted scan from your Codex session and enforcing the same policy in CI with a diff aware gate. The config lives in ~/.codex/config.toml and supports both local stdio and remote HTTP with a bearer token.

OpenAI Codex excels at large refactors, but refactors can introduce auth bypasses, injection and vulnerable dependencies that are hard to spot in a diff. The vibe coding security guide describes why AI built code needs findings with recorded evidence states instead of noisy lint. LyraShield AI is agent native AppSec for AI built software that follows Target to Scan to Evidence State to Fix Proposal to Retest to Assurance Report. This guide gives you the exact ~/.codex/config.toml entries for local and remote MCP using npx -y @lyrashield/mcp@0.2.12 and https://app.lyrashieldai.com/api/mcp, plus verification, inline checks and a GitHub Action. Findings retain their recorded evidence states. Current LyraShield tools record fix proposals and queue retests but do not edit code, create branches or open pull requests.

1. Prerequisites and setup

Use a current Codex release, Node 24 or newer, an authorized LyraShield workspace and a repository you may review. Run npx -y lyrashield@0.2.14 login --oauth in the same OS account as Codex; the local stdio adapter reads the selected workspace credential store. Codex loads MCP from ~/.codex/config.toml, as described in the official Codex MCP guide. Keep credentials out of committed configuration. Register the configured server, then use codex mcp list to confirm tool discovery. Review baseline risks through OWASP Top 10 and weak config guidance from CISA secure by design. For dependency risk, browse OSV to see how advisories map to versions. The Model Context Protocol spec explains how tools like scan and list_findings are exposed. Every Codex session reads ~/.codex/config.toml on startup, so one edit registers MCP tools for all projects. A workspace API key is a separate CI/headless fallback, stored in a private secret manager.

2. Configure Codex MCP servers

Edit ~/.codex/config.toml to register LyraShield. The canonical pattern is in the OpenAI Codex integration guide. Do not write bare internal paths in your own docs, link them as OpenAI Codex integration guide.

Local stdio example:

[mcp_servers.lyrashield]
command = "npx"
args = ["-y", "@lyrashield/mcp@0.2.12"]
startup_timeout_sec = 20
tool_timeout_sec = 120

Optional remote read-only API-key alternative:

[mcp_servers.lyrashield_remote]
url = "https://app.lyrashieldai.com/api/mcp"
bearer_token_env_var = "LYRASHIELD_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 120

An API key grants read calls only on this hosted connection; scans and retests require a browser-confirmed OAuth delegation. Local CLI login authenticates stdio separately. See the current remote MCP guide for hosted OAuth. The remote URL is https://app.lyrashieldai.com/api/mcp with Authorization: Bearer lsk_... derived from the token env var. The config uses the pinned npx form and exposes env expansion through bearer_token_env_var which Codex resolves at runtime. If you are comparing editor flows, the related Codex security workflow checklist shows a similar gate pattern and sibling editors are covered in guides like the Cline AI app security checklist for team wide rollout.

The local stdio entry is useful when Codex should spawn the npm package as a child process. The remote HTTP entry uses url and bearer_token_env_var, so Codex reads the token from the launching environment without storing it in TOML. Local and remote entries have different schemas: do not add command to the remote entry or use an env_vars table for explicit values. Keep startup_timeout_sec at 20 so cold starts of npx do not trip the watchdog and raise tool_timeout_sec to 120 for large repos.

3. Verify the connection in Codex

Start a new Codex session with codex --verbose and run codex mcp list or ask the agent “list MCP servers”. You should see lyrashield and lyrashield_remote as available. Call lyrashield_list_workspaces and confirm the intended workspace. If local stdio fails, check CLI OAuth login, the OS account and the Node path; an optional remote API-key connection needs its own credential. Discovery alone does not establish authentication. Common failure is launching Codex from a GUI that does not inherit shell env. For auth debugging, the OpenAI platform docs discuss bearer handling and docs.github.com on encrypted secrets covers secret propagation for CI parity. Reopen Codex after package upgrades so npx resolves the current package. If bearer_token_env_var is set but the env var is empty, Codex connects without auth and the server rejects calls with a 401, which shows as a tool error rather than a crash.

4. Run an inline scan from a Codex session

In your Codex prompt, target the authorized workspace and request a focused scan. Ask for every finding’s recorded evidence state, supporting evidence, file location, CWE and limitations. Call lyrashield_scan_target, then use lyrashield_get_findings; do not request “verified findings only”: current scans do not produce the reserved independent VERIFIED status, and detection and retest validation are distinct outcomes.

A finding retains its recorded evidence state, supporting detail, file location, CWE, severity and limitations when available. Evidence strength and reproducibility depend on that state; detection alone does not imply a reachable sink, a confirmed vulnerable call path or a retest-confirmed outcome. When you ask the agent to show findings, request the evidence block so the PR reviewer can assess the same recorded context without rerunning the scan. A retest-confirmed outcome still requires a fresh applicable retest.

Example Codex instruction you can paste:

Use lyrashield MCP to scan this repo diff against main.

- Return findings with their recorded evidence states, supporting evidence and fix guidance.
- Group by risk: auth, injection, secrets, supply chain
- Record the intended remediation with `lyrashield_record_fix_proposal`; do not claim that LyraShield generated or applied a patch.

lyrashield_record_fix_proposal stores a remediation summary; it does not produce a patch. After a developer changes the code, lyrashield_verify_fix queues a retest and returns a scan reference to poll.

5. Wire the GitHub Action diff aware gate

Add .github/workflows/lyrashield.yml to enforce the same policy on pull requests. This keeps Codex refactor safety aligned with CI and surfaces SARIF in code scanning as described in GitHub docs for SARIF upload.

name: lyrashield diff gate
on:
  pull_request:
    branches: [main]
permissions:
  contents: read
  security-events: write
  pull-requests: write
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: ecryptoguru/lyrashield-ai@v2
        with:
          fail_on_severity: HIGH

The Action derives a pull-request diff and limits its advisory checks to changed files, which is useful for Codex-generated PRs that touch many files. Its SARIF results do not carry hosted finding IDs or evidence states. Add a branch-protection rule for the local gate and run a separate recorded scan when you need retained coverage, evidence or retest semantics.

6. Add agent rules snippet for Codex

Review or extend the project AGENTS.md so every Codex agent run follows the same loop.

# Security loop for Codex

- Identify Target: app root, entry routes, data classification.
- Scan via LyraShield MCP before final answer on refactors.
- Summarize findings with recorded evidence states only, with evidence path and CWE.
- Record a fix proposal, apply the code change outside LyraShield, then queue and poll a retest.
- Append Report section: scan ID, SARIF file, policy version.

This rule file codifies Target to Scan to Evidence State to Fix Proposal to Retest to Assurance Report. It tells Codex to preserve evidence states, use lyrashield_record_fix_proposal only for the remediation record and use lyrashield_verify_fix only to queue a retest after code changes are applied. Neither tool writes code or opens a branch or pull request.

Step	Codex action	LyraShield MCP tool	Output
Target	Identify app root and risk areas	lyrashield_list_targets	target inventory
Scan	Run scoped scan via MCP	lyrashield_scan_target	SARIF + findings
Verify	Triage with evidence	lyrashield_get_findings	findings + evidence states
Fix and retest	Propose patch and rerun	lyrashield_record_fix_proposal, lyrashield_verify_fix	proposal record + retest status
Report	Summarize in PR body	lyrashield_create_report	audit note

7. Why pair Codex with LyraShield

Codex accelerates code change; LyraShield adds an evidence-driven verification layer. The vibe coding security guide explains how fast scaffolding without verification leaves injection and authorization gaps that appear late. The implemented product covers scans, SCA, secrets, findings and evidence, approval-gated fix proposals, retests, reports, MCP and the runner-local GitHub Action. Codex owns the change and LyraShield owns the evidence, so a recorded finding can move from editor review to retest without changing semantics. Automatic server-generated Fix PR execution is not enabled and the local Action remains an advisory diff gate rather than a recorded hosted scan.

Adopt this by configuring Codex MCP, running one bounded scan on your next AI-generated change, recording a reviewed fix proposal, applying the code change yourself and polling the queued retest. Expand with the AI app security checklist, then create an account at LyraShield AI.