---
name: codex-security
description: Scan repositories for security vulnerabilities with OpenAI Codex Security via the security_scan tool. Use when the user asks to audit, scan, or review code for vulnerabilities, check for CVEs/injection/Secrets, review a diff or PR for security issues, or fix findings from a previous scan.
---

# Codex Security

Find, validate, and fix security vulnerabilities using the `security_scan` tool (wraps `@openai/codex-security`).

## Prerequisites

- Node.js >= 22 and Python >= 3.10 on the machine.
- Authentication: interactive `npx codex-security login` (ChatGPT) or `OPENAI_API_KEY`/`CODEX_API_KEY` for CI.
- If unsure, call the `security_auth_status` tool first. If a scan fails with an auth error, check status and tell the user exactly how to sign in.

## Choosing the scan target

- Whole repo audit: `security_scan` with no `path` (defaults to cwd).
- Review uncommitted work: `diffBase: "HEAD"`.
- Review a branch/PR: `diffBase: "<base-branch>"`, `diffHead: "HEAD"` (e.g. `main` → `HEAD`).
- Sub-directory only: set `path` to the package/service directory.
- Deep audit (slower, higher cost): `mode: "deep"`. Mention cost to the user before using it.
- To cap spend: `maxCostUsd`.

Scans run for several minutes. Progress is streamed as tool updates — do not poll, just wait for the result.

## Reading results

The tool returns a severity-ranked summary (critical → high → medium → low → informational) and artifact paths:

- `report.md` — full human-readable report. **Read it before fixing anything.** The summary only shows the top findings.
- `findings.json` — machine-readable findings with locations, CWEs, code evidence, remediation.
- `exports/results.sarif` — SARIF for CI/code-scanning upload.

Each finding includes location (`path:line`), confidence, CWE, summary, and remediation guidance.

## Fixing findings

1. Sort by severity, then confidence. Fix critical/high first.
2. Read the finding's `report.md` section and the referenced code before editing — do not blind-fix from the summary line.
3. Fix the root cause (e.g. parameterize the query builder), not just the reported call site — check for the same pattern elsewhere with grep.
4. After fixing a batch, re-run `security_scan` on the same target to verify findings are gone and no new ones appeared.
5. For genuine false positives, use the CLI: `npx codex-security false-positive --reason "<why>"` (see `npx codex-security false-positive --help`), and tell the user what you marked and why.

## Cost and safety notes

- Scans send code to OpenAI for analysis. If the user is on a sensitive codebase, confirm before the first scan.
- A scan is read-only with respect to the repository; fixes are always applied through normal editing tools, never by the scanner.
- Scan state lives in the Codex Security state dir (or `CODEX_SECURITY_STATE_DIR`), not in the repo — no cleanup needed.