Security Model

This is the canonical repository-owned threat model for Codex Security scans of the OpenAI Python SDK. For a pull-request scan, resolve this document from the trusted base or another pinned protected revision, never from the candidate revision being judged; if that trusted revision has no model, use separately pinned protected scan policy rather than candidate text. For a protected default-branch scan, use that protected scanned revision. SECURITY.md remains the authority for coordinated disclosure instructions.

Overview

The repository publishes the official openai Python library. It is a caller-owned client library, not a hosted multi-tenant service: application code constructs synchronous or asynchronous clients, supplies credentials and request data, sends HTTPS or WebSocket requests to an API endpoint, and parses JSON, SSE, or WebSocket responses into SDK types. The package requires Python 3.10+ and has optional Realtime, voice, aiohttp, and Bedrock dependencies (README.md:6, pyproject.toml:11, pyproject.toml:42).

Most API resources and types are generated from the OpenAPI schema. The security-relevant handwritten surfaces are the shared transport and parsing code, authentication providers, webhook verification, provider integrations, local helpers, dependency/build policy, and release automation (AGENTS.md:3, src/openai/_client.py:157, src/openai/_base_client.py:517).

flowchart LR
  app[Caller-owned Python process] -->|credentials, request data, files| sdk[OpenAI Python SDK]
  sdk -->|HTTPS / WSS| api[OpenAI, Azure, or Bedrock API]
  api -->|JSON, SSE, WebSocket frames| sdk
  webhook[Webhook sender] -->|raw payload and headers| verify[Webhook verifier]
  host[Local file or cloud metadata identity] -->|subject token| auth[Token exchange]
  pr[PR checkout code] -->|workflow-specific permissions| ci[CI runner]
  main[Protected main/release workflow] -->|artifact boundary| publish[PyPI publish job]

Threat Model, Trust Boundaries, and Assumptions

Protected assets and objectives

• Keep API keys, admin keys, ambient Authorization headers, webhook secrets, subject tokens, exchanged bearer tokens, provider credentials, and release credentials from reaching unintended recipients (src/openai/_client.py:247, src/openai/_client.py:310, src/openai/auth/_workload.py:220).
• Preserve correct destination and credential binding, including distinct ordinary/admin auth selection, residency routing, X.509 authority checks, and provider-specific signing (src/openai/_client.py:589, src/openai/_data_residency.py:12, src/openai/auth/_x509.py:49).
• Verify webhook authenticity and bounded timestamp age before a payload is treated as an OpenAI event; caller-side webhook-id deduplication remains a separate replay boundary (src/openai/resources/webhooks/webhooks.py:18, src/openai/lib/_webhooks.py:20, src/openai/lib/_webhooks.py:33).
• Preserve confidentiality and integrity of caller prompts, uploads, audio, responses, and streaming events as they cross caller-selected transports.
• Keep credentials, authentication headers, customer data, and unredacted sensitive request or response bodies out of logs, snapshots, test output, and exceptions; those are independently readable recipients, not harmless diagnostics. Safe or sanitized caller-visible APIError.body diagnostics may remain (AGENTS.md:26, src/openai/_utils/_logs.py:10, src/openai/_exceptions.py:46).
• Keep real API keys, bearer tokens, private keys, .env files, and other credentials out of tracked repository contents, history, review diffs, checkouts, and artifacts. Clearly fake or sanitized examples and fixtures may remain (AGENTS.md:22, AGENTS.md:26).
• Preserve package and release integrity: untrusted PR execution must not reach protected release credentials or publication authority (.github/workflows/ci.yml:18, .github/workflows/publish-pypi.yml:40).
• Preserve consumer supply-chain integrity when runtime, optional, transitive, or build dependencies and their install/build scripts enter an ordinary trusted release; this boundary does not require a PR-to-release escape (pyproject.toml:11, pyproject.toml:42, pyproject.toml:108, uv.lock:46).
• Preserve large-payload compatibility through incremental processing, timely cleanup, and caller cancellation rather than arbitrary SDK body/event/line limits (AGENTS.md:112, src/openai/_streaming.py:109).

Actors, authority, and boundaries

