CONTRIBUTING Copy Section

Contributing

Thanks for helping improve Codex Security. We welcome bug reports, feature
requests, documentation corrections, and feedback from open-source
maintainers.

How this repository works Copy Chapter

Codex Security is developed in OpenAI's canonical repository and published
here through a one-way mirror. We can't import pull requests from this
repository into the canonical source.

Search existing issues
before opening a new one. Maintainers can carry accepted changes into the
canonical source or invite a focused pull request for this public repository.

Support for open-source projects Copy Chapter

If you maintain an open-source project,
open an issue with the
repository, your role, and what you need. Support is best effort. Scan only
repositories you trust and either own or have permission to assess.

Report a bug Copy Chapter

Include your CLI or SDK version, operating system, reproduction steps, and
the expected and observed behavior. Remove credentials, private code,
customer data, and security findings before posting.

Suggest a feature or improve the documentation Copy Chapter

Open an issue describing the problem and the workflow you want to support.
Documentation corrections and safe examples are welcome.

Report a security issue Copy Chapter

Report Codex Security vulnerabilities privately as described in
SECURITY.md. Do not post vulnerabilities, exploit details,
credentials, or sensitive scan results publicly.

If a scan finds a vulnerability in another project, report it to that
project's maintainers through their security policy.

Dependency and release maintenance Copy Chapter

Maintainers update package dependencies and the committed lockfile in the
canonical repository. The public release workflow installs that locked graph,
tests the package, and publishes a verified artifact with npm provenance.
GitHub Actions dependencies are maintained separately in this repository.

---

README Copy Section

Codex Security

@openai/codex-security is a CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities in your code.

See the Codex Security documentation for more details.

Some cybersecurity requests and protected findings require approval through
Trusted Access for Cyber. To apply or check your access, visit
chatgpt.com/cyber.

Quick start Copy Chapter

Requires Node.js 22.13.0 or later in the 22.x release line, Node.js 24.x, or
Node.js 26.x; Python 3.10 or later; and access to Codex Security.

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high
npx @openai/codex-security scan . --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5

For CI, set OPENAI_API_KEY or CODEX_API_KEY instead of signing in.
Environment API keys are passed directly to the current scan and are never
stored in Codex's credential home or system keyring.

Deep-scan discovery stops after 96 hours by default. Set --max-time-hours to
any positive number of hours, including fractional hours, up to 96. Completed
findings are preserved and returned when the limit is reached.

To use another inference provider, set its API key and select a model:

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
export FIREWORKS_API_KEY="<your-fireworks-api-key>"
npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna

Amazon Bedrock also supports standard AWS access keys, profiles, web identity,
container credentials, and the default AWS credential chain.

Local sign-in honors Codex's configured credential backend, including a system
keyring required by a managed device. Codex Security keeps login and scan
credentials in the same private, persistent state directory.

If both a ChatGPT sign-in and an API key are available, interactive scans ask
which credential to use. CI and other noninteractive scans keep the existing
API-key precedence. Select a credential explicitly when needed:

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

To make your ChatGPT sign-in the automatic default, unset any configured API
keys:

unset OPENAI_API_KEY CODEX_API_KEY

Scan history is stored in the Codex Security workbench state directory. If that
directory cannot be written, set CODEX_SECURITY_STATE_DIR to a writable
directory outside the repository.

findings list [repository] shows open findings across a repository's scans
and identifies findings not confirmed in its latest scan.

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID automatically matches findings by
root cause, reuses saved matches, and identifies new, persisting, reopened,
resolved, or unknown findings. Missing findings remain unknown when coverage is
incomplete or their original location was not reviewed.

Verbose diagnostics Copy Chapter

Add --verbose to print scan diagnostics to stderr:

npx @openai/codex-security scan . --verbose

CODEX_SECURITY_LOG_LEVEL=debug also enables diagnostics;
LOG_LEVEL=debug is its fallback. JSON results remain on stdout.

Verbose diagnostics may contain sensitive data. Review local logs before
sharing them. Saved failure summaries, bulk-scan receipts, and the interactive
dashboard omit messages that contain recognizable credentials.

Use npx @openai/codex-security scans logs SCAN_ID to inspect saved session
events from a scan and its workers.

TypeScript SDK Copy Chapter

import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
const result = await security.run(".");
await security.run(".", {
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});
console.log(result.reportPath);
await security.close();

Containerized bulk scans Copy Chapter

