OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
chore(codex-security): sync public projection
mldangelo-oai96a2bcea3bae
diff --git a/.gitignore b/.gitignoreindex c568a5919..350c583e8 100644--- a/.gitignore+++ b/.gitignore@@ -5,4 +5,8 @@ dist//*.csv/repositories.csv/results/+/security-scans//state/+/codex-security.json+/findings.json+/*.sarifdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.mdindex 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-securitynpx codex-security loginnpx 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:```bashprintenv 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-runnpx codex-security scan /path/to/repo --fail-on-severity highnpx 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-scansnpx codex-security scans list /path/to/reponpx codex-security scans list --scan-root /path/outside/repo/resultsnpx codex-security scans show SCAN_IDnpx codex-security scans rerun SCAN_IDnpx 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. Addinitializing 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 alltarget, output, and runtime options.@@ -98,9 +118,6 @@ Use `info --json` for SDK and bundled-plugin metadata. MCP exposes only thisread-only metadata command; scans, authentication, exports, validation, andpatching 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 thescan 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 writethe 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, elapsedtime, available token and worker counts, the results directory, and the nextuseful 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 hostenvironment or secret manager. For private repositories, provide `GH_TOKEN` or`GITHUB_TOKEN` the same way. Compose passes only the named, configuredcredentials 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` toretry 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 notverified.-## 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.mdindex 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.mdindex 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-securitynpx 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:```bashprintenv 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/repositornpx codex-security scan /path/to/repository --dry-runnpx codex-security scan /path/to/repository --fail-on-severity highnpx 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 4npx codex-security scans list /path/to/repositorynpx codex-security scans list --scan-root /path/outside/repository/resultsnpx codex-security scans show SCAN_IDnpx codex-security scans rerun SCAN_IDnpx 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 theMCP 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 authenticationmethod and, for an environment API key, its variable name. Authentication andmodel 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 operationdiff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex 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.tsindex 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 () => {