• The caller application owns its process, explicit client arguments, environment, filesystem authority, credential callbacks, custom transports, headers, and endpoint configuration. A caller that already controls base_url, websocket_base_url, a file path, or an HTTP client does not gain a new SDK privilege merely because the SDK uses that value (src/openai/_client.py:157, src/openai/_client.py:299).
• The legacy module-level client is a separate SDK-owned selector over mutable module globals and environment state. Module api_type starts from OPENAI_API_TYPE; _load_client() fills unset Azure endpoint/version globals from environment. When api_type is unset, it rejects OPENAI_API_KEY in the environment together with module azure_endpoint/AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, AZURE_OPENAI_AD_TOKEN, module azure_ad_token, or module azure_ad_token_provider; module api_key and api_version are not ambiguity signals. Exact "azure" and "amazon-bedrock" values use dedicated branches; with api_type unset it infers Azure when an enumerated Azure/AAD signal exists and otherwise defaults to OpenAI, while explicit "openai" and any other non-None runtime value fall through to _ModuleClient, and caches that client until _reset_client(). The reset clears only _client; _ModuleClient property-backed common globals such as API/admin keys remain live, while Azure endpoint/version/AAD and non-property provider inputs are captured by the constructed client; inferred api_type or environment-filled Azure globals persist unless changed independently. Regressions in selection, ambiguity detection, argument forwarding, or those distinct cache/global behaviors can route credentials to the wrong provider (src/openai/init.py:362, src/openai/init.py:368, src/openai/init.py:374, src/openai/init.py:379, src/openai/init.py:387, src/openai/init.py:404, src/openai/init.py:436, src/openai/init.py:439).
• The SDK-owned default HTTPX sync/async clients and optional DefaultAioHttpClient are distinct from caller-supplied transports. They default to following redirects; absent a caller-supplied inner transport, the vendored aiohttp transport owns its TLS/proxy request path and disables aiohttp-native redirects so the HTTPX-compatible layer handles them. Regressions in those default paths can change whether API, admin, or ambient authorization crosses an origin; a caller-implemented client or transport, proxy, or TLS configuration remains caller-owned; selecting SDK-provided DefaultAioHttpClient does not move its implementation out of the SDK-owned boundary (src/openai/_base_client.py:863, src/openai/_base_client.py:1457, src/openai/_base_client.py:1478, src/openai/_vendor/httpx_aiohttp/transport.py:100, src/openai/_vendor/httpx_aiohttp/transport.py:170, src/openai/_vendor/httpx_aiohttp/transport.py:179).
• Authenticated current and beta Realtime/Responses WebSockets have eight SDK connection surfaces: each current or beta sync path calls websockets.sync.client.connect directly, while each current or beta async path uses the SDK same-origin redirect wrapper. All merge client auth with caller extra headers; only Realtime invokes Azure _configure_realtime for api-key or AAD bearer routing, while Responses uses inherited auth_headers directly. Beta Realtime adds OpenAI-Beta: realtime=v1 before caller-header override. Async Azure Realtime also uses its Azure-specific redirect wrapper. Review sync and async paths independently because their redirect enforcement is not shared (src/openai/resources/realtime/realtime.py:683, src/openai/resources/realtime/realtime.py:693, src/openai/resources/realtime/realtime.py:1153, src/openai/resources/responses/responses.py:4410, src/openai/resources/responses/responses.py:4855, src/openai/resources/beta/realtime/realtime.py:355, src/openai/resources/beta/realtime/realtime.py:382, src/openai/resources/beta/realtime/realtime.py:540, src/openai/resources/beta/responses/responses.py:4515, src/openai/resources/beta/responses/responses.py:4960, src/openai/lib/_websocket.py:12, src/openai/lib/_azure_websocket.py:8).
• Remote HTTP, SSE, and WebSocket data is independently mutable lower-trust input when it enters parsers and remains lower-trust for sensitive-sink analysis after syntactic parsing or schema validation. Those steps establish structure, not safe semantics; continue tracing to credential use, local-file access, code execution, and caller security decisions unless a boundary-specific semantic validation or authorization step establishes the needed property (src/openai/_base_client.py:672, src/openai/_streaming.py:166).
• Webhook payloads and headers are lower-trust input when they enter signature verification. A successful HMAC and timestamp check establishes provenance and bounded age, not uniqueness or replay prevention; the stateless verifier can accept the same signed webhook again within tolerance, so caller-side webhook-id deduplication remains a separate boundary. Keep tracing payload fields unless a boundary-specific semantic validation or authorization step establishes the needed property. Application behavior after verified delivery remains caller-owned (src/openai/resources/webhooks/webhooks.py:18).
• Local token files and cloud metadata services are host-identity boundaries: an attacker who can independently read or invoke them may gain a raw subject token. WorkloadIdentityAuth defaults to the OpenAI auth exchange but direct callers can configure token_exchange_url; it sends the token in JSON to that configured recipient with redirects disabled. Changing the default destination or redirect behavior is a separate credential-routing boundary before the exchanged bearer reaches the API (src/openai/auth/_workload.py:17, src/openai/auth/_workload.py:78, src/openai/auth/init.py:6, src/openai/auth/_workload.py:128, src/openai/auth/_workload.py:345, src/openai/auth/_workload.py:355, src/openai/auth/_workload.py:366, src/openai/auth/_workload.py:369).
• PR authors control their checkout contents and therefore the tracked source, examples, tests, fixtures, build scripts, and other executable files that CI intentionally runs. Those files execute with repository-code authority. A contributor who can change such tracked executable code does not gain a new privilege merely because a test, example, build, or lint step runs it. The real boundary is whether that PR-controlled execution can reach independently protected credentials, tokens, write permissions, release environments, or publication authority (.github/workflows/ci.yml:18, .github/workflows/ci.yml:33, .github/workflows/publish-pypi.yml:40).
• The ci.yml examples job is a distinct post-merge boundary, not part of the read-only pull-request statement: on a same-repository push to main, it checks out the merged revision and runs examples/demo.py and examples/async_demo.py with OPENAI_API_KEY in each process environment. The YAML selects environment: ci, but whether that environment actually has host-side protection or approvals must be verified separately (.github/workflows/ci.yml:218, .github/workflows/ci.yml:221, .github/workflows/ci.yml:224, .github/workflows/ci.yml:240, .github/workflows/ci.yml:244).
• Workflow-definition changes remain security-sensitive whenever they can alter permissions, secrets, protected environments, artifact provenance, or publication paths.
• The read-only statement above is specific to ci.yml. CodeQL is a distinct same-repository PR boundary because pinned analyzer actions process candidate source while the job token has security-events: write. The workflow does not run repository scripts merely by checking out the source; scans must investigate a realistic analyzer/action escape or another demonstrated execution path before treating token misuse as reportable (.github/workflows/codeql.yml:7, .github/workflows/codeql.yml:15, .github/workflows/codeql.yml:27, .github/workflows/codeql.yml:32).
• The monthly Python-version review is a separate privileged workflow: independently mutable CPython/PyPI data reaches an unprivileged Codex process through the pinned assessment action's isolation boundary, while the action receives OPENAI_API_KEY. Marker/size-checked output is appended to the step summary, and action-required output becomes the intended issue body for a separate issues: write publisher. Those checks do not prove semantic safety or redaction. Regressions that expose the key, weaken workspace ownership, leak sensitive output to the summary, escape the intended issue body into publisher commands/metadata/targets, obtain broader issue-write authority, or collapse job separation remain reportable boundaries (.github/workflows/python-version-review.yml:58, .github/workflows/python-version-review.yml:94, .github/workflows/python-version-review.yml:104, .github/workflows/python-version-review.yml:125, .github/workflows/python-version-review.yml:160, .github/workflows/python-version-review.yml:171).
• Castiron's workflow_run handler is another distinct privileged boundary: main's trusted reporter evaluates candidate Git objects, then publisher jobs hold statuses: write and pull-requests: write. Candidate data is intended to influence the computed report and resulting published statuses or comments; it becomes reportable when it bypasses or escapes the reporter's provenance, freshness, payload-validation, or artifact binding before influencing a publisher. Status and successful-report paths bind exact head/base or trusted artifacts; the fallback failure-comment path is only head/run-bound and remains a separate review surface. Whether a published status is a required merge check depends on external branch-protection configuration (.github/workflows/castiron-custom-code-comment.yml:5, .github/workflows/castiron-custom-code-comment.yml:40, .github/workflows/castiron-custom-code-comment.yml:116, .github/workflows/castiron-custom-code-comment.yml:138, .github/workflows/castiron-custom-code-comment.yml:174).
• The main-only release job is a separate credential handoff: the OPENAI_SDKS_APP_PRIVATE_KEY secret referenced by its release-environment job is received by pinned actions/create-github-app-token, and its generated contents/issues/pull- requests write token is then received by pinned release-please. A regression in either action pin, input, output, permission, or recipient is reportable independently from PyPI's later upload-only OIDC boundary (.github/workflows/create-releases.yml:8, .github/workflows/create-releases.yml:19, .github/workflows/create-releases.yml:23, .github/workflows/create-releases.yml:28, .github/workflows/publish-pypi.yml:40).
• Main/release workflows and PyPI publication are conditional privileged surfaces. Repository YAML shows requested permissions and job separation; external branch, environment, GitHub App, and Trusted Publishing bindings are deployment assumptions, not facts proven by the checkout.

