Run a deep security scan
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.mdto the page URL.
Run a deep scan when you need a more thorough review and can allow for a longer runtime. Deep scans search a repository more extensively and can reduce variability between runs.
Start with a standard scan to check your scope and results. Then use a deep scan when you need a more thorough assessment.
Choose between standard and deep scans
| Standard scan | Deep scan | |
|---|---|---|
| Best for | First runs and routine repository or folder review | More thorough reviews after a standard scan |
| Variability | Standard | Reduced |
| Scope | Repository or explicit folder | Repository or explicit folder |
| Runtime and resources | Lower | Higher |
| Pull requests and diffs | Use the change-review workflow | Not supported; use the change-review workflow instead |
Configure deep-scan runtime
To control a deep scan's concurrency and duration, create or edit
~/.codex/codex-security/config.toml. If you set CODEX_HOME, use
$CODEX_HOME/codex-security/config.toml instead.
For example, this profile runs a shorter scan with limited concurrency:
[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5
| Setting | Default | Description |
|---|---|---|
workers |
4 |
Number of independent standard-scan workers allowed to run at the same time. Legacy "auto" also resolves to 4. |
subagents |
3 |
Number of subagents each worker may start. Set 0 to disable them. |
stop_after_no_new |
4 |
Stop after this many consecutive completed worker scans produce no new findings. |
stop_after_consecutive_errors |
3 |
Stop after this many consecutive worker errors. |
max_discovery_runs |
40 |
Limit the number of independent standard-scan runs before aggregation. |
max_time_hours |
96 |
Limit worker execution to a positive number of hours up to 96; use fractions as needed. |
Lower values can reduce scan time and token use but may miss findings. Configuration changes apply to new deep scans, not scans already in progress.
When the time limit expires, Codex Security stops unfinished workers, keeps completed scan results, and aggregates them into the final report. If no worker finishes source review before the deadline, the report records partial coverage.
The max_time_hours setting requires plugin version 0.1.19 or later. See the
plugin changelog for release details.
Start the deep scan
In the desktop app, open Security, select Scans, and select + Scan. Choose a repository or another folder, select Codebase, and turn on Deep scan. The scan covers the entire selected repository or folder.
You can also start a repository-wide deep scan from a Codex conversation:
Use $codex-security:deep-security-scan to run a deep security scan of this repository.
For one component in a monorepo, identify the folder explicitly:
Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.
For a scoped deep scan in the desktop app, select the folder as the codebase. The scan covers the entire selected folder.
Confirm setup and preflight
For the best scan quality, use gpt-5.6-sol
with xhigh reasoning effort.
- Select Codebase and turn on Deep scan.
- Confirm that the repository or selected folder is the code you intended to scan.
- Choose a model and reasoning effort.
- Open Additional context for concrete attack vectors, sensitive application areas, or repository context that the code can't reveal.
- Select Start scan.
Deep scan workers inherit your selected model and reasoning settings. Each worker runs a complete standard scan, and Codex Security aggregates the completed results. Follow the saved scan from Scans, or select View activity to inspect its Codex task. Check the plugin changelog before you update the plugin or start a long-running scan.
Review the result
Deep scans use the same saved scan details and complete scan directory as
standard scans. Open the completed scan in Scans or review its findings in
Findings. The generated report.md links to detailed vulnerability reports
or structural hardening guidance when you request those outputs.
Keep any linked findings/ and hardening/ directories with the report when
sharing or archiving the result.
Review the coverage summary before the findings. Even a deep scan has limits, so check deferred surfaces and remaining proof gaps before drawing a conclusion. For a finding you accept, continue with Fix and verify a finding.
To review a pull request, commit, branch range, or local patch, use Review code changes. A deep scan never substitutes for the diff-focused workflow.