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

chore(codex-security): sync public projection

mldangelo-oai96a2bcea3bae
diff --git a/.gitignore b/.gitignore
index c568a5919..350c583e8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,4 +5,8 @@ dist/
/*.csv
/repositories.csv
/results/
+/security-scans/
/state/
+/codex-security.json
+/findings.json
+/*.sarif
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1e93e6be8..19cdb71f9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,7 +1,30 @@
# Contributing
-This repository is a read-only mirror of OpenAI's canonical source. We cannot
-import public pull requests here.
+Codex Security is developed in OpenAI's canonical repository and published to
+this repository through a one-way mirror. External pull requests cannot be
+imported into the canonical source.
-Please use [GitHub issues](https://github.com/openai/codex-security/issues) to
-report bugs or request changes.
+## Report a bug
+
+Search [existing GitHub issues](https://github.com/openai/codex-security/issues)
+before opening a new one. Include the installed CLI or SDK version, operating
+system, reproduction steps, expected behavior, and the observed result.
+
+Remove API keys, access tokens, repository contents, security findings, and
+other sensitive information from public reports. Report security vulnerabilities
+privately as described in [SECURITY.md](SECURITY.md).
+
+## Request a feature or improve the documentation
+
+Open a GitHub issue describing the problem, the workflow you want to support,
+and any relevant product behavior. Documentation corrections and safe
+reproduction details are welcome in the issue discussion.
+
+Maintainers review issues and carry accepted changes into the canonical source.
+
+## Dependency and release maintenance
+
+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.
diff --git a/README.md b/README.md
index 55b75aa6d..d916d6b62 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,48 @@
# Codex Security
-Run Codex Security scans from the command line or a TypeScript application.
+Codex Security is an open-source CLI and TypeScript SDK for finding, validating,
+and reviewing security issues in code you own or have permission to assess.
-> [!WARNING]
-> Codex Security is in beta. APIs, CLI options, and output formats may change.
+> [!NOTE]
+> This package follows semantic versioning. Its public API may change between
+> minor versions before `1.0.0`.
## Requirements
-The SDK and CLI require Node.js 22 or later. Running a scan or exporting findings
-also requires Python 3.10 or later for the bundled Codex Security plugin;
-Python 3.10 also requires `tomli`. Python is not needed to install the package
-or run `--help` and `--version`.
+The SDK and CLI support macOS, Linux, and Windows and require Node.js 22 or
+later. Scanning and exporting findings also require Python 3.10 or later. If
+you use Python 3.10, install the `tomli` package. Python is not needed to
+install the package or run `--help` and `--version`.
+
+Sign in with your OpenAI account or provide an OpenAI API key before running a
+scan. Scan only repositories you own or have explicit permission to assess.
## Install and scan
```bash
-npm install @openai/codex-security@beta
+npm install @openai/codex-security
npx codex-security login
npx codex-security scan /path/to/repo
```
+Run `npx codex-security --help` to see all commands and
+`npx codex-security scan --help` for scan options.
+
On a remote or headless machine, use `npx codex-security login --device-auth`.
-For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`.
+For CI and other unattended scans, set `OPENAI_API_KEY` or `CODEX_API_KEY` using
+your shell, CI secret, or secret manager.
+
+On Windows, set an API key in PowerShell with:
-To store an API key or enterprise access token, pass it on stdin:
+```powershell
+$env:OPENAI_API_KEY = "<your-api-key>"
+npx codex-security scan C:\code\repository
+```
+
+To store an API key, pass it on stdin:
```bash
printenv OPENAI_API_KEY | npx codex-security login --with-api-key
-printenv CODEX_ACCESS_TOKEN | npx codex-security login --with-access-token
```
Use `npx codex-security login status` to check the stored sign-in and
@@ -51,17 +66,17 @@ npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results --
npx codex-security scan /path/to/repo --dry-run
npx codex-security scan /path/to/repo --fail-on-severity high
npx codex-security bulk-scan
-npx codex-security bulk-scan repositories.csv --output-dir ./security-scans
+npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans
npx codex-security scans list /path/to/repo
npx codex-security scans list --scan-root /path/outside/repo/results
npx codex-security scans show SCAN_ID
npx codex-security scans rerun SCAN_ID
npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
-npx codex-security export /path/outside/repo/results --export-format sarif --output results.sarif
-npx codex-security export /path/outside/repo/results --export-format csv --output findings.csv
-npx codex-security export /path/outside/repo/results --export-format json --output findings.json
-npx codex-security validate findings.json "Possible SQL injection in src/query.ts:42"
-npx codex-security patch findings.json "Missing authorization check in src/routes.ts:18"
+npx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif
+npx codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv
+npx codex-security export /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json
+npx codex-security validate /path/outside/repo/findings.json "Possible SQL injection in src/query.ts:42"
+npx codex-security patch /path/outside/repo/findings.json "Missing authorization check in src/routes.ts:18"
```
Use `npx codex-security --version` for the CLI version and
@@ -71,7 +86,12 @@ the default model and reasoning effort, and the next scan command. Add
initializing Codex or contacting the network.
The output directory must be outside the scanned directory and any enclosing Git
-worktree. When SARIF is produced, it is written to
+worktree. On macOS and Linux, an existing output directory must be private to
+the current user (`chmod 700`). Scan artifacts can contain source excerpts,
+vulnerability details, and reproduction steps. Keep them out of repositories,
+public issue reports, and shared locations.
+
+When SARIF is produced, it is written to
`<scan-dir>/exports/results.sarif`. Use `npx codex-security scan --help` for all
target, output, and runtime options.
@@ -98,9 +118,6 @@ Use `info --json` for SDK and bundled-plugin metadata. MCP exposes only this
read-only metadata command; scans, authentication, exports, validation, and
patching remain CLI-only because the MCP transport cannot cancel active scans.
-On macOS/Linux, an existing output directory must be private to the current
-user (`chmod 700`).
-
If the output directory already contains results, add `--archive-existing`.
The CLI moves them to `<output-dir>.previous-<timestamp>-<id>` and starts the
scan in a new, empty directory at the original path. Add `--dry-run` to see
@@ -112,11 +129,17 @@ Incomplete coverage and CLI/runtime errors exit 2. Incomplete scans still write
the available human or JSON result to stdout and a coverage warning to stderr,
including in report-only mode.
-For CI, keep machine-readable output on stdout and apply a severity policy;
-incomplete coverage and runtime errors still exit nonzero:
+For CI, save machine-readable output outside the checked-out repository and
+apply a severity policy. Incomplete coverage and runtime errors still exit
+nonzero:
```bash
-npx codex-security scan . --diff origin/main --json --fail-on-severity high > codex-security.json
+SCAN_ROOT="$(mktemp -d)"
+npx codex-security scan . \
+ --diff origin/main \
+ --output-dir "$SCAN_ROOT/results" \
+ --json \
+ --fail-on-severity high > "$SCAN_ROOT/findings.json"
```
JSON scans remain noninteractive, including when stderr is a terminal. Commands
@@ -135,12 +158,39 @@ and attack-path phases. Completion shows finding severity, coverage, elapsed
time, available token and worker counts, the results directory, and the next
useful command. Progress remains on stderr; JSON results remain on stdout.
+## Use the TypeScript SDK
+
+Create a client, choose a private output directory outside the repository, and
+close the client after the scan:
+
+```ts
+import { CodexSecurity } from "@openai/codex-security";
+
+const security = new CodexSecurity();
+
+try {
+ const result = await security.run("/path/to/repository", {
+ outputDir: "/path/outside/repository/results",
+ });
+
+ console.log(result.reportPath);
+ console.log(result.findings.findings.length);
+} finally {
+ await security.close();
+}
+```
+
+The SDK also supports path and diff targets, preflight, progress callbacks,
+cancellation, security knowledge bases, and typed scan results.
+
## Run bulk scans in Docker
-The customer container runs noninteractive bulk scans from a supplied CSV on a
-Linux Docker host. It does not support interactive repository discovery. The
-included `compose.yaml` configures the image, persistent files, and hardened
-Codex command sandbox.
+The included Docker image runs noninteractive bulk scans from a supplied CSV on
+a Linux Docker host. The included `compose.yaml` configures the image,
+persistent files, and a hardened Codex command sandbox.
+
+<details>
+<summary>Configure a Docker bulk scan</summary>
Create a `repositories.csv` with one full, immutable Git commit per repository:
@@ -165,27 +215,14 @@ For a one-time sign-in from a remote or headless Docker host, run:
docker compose run --rm codex-security login --device-auth
```
-Open the displayed verification URL in your own browser and enter the one-time
-code. The login remains in `state/` after the container exits. For unattended
-enterprise deployments, store an enterprise access token in the same directory
-without exposing the token in command arguments:
-
-```bash
-printenv CODEX_ACCESS_TOKEN | \
- docker compose run --rm -T codex-security login --with-access-token
-```
+Open the displayed verification URL in your browser and enter the one-time
+code. The login remains in `state/` after the container exits.
Alternatively, provide `OPENAI_API_KEY` or `CODEX_API_KEY` through your host
environment or secret manager. For private repositories, provide `GH_TOKEN` or
`GITHUB_TOKEN` the same way. Compose passes only the named, configured
credentials to the container.
-Security scans remain subject to the model's cybersecurity access policies.
-Depending on the account and repository contents, full-repository scans may
-require enrollment in [Trusted Access for Cyber](https://chatgpt.com/cyber).
-A valid Codex login and GitHub token do not grant that authorization. If access
-is denied, the scan records the repository as failed and exits unsuccessfully.
-
Start a resumable, four-worker scan with the default command:
```bash
@@ -265,6 +302,8 @@ of a GitHub Enterprise Server instance when needed.
Use `--workers` to control concurrent repository scans and `--max-attempts` to
retry failures. The command returns a nonzero status when any repository fails.
+</details>
+
## Scan history and reruns
`npx codex-security scans list` lists scans for the current repository. Pass a
@@ -307,29 +346,15 @@ loading credentials, or starting a scan. Dry runs do not inspect the plugin,
probe Python, or contact the network; their authentication metadata is not
verified.
-## TypeScript SDK
-
-```ts
-import { CodexSecurity } from "@openai/codex-security";
-
-const security = new CodexSecurity();
-try {
- const result = await security.run("/path/to/repo", {
- knowledgeBasePaths: ["/path/to/threat-models", "/path/to/architecture.pdf"],
- });
- console.log(result.reportPath);
-} finally {
- await security.close();
-}
-```
-
-Product documentation is available in the
-[Codex Security guide](https://developers.openai.com/codex/security).
-
-## Support and security
+## Documentation, support, and security
-Please use [GitHub issues](https://github.com/openai/codex-security/issues) for
-bugs and feature requests. Report vulnerabilities privately using the
-[security policy](SECURITY.md).
+- [Codex Security overview](https://developers.openai.com/codex/security)
+- [CLI quickstart and reference](https://developers.openai.com/codex/security/cli)
+- [TypeScript SDK guide](https://developers.openai.com/codex/security/sdk)
+- [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and
+ feature requests
+- [Security policy](SECURITY.md) for private vulnerability reporting and safe
+ operation
+- [Contribution guidelines](CONTRIBUTING.md)
This project is licensed under the [Apache-2.0 License](LICENSE).
diff --git a/SECURITY.md b/SECURITY.md
index a53c25966..0dfdddd59 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,6 +1,43 @@
# Security Policy
-Please report security vulnerabilities privately through OpenAI's
-[Bugcrowd program](https://bugcrowd.com/engagements/openai).
+## Report a vulnerability in Codex Security
-Do not report security vulnerabilities through public GitHub issues.
+Report vulnerabilities in the Codex Security CLI, SDK, bundled plugin, or
+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.
+
+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.
+
+## 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.
+
+## 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).
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 1f166bb92..477042080 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -1,23 +1,56 @@
# `@openai/codex-security`
-TypeScript SDK and CLI for running the Codex Security plugin. The package is
-ESM-only, includes TypeScript declarations, and installs the `codex-security`
-executable with the aligned `@openai/codex` runtime dependency.
+Open-source TypeScript SDK and CLI for running Codex Security scans. The
+ESM-only package includes TypeScript declarations, the `codex-security`
+executable, and the matching Codex runtime.
-> [!WARNING]
-> Codex Security is in beta. APIs, CLI options, and output formats may change.
+> [!NOTE]
+> This package follows semantic versioning. Its public API may change between
+> minor versions before `1.0.0`.
## Install
```bash
-npm install @openai/codex-security@beta
+npm install @openai/codex-security
npx codex-security --version
```
-Node.js 22 or later is required. Running a scan or exporting findings also requires
-Python 3.10 or later for the bundled plugin; Python 3.10 additionally requires
-`tomli`. Configure the interpreter with `--python`, `pythonPath`, or `PYTHON`
-when automatic discovery is not appropriate.
+The package supports macOS, Linux, and Windows and requires Node.js 22 or
+later. Scanning and exporting findings also require Python 3.10 or later. If
+you use Python 3.10, install the `tomli` package. Select another interpreter
+with `--python`, `pythonPath`, or `PYTHON` when needed.
+
+## Run a scan from TypeScript
+
+Sign in with `npx codex-security login` or set `OPENAI_API_KEY` or
+`CODEX_API_KEY`. Then create a client and scan a repository you own or have
+permission to assess:
+
+```ts
+import { CodexSecurity } from "@openai/codex-security";
+
+const security = new CodexSecurity();
+
+try {
+ const result = await security.run("/path/to/repository", {
+ outputDir: "/path/outside/repository/results",
+ });
+
+ console.log(result.reportPath);
+ console.log(result.findings.findings.length);
+} finally {
+ await security.close();
+}
+```
+
+The SDK supports repository, path, committed-diff, and working-tree targets.
+Use `security.preflight()` to validate local inputs, `onWorkerStatus` and
+`onReconnect` to observe long-running scans, and an `AbortSignal` to cancel a
+scan.
+
+Results can contain source excerpts, vulnerability details, and reproduction
+steps. Keep result directories and saved reports outside the repository and
+limit access to authorized reviewers.
## Authentication
@@ -34,12 +67,18 @@ On a remote or headless machine, use device authentication:
npx codex-security login --device-auth
```
-For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key or
-enterprise access token instead, pass it on stdin:
+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,
+pass it on stdin:
```bash
printenv OPENAI_API_KEY | npx codex-security login --with-api-key
-printenv CODEX_ACCESS_TOKEN | npx codex-security login --with-access-token
+```
+
+On Windows, set the API key in PowerShell:
+
+```powershell
+$env:OPENAI_API_KEY = "<your-api-key>"
+npx codex-security scan C:\code\repository
```
Check or remove the stored sign-in with `npx codex-security login status` and
@@ -65,17 +104,17 @@ npx codex-security scan /path/to/repository --output-dir /path/outside/repositor
npx codex-security scan /path/to/repository --dry-run
npx codex-security scan /path/to/repository --fail-on-severity high
npx codex-security bulk-scan
-npx codex-security bulk-scan repositories.csv --output-dir /tmp/security-scans --workers 4
+npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
npx codex-security scans list /path/to/repository
npx codex-security scans list --scan-root /path/outside/repository/results
npx codex-security scans show SCAN_ID
npx codex-security scans rerun SCAN_ID
npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
-npx codex-security export /path/outside/repository/results --export-format sarif --output results.sarif
-npx codex-security export /path/outside/repository/results --export-format csv --output findings.csv
-npx codex-security export /path/outside/repository/results --export-format json --output findings.json
-npx codex-security validate findings.json "Possible SQL injection in src/query.ts:42"
-npx codex-security patch findings.json "Missing authorization check in src/routes.ts:18"
+npx codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
+npx codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
+npx codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
+npx codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
+npx codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
```
Run `npx codex-security --version` for the installed CLI version or
@@ -173,11 +212,17 @@ read-only metadata command; scans, bulk repository scans,
authentication, exports, validation, and patching remain CLI-only because the
MCP transport cannot cancel active scans.
-For CI, keep machine-readable output on stdout and apply a severity policy;
-incomplete coverage and runtime errors still exit nonzero:
+For CI, save machine-readable output outside the checked-out repository and
+apply a severity policy. Incomplete coverage and runtime errors still exit
+nonzero:
```bash
-npx codex-security scan . --diff origin/main --json --fail-on-severity high > codex-security.json
+SCAN_ROOT="$(mktemp -d)"
+npx codex-security scan . \
+ --diff origin/main \
+ --output-dir "$SCAN_ROOT/results" \
+ --json \
+ --fail-on-severity high > "$SCAN_ROOT/findings.json"
```
JSON scans never use interactive terminal controls, even when stderr is a TTY.
@@ -217,26 +262,11 @@ Python interpreter. The preflight result includes the selected authentication
method and, for an environment API key, its variable name. Authentication and
model access remain unverified until a real scan starts.
-## SDK
-
-```ts
-import { CodexSecurity } from "@openai/codex-security";
-
-const security = new CodexSecurity();
-try {
- const result = await security.run("/path/to/repository", {
- knowledgeBasePaths: ["/path/to/threat-models", "/path/to/architecture.pdf"],
- });
- console.log(result.reportPath);
-} finally {
- await security.close();
-}
-```
-
-The SDK also supports scoped and diff targets, streaming, cancellation, API-key
-and Codex sign-in flows, and typed scan results.
+## Documentation and security
-Product documentation is available in the
-[Codex Security guide](https://developers.openai.com/codex/security). Please
-report bugs using [GitHub issues](https://github.com/openai/codex-security/issues)
-and vulnerabilities using the repository security policy.
+- [CLI quickstart](https://developers.openai.com/codex/security/cli)
+- [TypeScript SDK guide](https://developers.openai.com/codex/security/sdk)
+- [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and
+ feature requests
+- [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md)
+ for private vulnerability reporting and safe operation
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 02f652564..740d5db50 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -1,6 +1,6 @@
{
"name": "@openai/codex-security",
- "version": "0.0.0-dev",
+ "version": "0.1.0",
"description": "TypeScript SDK and CLI for Codex Security",
"license": "Apache-2.0",
"author": "OpenAI",
diff --git a/sdk/typescript/tests-ts/targets.test.ts b/sdk/typescript/tests-ts/targets.test.ts
index 3c104094c..a60dc50ab 100644
--- a/sdk/typescript/tests-ts/targets.test.ts
+++ b/sdk/typescript/tests-ts/targets.test.ts
@@ -61,7 +61,7 @@ function git(repo: string, ...args: string[]): string {
describe("scan target normalization", () => {
test("tolerates a temporary repository removed before cleanup", async () => {
const repo = await repository();
- await rm(join(repo, ".."), { recursive: true });
+ await rm(join(repo, ".."), { recursive: true, force: true });
});
test("normalizes repository and path targets", async () => {