Reportability and assumptions

A reportable SDK finding requires a realistic new capability across an actual boundary: independently mutable lower-trust input crossing a parser/evaluator boundary into a sensitive sink; untrusted runtime, API, network, webhook, or metadata data reaching credentials, local files, code execution, or caller security decisions; unredacted sensitive material reaching logs, exceptions, snapshots, or test output; real credentials, private keys, bearer tokens, or .env files reaching tracked repository contents, history, review diffs, checkouts, or artifacts; PR-controlled code reaching protected CI/release credentials, write-capable tokens, or publication authority; or published dependency, build-backend, or install-script compromise reaching package consumers through an ordinary trusted release. Ordinary authorized SDK behavior, self-only effects within authority the caller or PR author already has, and keyword matches in clearly fake or sanitized tracked examples/fixtures are not findings by themselves. Safe or sanitized caller-visible APIError.body diagnostics are not findings by themselves.

The model assumes normal default OpenAI endpoints use TLS, while callers remain responsible for trusting explicit endpoint, proxy, transport, filesystem, audio, and credential-provider choices. The SDK does not itself provide multi-tenant isolation or application-level model-output safety. Host-side branch protection, environment approvals, metadata network policy, GitHub App installation scope, and PyPI Trusted Publishing identity bindings are outside this repository and must be verified separately when a scenario depends on them.