Use the official image and included Docker Compose configuration for
noninteractive, resumable scans of repositories pinned to immutable Git
revisions. See the container quick start
for authentication, private result storage, and optional Ubuntu AppArmor
hardening.

Pass --knowledge-base PATH to share security documents with every repository;
repeat the option for multiple files or directories.

Use --scan-prompt-file PATH to add shared scan instructions, and add a prompt
CSV column for repository-specific instructions. Use
--post-scan-prompt-file PATH to run a follow-up after each scan, including
incomplete or failed scans.

For complete command help, runtime defaults, native multi-agent worker limits,
environment variables, deep-scan configuration, and SDK options, see the
package README and the
official CLI reference.

---

SECURITY Copy Section

Security policy

Codex Security is a local tool for reviewing repositories you trust and have
permission to assess. This policy explains which security issues are in scope
and how to report them.

Report a vulnerability in Codex Security Copy Chapter

Report vulnerabilities in the CLI, SDK, bundled plugin, scan runtime, or
published release artifacts privately through
OpenAI's Bugcrowd program.

Do not post unpatched vulnerabilities, exploits, credentials, sensitive scan
results, or proofs of concept in GitHub issues or pull requests. Use public
issues for ordinary bugs, documentation, and feature requests.

OpenAI's
coordinated vulnerability disclosure policy
explains the reporting process, confidentiality, and program eligibility.

Scope and supported versions Copy Chapter

This policy applies to:

- The published @openai/codex-security package and codex-security CLI.
- The TypeScript SDK, including target selection, authentication,
configuration, execution, and result validation.
- The Codex Security plugin, interpreter, and Codex runtime bundled with an
official release.
- Scan output, including manifests, findings, coverage, reports, SARIF, and
scan history.
- Official package, build, and release integrity.

Check that the issue affects the latest published package or the current default
branch. Include the package version and, when relevant, the commit, plugin
version, and operating system. If you found the issue in an older version,
explain whether a supported release is also affected.

Threat model Copy Chapter

Codex Security runs under your local operating-system account. Scan only
repositories you trust and either own or have explicit permission to assess.
Permission to assess a repository does not mean you can trust it.

The repository you select, your Git installation, and the tools and
configuration you choose run with your existing local permissions. Normal Git
operations can use repository configuration, hooks, filters, attributes,
credential helpers, worktrees, and executables on your PATH. These are not
separate security boundaries.

Local trust and attacker prerequisites Copy Section

The product does not isolate users, tasks, repositories, or scan jobs that
share the same operating-system account, credentials, or local state. Do not
treat shared local state as a multi-user or multi-tenant system.

Private Codex state, workbench databases, output directories, and resume
receipts are not separate security boundaries from your operating-system
account. A report that depends on changing them must show how an
attacker-controlled input reaches them through a supported workflow and
crosses a security boundary.

Trusting a repository does not authorize unrelated actions. Repository
contents, filenames, symlinks, model output, patches, service responses, and
imported artifacts are data. They do not authorize another target, a broader
scope, a different credential, an unrelated read or write, an unapproved
patch or network destination, a bypassed restriction, or a passing result for
incomplete coverage.

How scans run Copy Section

Each scan uses the product's codex_security_scan filesystem profile and
approvalPolicy: "never". The scan does not request interactive approval or
grant filesystem escalations. Its profile allows reads of the local filesystem
and writes to workspace roots and the selected scan state directory.

Setting approval_policy, approvals_reviewer, sandbox_mode, or permissions
through --codex or SDK codexOverrides does not replace the scan's approval
policy or make its filesystem profile more restrictive. Separately enforced
host and network restrictions still apply.

Scan and workbench subprocesses can inherit your environment. The workbench
removes OPENAI_API_KEY and CODEX_API_KEY, but it does not remove every
credential. Other variables, such as GITHUB_TOKEN or AWS_SECRET_ACCESS_KEY,
can remain available to local subprocesses. Run a scan with only the
environment credentials it needs.

Security boundaries Copy Section

A security issue must cross a boundary the product actually provides:

- Scan only the selected target and requested scope; write only to authorized
output paths.
- Honor explicitly selected credentials and documented cost controls.
- Keep credentials, private source, and scan results out of model requests,
logs, reports, and network destinations the operator did not authorize.
- Apply the scan's actual filesystem and execution profile and respect host or
network restrictions enforced independently of the scan.
- Do not follow a symlink or replaced file into an unauthorized read or write.
- Mark a scan complete only when its results match the reviewed scope,
documented mode, and stated exclusions.
- Protect official packages, bundled runtimes, dependencies, build artifacts,
and release credentials from unauthorized changes.

