codex-security Tests the Repo Boundary

OpenAI’s codex-security is an open-source CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities in code. How much of a real repository should an AI security tool be allowed to inspect, remember, and change? Treat the scanner like a privileged contributor, not a harmless linter. In a Codex CLI workflow that touches GitHub, the scanner belongs behind the same repo, credential, and review boundaries you would use for any tool that can propose security fixes.

Codex Security is a security scanning package for OpenAI Codex users that can scan repositories, review changes, track findings over time, and run checks in CI. As of July 2026, the GitHub repository shows an Apache-2.0 license, TypeScript as the main language, and public activity around a project developers clearly wanted to try quickly.

Start with what the package actually does

The repo describes @openai/codex-security as both a command-line tool and a TypeScript SDK. That matters because it is not only a web dashboard and not only a model prompt. It is meant to sit in the places engineers already work: local repos, pull requests, CI jobs, and code review loops.

The first interesting boundary is authentication. The README says local interactive scans can use a ChatGPT sign-in or an API key, while CI should use OPENAI_API_KEY. You pick the credential explicitly with --auth chatgpt or --auth api-key rather than relying on the tool to guess.

That sounds like a small implementation detail. It is not. Security tools touch code, diffs, dependency files, and sometimes exploit-shaped examples, so the identity they run under determines what they can see and what audit trail you get.

Don't treat “AI security scanner” as a single capability. There are at least four separate capabilities here: read the repository, analyze a finding, store scan history, and propose or apply a fix. Each one deserves its own yes or no.

Notice where state and ownership become security questions

One of the more human reactions around the project was not “does it use a model?” It was “why am I getting auth or blocked-project errors?” That is the right frustration, even if the answer is not always obvious from the outside.

The docs give one concrete clue: scan history is stored in a local state directory, documented on OpenAI's Codex Security CLI page. If that directory cannot be written, you can set CODEX_SECURITY_STATE_DIR to a writable directory outside the repository.

That small environment variable is a good design signal. State should not be smeared into the repo just because the tool is running from the repo. Scan history can contain sensitive context: file paths, vulnerability classes, generated reasoning, and the sequence of findings over time.

A safe local experiment keeps that state outside the checkout:

mkdir -p "$HOME/.cache/codex-security-state"
export CODEX_SECURITY_STATE_DIR="$HOME/.cache/codex-security-state"

# For local interactive use, choose one credential path clearly.
# If you want ChatGPT sign-in to be the default, unset API keys first.
unset OPENAI_API_KEY

For CI, invert that pattern. Do not depend on an interactive sign-in. Set OPENAI_API_KEY in the CI secret store, keep the job noninteractive, and make the generated output part of the pull request review rather than a silent mutation.

Watch for running a scanner from a dirty working tree with unclear credentials. If the tool finds a real issue, you want to know whether the result came from your local account, a CI service account, or a credential you forgot was exported months ago.

Read the bundled skills as product clues

A fair objection from developers was that codex-security might just be a convenient CI wrapper around existing models. The repository itself suggests there is more shape than that, including bundled plugin skills under the TypeScript SDK tree.

That does not mean the tool is magic. It means the interesting work may be in the workflow packaging: when to scan, what evidence to gather, how to validate a finding, and how to turn that into a patch a reviewer can understand.

This is the same pattern behind good Codex CLI workflows. The model matters, but the loop matters more: inspect, edit, run checks, explain the change, and hand the result back to a human reviewer. If you want a broader map of that loop, keep CLI workflows nearby, but do not turn this particular story into a generic agent lesson.

A concrete example: suppose a Node service accepts uploaded files and writes them to disk. A scanner might flag path traversal risk. The useful output is not “possible path traversal”; it is a small patch, a test that proves ../ is rejected, and a note about what user-controlled value reached the file write.

Don't accept a vulnerability label without a reproduction path. Security review needs evidence. AI output needs it even more.

Put one minimal boundary around the experiment

You do not need a grand process to try codex-security safely. You need a small permission boundary that makes the first scan boring.

Use a throwaway branch. Run from a repo you own or are allowed to test. Keep scan state outside the repository. Decide whether the tool may only report findings or may also create edits. Then review any patch like security-sensitive code, because it is.

Here is a lightweight AGENTS.md note you can drop into a test repo before using Codex around security fixes:

# AGENTS.md

## Security scan boundary

- Treat codex-security findings as review candidates, not accepted facts.
- Do not modify authentication, authorization, crypto, or data-deletion code without a human review step.
- When proposing a fix, include the vulnerable path, the changed files, and the verification command.
- Keep scan history outside this repository by setting CODEX_SECURITY_STATE_DIR.
- Do not call external MCP servers during security triage unless the task explicitly requires that data source.

That last line is easy to skip. It is also the line that keeps Codex MCP integrations from becoming accidental data pipes during a security task. A scanner looking at vulnerable code does not automatically need Slack, Jira, a database, or a document store.

Here is the “risks before you copy this” version:

This is not a permanent operating model. It is the smallest useful boundary for a first serious look.

For people comparing this with other command-line agent stories, the same principle shows up in Termic Runs CLI Coding Agents: local power is useful only when the handoff is legible.

Try one safe scan next

Pick a small repository you own, create a branch, set the state directory outside the checkout, and run codex-security with report-first expectations. If the first useful output includes a finding, a patch, and a verification command, you have something worth reviewing.

Further reading

• codex-security on GitHub
• Codex CLI docs
• Codex on GitHub

Next move

Start from CLI workflows.