Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

docs: define the trusted-local Codex Security threat model (#61)

mldangelo-oai010ccaa91cba
diff --git a/SECURITY.md b/SECURITY.md
index 0dfdddd59..b2ca5bf7f 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,43 +1,186 @@
-# Security Policy
+# 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
-Report vulnerabilities in the Codex Security CLI, SDK, bundled plugin, or
-release artifacts privately through
+Report vulnerabilities in the CLI, SDK, bundled plugin, scan runtime, or
+published release artifacts privately through
[OpenAI's Bugcrowd program](https://bugcrowd.com/engagements/openai).
-Include the affected version, security impact, and the smallest safe
-reproduction. Remove API keys, access tokens, private source code, and customer
-data from the report unless a private submission requires that material and you
-have permission to share it. Use the latest published version when confirming a
-finding.
+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](https://openai.com/policies/coordinated-vulnerability-disclosure-policy/)
+explains the reporting process, confidentiality, and program eligibility.
+
+## Scope and supported versions
+
+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
+
+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.
+
+The product also 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.
+
+Trusting a repository does not authorize unrelated actions. Repository
+contents, model output, patches, service responses, and imported artifacts
+are data. They are not permission to scan another target, expose a credential,
+contact another destination, modify an unrelated file, or apply a patch.
+
+### How scans run
+
+Each scan uses the product's `codex_security_scan` filesystem profile and
+`approvalPolicy: "never"`. The scan does not request interactive approval. Its
+profile allows reads of the local filesystem and writes to workspace roots and
+the selected scan state directory.
+
+Setting `approval_policy`, `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.
-Public GitHub issues are for ordinary bugs, documentation problems, and feature
-requests. Keep unpatched vulnerabilities and sensitive scan artifacts out of
-public issues and pull requests.
+### Security boundaries
+
+A security issue must cross a boundary the product actually provides:
+
+- Scan only the selected target and write only to authorized output paths.
+- 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
+
+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.
+- 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
+
+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.
+- An attack that first requires control of your trusted repository, local Git
+ installation, operating-system account, environment, or Codex state.
+- A claim that depends on you intentionally selecting a malicious plugin,
+ interpreter, executable, credential, scan artifact, or override.
+- Access, cancellation, modified results, or scan-history visibility between
+ processes that already share your operating-system account and local state.
+- Prompt injection, unexpected model output, a missed finding, or a false
+ positive that does not cross an actual security boundary.
+- A documented exclusion, ignore rule, soft cost limit, estimate, or Git
+ behavior accurately reflected in the scan and its results.
+- 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
+
+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
-A vulnerability found in another repository belongs to that repository's
-owner. Follow its security policy or coordinated disclosure process, and share
-the finding only with people authorized to receive it. OpenAI's Bugcrowd program
-is for vulnerabilities in OpenAI products and services, not for findings in
-unrelated projects.
+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
-- Scan only code you own or have explicit permission to assess.
-- Treat repository files, instructions, build scripts, and findings as
- untrusted. Scans and validation may inspect code and run commands inside the
- Codex sandbox.
-- Store credentials in an approved secret manager or environment variable.
- Keep your Codex home directory outside the repository being scanned.
-- Store results outside the enclosing Git worktree. Findings, reports, logs,
- and SARIF can contain private source code, vulnerability details, and
- reproduction steps.
-- Restrict access to scan artifacts, apply a suitable retention period, and
- review them before sharing or uploading them to another service.
-- Review proposed patches before applying or merging them.
-
-For more about Codex sandboxing, approvals, and network controls, see
-[Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security).
+- 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](https://developers.openai.com/codex/agent-approvals-security/).
+For information about vulnerability identifiers and disclosure timelines, see
+[OpenAI's CVE assignment policy](https://openai.com/policies/openai-cve-assignment-policy/).
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 4f0de1cbf..8d0690148 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -197,6 +197,9 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
`--codex KEY=VALUE` for other Codex settings; existing
`--codex 'model_reasoning_effort="high"'` overrides remain supported.
+These overrides do not change the scan's approval policy or filesystem
+permissions. See [Local security model](#local-security-model).
+
Scan progress identifies the requested paths and reports actual ranking,
file-review, validation, and attack-path phases as they become available.
Completion summarizes findings, severity, coverage, elapsed time, available
@@ -344,6 +347,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
failures and rate limits remain retryable; definitive authentication and model
authorization failures stop immediately.
+## Local security model
+
+Codex Security runs with your local operating-system permissions. Scan only
+repositories you trust and either own or are authorized to assess. Your
+repository, Git installation, configured tools, and other scans under the
+same account are not separate security principals.
+
+Every scan uses the `codex_security_scan` filesystem profile and
+`approvalPolicy: "never"`. It can read the local filesystem and write to
+workspace roots and the selected scan state directory. Scans do not request
+interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
+through `--codex` or SDK `codexOverrides` does not replace these controls or
+make them more restrictive. Independently enforced host and network
+restrictions still apply.
+
+Scan and workbench subprocesses can inherit your environment, including
+unrelated API tokens and cloud credentials. Start a scan with only the
+credentials it needs.
+
+The scanner must stay within the target and output paths you authorize and
+must not disclose private data beyond the operation you requested. Its results
+must accurately report the scan mode, reviewed files, and exclusions. Consult
+the security policy for the full threat model and private reporting process.
+
## Documentation and security
- [CLI quickstart](https://developers.openai.com/codex/security/cli)