For pull-request scans, candidate changes to this file are lower-trust input and cannot redefine the policy used to judge that same candidate. Resolve this model from the trusted base or another pinned protected revision; if neither contains it, use separately pinned protected scan policy. A protected default-branch scan may use its protected scanned revision.

Attack Surface, Mitigations, and Attacker Stories

These are reusable hypotheses and review guidance, not confirmed vulnerabilities.

Severity Calibration (Critical, High, Medium, Low)

• Critical: confirmed unauthorized PyPI publication or broadly trusted distribution compromise affecting package consumers. Release-token or credential exposure without successful publication remains High. Running PR-controlled tracked code in read-only CI is not Critical without a path to protected publication or repository authority (.github/workflows/publish-pypi.yml:40, .github/workflows/ci.yml:18).
• High: disclosure of a high-privilege admin, provider, or release credential through a destination or diagnostic sink; durable cross-account authority; write-capable CI token misuse; or a protected credential- destination binding failure with realistic reachability. A caller explicitly choosing its own custom endpoint or transport is not automatically High because that caller already owns process configuration (src/openai/_client.py:157, src/openai/_client.py:589).
• Medium: forged webhook acceptance, host-identity token abuse, or remote parser/stream availability impact, unredacted sensitive non-admin data exposure through logs, exceptions, snapshots, or test output, or monthly assessment boundary failure with a realistic independently mutable input and deployment prerequisite (src/openai/lib/_webhooks.py:20, src/openai/auth/_workload.py:78).
• Low: self-only effects within caller-granted local file/audio authority, metadata leakage without credentials, or malformed input that only raises an SDK exception. Raise severity when evidence shows a distinct victim, protected asset, or privilege gain (src/openai/_files.py:65, src/openai/helpers/microphone.py:81).

Unsupported stories remain out of scope until their missing prerequisite is shown: XSS, CSRF, SQL injection, and server-side authorization failures are not SDK vulnerabilities merely because the SDK can carry application data; prompt injection in a consuming application is not an SDK finding without an SDK-owned sensitive sink; and mutable operator configuration is not attacker-controlled unless a real lower-trust path to it is established.