In-scope reports Copy Chapter

Report reproducible issues in an official release, such as:

- Credentials, private source, or scan results sent to another security
principal, model request, or network destination without authorization.
- Model or remote input that bypasses the scan's effective permissions or an
independently enforced host, execution, filesystem, or network restriction.
- A scan, patch, file write, or network request outside the action you
authorized.
- Ignoring the target, path scope, credential, or documented cost limit you
explicitly selected.
- Path traversal, a symlink, an archive, or a file-replacement race that writes
outside the approved output or sends an unrelated local file to a model.
- An incomplete, forged, or incorrectly scoped scan accepted as complete or as
a passing CI result.
- GitHub, package, update, dependency, or model-service input that causes an
unauthorized local action or compromises a release.
- A reachable vulnerability in the published package, bundled runtime, build,
or release process.
- Resource exhaustion that reaches a supported service, CI process, or other
actual availability boundary.

Usually out of scope Copy Chapter

The following are not security vulnerabilities by themselves:

- Reading selected repository files, resolving worktrees, running Git, or
using configured hooks, filters, credential helpers, and executables within
the authority you granted.
- An attack that assumes prior control of your operating-system account,
trusted local Git settings, private Codex state, or private scan outputs
without showing how a supported input gains that control.
- A claim that depends on you deliberately granting a plugin, interpreter, or
executable the authority your account already has.
- Access, cancellation, or changes to private scan state, workbench databases,
results, resume receipts, or scan history by a process that already shares
your account and local state.
- Prompt injection, unexpected model output, missed findings, false positives,
or unsigned review receipts that do not cross a boundary or cause a supported
security gate to accept incomplete or misrepresented coverage.
- A documented exclusion, ignore rule, estimate, or Git behavior accurately
reflected in the scan and its results.
- Disclosed estimation uncertainty or unavoidable in-flight cost overruns
when an explicitly requested limit is still enforced as documented.
- Terminal formatting or control characters without a demonstrated security
impact in a supported terminal.
- A hypothetical compromise of a trusted release runner, registry, or
dependency supplier without a path from untrusted input to a protected
release or a bypass of its integrity controls.
- A dependency advisory, theoretical attack, or old package version without a
reproducible impact on a supported release.
- Slow processing of a file, document, or repository you deliberately selected.
- Vulnerabilities in a third-party repository being scanned.
- Documentation, tests, fixtures, or development code that a published runtime
or release process cannot reach.

Hosted services, multi-user installations, pull-request CI, and imported
third-party artifacts can have different trust boundaries. For those cases,
identify the deployment, attacker-controlled input, affected component, and
actual boundary. Storing multiple local scans does not make the CLI a
multi-tenant system.

If you are not sure whether a finding is in scope, report it privately.

What to include in a report Copy Chapter

Include:

- The affected component, package version, plugin version, and commit.
- Your platform, authentication method, scan mode, and target type.
- The attacker's starting permissions and the security boundary crossed.
- Minimal steps to reproduce the issue in a supported release or the default
branch.
- The expected and actual behavior, impact, and any known mitigation.
- Sanitized logs or scan artifacts if they are needed to reproduce the issue.

Remove API keys, access tokens, customer data, and private source unless the
private report requires them and you are authorized to share them. Never
include a live credential in a proof of concept.

Report a finding in a scanned repository Copy Chapter

If a scan finds a vulnerability in someone else's repository, follow that
project's security policy and share the finding only with authorized people.
OpenAI's Bugcrowd program covers OpenAI products and services, not
vulnerabilities in other projects.

Run scans safely Copy Chapter

- Scan only repositories you trust and either own or have explicit permission
to assess.
- Review repository instructions and inspect a patch before you apply or merge
it.
- Pass only the credentials the scan needs. Local subprocesses can inherit
other environment variables.
- Keep your credentials and Codex home outside the repository.
- Store scan state, findings, reports, logs, and SARIF outside the enclosing
Git worktree.
- Limit access to results, set a retention period, and review them before you
share or upload them.
- Keep the package, runtime, and dependencies up to date.

For details on Codex sandboxing, approvals, and network controls, see
Agent approvals and security.
For information about vulnerability identifiers and disclosure timelines, see
OpenAI's CVE assignment policy.

---