codex-security-review

name	codex-security-review
description	Security-focused code review using OWASP Top 10 and CWE patterns. Detects vulnerabilities through adversarial debate.

Codex Security Review

Purpose

Security-focused review identifying vulnerabilities aligned with OWASP Top 10 2021 and common CWE patterns.

When to Use

When changes touch auth, crypto, SQL, user input, file uploads, or APIs. Complements /codex-impl-review.

Prerequisites

• Working directory with source code. Optional: dependency manifests for supply chain analysis.

Runner

RUNNER="{{RUNNER_PATH}}" SKILLS_DIR="{{SKILLS_DIR}}" json_esc() { printf '%s' "$1" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(JSON.stringify(d)))'; }

Critical Rules (DO NOT skip)

• Stdin: printf '%s' "$PROMPT" | node "$RUNNER" ... -- NEVER echo. JSON via heredoc.
• Validate: init output must start with CODEX_SESSION:. start/resume must return valid JSON. CODEX_NOT_FOUND->tell user install codex.
• status === "completed" means Codex's turn is done -- NOT that the debate is over. MUST check Loop Decision table.
• Loop: Do NOT exit unless APPROVE or stalemate. No round cap.
• Errors: failed->retry once (re-poll 15s). timeout->report partial, suggest lower effort. stalled+recoverable->stop->recovery resume->poll; not recoverable->report partial. Cleanup sequencing: finalize+stop ONLY after recovery resolves.
• Cleanup: ALWAYS run finalize + stop, even on failure/timeout.
• Runner manages all session state -- NEVER read/write session files manually.
• For detailed error flows -> Read references/protocol.md

Workflow

1. Collect Inputs

Scope: working-tree (staged/unstaged), branch (diff vs base), or full (entire codebase). Auto-detect via git status --short and git rev-list. Effort: <10 files=medium, 10-50=high, >50=xhigh. Announce defaults. Scope guide: working-tree=pre-commit, branch=pre-merge, full=security audit.

2. Pre-flight

Working-tree: changes must exist. Branch: diff must exist. Full: no pre-flight needed.

3. Init + Render + Start

Init: node "$RUNNER" init --skill-name codex-security-review --working-dir "$PWD" Render (nested): First render scope template (working-tree/branch/full) with BASE_BRANCH. Then render template=round1 with WORKING_DIR, SCOPE, EFFORT, BASE_BRANCH, SCOPE_SPECIFIC_INSTRUCTIONS. Start: printf '%s' "$PROMPT" | node "$RUNNER" start "$SESSION_DIR" --effort "$EFFORT"

4. Poll -> Apply/Rebut -> Resume Loop

Poll + report activities. Parse review.blocks[] (id, title, severity, category, confidence, cwe, owasp, problem, evidence, attack_vector, suggested_fix). Risk summary in review.verdict.risk_summary. Fallback: review.raw_markdown. Present grouped by severity (Critical->High->Medium->Low). Critical/High=blocking; Medium/Low=advisory.

• Valid -> fix vulnerabilities, verify fixes.
• False positives -> rebut with mitigating controls.
• Branch mode: commit fixes before resume. Render template=round2+, placeholders: FIXED_ITEMS, DISPUTED_ITEMS. Resume: printf '%s' "$PROMPT" | node "$RUNNER" resume "$SESSION_DIR" --effort "$EFFORT". Back to Poll.

#	Condition	Action
1	verdict === "APPROVE"	EXIT -> step 5
2	convergence.stalemate === true	EXIT -> step 5 (stalemate)
3	verdict === "REVISE" or open issues	CONTINUE -> Apply/Rebut

5. Completion + Output

APPROVE -> done. Stalemate -> present deadlocked issues, ask user. Report: Rounds, Verdict, Risk Level, Issues Found/Fixed/Disputed. Risk Summary: Critical/High/Medium/Low counts with fixed/open breakdown. Present: fixed vulnerabilities, disputed items, residual risks, blocking vs advisory, recommended next steps (dynamic testing, pentest).

6. Finalize + Cleanup

finalize + stop. Always run. (-> references/protocol.md for error handling)

Flavor Text Triggers

SKILL_START, POLL_WAITING, CODEX_RETURNED, APPLY_FIX, SEND_REBUTTAL, LATE_ROUND, APPROVE_VICTORY, STALEMATE_DRAW, FINAL_SUMMARY

Rules

• If in plan mode, exit first -- this skill requires code editing.
• CWE + OWASP mappings for all findings. Include attack vector. Mark confidence level.
• Every accepted issue -> concrete code diff. Never claim 100% security coverage.