Run a Codex Security scan
Start with a standard Codex Security scan for an initial review or a routine repository or component assessment. It runs the full scan workflow once.
For a more thorough assessment, review the results and then run a deep scan. Deep scans take longer and search more extensively.
Choose the scan area
Scan the whole repository when you need broad coverage and the repository is a reasonable review unit:
Use $codex-security:security-scan to scan this repository for security vulnerabilities.
Scan a folder when a monorepo is too large or one service, package, or component has a clear owner and security boundary:
Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.
For a large monorepo, start with one meaningful product or service boundary.
Configure the scan
- Confirm Scan type is
Codebaseand leave Deep scan off. - Confirm the Codebase, Current branch, and Last commit.
- Set Scan area to
Entire codebaseor enter one repository-relative folder. - Add threat-model guidance only when it changes the review. Useful guidance names attacker-controlled inputs, trust boundaries, sensitive actions, or a specific area to prioritize.
- Select Start scan.
Add SECURITY.md to the repository root for persistent security guidance.
Describe the threat model, security invariants, reportable finding criteria,
exclusions, and severity context. Add nested SECURITY.md files for
directory-specific guidance. When policies conflict, the file closest to the
code takes precedence. Codex Security treats these files as policy context,
not executable instructions.
Use AGENTS.md for supported build and validation commands and other
repository-specific instructions.
Let the phases complete
A scan runs these phases in order:
- Threat modeling identifies assets, entry points, trust boundaries, and security invariants.
- Finding discovery reviews the requested code for plausible broken controls and source-to-sink paths.
- Validation tests or otherwise checks each candidate and records evidence or proof gaps.
- Impact and path analysis evaluates each candidate's realistic paths, impact, and severity.
- Detailed reporting creates one source-backed vulnerability report per reportable finding, with supporting proof-of-concept files when available.
- Structural hardening analyzes the complete finding set and creates a design portfolio when reportable findings remain.
- Finalization validates the structured scan contract and generates
report.md, which links the detailed reports and hardening portfolio.
Codex reports phase and coverage progress as the scan runs. Wait for the complete result instead of judging early candidates or stopping because one phase takes longer than another.
Review the completed scan
Review the result in this order:
- Confirm the target, revision, and scan area.
- Read reviewed surfaces and every explicit deferred or follow-up area.
- For each finding, inspect the root control or sink, attacker-controlled input, validation method, remaining uncertainty, realistic reachability, severity rationale, and proposed remediation.
- Dismiss findings whose evidence doesn't support the claimed path or impact.
- Select one accepted finding before starting a fix.
Reopen or rerun a previous scan
In the ChatGPT desktop app, open a completed scan from the security scan list to review its saved findings workspace. To update the results, rerun the saved configuration against the current code. The rerun creates a new scan and leaves the earlier scan and its artifacts unchanged.
Scan history, rerun controls, and other workspace features depend on your Codex surface and installed plugin version. A rerun doesn't pin that version or guarantee that interrupted work will resume after a plugin update. Check the plugin changelog before you start or rerun a long-running scan.
Use the results
Use the findings workspace to review findings, coverage, and follow-up areas
without inspecting raw JSON. Open report.md for the readable entry point to
the complete scan directory. Keep the directory together when you share or
archive it: the report links to detailed reports in findings/ and, when
reportable findings exist, structural hardening guidance in hardening/.
Behind the workspace, each scan preserves scan-manifest.json, findings.json,
and coverage.json for automation and integrations. You normally don't need to
open these files yourself.
The findings workspace can also create portable JSON, CSV, and SARIF files. See Export or track findings.
Next step
After you accept a finding, use Fix and verify a finding to generate and review one bounded patch. Don't ask Codex to fix every finding from a scan in one chat.