Skip to content

Commit 010ccaa

Browse files
mldangelo-oaimldangelo-oai
authored
docs: define the trusted-local Codex Security threat model (#61)
* docs: define trusted-local security threat model * fix: keep bundled threat-model skills unchanged * docs: address trusted-local security review feedback * docs: clarify trusted-local security guidance
1 parent 3384dcc commit 010ccaa

2 files changed

Lines changed: 201 additions & 31 deletions

File tree

‎SECURITY.md‎

Lines changed: 174 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,186 @@
1-
# Security Policy
1+
# Security policy
2+
3+
Codex Security is a local tool for reviewing repositories you trust and have
4+
permission to assess. This policy explains which security issues are in scope
5+
and how to report them.
26

37
## Report a vulnerability in Codex Security
48

5-
Report vulnerabilities in the Codex Security CLI, SDK, bundled plugin, or
6-
release artifacts privately through
9+
Report vulnerabilities in the CLI, SDK, bundled plugin, scan runtime, or
10+
published release artifacts privately through
711
[OpenAI's Bugcrowd program](https://bugcrowd.com/engagements/openai).
812

9-
Include the affected version, security impact, and the smallest safe
10-
reproduction. Remove API keys, access tokens, private source code, and customer
11-
data from the report unless a private submission requires that material and you
12-
have permission to share it. Use the latest published version when confirming a
13-
finding.
13+
Do not post unpatched vulnerabilities, exploits, credentials, sensitive scan
14+
results, or proofs of concept in GitHub issues or pull requests. Use public
15+
issues for ordinary bugs, documentation, and feature requests.
16+
17+
OpenAI's
18+
[coordinated vulnerability disclosure policy](https://openai.com/policies/coordinated-vulnerability-disclosure-policy/)
19+
explains the reporting process, confidentiality, and program eligibility.
20+
21+
## Scope and supported versions
22+
23+
This policy applies to:
24+
25+
- The published `@openai/codex-security` package and `codex-security` CLI.
26+
- The TypeScript SDK, including target selection, authentication,
27+
configuration, execution, and result validation.
28+
- The Codex Security plugin, interpreter, and Codex runtime bundled with an
29+
official release.
30+
- Scan output, including manifests, findings, coverage, reports, SARIF, and
31+
scan history.
32+
- Official package, build, and release integrity.
33+
34+
Check that the issue affects the latest published package or the current default
35+
branch. Include the package version and, when relevant, the commit, plugin
36+
version, and operating system. If you found the issue in an older version,
37+
explain whether a supported release is also affected.
38+
39+
## Threat model
40+
41+
Codex Security runs under your local operating-system account. Scan only
42+
repositories you trust and either own or have explicit permission to assess.
43+
Permission to assess a repository does not mean you can trust it.
44+
45+
The repository you select, your Git installation, and the tools and
46+
configuration you choose run with your existing local permissions. Normal Git
47+
operations can use repository configuration, hooks, filters, attributes,
48+
credential helpers, worktrees, and executables on your `PATH`. These are not
49+
separate security boundaries.
50+
51+
The product also does not isolate users, tasks, repositories, or scan jobs
52+
that share the same operating-system account, credentials, or local state.
53+
Do not treat shared local state as a multi-user or multi-tenant system.
54+
55+
Trusting a repository does not authorize unrelated actions. Repository
56+
contents, model output, patches, service responses, and imported artifacts
57+
are data. They are not permission to scan another target, expose a credential,
58+
contact another destination, modify an unrelated file, or apply a patch.
59+
60+
### How scans run
61+
62+
Each scan uses the product's `codex_security_scan` filesystem profile and
63+
`approvalPolicy: "never"`. The scan does not request interactive approval. Its
64+
profile allows reads of the local filesystem and writes to workspace roots and
65+
the selected scan state directory.
66+
67+
Setting `approval_policy`, `sandbox_mode`, or permissions through `--codex` or
68+
SDK `codexOverrides` does not replace the scan's approval policy or make its
69+
filesystem profile more restrictive. Separately enforced host and network
70+
restrictions still apply.
71+
72+
Scan and workbench subprocesses can inherit your environment. The workbench
73+
removes `OPENAI_API_KEY` and `CODEX_API_KEY`, but it does not remove every
74+
credential. Other variables, such as `GITHUB_TOKEN` or `AWS_SECRET_ACCESS_KEY`,
75+
can remain available to local subprocesses. Run a scan with only the
76+
environment credentials it needs.
1477

15-
Public GitHub issues are for ordinary bugs, documentation problems, and feature
16-
requests. Keep unpatched vulnerabilities and sensitive scan artifacts out of
17-
public issues and pull requests.
78+
### Security boundaries
79+
80+
A security issue must cross a boundary the product actually provides:
81+
82+
- Scan only the selected target and write only to authorized output paths.
83+
- Keep credentials, private source, and scan results out of model requests,
84+
logs, reports, and network destinations the operator did not authorize.
85+
- Apply the scan's actual filesystem and execution profile and respect host or
86+
network restrictions enforced independently of the scan.
87+
- Do not follow a symlink or replaced file into an unauthorized read or write.
88+
- Mark a scan complete only when its results match the reviewed scope,
89+
documented mode, and stated exclusions.
90+
- Protect official packages, bundled runtimes, dependencies, build artifacts,
91+
and release credentials from unauthorized changes.
92+
93+
## In-scope reports
94+
95+
Report reproducible issues in an official release, such as:
96+
97+
- Credentials, private source, or scan results sent to another security
98+
principal, model request, or network destination without authorization.
99+
- Model or remote input that bypasses the scan's effective permissions or an
100+
independently enforced host, execution, filesystem, or network restriction.
101+
- A scan, patch, file write, or network request outside the action you
102+
authorized.
103+
- Path traversal, a symlink, an archive, or a file-replacement race that writes
104+
outside the approved output or sends an unrelated local file to a model.
105+
- An incomplete, forged, or incorrectly scoped scan accepted as complete or as
106+
a passing CI result.
107+
- GitHub, package, update, dependency, or model-service input that causes an
108+
unauthorized local action or compromises a release.
109+
- A reachable vulnerability in the published package, bundled runtime, build,
110+
or release process.
111+
- Resource exhaustion that reaches a supported service, CI process, or other
112+
actual availability boundary.
113+
114+
## Usually out of scope
115+
116+
The following are not security vulnerabilities by themselves:
117+
118+
- Reading selected repository files, resolving worktrees, running Git, or
119+
using configured hooks, filters, credential helpers, and executables.
120+
- An attack that first requires control of your trusted repository, local Git
121+
installation, operating-system account, environment, or Codex state.
122+
- A claim that depends on you intentionally selecting a malicious plugin,
123+
interpreter, executable, credential, scan artifact, or override.
124+
- Access, cancellation, modified results, or scan-history visibility between
125+
processes that already share your operating-system account and local state.
126+
- Prompt injection, unexpected model output, a missed finding, or a false
127+
positive that does not cross an actual security boundary.
128+
- A documented exclusion, ignore rule, soft cost limit, estimate, or Git
129+
behavior accurately reflected in the scan and its results.
130+
- A dependency advisory, theoretical attack, or old package version without a
131+
reproducible impact on a supported release.
132+
- Slow processing of a file, document, or repository you deliberately selected.
133+
- Vulnerabilities in a third-party repository being scanned.
134+
- Documentation, tests, fixtures, or development code that a published runtime
135+
or release process cannot reach.
136+
137+
Hosted services, multi-user installations, pull-request CI, and imported
138+
third-party artifacts can have different trust boundaries. For those cases,
139+
identify the deployment, attacker-controlled input, affected component, and
140+
actual boundary. Storing multiple local scans does not make the CLI a
141+
multi-tenant system.
142+
143+
If you are not sure whether a finding is in scope, report it privately.
144+
145+
## What to include in a report
146+
147+
Include:
148+
149+
- The affected component, package version, plugin version, and commit.
150+
- Your platform, authentication method, scan mode, and target type.
151+
- The attacker's starting permissions and the security boundary crossed.
152+
- Minimal steps to reproduce the issue in a supported release or the default
153+
branch.
154+
- The expected and actual behavior, impact, and any known mitigation.
155+
- Sanitized logs or scan artifacts if they are needed to reproduce the issue.
156+
157+
Remove API keys, access tokens, customer data, and private source unless the
158+
private report requires them and you are authorized to share them. Never
159+
include a live credential in a proof of concept.
18160

19161
## Report a finding in a scanned repository
20162

21-
A vulnerability found in another repository belongs to that repository's
22-
owner. Follow its security policy or coordinated disclosure process, and share
23-
the finding only with people authorized to receive it. OpenAI's Bugcrowd program
24-
is for vulnerabilities in OpenAI products and services, not for findings in
25-
unrelated projects.
163+
If a scan finds a vulnerability in someone else's repository, follow that
164+
project's security policy and share the finding only with authorized people.
165+
OpenAI's Bugcrowd program covers OpenAI products and services, not
166+
vulnerabilities in other projects.
26167

27168
## Run scans safely
28169

29-
- Scan only code you own or have explicit permission to assess.
30-
- Treat repository files, instructions, build scripts, and findings as
31-
untrusted. Scans and validation may inspect code and run commands inside the
32-
Codex sandbox.
33-
- Store credentials in an approved secret manager or environment variable.
34-
Keep your Codex home directory outside the repository being scanned.
35-
- Store results outside the enclosing Git worktree. Findings, reports, logs,
36-
and SARIF can contain private source code, vulnerability details, and
37-
reproduction steps.
38-
- Restrict access to scan artifacts, apply a suitable retention period, and
39-
review them before sharing or uploading them to another service.
40-
- Review proposed patches before applying or merging them.
41-
42-
For more about Codex sandboxing, approvals, and network controls, see
43-
[Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security).
170+
- Scan only repositories you trust and either own or have explicit permission
171+
to assess.
172+
- Review repository instructions and inspect a patch before you apply or merge
173+
it.
174+
- Pass only the credentials the scan needs. Local subprocesses can inherit
175+
other environment variables.
176+
- Keep your credentials and Codex home outside the repository.
177+
- Store scan state, findings, reports, logs, and SARIF outside the enclosing
178+
Git worktree.
179+
- Limit access to results, set a retention period, and review them before you
180+
share or upload them.
181+
- Keep the package, runtime, and dependencies up to date.
182+
183+
For details on Codex sandboxing, approvals, and network controls, see
184+
[Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security/).
185+
For information about vulnerability identifiers and disclosure timelines, see
186+
[OpenAI's CVE assignment policy](https://openai.com/policies/openai-cve-assignment-policy/).

‎sdk/typescript/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,9 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
197197
`--codex KEY=VALUE` for other Codex settings; existing
198198
`--codex 'model_reasoning_effort="high"'` overrides remain supported.
199199

200+
These overrides do not change the scan's approval policy or filesystem
201+
permissions. See [Local security model](#local-security-model).
202+
200203
Scan progress identifies the requested paths and reports actual ranking,
201204
file-review, validation, and attack-path phases as they become available.
202205
Completion summarizes findings, severity, coverage, elapsed time, available
@@ -344,6 +347,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
344347
failures and rate limits remain retryable; definitive authentication and model
345348
authorization failures stop immediately.
346349

350+
## Local security model
351+
352+
Codex Security runs with your local operating-system permissions. Scan only
353+
repositories you trust and either own or are authorized to assess. Your
354+
repository, Git installation, configured tools, and other scans under the
355+
same account are not separate security principals.
356+
357+
Every scan uses the `codex_security_scan` filesystem profile and
358+
`approvalPolicy: "never"`. It can read the local filesystem and write to
359+
workspace roots and the selected scan state directory. Scans do not request
360+
interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
361+
through `--codex` or SDK `codexOverrides` does not replace these controls or
362+
make them more restrictive. Independently enforced host and network
363+
restrictions still apply.
364+
365+
Scan and workbench subprocesses can inherit your environment, including
366+
unrelated API tokens and cloud credentials. Start a scan with only the
367+
credentials it needs.
368+
369+
The scanner must stay within the target and output paths you authorize and
370+
must not disclose private data beyond the operation you requested. Its results
371+
must accurately report the scan mode, reviewed files, and exclusions. Consult
372+
the security policy for the full threat model and private reporting process.
373+
347374
## Documentation and security
348375

349376
- [CLI quickstart](https://developers.openai.com/codex/security/cli)

0 commit comments

Comments
 (0)