Use Codex Security to scan code, investigate a supplied finding, or make and verify a security fix. Choose the task that matches the evidence you already have; a repository scan is the default when you are looking for new findings.
Open your repository in Codex. Find Codex Security in the desktop plugin
browser, or enter /plugins in the interactive Codex CLI. Install the plugin,
confirm it is enabled, and start a new chat. See the
plugin quickstart for host setup
and access requirements.
Ask for the task in plain language, including the repository or paths and any security context:
Scan this repository with Codex Security. Focus on authorization boundaries, use the existing SECURITY.md, and return the saved report and coverage limits.
The task map below also gives explicit skill names. Local scans do not require the optional Cloud connection. To read existing Cloud findings, follow the separate Cloud setup.
The terminal package includes the plugin used by its own scans. You can follow the CLI quick start without setting up an interactive Codex plugin session.
| Task | In Codex | From the terminal |
|---|---|---|
| Scan a repository or selected paths | Ask for a Standard scan ($security-scan). |
cs scan . or cs scan . --path src |
| Review a PR, commit, branch diff, or working-tree patch | Ask for $security-diff-scan with the change to review. |
cs scan . --diff origin/main for committed changes, or cs scan . --working-tree for local changes. |
| Run repeated audits of the same target | Ask for $deep-security-scan. Later audits use findings from earlier ones. |
cs scan . --mode deep |
| Assess supplied findings against the source | $triage-finding returns a verdict and any missing evidence for each claim. |
cs validate findings.json returns a validation report. |
| Investigate a dependency alert | Give $resolve-dependency-alert the alert and the checkout or image. It traces the dependency and proposes an upgrade or dismissal where the evidence supports one. |
To retrieve a saved alert for that review, see below. |
| Prepare a fix | Ask $fix-finding to patch a specific finding in the affected repository. |
cs patch --scan SCAN_ID |
| Check an existing fix | Give $verify-fix the finding and current checkout. |
cs verify-fix --scan SCAN_ID |
| Track a validated finding | Give $track-findings the finding and destination. See plugin connectors. |
For completed scans, see publishing to Linear. |
| Inspect a downloaded skill | Review the skill before installation in a trusted Codex chat. | Use the interactive Codex CLI with the plugin enabled. |
Read a saved dependency alert. Run cs findings imported ./project --format json
to list the records saved for that checkout. Give the relevant record to
$resolve-dependency-alert to check installed versions and upgrade options.
To bring in an alert from your scanner, use the scanner import guides.
A scan or triage request produces findings. Ask to fix a specific finding when
you want a patch. A separate fix verification reports fixed,
still_vulnerable, or inconclusive with evidence.
Existing root and component SECURITY.md files already guide scans. Use
policy generation to draft or update one.
To review a skill before giving it to a coding agent, ask
$check-skills directly:
Use $check-skills on ../downloaded-skills before I install them in Claude Code.
Start the chat in a trusted workspace with the Codex Security checker enabled.
Keep the downloaded checkout outside the host's skill discovery paths and pass
its path to the checker. If you already opened the checkout as your workspace
or enabled its skills, start a clean chat with the target outside discovery.
The previous chat may have loaded its AGENTS.md or a replacement checker.
Point it at a file, an extracted bundle, a checkout containing several skills, or paste the skill text. It returns a per-skill PASS, REVIEW, BLOCK, or INCOMPLETE with source evidence and coverage limits. A file review covers only that file. Supply the folder to include helpers and references. The review does not install the target or require the plugin MCP server.
Open the report at the path in the completion summary. Read the source
locations and validation evidence for each finding. Check the
scan.review.excludedPaths list in scan-manifest.json for additional
exclusions. To find the files selected for discovery, check the retained
scope list.
A report with zero findings can still list exclusions or unresolved questions. Static triage reports what the source supports. An inconclusive fix verification identifies what evidence would resolve the question.
For automation, scan exit codes distinguish these outcomes:
0: the scan completed without triggering a configured findings threshold.1: findings meet the configured--fail-on-severitythreshold.2: execution, target-integrity, or required-output failure.
Coverage gaps and investigation notes do not by themselves fail a completed scan. See scan output and SDK results for the saved fields and failure output.
If your scan retained artifacts/02_discovery/in_scope_files.txt, open it in
the saved results directory. It lists the paths selected for discovery. For a
scan between two commits, find baseRevision and headRevision under
scan.target in the saved scan-manifest.json. In your Git client, compare
the two commit trees directly (base..head). A three-dot PR comparison uses
the merge base and can show different files when the commits have diverged.
Current diff scans select regular text files regardless of extension. Git can
also list changes to binary files, symlinks, and submodules.
Plugin 0.1.32 could omit changed Perl files (.cgi, .pl, .pm, and .t).
CLI 0.3.0 was the first release to bundle the fix. To repeat the scan with
that version or later, use a clean, full checkout at the original head.
Select the same two commits from your repository,
passing the base to --diff and the head to --head. See the
CLI quick start.
The full plugin, generated CLI skills, and CLI MCP registration serve different purposes:
| Integration | What it provides |
|---|---|
| Codex Security plugin | The security workflow skills above, their MCP tools, and optional connected apps. |
cs skills add |
Generated guidance for an agent using CLI commands. This does not install the full security plugin. |
cs mcp add |
The CLI's read-only info tool. It does not expose scan or patch tools; this transport cannot cancel active commands. |
An agent using the terminal can discover current commands and their schemas:
cs --llms
cs scan --schema --format json
cs scan --helpChoose a connected app or CLI integration for your destination. See the CLI reference for command discovery and output formats.
| Symptom | Next step |
|---|---|
cs is missing or opens another program |
Check that npm’s executable directory is on PATH, or use codex-security or npx @openai/codex-security. See CLI setup. |
| Codex shows CLI guidance but no security workflow skills | Install and enable the full plugin in your host, then start a new chat. |
| A skill is visible but its scan tools are unavailable | Check the plugin server’s setup error and resolve it before starting a scan. |
| Authentication fails on a headless machine | Use device or SSH login, or configured API credentials for CI. |
If Codex stops waiting for a Deep Scan in chat, ask it to continue the same scan ID. The scan can keep running after the turn ends. If a scan reports an error, keep its ID, output directory, and error message.
For terminal scans, inspect an explicit ID so history commands refer to the same run:
cs scans show SCAN_ID
cs scans logs SCAN_IDWithout an ID, scans show selects the latest completed scan, while scans logs
selects the latest scan of any status. An interrupted Deep Scan still marked
running can use cs scans resume SCAN_ID with its original checkout, output,
session, and state directory. Completed, failed, and canceled scans need a new
attempt with cs scans rerun SCAN_ID. A rerun uses the current checkout and may
need the original custom prompt files supplied again. See
resume requirements
and runtime troubleshooting.