OpenAI’s newly released Codex Security repository can now be run locally for a first scan, but the open-source release is narrower than some users may assume. The openai/codex-security repo on GitHub is published under Apache-2.0 and covers the tooling layer used to run scans, manage results and wire the workflow into CI. The service that actually reads source code, reproduces vulnerabilities in isolated environments and produces patch files still runs on OpenAI’s own servers.
That distinction matters. Cloning the repository does not give a user full standalone access. The README lists three requirements: Node.js 22 or later, Python 3.10 or later, and access to Codex Security. The product is in research preview and is available to ChatGPT Pro, Business, Edu and Enterprise accounts. Some enterprise tenants may also require an administrator to enable access first.
The repository is open source, but not the full analysis stack
The source article makes the split explicit. What OpenAI has released is the client-side and workflow layer: the code that launches scans, handles findings and connects the process to development pipelines. The backend analysis service remains proprietary and hosted by OpenAI.
The package’s release cadence also points to an early-stage product. On npm, @openai/codex-security version 0.1.0 was published at 17:09 UTC on July 28, followed by 0.1.1 at 23:48 UTC the same day, a gap of 6 hours and 39 minutes. The SDK documentation notes that before 1.0.0, public APIs may change across minor releases, which makes version pinning the safer option for production use.
Open source does not mean outside PRs are merged upstream
The article also points to CONTRIBUTING.md, which says the repository is a one-way mirror of OpenAI’s internal canonical repository. Users can open issues, report bugs and submit feature requests, but external pull requests cannot be imported directly into the source of record.
That leaves two separate layers in place. The license still allows modification and redistribution. The contribution model, though, stays under OpenAI’s internal control.
System requirements and the first scan
Codex Security supports macOS, Linux and Windows. The basic setup uses three commands:
npm install @openai/codex-securitynpx codex-security loginnpx codex-security scan .
If the tool is running on a remote machine or in an environment without a browser, device authentication is available:
npx codex-security login --device-auth
In CI, interactive login is not required. The article says an API key can be provided through an environment variable:
export OPENAI_API_KEY=<YOUR_KEY>
To see which credentials are active, users can run:
npx codex-security login status
That command reports the credential source without printing the key itself.
Dry-run first, spend later
Before launching a real scan, the walkthrough recommends a dry run:
npx codex-security scan . --dry-run
This does not start Codex, does not touch the network and does not load credentials. It validates the repository, scan target, output location and model configuration, while also showing which model and reasoning level would be used. In the article’s framing, it is a zero-cost check and worth doing before a paid run.
Default model and reasoning level affect the bill
The default scan path uses gpt-5.6-sol with reasoning effort set to extra-high. To switch models:
npx codex-security scan . --model gpt-5.6-terra
Other Codex settings can be overridden with --codex KEY=VALUE, including reasoning effort:
npx codex-security scan . --codex 'model_reasoning_effort="high"'
The article stresses a simple point: reasoning effort changes token consumption, and token consumption changes cost. For a first test, the highest setting may not be necessary.
Five pitfalls that can waste money or effort
1. --max-cost is not a hard billing cutoff
OpenAI’s documentation says scans stop once cumulative cost exceeds the configured ceiling, including dispatched workers, but requests already in progress may still finish after the threshold has been crossed.
So a scan configured with a $5 limit can still end up costing more than $5. For a first attempt, the article recommends starting with a smaller repository or limiting scope with --path:
npx codex-security scan . --path src --max-cost 5
The estimated cost reported by each scan uses OpenAI’s standard API token pricing and includes cached input and cached writes. It does not include fees or surcharges, which is why the estimate should be treated as a floor, not an all-in total.
2. Output directories inside the repository are blocked
The output directory must sit outside the scanned directory and outside any Git worktree that encloses it. If the output path is placed inside the repository, the CLI rejects it.
The reason is straightforward. Scan results can contain source code snippets, vulnerability details and reproduction steps. The article describes that as effectively an attack roadmap, one that should not be committed by mistake.
On macOS and Linux, if the output directory already exists, it must also have chmod 700 permissions so only the current user can read and write it:
mkdir -p ~/security-scans/myrepochmod 700 ~/security-scans/myreponpx codex-security scan . --output-dir ~/security-scans/myrepo
If old results already exist there, --archive-existing moves them to <output-dir>.previous-<timestamp>-<id> before creating a clean directory. With --dry-run, users can inspect the intended move without changing any files.
3. Environment-variable API keys override ChatGPT login
By default, API keys found in environment variables take precedence over a stored ChatGPT login. In interactive scans, the tool prompts the user to choose credentials. In non-interactive contexts such as JSON output, dry runs and CI, there is no prompt, and the API-key-first rule applies automatically.
That can lead to charges being billed to the API side when a user thinks a ChatGPT plan is being used. The article says the credential source can be forced with:
npx codex-security scan . --auth chatgptnpx codex-security scan . --auth api-key
Using --auth chatgpt completely ignores OPENAI_API_KEY and CODEX_API_KEY. To make ChatGPT login the standing default, the article says both environment variables should be unset:
unset OPENAI_API_KEY CODEX_API_KEY
4. Python 3.10 needs tomli
The requirements say Python 3.10 and above are supported, but Python 3.10 users still need to install tomli separately. Starting with 3.11, the standard library includes tomllib, so no extra package is needed.
Alternative interpreters can be selected through the --python argument, the SDK’s pythonPath, or the PYTHON environment variable.
5. MCP is read-only and cannot run scans
The CLI can register as an MCP server with npx codex-security mcp add, but the MCP interface exposes only read-only metadata queries. Scanning, batch scanning, authentication, export, validation and patching all remain CLI-only operations.
The source article says OpenAI’s explanation is practical: the MCP transport layer cannot cancel an in-progress scan. A scan that continues running and billing without a way to stop it is worse than no scan support at all.
CI usage and pre-commit checks
For local development, the tool can install a hook that runs before each commit:
npx codex-security install-hook
After installation, it scans both staged and unstaged changes before a commit is accepted. The article says it respects core.hooksPath, does not overwrite existing hooks, and blocks commits on findings rated high or above by default. That threshold can be changed with --fail-on-severity.
The CI example shown in the article is:
SCAN_ROOT="$(mktemp -d)"npx codex-security scan . \ --diff origin/main \ --output-dir "$SCAN_ROOT/results" \ --json \ --fail-on-severity high > "$SCAN_ROOT/findings.json"
--diff origin/main scans only the code touched in the current change set, which the article notes is often much cheaper than scanning an entire repository. --working-tree covers staged and unstaged local changes.
The tool’s exit codes are also laid out clearly:
- 0: report-only scan completed, or policy passed
- 1: scan completed but policy failed
- 2: invalid input, incomplete coverage, or runtime/export error
- 130: interrupted
- 143: terminated
Incomplete coverage is intentionally mapped to 2 rather than 0, to avoid treating a partial scan as a clean pass. Even when a scan does not finish fully, usable results are still written to stdout and coverage warnings go to stderr. Report-only mode works the same way. Progress updates use stderr, while structured output uses stdout, so redirecting --json to a file does not mix it with progress messages.
Exporting SARIF, CSV and JSON does not trigger a new paid scan
To feed results into an existing security platform, the article recommends the export command:
npx codex-security export ~/security-scans/myrepo \ --export-format sarif \ --output ~/security-scans/results.sarif
The supported export formats are SARIF, CSV and JSON. When SARIF is generated, another copy is also written to <scan-dir>/exports/results.sarif. Adding --source-root can supply fingerprints for source lines.
One practical detail stands out in the article: export does not start Codex and does not load credentials. It costs nothing by itself. If the scan result has already been archived and only needs a different output format, it can be exported directly rather than rescanned.
Scan history, reruns, false positives and comparison
Scan history is stored locally in SQLite at $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. If that path is not writable, CODEX_SECURITY_STATE_DIR can point to another location.
The article lists these commands for scan history management:
npx codex-security scans listnpx codex-security scans show SCAN_IDnpx codex-security scans rerun SCAN_ID
A full scan ID is not required. A prefix of at least 8 characters is enough.
To verify whether a fix really removed a vulnerability, scans rerun reruns the original configuration against the current checkout. To compare two scans:
npx codex-security scans match BEFORE_ID AFTER_IDnpx codex-security scans compare BEFORE_ID AFTER_ID
match links findings that share the same root cause. compare then sorts outcomes into five categories: new, still present, reintroduced, resolved and unknown.
The article highlights one safeguard here. If the later scan is incomplete, or it does not cover the original scope, missing findings are not counted as resolved. That avoids creating a false impression that a vulnerability was fixed when the scan simply looked at less code.
False positives can be marked with:
npx codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
The article says the reason field is not just ceremonial. Future scans keep ignoring that finding only if the same rationale still applies. If the code changes and the route no longer checks permissions, the finding can surface again.
Batch scans across multiple repositories
After running gh auth login, users can launch:
npx codex-security bulk-scan
This fetches GitHub repositories the user has pushed to in the last 90 days, excludes archived repositories and forks, and then presents a search-and-select flow before starting scans. The chosen repository list is stored in <output-dir>/repositories.csv, which can later be reused to rerun or resume the job.
Users can also prepare their own CSV file. The required fields are id, repository and revision, with revision set to a full commit hash. Optional scope and mode fields can narrow the scan target for individual repositories. Concurrency is controlled by --workers, and retry behavior by --max-attempts.
The repository also includes a Dockerfile and compose.yaml. The container setup disables risky capabilities by default, including cap_drop: ALL, no-new-privileges, a custom seccomp profile, and a non-root user with ID 10001. The article notes that this can serve as a useful base for batch scanning on shared machines.
SDK support, reference material and FAQ points
The source article also points readers to the openai/codex-security GitHub repository and README, the official CLI quickstart, the official TypeScript SDK guide, the npm package page and Incur, the framework used for structured output and agent-style exploration. It says CLI flags such as --llms and --schema come from Incur.
For developers who prefer code over shell commands, the article includes a minimal TypeScript SDK example:
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
try { const result = await security.run("/path/to/repository", { outputDir: "/path/outside/repository/results", });
console.log(result.reportPath); console.log(result.findings.findings.length);} finally { await security.close();}
According to the article, the SDK supports four scan targets: full repository, selected paths, committed diffs and working tree changes. preflight() maps to the CLI’s dry run. onWorkerStatus and onReconnect expose progress for long-running scans, and AbortSignal can be used to cancel them.
The FAQ section adds several clarifications. Downloading the source code is not enough for users without ChatGPT Pro or enterprise access. Scan pricing has no fixed table and is estimated from actual token usage. Existing security platforms can ingest output through export in SARIF, CSV or JSON. Windows is supported as well, and the article gives a PowerShell example using $env:OPENAI_API_KEY = "<your-api-key>" before running npx codex-security scan C:\code\repository.
The article was compiled by Mickey帽鼠 and cites the official openai/codex-security README and CLI documentation as its reference material.