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
docs: clarify READMEs and separate SDK reference guides (#1307)
mldangelo-oaic60deac2537c
diff --git a/README.md b/README.mdindex d64fa8138..be83c4a87 100644--- a/README.md+++ b/README.md@@ -1,89 +1,106 @@# Codex Security-`@openai/codex-security` is a CLI and TypeScript SDK for defining security policy and finding, validating, and fixing security vulnerabilities in your code.--**👉👉 See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for full documentation.--Some cybersecurity requests and protected findings require approval through-Trusted Access for Cyber. To join the program, visit-[chatgpt.com/cyber](https://chatgpt.com/cyber).+`@openai/codex-security` is a CLI and TypeScript SDK for finding, validating, and+fixing security vulnerabilities in your code.++## Features++- Scan repositories, selected paths, or Git changes. Deep scans run parallel+ discovery workers on repositories and selected paths.+- Validate candidate findings, generate patches, and verify existing fixes.+- Draft `SECURITY.md` policies and save threat models for later review.+- Browse saved scans and findings, identify duplicates, assess severity against+ your own rubric, and suggest owners from source and Git history.+- Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish+ findings to Linear or a findings service.+- Automate scans across repositories or project components, including in CI and+ containers.## Quick start-Requires Node.js 22.13.0 or later and Python 3.10 or later.+Requires Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, and Python 3.10+.+Python 3.10 also requires `tomli`.```bashnpm install @openai/codex-securitynpx @openai/codex-security login-npx @openai/codex-security scan /path/to/directory+npx @openai/codex-security scan /path/to/repository```+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.On remote or headless machines, use `login --device-auth` if your workspace-allows it. If device auth is disabled,-[sign in over SSH](sdk/typescript/README.md#remote-login-with-ssh-forwarding).+allows it, or [sign in over SSH](sdk/typescript/README.md#remote-login-with-ssh-forwarding).-For CI, set `OPENAI_API_KEY` instead of signing in.+Some cybersecurity requests and protected findings require+[Trusted Access for Cyber](https://chatgpt.com/cyber) approval.-## Generate SECURITY.md+### Scan options-Draft repository-wide or component-scoped `SECURITY.md` guidance for future scans:+Choose a scope and scan mode:```bash-npx @openai/codex-security policy .-npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md+# Scan selected paths.+npx @openai/codex-security scan . --path src --path tests++# Scan committed changes from a base revision to HEAD.+npx @openai/codex-security scan . --diff origin/main++# Run a deep scan of the repository.+npx @openai/codex-security scan . --mode deep```-The command saves a draft outside the checkout; it does not install it or run a-vulnerability scan. Review the proposed diff before copying the policy. Supporting architecture,-threat-model, and review documents stay outside the repository and may contain-sensitive details. See the [SDK policy guide](sdk/typescript/README.md#generate-a-security-policy)-for headless generation, saved artifacts, and SDK usage.+Use `npx @openai/codex-security --help` to browse commands, or `scan --help`+for scan options, cost limits, and patching after a scan.-## Save and export threat models+## TypeScript SDK-Scans and policy generation retain their threat model with the run and write-a `threatmodel.md` copy when possible. Export the saved model without starting-another analysis:+```ts+import { CodexSecurity } from "@openai/codex-security";-```bash-npx @openai/codex-security export --artifact threat-model-npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output docs/threatmodel.md+const security = new CodexSecurity();++try {+ const result = await security.run("/path/to/repository");+ console.log(result.reportPath);+} finally {+ await security.close();+}```-The default source is the current repository's latest completed scan. Explicit-scan IDs or result directories can export saved provisional models. See the-[export guide](sdk/typescript/README.md#exports-and-ci) for policy results,-stdout, and the offline TypeScript API.+The [SDK guide](sdk/typescript/README.md) includes deep-scan configuration,+validation, severity classification, owner suggestions, and result handling.-## TypeScript SDK+## Generate SECURITY.md++Draft security guidance for a repository or one of its components:++```bash+npx @openai/codex-security policy .+npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md+```-To suggest owners for existing findings from source and Git history, see-[Suggest finding owners](sdk/typescript/README.md#suggest-finding-owners).+The command saves a draft outside the checkout. Review it before installing it+as guidance for future scans. See the [policy guide](sdk/typescript/docs/cli.md#generate-a-security-policy)+for supporting documents and SDK usage.-Codex Security is a Javascript package:+## Save and export threat models-```ts-import { CodexSecurity } from "@openai/codex-security";+Scans and policy generation save threat models with their results. Export a saved+model without starting another analysis:-const security = new CodexSecurity();-const result = await security.run("/path/to/directory");-await security.run("/path/to/directory", {- mode: "deep",- workers: 2,- subagents: 0,- stopAfterNoNew: 3,- maxDiscoveryRuns: 10,- maxTimeHours: 1.5,-});--console.log(result.reportPath);-await security.close();+```bash+npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md```+Omit `--scan` to use the current repository's latest completed scan. The+[export guide](sdk/typescript/docs/cli.md#exports-and-ci) also covers findings,+SARIF output for CI, and the offline TypeScript API.+## GitHub Actions-Scan your repository on a scheduled basis, in PR, or on demand. Add an OpenAI API key as the repository-secret `CODEX_SECURITY_API_KEY`, then save this workflow in+Run scheduled, manual, or pull request scans with the GitHub Action. For a weekly+repository scan, add an OpenAI API key as the repository secret+`CODEX_SECURITY_API_KEY`, then save this workflow in`.github/workflows/codex-security.yml`. Replace `REPLACE_WITH_REVIEWED_COMMIT`with the full SHA of an Action commit.@@ -92,7 +109,7 @@ name: Codex Securityon:workflow_dispatch:schedule:- - cron: '23 7 * * 1' # Mondays at 07:23 UTC+ - cron: "23 7 * * 1" # Mondays at 07:23 UTCpermissions:contents: read@@ -112,76 +129,53 @@ jobs:OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}```-Findings are report-only by default. Valid partial scans warn; scanner and-required reporting errors fail the job. Severity thresholds apply to complete scans.+Findings are report-only by default. Partial scans with valid results produce a+warning; scanner and required reporting errors fail the job. Severity thresholds+apply to complete scans.See the [Action setup and input reference](github-action/README.md) for PR scans,severity thresholds, and report uploads.## Containerized bulk scans-Use the included Docker Compose configuration for scans of many repositories. See the [container quick start](sdk/typescript/README.md#containerized-bulk-scans) for more detail.--For individual CLI stages with durable state and access to a separately deployed-findings service, use the same scanner image with the-[workflow runner Compose example](docker/README.md#workflow-runner).+Scan a list of repositories with the included Docker Compose configuration,+which keeps results and authentication between runs. See the+[container quick start](sdk/typescript/docs/cli.md#containerized-bulk-scans).+The [workflow runner](docker/README.md#workflow-runner) runs individual CLI stages+in containers and can connect to a separately deployed findings service.## Findings service (preview)-Run `npx @openai/codex-security serve` to start the service without Docker. See-[running without Docker](sdk/typescript/README.md#running-without-docker)-for prerequisites, credentials, and storage configuration.--The [findings service](sdk/typescript/README.md#findings-service-preview) runs-from the same `ghcr.io/openai/codex-security` image as the scanner (or a local-source build), with a separate container and state volume configured by-`compose.findings.yaml`. It stores findings and embeddings in SQLite and lists-findings with pagination. Its read-only dashboard at `/dashboard` refreshes every-five seconds and shows stored findings and duplicate groups from the service's-database. It also returns potential duplicates by embedding similarity within a-repository or an explicit all-repository scope. The-`npx @openai/codex-security publish scan --to custom --findings-url http://localhost:3000`-command uploads completed findings and their repository ID. The SDK and-`npx @openai/codex-security dedupe` command retrieve candidates, run independent Codex-reviews locally, and persist accepted duplicate groups; `--all-repositories`-opts into the broader scope.--Use `npx @openai/codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md`-to assess selected findings under your own policy before publishing tickets.-Scan classification checkpoints each finding in SQLite and reuses matching-assessments on reruns; `--reprocess` forces reassessment. The SDK exposes the same-classification operation; original scan severity stays unchanged. See [severity classification](sdk/typescript/README.md#classify-finding-severity).--## Other providers--Amazon Bedrock uses native Codex support; no connector or adapter is needed.-Select an AWS profile, the region where your account can invoke the model, and-the Bedrock model ID:+Store findings, browse them in a dashboard, and review potential duplicates.+Start the local service with:```bash-export AWS_PROFILE="security-scan"-export AWS_REGION="us-east-2"-npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna+npx @openai/codex-security serve```-Run the exports and scan in the same shell. Bedrock also accepts bearer tokens-and the AWS credential chain. Native Bedrock scans and local result viewing or-export do not require an OpenAI CLI login. Daybreak Blue and Red still need-[approved model access](docs/bedrock.md#daybreak-blue-and-red). Hosted publication has its-own authentication requirements. See [Bedrock setup and verification](docs/bedrock.md).+Publish a completed scan with `publish scan --to custom`, then use `dedupe` to+review potential duplicates and save accepted groups. Point both commands at the+service with `--findings-url`. The [service guide](sdk/typescript/docs/findings-service.md)+covers setup, publishing, deduplication, and Docker deployment.-For other inference providers, set the provider's API key and select a model:+The API has no built-in authentication. Imports send complete finding JSON to+the configured embeddings endpoint and need an embedding API key, even after+ChatGPT login.-```bash-export OPENROUTER_API_KEY="<your-openrouter-api-key>"-npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5+## Other providers-export FIREWORKS_API_KEY="<your-fireworks-api-key>"-npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b-```+Scans support OpenAI, Amazon Bedrock, OpenRouter, and Fireworks AI. Bedrock uses+AWS credentials and does not require a separate OpenAI login. See+[Bedrock setup](docs/bedrock.md) for AWS profiles, regions, and model access.++For OpenRouter and Fireworks AI, set the provider's API key and choose a supported+model. See [provider configuration](sdk/typescript/docs/cli.md#native-command-authentication-and-other-providers)+for examples.## Documentation-**👉👉 See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for full documentation.+- [Online documentation](https://learn.chatgpt.com/docs/security/cli)+- [CLI reference](sdk/typescript/docs/cli.md)+- [Project configuration](docs/project-configuration.md)+- [Examples](examples/README.md)-See [project configuration](docs/project-configuration.md) for reusable YAML/JSON-settings, CLI overrides, and editor schema support.+To report a vulnerability privately, follow the [security policy](SECURITY.md).diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 6e9d8a635..7d3b8a31b 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -1,7 +1,21 @@# `@openai/codex-security`-Run Codex Security scans from TypeScript or the command line. This ESM-only-package includes TypeScript declarations and the Codex runtime.+Run Codex Security from TypeScript or the command line to find, validate, and fix+security vulnerabilities in your code. The package includes the Codex runtime,+security plugin, and TypeScript declarations. It uses ES modules.++- Scan repositories, selected paths, or Git changes. Deep scans run parallel+ discovery workers on repositories and selected paths.+- Validate findings, generate patches, and verify existing fixes.+- Draft security policies and retain threat models.+- Review saved findings, identify duplicates, classify severity, and suggest owners.+- Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish+ findings to Linear or a findings service.+- Automate scans across repositories and project components.++See the [CLI reference](docs/cli.md),+[findings service guide](docs/findings-service.md), or+[online documentation](https://learn.chatgpt.com/docs/security) for setup and examples.Before version `1.0.0`, minor releases may change the public API.@@ -12,232 +26,11 @@ npm install @openai/codex-securitynpx @openai/codex-security --version```-Use Node.js 22.13.0+ (22.x), 24.x, or 26.x on macOS, Linux, or Windows.-Policy drafting, scans, exports, scan history, and saved findings also need Python 3.10+-(plus `tomli` on Python 3.10).+Supported runtimes:-## Run a scan from TypeScript--Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or-`CODEX_API_KEY`, then 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();-}-```--`result.findings` contains this scan's findings; `repositoryFindings` also-includes earlier open findings when available. Matching earlier findings can-make extra model calls; see [Progress and cost](#progress-and-cost).--Keep results outside the repository and restrict access: reports can contain-source code, vulnerability details, and reproduction steps.--### Select a Cyber access program--For the built-in OpenAI provider, select `standard`, `daybreak_blue`, or-`daybreak_red` per scan:--```ts-await security.run("/path/to/repository", {- auth: "api-key",- cyberAccessProgram: "daybreak_blue",-});-```--```sh-codex-security scan . --auth api-key --cyber-access-program daybreak_blue-```--`scan-components` accepts the same flag. Project files use-`scan.cyber_access_program`, including for bulk scans. An explicit CLI or SDK-selection overrides the project setting. Omission preserves Codex defaults;-`standard` explicitly selects the standard program.--The selection applies to Deep Scan discovery and reducer workers, resumed-workers, custom validation, and post-scan turns. Saved scan recipes retain it-for resume and rerun. Automatic component planning and finding matching also-use the selected program. API-key selection enables Codex's experimental Cyber-support unless the effective native configuration explicitly disables-`features.api_key_cyber_access_programs`.-Explicit disables and API entitlement failures remain errors. Selecting a-program does not grant access; the API verifies the key's entitlement.--### Validate an existing finding--```ts-const security = new CodexSecurity();-try {- const result = await security.validate({- repositoryPath: "/path/to/repository",- finding: {- title: "Possible SQL injection",- location: "src/query.ts:42",- },- outputDir: "/path/outside/repository/validation",- });- console.log(result.disposition);- console.log(result.report);-} finally {- await security.close();-}-```--Pass literal text or a JSON-serializable object as `finding`, not a file path.-Validation uses the client's settings and credentials without changing-repository files or adding a scan to history.--To disable Codex usage analytics and built-in metrics, create the client with-`new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.-This setting also applies to scans run by the same client.--Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,-or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.-`reportable` may rely on static analysis; `deferred` means insufficient evidence.-Failed, incomplete, or malformed responses reject the promise.--`outputDir` must be empty and outside the Git worktree; it defaults to-`validations/` under the state directory. Pass `auth` to select credentials-or `signal` to cancel.--### Import GitHub code scanning alerts--Import alerts, including third-party SARIF uploads, and validate them against-the matching local checkout:--```ts-import {- CodexSecurity,- importGitHubCodeScanningAlerts,-} from "@openai/codex-security";--const findings = await importGitHubCodeScanningAlerts({- repository: "example/repository",- alertNumbers: [12, 18], // Omit to list all open alerts on the default branch.- githubToken: process.env["GH_TOKEN"],-});--const security = new CodexSecurity();-try {- for (const finding of findings) {- const result = await security.validate({- repositoryPath: "/path/to/repository",- finding,- });- console.log(finding.url, result.disposition, result.outputDir);- }-} finally {- await security.close();-}-```--Each result contains `source`, `repository`, `number`, `url`, and the full-upstream `alert`. Import is read-only and does not start Codex or check out code.--Without `alertNumbers`, `state` filters alerts and defaults to `"open"`.-It also accepts `"closed"`, `"dismissed"`, `"fixed"`, and `"all"`. Exact alert-numbers ignore state and reject a nondefault `state`. Use `ref` for another-branch or pull-request reference.--Supply `githubToken` or use your `gh auth token` credentials, including GitHub-CLI token environment variables. `githubHost` defaults to `GH_HOST` or-`github.com`. The token needs read access to code scanning alerts; access-failures reject the import. Pass `signal` to cancel.--### SDK configuration and scan options--Constructor options:--| Option | Description |-| ---------------- | ----------------------------------------------------------------------- |-| `pluginPath` | Plugin directory or ZIP; defaults to the bundled plugin. |-| `pythonPath` | Python interpreter; overrides `PYTHON`. |-| `codexOverrides` | Supported settings to deep-merge into the isolated Codex configuration. |--Options for `security.run(repository, options)` and-`security.preflight(repository, options)`:--| Option | Description |-| ------------------------------------------- | ----------------------------------------------------------------------------------- |-| `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |-| `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |-| `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |-| `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |-| `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |-| `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |-| `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |-| `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |-| `outputDir` | Artifact directory outside the enclosing Git worktree. |-| `archiveExisting` | Archive existing results in `outputDir` before scanning. |-| `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |-| `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |-| `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |-| `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |-| `parentScanId` | Parent scan ID for a rerun. |-| `expectedPluginVersion` | Required original plugin version when replaying a scan. |-| `signal` | `AbortSignal` to cancel a scan. |--Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives-saved events with thread IDs and worker numbers. Deep scans can additionally use-`onDeepProgress` for durable independent-review counts: `completed`, `active`,-and `maximum`. The maximum is a configured cap, not a percentage denominator.-`ScanOptions` lists all callbacks.--`preflight` and CLI `--dry-run` check local inputs without starting Codex or-using the network. They don't authenticate, verify model access, resolve Python,-inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.-Deep preflight includes all six resolved deep settings and their origins in-`deepScanSources`. Applicable legacy deep configuration is validated during-preflight rather than after runtime startup.--`ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,-cancellation, workflow, and runtime controls. Load the same project file used by-`scan -c` through the SDK:--```ts-import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";--const { config, options } = await loadProjectConfig("codex-security.yaml");-await using security = new CodexSecurity(config);-const result = await security.run(repository, options);-if (- options.failureSeverity !== undefined &&- result.hasFindingsAtOrAbove(options.failureSeverity)-) {- process.exitCode = 1;-}-```--`resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`-object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,-options }` pair and an immutable `sources` map. Resolved context, prompt, and output-paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file-from `directory`, which defaults to the current directory; paths inside the file-are relative to that file. Object paths are relative to the supplied directory.-Scope paths remain relative to the selected repository. Neither helper starts a-scan, reads prompt contents, or discovers another configuration file. `preflight`-and `run` apply the existing local checks and remaining legacy deep defaults.-Project-file keys follow Codex's configuration convention; SDK options keep their-existing `camelCase` names, and CLI flags keep `kebab-case`.--Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add-callbacks there. Direct SDK prompt-file paths use the current directory; inline-text takes precedence over its matching file. Files use the same regular-file-protections as the CLI. The SDK records `failureSeverity` without throwing or-changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering-and leaves the findings unchanged.+- Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.+- Python 3.10+ for scans, policy generation, exports, scan history, and saved+ findings. Python 3.10 also needs `tomli`.## Authentication@@ -245,2654 +38,387 @@ Sign in with ChatGPT:```bashnpx @openai/codex-security login-npx @openai/codex-security scan .```-On remote or headless machines, use device auth if your workspace allows it:--```bash-npx @openai/codex-security login --device-auth-```--If device auth is disabled, [sign in over SSH](#remote-login-with-ssh-forwarding).--For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin:+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.+These keys apply to the current command without replacing your saved login.+To save an API key instead, pass it on stdin:```bashprintenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key```-Environment API keys apply to the current command; only `login --with-api-key`-saves them. Pass Codex access tokens on stdin to `login --with-access-token`.-Access-token environment variables are not scan API keys.+SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,+prefers `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.+Use `"chatgpt"` to ignore environment API keys. The CLI uses the same `--auth`+values and prompts in an interactive terminal when both credential types are available.-### Remote login with SSH forwarding+Some cybersecurity requests and protected findings require+[Trusted Access for Cyber](https://chatgpt.com/cyber) approval. See the+[authentication reference](docs/cli.md#authentication) for providers, stored+credentials, and Cyber access program selection.-Use an SSH tunnel when device auth is disabled.+### Remote login with SSH forwarding-On your local machine, replace `user@remote-host` with your SSH address and run:+On a remote or headless machine, try `login --device-auth` if your workspace+allows it. Otherwise, open an SSH tunnel from your local machine:```bashssh -L 1455:localhost:1455 user@remote-host```-Run login in that SSH session:--```bash-npx @openai/codex-security login-```--Open the sign-in URL in your local browser. Keep SSH connected until login finishes.--See the [authentication guide](https://learn.chatgpt.com/docs/auth?surface=cli#cli-fallback-forward-the-localhost-callback-over-ssh).--### Native command authentication and other providers--SDK callers can select native command authentication through-`codexOverrides.model_providers.<id>.auth` and `model_provider` (including a-selected `profile`). Scans, comparisons, and deduplication reviews preserve-that selection without requiring an API key or replacing it with a stored-login. Codex executes the helper and renews its token. Helper paths and relative-`auth.cwd` values resolve from the supplied `CODEX_HOME` (default `~/.codex`),-not the source checkout; an absolute `auth.cwd` is preserved. Comparisons and-reviews also honor the selected command provider in that home's `config.toml`.-Configuration is passed to Codex for validation, including profile support.--For other inference providers:--```bash-export OPENROUTER_API_KEY="<your-openrouter-api-key>"-npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5--export FIREWORKS_API_KEY="<your-fireworks-api-key>"-npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b-```+Run `npx @openai/codex-security login` in that SSH session, then open its sign-in+URL in your local browser. Keep SSH connected until login finishes.### Amazon Bedrock-Bedrock uses Codex's native provider; no custom connector or adapter is needed.-Choose an AWS identity and a region with access to the exact Bedrock model ID:--```bash-export AWS_PROFILE="security-scan"-export AWS_REGION="us-east-2"-npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna-```--For an AWS account with approved Daybreak Blue access in `us-east-2`:--```bash-npx @openai/codex-security scan . --provider amazon-bedrock \- --model openai.gpt-daybreak-blue-5.6-sol --effort high-```--For separately approved Daybreak Red model access in the same region:--```bash-npx @openai/codex-security scan . --provider amazon-bedrock \- --model openai.gpt-5.6-cyber --effort high-```--Both require OpenAI approval/enrollment followed by AWS model-access provisioning.-Red requires separate Red approval and the model-specific approval for-GPT-5.6-Cyber; Blue access does not include it. Contact your AWS account team.-See the AWS model cards for-[Blue](https://docs.aws.amazon.com/en_en/bedrock/latest/userguide/model-card-openai-gpt-daybreak-blue-56-sol.html)-and [Red](https://docs.aws.amazon.com/en_en/bedrock/latest/userguide/model-card-openai-gpt-56-cyber.html),-and [OpenAI's access overview](https://help.openai.com/en/articles/20001258-openai-daybreak-trusted-access-for-cyber-overview).--Run the exports and CLI command in the same shell, job, or container. Environment-changes in another terminal or a completed subprocess do not reach the scan.-Instead of a profile, you can use `AWS_BEARER_TOKEN_BEDROCK`, AWS access keys, web-identity, container credentials, or the default AWS credential chain. Temporary-access keys require all three of `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,-and `AWS_SESSION_TOKEN`. Set `AWS_REGION` for the selected model's region and-avoid mixing a profile with unrelated credential environment variables.--Once model access is provisioned, native Bedrock scans, including Deep Scan-workers, use AWS authentication without a separate `codex-security login` or-OpenAI API key. AWS still controls whether that identity can invoke the model.-Reading local reports, `scans show`, and `export` requires no cloud login.-[Publishing to Cloud](#publish-findings-to-cloud) is a separate operation that-requires ChatGPT credentials; AWS inference credentials do not grant that access.--`info` and `scan --dry-run` inspect local configuration and inputs. They do not-verify AWS credentials or invoke the model. A model-metadata or OpenAI access-advisory does not establish Bedrock access; use the actual inference result.-An AWS authentication error or model-access denial must be resolved for the-selected AWS identity, model, and region. See the-[Bedrock verification guide](../../docs/bedrock.md) for a live scan recipe.--OpenAI models such as `openai.gpt-5.6-luna` support `--max-cost`. The exact-`openai.gpt-daybreak-blue-5.6-sol` ID has AWS Standard commercial in-region price-estimates, including short/long-context ranges and the included AWS fee. These-estimates enable `--max-cost`; they are not billing totals or a guaranteed bill-limit. This pricing entry does not change other Bedrock models' estimates.--Bedrock scans, including Deep Scan workers, default to-`model_reasoning_summary = "none"` because some Bedrock models reject-`reasoning.summary`. This leaves reasoning effort unchanged. Explicit summary-settings in `--codex` overrides or the selected Codex profile take precedence.-For standard scans on older CLI versions, append-`--codex 'model_reasoning_summary="none"'` to your scan command if Bedrock-reports that `reasoning.summary` is unsupported. Deep scans require a CLI-version that forwards this setting to discovery and reducer workers, including-resumed workers. Version `0.1.27` and later includes that fix.--### OpenAI credentials--On Windows, set the API key in PowerShell:--```powershell-$env:OPENAI_API_KEY = "<your-api-key>"-npx @openai/codex-security scan C:\code\repository-```--Login, logout, scans, validation, patching, and fix verification share a private-credential home for stored OpenAI credentials, including custom providers with-`requires_openai_auth = true`:-`$CODEX_SECURITY_STATE_DIR/codex-home`, or-`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this credential-home outside the target directory and every enclosing Git worktree, including-when running a command from a subdirectory. Codex carries-`cli_auth_credentials_store`, `forced_login_method`, and-`forced_chatgpt_workspace_id` from the ambient configuration into this home,-including removing settings that are no longer present in the ambient configuration.-Each command carries its selected provider into this home. Patching and fix-verification also synchronize the ambient home's project-trust decisions and-project-root markers, preserving which project configuration Codex loads.-They hold the credential-home lock until the app-server thread is ready,-then release it before model execution.-Managed-device policies still apply. If this home has no credentials, it imports-an existing file-based Codex sign-in. Logout disables-imports until you log in again.--Finish operations using older versions before upgrading. Runtime preparation-holds the credential-home lock through pauses; exit or crash releases it.-Compatibility heartbeats protect active locks from older heartbeat-only-clients, but those clients can replace a paused client's lock.--Keep `.codex-security-scan.sqlite3` between operations; never remove it during-an operation. PID reuse can make old PID-only locks appear active and block-recovery. Stop all operations using this home before removing an old-`.codex-security-scan.lock` directory manually.--If ChatGPT credentials cannot be refreshed, run `login status`. Retry if the-sign-in recently changed; otherwise run `logout`, then `login`.--Interactive scans ask whether to use ChatGPT or an environment API key when-both are available. The choice applies to that scan. Noninteractive scans,-including CI, JSON output, and dry runs, prefer the API key. Choose with `--auth`:--```bash-npx @openai/codex-security scan . --auth chatgpt-npx @openai/codex-security scan . --auth api-key-```--`--auth` also works with `validate`, `patch`, and `verify-fix`. These commands-use the same stored login as `scan`, including a sign-in created with-`codex-security login --device-auth`:--```bash-npx @openai/codex-security patch OCCURRENCE_ID --auth chatgpt-npx @openai/codex-security verify-fix OCCURRENCE_ID --auth api-key-```--`--auth chatgpt` ignores environment API keys. `--auth api-key` requires-`OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; noninteractive-commands prefer `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.-Patch follow-up assessment uses the same selection, and `scan --patch` keeps-the scan's choice. Environment API keys do not replace the saved login.-The SDK uses the same `auth` option on `run`, `validate`, and `preflight`.-Codex may still need ChatGPT credentials to load workspace-managed policies-when using an API key.--Some cybersecurity requests and protected findings require Trusted Access for-Cyber approval. Apply or check your access at-[chatgpt.com/cyber](https://chatgpt.com/cyber).--## Generate a security policy--`policy` drafts `SECURITY.md` guidance for future scans. It does not run a-vulnerability scan, change application settings, or install the draft in the-checkout. It uses the scan runtime and authentication, requesting read-only-access to the selected repository or component and required tools. Network access,-web search, apps, and MCP servers are disabled. Drafts stay outside the checkout.-The host resolves inherited guidance once and includes each checked descendant-policy separately. Descendant policy links must stay within the selected component.-Inherited and reporting-policy links may also resolve to ancestor `SECURITY.md`-files or the checkout's `.github/SECURITY.md` and `docs/SECURITY.md`.-The model cannot read sibling components or Git metadata. Policy turns deny-access to the resolved Git metadata and markers, including those inside the-selected source tree, nested bare repositories, and associated alternate object-stores.-Policy shell tools inherit only Codex's core environment; custom shell environment-settings, login shells, and shell snapshots are disabled for these turns.-Knowledge-base text stays with the private review artifacts during generation-and is removed afterward.--Known limitation: policy preflight and generation currently fail on Unix-directories with non-UTF-8 names.--On macOS, the pinned Codex runtime does not fully enforce write restrictions-under `/tmp` (including `/private/tmp`). Keep the repository and artifacts outside-that tree when read-only enforcement is required. See the-[upstream sandbox limitation](https://github.com/openai/codex/issues/32395).--```bash-npx @openai/codex-security policy .-npx @openai/codex-security policy . --path services/api-npx @openai/codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high-npx @openai/codex-security policy . --dry-run --json-```--The repository defaults to the current directory. `--path` selects a component,-which inherits policies from its Git root, with the closest policy taking-precedence. Linked worktrees and initialized submodules use their own roots.-Targets and policy links must stay in the selected checkout, outside Git-metadata; ancestor links cannot widen a component policy's scope.--For an intentional separate Git directory, set `core.worktree` to the checkout's-absolute path. Use `git worktree repair` for moved linked worktrees.--Generation uses three Codex stages: describe the system, build a threat model,-then draft the policy. The first two documents support review; they are not-additional approval steps or policies to install.-In a terminal, it asks about facts the source cannot establish and shows the-exact diff. If both ChatGPT and API-key credentials are available, it asks which-to use; `--auth chatgpt` or `--auth api-key` selects one explicitly.--| Invocation | Calls Codex? | Result |-| ---------------------------- | ------------ | ----------------------------------------------------------------------- |-| `policy .` | Yes | Ask owner questions, save documents, and preview the draft. |-| `policy . --headless --json` | Yes | Save documents without prompts and return their paths and review notes. |-| `policy . --format md` | Yes | Generate a draft and write its Markdown to stdout. |-| `policy . --dry-run --json` | No | Check local inputs and show the resolved target and settings. |--None of these commands installs `SECURITY.md` in the repository. Output formats-change presentation; they do not turn generation into a saved-draft read.--### Review the draft--Review the saved `SECURITY.md` before copying it to the reported target. Check-links from `.github/SECURITY.md` or `docs/SECURITY.md`: copying can change their-guidance too. Preserve reporting instructions and obtain owner approval for-exclusions, accepted risks, and severity decisions. Later scans read this policy.--Generation and preview check for changes to the selected or inherited policies.-If governing guidance changes during generation, completed documents remain for-inspection, but no completed-draft manifest is written. Other source files are not-frozen; regenerate if relevant source or neighboring policies change.-A failed terminal preview reports a warning and the saved draft paths. Explicit-output formats return the draft directly without running a diff preview.--Use `--headless` or an explicit output format to skip questions. Unanswered-questions remain in the review notes. Drafts default to the Codex Security state-directory; `--output-dir` selects an empty directory outside every enclosing-Git checkout and its Git metadata.--```bash-npx @openai/codex-security policy . --path services/api \- --headless --output-dir /path/outside/repository/api-policy --json-```--The artifact directory contains:--| File | Purpose |-| ---------------------- | --------------------------------------------------------------------------------------- |-| `SECURITY.md` | Editable policy draft. |-| `threatmodel.md` | Detailed threat model with source references. |-| `project-spec.md` | System description and security boundaries. |-| `previous-SECURITY.md` | Original policy used for the diff. |-| `policy-draft.json` | Target, policy hashes, revision, retained threat model, stage status, and review notes. |--Keep supporting documents private until reviewed for disclosure. A generated-threat scenario is neither owner approval nor a confirmed vulnerability.+Bedrock scans use AWS credentials and model access. They do not require+`codex-security login` or an OpenAI API key. See the+[Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)+for setup, model selection, and verification.-`--format md` writes the draft to stdout. `--json` returns paths, review notes,-status, and estimated cost. Global filters and token options work with these-formats. Progress goes to stderr. `--full-output` reports failures with-`ok: false`. `--max-cost` applies to the whole generation. If a stage cannot-inspect required source evidence, generation stops and preserves completed-documents. Fix the reported problem and use a new output directory to retry.+## Run a scan from TypeScript-### Generate a policy from TypeScript+Scan a repository you own or have permission to assess:```tsimport { CodexSecurity } from "@openai/codex-security";const security = new CodexSecurity();+try {- const draft = await security.generatePolicy("/path/to/repository", {- path: "services/api",- knowledgeBasePaths: ["/path/to/architecture.md"],- onStage: (stage) => console.error(stage),- });-- console.log(await security.previewPolicy(draft));- // Open draft.draftPath in an editor to review the saved policy.+ const result = await security.run("/path/to/repository");++ console.log(result.reportPath);+ console.log(result.findings.findings);++ if (result.hasFindingsAtOrAbove("high")) {+ process.exitCode = 1;+ }} finally {await security.close();}```-`preflightPolicy()` checks local inputs without starting Codex.-`previewPolicy()` previews the supplied in-memory draft, uses the client's Python-setting, and makes terminal control characters visible. Editing the saved file-does not change that object. The standalone `securityPolicyDiff()` returns a raw diff-for files or other non-terminal uses; pass an interpreter explicitly if needed.-`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,-`maxCostUsd`, `signal`, and progress and cost callbacks. An optional-`answerQuestions` callback receives each group of up to three owner questions-and a cancellation signal. Without it, the questions remain unresolved.+Omitting `outputDir` saves results in the private Codex Security state directory.+To choose another location, use a new or empty directory outside the scanned+repository and its enclosing Git worktree. On macOS and Linux, an existing output+directory must be private to you (`chmod 700`).-## CLI+### Read results-```bash-npx @openai/codex-security policy . --path services/api-npx @openai/codex-security scan .-npx @openai/codex-security scan /path/to/repository --path src --path tests-npx @openai/codex-security scan /path/to/repository --diff origin/main --json-npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results-npx @openai/codex-security scan /path/to/repository --dry-run-```+| Result | Contents |+| --------------------------------- | ---------------------------------------------------------------- |+| `findings.findings` | Findings from this scan. |+| `reportPath` | Path to the Markdown report. |+| `coverage` | What the scan assessed and any coverage gaps. |+| `repositoryFindings` | This scan's findings plus earlier open findings, when available. |+| `sarifPath` | SARIF export path, or `null`. |+| `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |+| `cost` | Estimated model usage cost, or `null` when unavailable. |-Use `--help` to browse commands by task, or `<command> --help` (or `-h`) for-options and examples. `scan --help` groups options by scope, Deep Scan, results,-and patching; `publish scan --help` groups destination settings. `scans` and-`findings` run `list` when no subcommand is given.+Review coverage alongside findings. A report with no findings does not establish+that the repository is secure. Reports and logs can contain source code,+vulnerability details, and credentials; review them before sharing.-Use `--version` for the installed version, and-`info --json` for package, plugin, runtime, and model details. `--dry-run`-runs local preflight checks. `info -c FILE --json` inspects resolved configuration-and its sources without a repository or runtime.--### Project files--Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:--```bash-codex-security scan . -c codex-security.yaml --dry-run --json-codex-security scan . -c codex-security.json --model gpt-5.6-terra-codex-security init-codex-security info -c codex-security.yaml --json-```--Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,-and `info` accept `-c`. They also accept an operator-set-`CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is-loaded or discovered. The repository still comes from the command's target-selection. SDK `run()` and saved reruns do not load project files automatically.--The selected file is trusted like CLI options and SDK `codexOverrides`. Native-settings can start configured MCP server processes and select model-service destinations. Do not-select configuration controlled by an untrusted repository or pull request; keep-CI scanner configuration outside the checkout being assessed.--`init [file]` writes `codex-security.yaml` by default and never overwrites an-existing file. YAML starters show defaults as comments; JSON starters contain the-editor schema hint, relative to the chosen file and the invocation directory's-local package installation. `info` reports effective model details and native key sources-without dumping raw native values.--```yaml-# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json-scan:- mode: standard- scope:- paths: [src]-codex:- model: gpt-5.6-sol- model_reasoning_effort: xhigh-policy:- fail_on_severity: high-```--All settings are optional; `{}` uses the existing defaults. JSON files can use a-root `$schema` string pointing to the same packaged schema. Schema hints are for-editors; the CLI uses its bundled validator without fetching URLs, coercing values,-or dropping unknown keys. Native `codex` settings retain their existing checks and-profile semantics. CLI `scan --schema --json` describes command arguments.--Settings use built-in defaults, applicable legacy deep defaults, the file, then-explicit CLI values. Lists and scope variants are replaced. `--head` can refine-a file diff and `--base` a file working-tree scope. A selected native profile can-still override root model/effort values. Existing native alias-conflict checks-and the behavior of `--provider openai` are unchanged.--File context, instruction, validation, and output paths resolve from the file's-directory. CLI file paths resolve from the invocation directory; scope paths-resolve from the repository. The file cannot select a different repository or-enable automatic patching/publication. The loader does not evaluate code,-interpolate environment values, include remote files, or merge multiple files.--Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected-prompt paths, and the finding policy without dumping raw native configuration.-Missing or invalid selected files exit `2`. Help, version, and command schema-output do not load project files. Existing scan and finding-policy exit codes-remain unchanged.+The SDK does not set your process's exit status. Use `hasFindingsAtOrAbove()`+as in the example to enforce a severity threshold.### Scan options and output-`--path` scopes a scan to one or more paths, `--diff` scans committed changes,-and `--working-tree` scans staged and unstaged changes. Deep scans support-repository and path targets.--Bulk scans use clean, shallow checkouts and support repository or path scopes.-They reject configured diff or working-tree scopes before starting unless each-affected CSV row supplies its own path scope.--Working-tree snapshots include files from untracked nested Git repositories.-Initialized submodules must be clean and checked out at the commit recorded by-the parent repository.--Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including-JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,-skipping other binary files. Explicitly supplied unsupported binary files are rejected.-Bulk scans share these documents with every repository.--Use an empty output directory outside the scanned directory and enclosing Git-worktree. On macOS/Linux, existing directories must be private to you-(`chmod 700`). `--archive-existing` moves previous results to-`<output-dir>.previous-<timestamp>-<id>`; add `--dry-run` to preview the move.-SARIF output, when produced, is at `<scan-dir>/exports/results.sarif`.--Scans are report-only by default. Set `--fail-on-severity high` to exit with-`1` if a completed scan finds high or critical issues. Incomplete scans exit-with `2`, writing available results to stdout and a coverage warning to stderr.--For machine-readable scan output (`--format json` or `--format jsonl`), a scan-execution failure writes one structured object to stdout:--```json-{- "status": "failed",- "code": "SCAN_FAILED",- "message": "..."-}-```--With `--full-output`, the same code and message are reported under `error` in-an `ok: false` envelope instead.--The command still exits with `2` for runtime, export, invalid-input, or-incomplete-scan failures, and human-readable diagnostics remain on stderr.-Use `scan --schema --format json` to discover this failure variant alongside-the successful scan output. Cancellation and termination retain their `130`-and `143` exit codes.--### Import findings as a saved scan--Import an existing findings CSV or JSON file into local scan history and SQLite:+Pass scan settings as the second argument to `run()`. The following SDK snippets+assume an open `CodexSecurity` client named `security`; close it when finished.-```bash-codex-security scan import --csv /path/to/findings.csv-codex-security scan import --json /path/to/findings.json --format json-codex-security scan import --csv /path/to/findings.csv --dry-run+```ts+const result = await security.run("/path/to/repository", {+ target: ["src", "tests"],+ knowledgeBasePaths: ["/path/to/architecture.md"],+ scanPrompt: "Focus on authentication and authorization.",+ outputDir: "/path/outside/repository/results",+ maxCostUsd: 5,+});```-Supply exactly one of `--csv PATH` or `--json PATH`. CSV uses the existing-[findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv),-including the optional `candidate_id` column. JSON accepts a complete-`codex-security.findings` document or `{ "findings": [...] }`, with each finding-matching the existing findings schema. On `scan import`, `--json` selects the-input file; use `--format json` for JSON output. Other commands retain their-existing `--json` output flag. The selected input must be a regular file, and its-path must not traverse symbolic links or directory junctions. Use the direct-filesystem path when the file or a parent directory is linked.--Each import creates one completed scan using the configured-`CODEX_SECURITY_STATE_DIR`. The target is a retained copy of the input dataset,-independent of the current repository. Every source occurrence remains a separate-finding, including duplicate reports. Original identifiers are preserved in-`extensions.import`; the original file is sealed under `artifacts/import/`.-JSON writeup paths are retained as source metadata without reading external files.--Completion means the import finished. Coverage is unknown and the report states-that no security analysis was performed. Importing requires no model calls or-authentication. `--dry-run` validates without saving a scan. `--output-dir` and-`--archive-existing` control saved output, and `scans rerun SCAN_ID` reimports the-retained input.--### Generate mock scan results--Use `--mock` to populate a Standard scan with synthetic test data in seconds,-without Codex authentication or any LLM calls:+| Option | Use |+| ------------------------------------------- | ------------------------------------------------------------------------------ |+| `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |+| `mode` | `"standard"` (default) or `"deep"`. Deep scans support repositories and paths. |+| `knowledgeBasePaths` | Supporting text, PDF, DOCX files, or directories. |+| `scanPrompt` / `scanPromptFile` | Additional scan instructions. Inline text takes precedence. |+| `validationPrompt` / `validationPromptFile` | Custom validation instructions for standard scans. |+| `postScanPrompt` / `postScanPromptFile` | Follow-up instructions after the scan. |+| `outputDir` | Results directory; omit to use the state directory. |+| `archiveExisting` | Move previous results aside before reusing `outputDir`. |+| `maxCostUsd` | Stop at an estimated model cost; see [cost limits](#progress-and-cost). |+| `signal` | An `AbortSignal` to cancel the scan. |-```bash-codex-security scan /path/to/repository --mock-codex-security scan /path/to/repository --mock --output-dir /path/outside/repository/mock-results-```+The exported `ScanOptions` type describes all options and callbacks. For full+CLI behavior, see [scan options and output](docs/cli.md#scan-options-and-output).-The SDK equivalent is `await security.run(repository, { mock: true })`.-Mock mode is off by default. It uses normal target validation, scan registration,-artifact finalization, reports, and local scan/finding history. Output directories,-archiving, JSON output, exports, and `--fail-on-severity` work as usual.-`--dry-run` only validates inputs; `--mock` saves a completed scan.+### Scan a diff-Each run contains 12 findings across all severity levels: eight stable findings-recur on subsequent scans of the same repository, and four have new identities-on every run. Two pairs describe the same root causes with different titles and-identities, providing inputs for deduplication testing. Mock scans skip automatic-LLM matching; existing identity-based history indexing still runs. Separate-comparison or deduplication commands retain their usual model behavior.+```ts+import { DiffTarget } from "@openai/codex-security";-Titles, provenance, artifact metadata, and reports identify the results as-synthetic. Paths and code snippets are fictional and are never written into the-repository. Completion means fixture generation finished, not that the repository-was audited. Results enter the selected local state just like other scans; set-`CODEX_SECURITY_STATE_DIR` to a separate directory when creating disposable data.-Token usage is zero. `scans rerun` preserves mock mode.+const result = await security.run("/path/to/repository", {+ target: DiffTarget.refs({ base: "origin/main" }),+});+```-Mock mode supports repository, path, and diff targets in Standard mode. It cannot-be combined with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan-prompts. Scan prompts and knowledge-base inputs do not change the fixtures, and-mock scans do not offer interactive patching.+`DiffTarget.refs()` compares the base with `HEAD` unless you supply `head`.+The checkout must be clean, complete, and at that head revision.+Use `DiffTarget.workingTree()` for staged and unstaged changes relative to `HEAD`.+Diff targets require standard mode.-### Attribute scans to end users+### Configure the client-When scanning on behalf of users, pass each user's stable hashed ID:+Set model and native Codex settings on the client:```ts-await security.run("/path/to/repository", {- auth: "api-key",- safetyIdentifier: hashedUserId,+const security = new CodexSecurity({+ codexOverrides: {+ model_reasoning_effort: "high",+ analytics: { enabled: false },+ },});```-```bash-codex-security scan /path/to/repository --auth api-key --safety-identifier hashed-user-id-```+Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.+The bundled runtime and plugin are used by default. `pythonPath` overrides the+`PYTHON` environment variable. To choose a model, set `codexOverrides.model`.-Use a nonblank ID of 1 to 64 characters without NUL or personal data such as-email addresses. It applies to the scan, workers, retries, and follow-up work-without changing shared configuration. Supply it again for reruns.+Scans use an isolated Codex configuration. See+[runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)+for supported overrides and defaults.-The runtime needs native `--safety-identifier` support, and the plugin must-forward it to workers. The bundled runtime doesn't support it yet; choose a-compatible build with `CODEX_CLI_PATH`. The SDK checks the ID's format, not-runtime or plugin compatibility. Older versions may omit the ID.+### Load a project file-### Scan project components+Load shared CLI and SDK settings explicitly:-`scan --path` runs one scan across selected paths. To scan each local project-component separately (standard mode by default), use `scan-components`:+```ts+import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";-```bash-npx @openai/codex-security scan-components /path/to/project \- --component apps/api --component apps/web --component packages/shared \- --workers 4 --output-dir /path/outside/project/results+const { config, options } = await loadProjectConfig("codex-security.yaml");+const security = new CodexSecurity(config);++try {+ const result = await security.run("/path/to/repository", options);+ if (+ options.failureSeverity !== undefined &&+ result.hasFindingsAtOrAbove(options.failureSeverity)+ ) {+ process.exitCode = 1;+ }+} finally {+ await security.close();+}```-Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt-files, per-scan deep workers, cost limits, and severity policy. Component plans-override the file's scope. `output.directory` supplies the results directory when-`--output-dir` is omitted. A configured severity threshold returns exit `1` after-completed scans; failures or incomplete results return `2`.+`run()` does not discover project files. Paths inside a file resolve from that+file's directory; scope paths resolve from the repository. For a typed object,+use `resolveProjectConfig(input, directory?)`. Override loaded options with+`{ ...options, maxCostUsd: 5 }`.-Use `--auto` instead of `--component` for a proposed split. Save a plan to-review or edit, then run it with a new output directory:+Project files are trusted configuration and can select model endpoints or start+MCP servers. Keep CI scanner configuration outside the checkout being assessed.+See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)+for the schema and precedence rules.-```bash-npx @openai/codex-security scan-components /path/to/project \- --auto --plan-only --output-dir /path/outside/project/plan-npx @openai/codex-security scan-components /path/to/project \- --components-file /path/outside/project/plan/components.json \- --output-dir /path/outside/project/results-```+### Check inputs before scanning-For large repositories, automatic planning splits inventories into separate calls-that fit Codex's input character limit. It preserves directory boundaries where-possible and subdivides oversized packages and flat directories as needed. Each-call uses a fresh context and can select only paths within its batch. Omitted-files are retained in `Other files` components within those same boundaries.-Large repositories can therefore require more planning calls and produce more-components. Review or edit the saved plan before scanning with `--components-file`.--Components use repository-relative paths:--```json-{- "components": [- { "name": "API", "paths": ["apps/api", "packages/auth"] },- { "name": "Web", "paths": ["apps/web"] }- ]-}+```ts+const plan = await security.preflight("/path/to/repository", {+ target: ["src"],+ maxCostUsd: 5,+});+console.log(plan);```-Automatic planning respects Git ignore rules and groups omitted files under-`Other files`. Each proposed path must contain an inventoried file. Planning-leaves source files unchanged.--Each component saves artifacts under `component-N/`. Combined `findings.json`-merges high-confidence root-cause matches, keeping the highest severity and-original IDs. Uncertain matches stay separate. `summary.json` records coverage-and matching status; `report.md` links to component reports. Export and publish-from the individual scan folders, not the combined summary.--Large comparisons use bounded batches that cover every earlier/later finding-pair. Overlapping confirmed groups are joined in code. Finding text is not-truncated; pairs above Codex's input limit leave matching incomplete.--Use an empty output directory outside the project. Failed components don't-stop others, but failures, incomplete coverage, or failed matching exit with-`2`. Retry failed or incomplete components with-`--components-file retry-components.json` and a new output directory.-The retry report covers only those components; it does not update the original-combined report.--`--max-cost` applies per component, excluding planning and matching.-`--model` and `--effort` also apply to matching; `--auth` applies throughout.-Planning and matching reject an ambient command provider that conflicts with-explicit `--auth chatgpt` or `--auth api-key`. A command provider explicitly-selected through SDK `codexOverrides` retains its authentication configuration.-Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for-bulk scans.--From TypeScript, use `runComponentScans({ repository, outputDir, components })`.-Use `auto: true` for planning, `planOnly: true` to save the plan without scans,-and `scanOptions.auth` to select credentials.+`preflight()` checks local inputs without starting Codex or using the network.+It does not verify credentials, model access, Python, or the plugin. The CLI+equivalent is `scan --dry-run`.### Configure deep scans-For `scan --mode deep`, `--workers` sets discovery concurrency and `--subagents`-sets subagents per worker. `--stop-after-no-new` stops after that many runs-without new issues. `--max-discovery-runs` and `--max-time-hours` cap discovery-runs and duration. SDK equivalents:-```ts-await security.run("/path/to/repository", {+const result = await security.run("/path/to/repository", {mode: "deep",workers: 2,subagents: 0,stopAfterNoNew: 3,- stopAfterConsecutiveErrors: 2,+ stopAfterConsecutiveErrors: 3,maxDiscoveryRuns: 10,maxTimeHours: 1.5,});```-Set defaults in `$CODEX_HOME/codex-security/config.toml`:--```toml-[deep_scan]-workers = 4-subagents = 3-stop_after_no_new = 4-stop_after_consecutive_errors = 3-max_discovery_runs = 40-max_time_hours = 96-```--CLI and SDK options override these defaults. Project files can use-`scan.deep.stop_after_consecutive_errors`, and SDK calls can use-`stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot-configure this section. Worker and run counts must-be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means-four workers. Unknown keys are rejected.--`max_time_hours` accepts positive values up to 96, including fractional hours.-At the deadline, discovery stops; the scan combines and returns completed findings.--`scan --workers` controls discovery workers within one deep scan;-`bulk-scan --workers` controls how many repositories are scanned concurrently.--The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI-`subagents` setting. A valid deep block can remain inactive in standard mode;-explicit deep CLI options require deep mode. All six active values are resolved-before runtime preparation and saved in new recipes. Complete saved values are-independent of later changes to the legacy TOML file.--### Runtime configuration and worker limits--Scans use these isolated Codex defaults instead of your user or repository-configuration:--```toml-approval_policy = "on-request"-approvals_reviewer = "auto_review"-cli_auth_credentials_store = "auto"-model = "gpt-5.6-sol"-model_reasoning_effort = "xhigh"-model_reasoning_summary = "detailed" # "none" for amazon-bedrock-show_raw_agent_reasoning = true--[features]-plugins = true-goals = true--[features.multi_agent_v2]-enabled = true-max_concurrent_threads_per_session = 9--[windows]-sandbox = "unelevated"-```--Use `--model MODEL` to choose a model and `--effort EFFORT`-for reasoning effort. Both flags work with `scan`, `bulk-scan`, `scan-components`,-`policy`, `validate`, `patch`, `verify-fix`, `suggest-owners`, `classify-severity`,-`scans match`, and `scans compare`.--Model IDs and reasoning effort values are passed through to Codex unchanged.-The wrapper accepts values such as `minimal`, `none`, and `high`, as-well as future values, without requiring a wrapper update. Supported combinations-depend on the model, inference provider, installed Codex version, and credentials.-Codex and provider errors are reported without substituting another model or effort.-Omitting these flags preserves each command's defaults: scans, policy generation,-validation, patching, verification, and owner suggestions use `gpt-5.6-sol`/`xhigh`;-matching and severity classification use Codex's configured model and `medium` effort.--Repeat `--codex KEY=VALUE` for other TOML settings on commands that support it:--```bash-npx @openai/codex-security scan . \- --model gpt-6.1-sol \- --effort high \- --codex features.multi_agent_v2.max_concurrent_threads_per_session=4--npx @openai/codex-security patch issues.md --model gpt-6-astra --effort max-npx @openai/codex-security verify-fix issues.md --model gpt-6.1-sol --effort high-```--The thread limit of `9` includes the parent and up to eight delegated workers.-It is separate from deep-scan and bulk-scan worker counts.--Quote string values as TOML, for example-`--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and-`--codex 'model="..."'`, or both `--effort` and-`--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are-rejected.--Choose plugins with `--plugin-path`. Overrides of `plugins`, `marketplaces`,-or `features.plugins` are rejected, including in profiles. Multi-agent v2 must-stay enabled: `agents.max_threads` and-`features.multi_agent_v2.enabled=false` are rejected.--`validate`, `patch`, and `verify-fix` accept `--auth`, `--model`, and `--effort`.-Their `--codex` overrides are limited to `model`, `model_reasoning_effort`,-`model_provider`, `model_providers`, and `analytics.enabled`.-Use the same provider settings as `scan` when routing a standalone patch-through a custom inference gateway:--```bash-npx @openai/codex-security patch "Security issue" \- --model gateway-model \- --codex 'model_provider="gateway"' \- --codex 'model_providers.gateway.name="Gateway"' \- --codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \- --codex 'model_providers.gateway.wire_api="responses"' \- --codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'-```--Set the selected provider's API-key environment variable before running the-command; `--auth api-key` uses that configured variable. For `patch` and-`verify-fix`, provider overrides preserve unspecified fields from the provider's-existing Codex configuration. With `auto` or `api-key` authentication, a configured-`env_key` takes precedence over OpenAI account authentication, matching native Codex.-Explicit `--auth chatgpt` omits the selected custom provider's API-key environment-variable, clears any configured `experimental_bearer_token`, and selects stored-account authentication in its runtime configuration, even if the provider normally-uses only an API key or bearer token. The original environment and-Codex configuration remain unchanged.-Model, effort, and provider settings also apply to-`patch --assess-patch-risk`.-Sandbox, approval, and plugin settings remain controlled by the command.--`scans resume` and `scans rerun` retain the saved scan's settings. `dedupe` uses-separate screening and review models, so it does not expose a single model/effort-override.--Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and-built-in metrics for a command:--```bash-npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'-npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'-npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'-```--The same setting works for `scan` and `bulk-scan`. An explicit setting is-preserved when `scan --patch` starts remediation and when-`patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`-is also accepted; omitting the setting preserves the command's existing-configuration and Codex defaults. Validation ignores user configuration.-For stored OpenAI credentials, patching and verification read configuration-from the shared credential home. API-key commands and custom providers that use their own credentials retain-their ambient Codex configuration. Patching and verification preserve project trust from the-ambient home; explicit `--codex` settings apply to the command and its-patch-risk assessment.--This setting does not control explicitly configured OpenTelemetry log or trace-exporters, authentication, integrations, or CLI update checks.--See [Local security model](#local-security-model) for approval and filesystem-restrictions.--### Environment variables--| Variable | Effect |-| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |-| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |-| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |-| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |-| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |-| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |-| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |-| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |-| `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |-| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |-| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |-| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |-| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |-| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |-| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |-| `CI` | Disables interactive update notices. |-| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |--Custom Codex executables need thread source attribution for `exec` and-`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;-command shims such as `codex.cmd` fall back to the bundled executable.--Python lookup order: `--python` (on `scan`, `bulk-scan`, or `export`) or SDK-`pythonPath`, then `PYTHON`, the managed Codex runtime, and `python3` or `python`-on `PATH` (`py` also works on Windows). `CODEX_SECURITY_STATE_DIR` overrides-`CODEX_HOME` for state storage. Keep state and results outside the repository.--### Troubleshooting--By default, scans show progress, state transitions, warnings, and summaries.-Add `--verbose` or set-`CODEX_SECURITY_LOG_LEVEL=debug` to include lifecycle, configuration, retry,-and worker diagnostics on stderr. `LOG_LEVEL=debug` is the fallback when-`CODEX_SECURITY_LOG_LEVEL` is unset or blank.--```bash-npx @openai/codex-security scan . --verbose-```--Codex Security preserves diagnostic text, including credential-shaped values,-in CLI output, stored failures, publication receipts, and patch-risk summaries.-Verbosity controls the amount of diagnostic detail. Native Codex and upstream-SDK output may already have been redacted before reaching Codex Security.-Review output and artifacts for sensitive information before sharing them.+`workers` controls concurrent discovery workers; `subagents` controls delegation+within each worker. Time and run limits apply to discovery. After discovery+stops, the scan combines and returns completed findings. See+[deep scan settings](docs/cli.md#configure-deep-scans) for defaults and saved settings.### Progress and cost-Interactive scans show full-screen progress; CI, redirected output, and-`--headless` use plain status lines. Results go to stdout, progress and-diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for-sensitive information before sharing them.--The token summary shows uncached input, cache reads, cache writes, output,-and total tokens. Total tokens include all input plus output; cache reads and-writes are subsets of input, not extra tokens. When cache-write usage is missing,-the summary shows uncached input and cache writes as unavailable.-The final summary preserves missing-data information from a matching session log.-If the Codex runtime converts an omitted count to zero before recording it, the-CLI cannot distinguish that zero from reported usage.--Cost displays show a range using-[standard API prices](https://developers.openai.com/api/docs/pricing), because-runtime usage does not identify which requests received long-context pricing.-The minimum assumes short-context pricing; the maximum assumes long-context-pricing. These are token-cost estimates for the observed usage, excluding other-processing tiers, fees, surcharges, and account-specific pricing.--JSON results, scan history, and bulk-scan receipts preserve-`cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum-means an upper estimate is unavailable, including models without verified-long-context rates. `cost.pricing` records the price source, verification date,-processing tier, short-context rates, and verified long-context rates when known.-Models without known short-context prices still have no cost estimate.-GPT-6 Astra, GPT-6.1 Sol, and GPT-6 Luna have verified standard prices for cost-estimates and `--max-cost` limits.--For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.-`cacheWriteInputTokensReported: false` means at least one included usage record-did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.-In that case, the range minimum prices unclassified input as ordinary input,-and the maximum allows it to be cache writes. Token counts remain unchanged.-Older saved records remain readable and display a labeled legacy estimate;-they are not repriced using current rates.--For compatibility, `cost.estimatedUsd` retains the short-context baseline used-by existing spending limits. `cost.pricing.context: "short"` describes that-baseline, not observed request contexts. Use `estimatedUsdRange` for cost-reporting. This change does not change when spending limits stop scans.--`--max-cost USD` stops the scan and its workers when estimated cost exceeds-the limit, though in-flight requests can finish above it. If deep-scan-discovery has finished, the scan returns a sealed partial report without more-model calls and lists unvalidated candidates as follow-up work. Bulk scans-apply the limit per repository attempt.--With `--max-cost`, automatic finding-history matching makes at most one extra-model call. If it needs more context, the completed scan is kept and a warning-directs you to run `scans match --all` explicitly.--For a single scan in the interactive dashboard, reaching 80% of the limit-offers a higher **total** USD limit. Enter a larger amount to approve it, or-press Enter with an empty input or Escape to keep the current limit. The scan-continues running while you decide, and the existing limit remains enforced-until the increase is saved. Increases keep the same scan and accumulated cost;-they do not restart work or extend time or discovery limits. CI, JSON/JSONL,-`--headless`, and `--verbose` scans do not offer budget increases. If usage crosses the limit-before an increase is approved, the scan still stops.--SDK callers can supply `onBudgetApproaching({ maxCostUsd, cost, signal })` and-return a higher total limit, or `undefined` to keep the current limit. The-callback runs once per limit at 80% usage without blocking tracking or-execution. Its signal aborts when the scan stops or finishes model work; late-answers are ignored. Invalid increases or failures to save them leave the-existing limit in place and report a warning. `onCost(cost, maxCostUsd)` reports-the current limit, including after an approved increase.--These amounts estimate API-equivalent model usage, not ChatGPT subscription-allowance. Post-scan prompts run after scan cost tracking ends and are outside-this limit.--### Bulk scans--Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select-GitHub repositories pushed in the last 90 days. Forks and archived repositories-are excluded; private checkouts use your GitHub CLI sign-in. The command asks-for an output directory and saves your selection there as `repositories.csv`.-`--output-dir` requires CSV input.--For CI or an existing repository list, pass a CSV with `id`, `repository`, and-`revision` (full commit hash). Optional `scope`, `mode`, and `prompt` columns-customize each scan:--```csv-id,repository,revision,scope,mode,prompt-service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Focus on authentication and authorization.-```--```bash-npx @openai/codex-security bulk-scan repositories.csv \- --output-dir /path/outside/repositories/security-scans --workers 4-```+Use `onProgress` for scan progress, `onWorkerStatus` for individual workers, and+`onCost` for cost updates. `onDeepProgress` reports completed, active, and maximum+independent reviews; the maximum is a cap, not a percentage denominator.-`--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each-repository's CSV `prompt` follows the shared instructions.-`-c FILE` shares config with single scans: CSV mode/scope override file defaults,-and deep settings apply only to deep rows. `output.directory` can supply the-results directory. `fail_on_severity` returns exit `1` without retrying completed-scans, including when resuming saved results. A changed project configuration-requires a new campaign output directory.-`--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,-even after a failed or incomplete scan, but not after cancellation or a-cost-limit stop.+Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription+allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the+short-context estimate; in-flight requests can exceed it. Post-scan prompts run+outside that limit. Matching earlier findings can also make model calls.+See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.-`--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending-repository per invocation. Rerunning the command continues the campaign, skips-completed results, and starts new attempts for pending repositories. If an-attempt directory is occupied, that repository stops before replacing its-checkout and the command recommends `--recover`.--#### Recovering failed or interrupted bulk scans--Use the original CSV, output directory, and campaign options with `--recover`:--```bash-npx @openai/codex-security bulk-scan repositories.csv \- --output-dir /path/outside/repositories/security-scans --recover-```--Recovery requires an existing campaign with a matching manifest. It skips-completed results, including partial coverage, and repositories never started.-For each failed or interrupted repository, it checks the latest attempt:--- A sealed scan is recorded in `results.jsonl` without scanning again.-- An eligible running Deep Scan resumes its original session, keeping its scan- ID, completed workers, artifacts, saved settings, and accumulated cost.-- A failed, canceled, or otherwise unavailable scan starts a new attempt at the- CSV's pinned revision. Attempt numbers account for both receipts and existing- directories. Old artifacts and checkouts are preserved; new attempts use- `recovery-checkouts/<id>/attempt-<n>`.--`--workers` still defaults to `4`; `--max-attempts` defaults to one recovery or-new attempt per repository. A resume connection failure stops that repository-for this invocation instead of starting another scan. Other repositories-continue. Failed and interrupted recovery checkouts remain available for a later-`--recover`; fresh completed checkouts are removed after recording the result.-If a reboot interrupted a receipt write, its unfinished tail is saved beside-`results.jsonl` as `results.jsonl.interrupted-<id>` before appending valid records.--Same-scan resume requires the original checkout, session logs, and Codex Security-state directory. Recovery does not reconstruct deleted checkpoints or fix the-underlying cause of execution failures. New attempts incur new scan costs.-Any remaining failures or partial coverage keep exit code `2`.-`bulk-scan --help` lists all options.--### Custom validation--Replace the final validation step of a standard or diff scan with a prompt-file. Source review still runs; discovery workers do not receive this prompt.--```bash-npx @openai/codex-security scan . --validation-prompt-file validation.md-```--The SDK accepts the same file as `validationPromptFile`, or inline text as-`validationPrompt`:+### Validate an existing finding```ts-const result = await security.run(repository, {- validationPrompt:- "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",+const result = await security.validate({+ repositoryPath: "/path/to/repository",+ finding: {+ title: "Possible SQL injection",+ location: "src/query.ts:42",+ },});+console.log(result.disposition, result.report);```-Put setup, allowed targets, required evidence, and cleanup in the prompt.-There are no separate setup or teardown hooks. Use environment variables for-credentials; keep secrets out of prompts and validation output. Deep scans-reject this option; scans without candidates skip it.--The SDK supplies the candidate IDs and requires a `CustomValidationResult`:--```json-{- "status": "complete",- "reason": null,- "validations": [- {- "candidateId": "candidate-1",- "validation": {- "disposition": "reportable",- "method": "integration test",- "confidence": "high",- "confidence_rationale": "The test reproduced the reported behavior.",- "rubric": "Check the protected operation.",- "evidence": ["The unauthorized request succeeded."],- "counterevidence_or_proof_gap": "",- "remaining_uncertainty": "",- "artifact_paths": []- },- "severity": null,- "impact": null- }- ]-}-```--Return one result per candidate with disposition `reportable`, `suppressed`,-`not_applicable`, or `deferred`. Set `severity` or `impact` to-`{ "level": "medium", "rationale": "..." }` to revise an assessment, or `null`-to retain it. Identity and source locations stay unchanged.--The scan saves candidates and results, including suppressed and deferred-cases, under `artifacts/custom-validation/`. Coverage is incomplete if setup-fails, output is incomplete or invalid, or any candidate is deferred. An-incompatible plugin stops the scan; validation never falls back to the default.-Repeat `--validation-prompt-file` on reruns.--### Publish findings to Cloud--Choose completed scans from local history:--```bash-npx @openai/codex-security publish scan --to cloud --dry-run --json-```--Press Space to select scans, then Enter to submit. Nothing is preselected.--For scripts, repeat `--scan` with saved IDs or unique prefixes of at least-eight characters:--```bash-npx @openai/codex-security publish scan \- --scan SCAN_ID_A --scan SCAN_ID_B \- --to cloud --dry-run --json-```--Find IDs with `scans list --json`, or use `--scan latest` for the current-repository's latest completed scan. You still need the local sealed artifacts.--`--dry-run` checks inputs and prints findings without logging in or uploading.-Uploads need ChatGPT credentials saved to a file. Set this in Codex-`config.toml`, then sign in with ChatGPT again:+Pass finding text or a JSON-serializable object, not a file path. Validation uses+the client's settings and credentials without changing repository files or+adding a scan to history.-```toml-cli_auth_credentials_store = "file"-```+The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.+`reportable` can rely on static analysis; `deferred` means there is insufficient+evidence. Failed or malformed responses reject the promise. `outputDir`, `auth`,+and `signal` are also supported.-Cloud publication rejects automatic and keyring storage, even if an-`auth.json` file exists: the file may be stale or belong to another account.+To validate GitHub code scanning alerts, first import them with+`importGitHubCodeScanningAlerts()`. See the+[import guide](docs/cli.md#import-alerts-from-the-cli) for CLI and SDK examples.-For CSV input, use an export from `codex-security export --export-format csv`:+## CLI```bash-npx @openai/codex-security publish scan --to cloud \- --csv /path/outside/repository/findings.csv+npx @openai/codex-security scan .+npx @openai/codex-security scan . --path src --path tests+npx @openai/codex-security scan . --diff origin/main --json+npx @openai/codex-security scan . --dry-run```-The [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)-has the required columns; deep-scan exports may add `candidate_id`. `--csv`-only supports Cloud and cannot be combined with scan IDs or directories.--For artifacts outside local history, pass a directory or repeat `--scan-dir PATH`.-Each directory must contain one completed, sealed scan. Bulk-run directories-and `results.jsonl` files aren't accepted. Don't mix directories with `--scan`.--Multiple scans return:--- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.-- `failed`: errors with `scanDir` and, for saved selections, `scanId`.-- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command- did not reach before cancellation.--One scan returns its result directly. Uploads run sequentially. A failed upload-doesn't stop the rest, but the command exits with `2` if any failed. Cancellation-stops new requests and returns results so far with `130` (Ctrl-C) or `143`-(SIGTERM), unless all publications were already confirmed.--Save the output: Cloud receipts aren't stored in scan history. They contain-Cloud finding IDs in request order, not local IDs. Uploads aren't retried-automatically. Cloud may have accepted an upload even if its receipt is missing-or invalid. Check Cloud before retrying; never resend a scan with a confirmed-receipt.+Use `--help` to find commands and `<command> --help` for options. Scans are+report-only by default. Add `--fail-on-severity high` to return exit code `1`+for high or critical findings; incomplete scans and execution failures return `2`.-### Publish completed scans to Linear+The [CLI reference](docs/cli.md) covers scan history, reruns, bulk and component+scans, custom validation, imports, patching, and integrations.-Linear publication accepts one completed scan:+### Generate a security policy```bash-npx @openai/codex-security publish scan --scan SCAN_ID \- --to linear \- --linear-team TEAM_ID+npx @openai/codex-security policy .+npx @openai/codex-security policy . --path services/api```-Choose a scan by ID, unique prefix, `latest`, or directory (positional or-`--scan-dir PATH`). Omit the selector for an interactive picker. Live publication-and `--skip-existing` require the scan in local history; a directory-based-`--dry-run` alone does not.--Add `--linear-project PROJECT_ID` (`--project` is an alias) to place issues in-a project. Destination flags override `CODEX_SECURITY_LINEAR_TEAM` and-`CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run` previews issue titles without-contacting Linear; `--json` returns structured results.--Sign in to Codex and connect Linear to publish with your existing Codex-configuration; publication doesn't use the isolated scan home. To use the-Linear API directly, set a personal API key:--```bash-export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY-npx @openai/codex-security publish scan /path/to/completed-scan \- --to linear \- --linear-team TEAM_ID-```+`policy` drafts `SECURITY.md` outside the checkout. Review the draft before+installing it; it guides future scans. The SDK provides `generatePolicy()`,+`preflightPolicy()`, and `previewPolicy()`. See+[policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,+headless use, artifacts, and review requirements.-Direct API publication leaves issues unassigned unless `--linear-assignee`-specifies a user ID or email. `--linear-api-key KEY` overrides the environment-variable, but exposes the key in shell history and process listings. Keys are-omitted from saved results and artifacts; error messages are returned unchanged.+### Exports and CI-Check scan integrity and recorded publications before publishing:+Export saved findings or a threat model without starting another analysis:```bash-npx @openai/codex-security publish check /path/to/completed-scan \- --to linear --linear-team TEAM_ID --json-```--`publish check` is read-only. With an API key it also checks authentication,-team, project, and assignee access; connected-app access is `not-checked`.-Issue-creation permission is always `not-tested`.--Each finding becomes an issue titled `[Codex Security][HIGH] Finding title`-with source locations, code, evidence, and remediation. Choose a destination-authorized to receive these details. Local history stores successful issue IDs-separately from sealed scan artifacts.--Republishing creates duplicates by default. `--skip-existing` skips recorded-successes for the same occurrence, team, and project, without checking remote-issues. Results distinguish `created` and `skipped` issues. Add `--dry-run`-to preview the remaining findings.--After an interrupted or indeterminate publication, check the retained handoff,-evidence, and Linear destination before retrying. Issues may exist without a-local record. The CLI can't recover those issues, and `--skip-existing` can't-prevent duplicates from them or concurrent publications.--```ts-import { publishScan } from "@openai/codex-security";--const publication = await publishScan("/path/to/completed-scan", {- destination: "linear",- teamId: "TEAM_ID",-});--console.log(publication.scanId);-console.log(publication.created.length);+npx @openai/codex-security export --scan SCAN_ID --export-format sarif --output results.sarif+npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md```-Options include `projectId`, `skipExisting`, `linearApiKey` for direct API-publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts-the same destination options for a read-only check.+The SDK provides `exportArtifact()` for the same offline operations. See+[exports and CI](docs/cli.md#exports-and-ci) for details. For repository or pull+request scans in GitHub Actions, use the+[GitHub Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md).+Separate examples cover+[GitHub Actions with Bedrock](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md)+and [Azure Pipelines](https://github.com/openai/codex-security/blob/main/examples/azure-pipelines/README.md).### Classify finding severity-Classify findings after a scan or dedupe without repeating discovery or changing-the original severity, evidence, or sealed scan artifacts:--```bash-codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json-codex-security classify-severity --scan latest --rubric /path/to/policy.md --json-codex-security classify-severity --scan-dir /path/to/completed-scan --json-```--`--scan` accepts a saved scan ID, unique prefix, or `latest` for the current-repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external-completed scan without requiring local history. Supply exactly one selector.-Omitting `--rubric` inherits each finding's existing severity without a model call.--`--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`-to provide supporting architecture, deployment, or business context. Both accept-the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.-Rubric classification uses the full supplied report and context in a separate-read-only Codex turn per finding, without source inspection, tools, or new-validation. `--model` and `--effort` select the classification model and reasoning-effort; otherwise Codex's configured model and the helper's medium effort apply.--The result contains one assessment per selected finding:--- `decision`: `assessed` or `excluded`; policy exclusions do not become Low.-- `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.-- `rubricLabel`: the policy's original label, such as `URGENT`, normalized to- `critical`; null for inherited severity or exclusions.-- `rationale`, separate `confidence`, and `reviewTrigger` describing a missing- fact that would change the classification. Inherited severity has no new- classification-confidence judgment.-- `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the- report. Top-level metadata includes `assessedAt`, `rubricSha256`, and- `knowledgeBaseSha256` for the supplied policy and context snapshots.--Scan classification saves each successful finding immediately in the local-workbench SQLite database. Rerunning skips assessments with matching finding-evidence, rubric, and knowledge-base hashes, including exclusions, and returns-both reused and newly generated assessments. Changed inputs are classified again.-Use `--reprocess` to rerun every selected finding regardless of its saved-assessment; each row is replaced only after its new assessment succeeds. A failed-or canceled run keeps completed checkpoints, so a normal retry resumes missing-work. Changing only the model or effort requires `--reprocess`.--SQLite is authoritative. A successful run also exports the complete selected-result to `severity-classification.json` alongside the sealed artifacts. The file-is replaced atomically and is not read for reuse or publication. The scan's-original findings and severity are unchanged. The database stores the requested-selection and policy/context hashes; publication rejects an incomplete selection-or assessments whose inputs no longer match. Rubric documents are read at-classification time, not again at publication time.--```bash-codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess-```--Use repeatable `--finding-id ID` to classify a selected set, such as the-`uniqueFindingIds` returned by dedupe. With a saved classification, Linear-publication defaults to that selection, omits excluded records, and uses assessed-severity for issue priority and title. The description retains original scan-severity and adds classification reasoning. Without a saved classification,-publication retains its existing severity mapping and selection behavior.-Publication rejects assessments whose IDs or evidence hashes no longer match.--```bash-codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \- --finding-id FINDING_ID --json-codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \- --dry-run --json-codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \- --skip-existing --json-```--`publish scan --to linear` also accepts repeatable `--finding-id ID` to select a-subset directly. If a classification exists, every explicitly selected finding-must have an assessment. Classification does not change existing Linear tickets;-`--skip-existing` preserves recorded tickets and any human priority edits. It-retains the existing limitations around unrecorded or concurrent publications.--The SDK exposes the same operations:--```ts-import {- classifySeverity,- classifyScanSeverity,- classifyScanDirectorySeverity,- publishScan,-} from "@openai/codex-security";--// Supplied reports from any source: returns an assessment without writing files.-const classification = await classifySeverity(findings, {- rubricPath: "/path/to/policy.md",- knowledgeBasePaths: ["/path/to/context.md"],-});--// Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.-await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });-await classifyScanDirectorySeverity(scanDirectory, {- rubricPath: "/path/to/policy.md",- findingIds: dedupeResult.uniqueFindingIds,-});--await publishScan(scanDirectory, {- destination: "linear",- teamId: "TEAM_ID",- skipExisting: true,-});--// Alternatively supply a classification directly, without a saved assessment.-await publishScan(scanDirectory, {- destination: "linear",- teamId: "TEAM_ID",- classification,- findingIds: classification.assessments.map(({ findingId }) => findingId),- dryRun: true,-});-```--`classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus-their available evidence and metadata. Original `severity` and `occurrenceId`-may be absent for imported reports; reports without severity require a rubric.-`classifySeverity` remains an in-memory operation without database persistence.-The scan wrappers use the local state database (also for external scan-directories), accept `reprocess: true`, and accept `findingIds: []` as an-intentionally empty selection. Rows outside the selected set are retained.-Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.-JSON exports from versions without database checkpoints must be reclassified-once before they can be reused.-Pass `signal` to cancel any classification operation. Keep human overrides in the-calling workflow or issue tracker; assessments remain separate recommendations.+Use `classify-severity` with your own rubric to assess saved findings without+changing their original severity or evidence. The SDK exposes `classifySeverity()`,+`classifyScanSeverity()`, and `classifyScanDirectorySeverity()`. See+[severity classification](docs/cli.md#classify-finding-severity) for selection,+checkpointing, and publication behavior.### Suggest finding owners-Suggest contributors who can fix findings in a local Git repository:--```bash-npx @openai/codex-security suggest-owners findings.json --source-root /path/to/repo --json > owners.json-```--The input is a Codex Security findings document or a JSON object containing a-`findings` array, such as the output of `export --export-format json`. The source-root defaults to the current directory. The command reads committed `HEAD`,-source around each finding location, blame for the affected lines, and file-history reachable from that commit. It does not read uncommitted source or change-findings, files, or ticket assignments.--The checkout must own its Git references and objects. Linked worktrees and bound-separate Git directories are supported. Checkouts that borrow external object-stores, including `git clone --shared`, are rejected; use an independent clone.--Each result preserves the finding and occurrence IDs and has status `identified`,-`abstained`, or `error`. Identified results include an observed Git author name-and email, a reason, and checked Git citations. Missing source or unclear-ownership produces an abstention. Git identities do not establish active-employment or an issue tracker account. Match accounts before assigning tickets.-Use a checkout that matches the findings; otherwise their line ranges may be stale.--The command uses existing Codex credentials and the Codex Security default model and effort.-Use `--model` and `--effort` to override them. Model selection runs with tools and-network access disabled. Exit code `0` includes successful recommendations and-abstentions; `2` means invalid input or at least one failed recommendation. A-per-finding failure retains the other results in the report. Cancellation uses-exit code `130` for SIGINT or `143` for SIGTERM.--The SDK accepts finding IDs, titles, summaries, and source locations directly:--```ts-import { suggestOwners } from "@openai/codex-security";--const owners = await suggestOwners("/path/to/repo", result.findings, {- reasoningEffort: "high",-});-```--SDK inputs may include `sourceRevision`. If it differs from `HEAD`, the collector-ignores the old line ranges and reports the mismatch. Reports record the analyzed-revision, model, effort, and limitations; they remain separate from scan artifacts.--### Feedback--Send a problem report to OpenAI and share the returned feedback ID with support:--```sh-codex-security feedback --reason "The scan stopped before it finished"-codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs-```--Without an ID, `feedback` selects the most recently started scan in the current-repository, including active or failed scans. If there are no saved scans, it sends-a general report. The report includes your description, version details, and the selected-scan and session IDs. Add `--json` for structured output.--Logs are off by default. `--include-logs` uploads Codex diagnostics and saved scan-and worker activity. These can contain source code, prompts, findings, tool-output, and other sensitive data. Only include logs you can share with OpenAI.-The command uses Codex's feedback service and respects `feedback.enabled = false`.--For scans started through the Desktop plugin, run the command on the machine-where the scan ran, using the same Codex home and Codex Security state directory.-It searches active and archived sessions in both that Codex home and the CLI's-managed home, and attaches available worker logs even if the parent log is missing.-Earlier retries that started separate sessions may be missing when their session-IDs are no longer recorded.--Standard scans run inside an existing Codex conversation attach only the owner's-saved session; they do not record which subagents belong to the scan. Deep Scans-and scans launched by `codex-security` also attach their recorded execution-threads and descendants, without following unrelated children of the owner.--### Scan history and reruns--Commands default to the current repository. Select scans by full ID or a-unique prefix of at least eight characters.--New recipes retain resolved settings and the authentication choice, not-credentials. Reruns do not reload project files; complete saved deep settings do-not use current legacy defaults. Older partial recipes retain their previous-fallback behavior. Context paths and the current checkout are not immutable input-snapshots.--Reruns require replacement scan instructions when the original scan used them.-New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use-`scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.-Replacement files resolve from the invocation directory. Custom validation keeps its existing-`scans rerun --validation-prompt-file` requirement.--| Command | Purpose |-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |-| `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |-| `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |-| `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |-| `scans resume SCAN_ID` | Resume an interrupted Deep Scan in its original session and output directory. |-| `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |-| `scans match BEFORE AFTER` | Link findings with the same root cause. |-| `scans match --all` | Match completed scans across the repository's worktrees and clones. |-| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to the latest two completed scans. |-| `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |-| `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |--#### Resuming an interrupted Deep Scan--After the CLI process or host stops unexpectedly, find the scan and rejoin it:--```bash-npx @openai/codex-security scans list --scan-root /path/to/security-scans-npx @openai/codex-security scans resume SCAN_ID-```--The scan must still be `running`, with its original checkout, output directory,-and owning Codex session available in the same Codex Security state directory.-The checkout's identity, revision, and contents must match the saved target.-Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.--Resume uses the saved configuration and instructions with the installed plugin.-New scans save the selected authentication mode, explicit safety identifier, and-post-scan prompt contents. Resume restores the authentication choice without-saving credentials. Single-scan resume restores the prompt even if its original-file changes or disappears.-Older records that did not save these values cannot reconstruct them. Bulk-recovery still requires matching campaign inputs and options; it uses the supplied-post-scan prompt when the scan has no saved prompt.-It keeps the scan ID, completed workers, artifacts, and accumulated session cost.-The existing coordinator recovers interrupted workers after its lease expires.-If discovery finished before the interruption, resume completes and seals the-same scan. No archiving or new attempt directory is needed. A failed connection-leaves the existing scan available for another resume attempt.--Compatible saved scans can resume after a plugin update. Already-sealed results-keep their original producer version and contents when completion is recorded.-Unsupported or invalid sealed artifacts are rejected before resuming, preserving-the saved scan state and files.--For bulk campaigns, use [`bulk-scan --recover`](#recovering-failed-or-interrupted-bulk-scans)-to recover eligible attempts and update `results.jsonl`. Individual `scans resume`-does not update campaign receipts.--#### Matching saved scans--Matching requires sealed artifacts and reuses saved matches unless you pass-`--force`. Comparisons classify findings as new, persisting, reopened, resolved,-or unknown. Missing findings aren't resolved if the later scan is incomplete-or excludes their original scope. With one ID, `scans compare` compares it-to the latest completed scan.--Use `scans match --all --force` to rebuild comparisons chronologically while-retaining stable finding identities. Ctrl-C keeps comparisons already saved.-Only high-confidence duplicates are grouped; uncertain and independently-related findings stay separate. Matching preserves triage and sealed artifacts.--Codex runs only for new matching decisions, using existing authentication.-`scans match` and `scans compare` accept `--model` and `--effort`; the defaults-are Codex's configured model and `medium` effort. Cached matches are reused-even when these flags change. To recompute all matches:--```bash-npx @openai/codex-security scans match --all --force \- --model gpt-6.1-sol --effort high-```--Scans without sealed artifacts are skipped, but their confirmed links can still-be reused. Older custom plugins save confirmed and uncertain matches; use the-bundled plugin for related links and large comparisons.--SDK callers can compare findings without saving a workbench comparison:--```ts-import { readFile } from "node:fs/promises";-import {- matchScanFindings,- type FindingsDocument,-} from "@openai/codex-security";--const before = JSON.parse(- await readFile("/path/to/earlier-scan/findings.json", "utf8"),-) as FindingsDocument;-const after = JSON.parse(- await readFile("/path/to/later-scan/findings.json", "utf8"),-) as FindingsDocument;--const comparison = await matchScanFindings(- { before: before.findings, after: after.findings },- { workingDirectory: "/path/to/repository" },-);-console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);-```--Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values-from your store. Results identify the original `occurrenceId` values. Options-include model, reasoning effort, `AbortSignal`, and an optional `onProgress`-callback whose errors do not interrupt matching.--History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or-`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and-workbench maintain the database and its journal files as the current user.-Keep state private, writable, and outside the scanned repository.--On Windows, an older sandboxed run can leave an invalid credential-home ancestor-ACL. Preserve that state and its reports, and select a **new**, private-`CODEX_SECURITY_STATE_DIR` outside both the old state and the repository.-Sign in again if needed and keep using the new setting; it starts separate scan-history. Existing ancestor ACLs are not rewritten.--Scan configurations don't store credentials; session logs and live details can-contain them. Press `d` during a scan for details, then `a` for all sources,-`m` for the main scan, or `1` through `9` for a worker.--### Exports and CI--`export` reads saved results without starting Codex or loading credentials.-It defaults to the current repository's latest completed scan. Select a result-directory positionally, or use `--scan ID` with a scan ID or unique prefix;-these source selectors cannot be combined. `--artifact findings` is the default-and requires sealed results. Findings support `--export-format csv|json|sarif`,-with `sarif` as the default. Use `--source-root PATH` to add SARIF source-line-fingerprints.--Standard, Deep, Diff, and policy workflows save threat models with-their results. They also write `threatmodel.md`; if that file cannot be written,-the saved model remains available for export. Component and bulk scans keep a-separate model for each child run. New documents record the model and scan-scopes and identify provisional or recovered content. Some results have no-saved model.--Use `--artifact threat-model` to export the retained model as Markdown. The-format is `md` and the default destination is `./threatmodel.md`. Explicitly-selected results can expose a saved model before scan completion or after a-later failure. Policy result directories and historical saved Markdown models-are also supported. A historical document in a sealed scan must be listed in-the manifest with a matching digest. A missing model returns an error; export-does not substitute an older run or generate a new model.--```bash-codex-security export --artifact threat-model-codex-security export --scan SCAN_ID --artifact threat-model --output docs/threatmodel.md-codex-security export /path/to/policy-results --artifact threat-model --output --codex-security scan . --knowledge-base docs/threatmodel.md-```--`--output -` emits only artifact content, with diagnostics on stderr. Markdown-and CSV stdout cannot be combined with JSON command output. Exporting into a-repository does not make the document automatic scan input; use the existing-`--knowledge-base` option when you want to provide it as context.--`ScanResult.threatModel` contains the saved structured model or Markdown.-`threatModelPath` points to its current document, including supported historical-filenames. Either can be null. The model remains exportable when the document-could not be written. Scan JSON and policy results expose these fields. History-reports model availability, provenance, and the document path without including-the model body. Policy generation saves its model before drafting `SECURITY.md`,-so a later drafting failure does not discard it.--SDK scan methods verify model paths before returning them. A manually-constructed `ScanResult` uses the `threatModelPath` supplied in its options, or-`null` if omitted.--The SDK offers the same offline export without an authenticated session:--```ts-import { exportArtifact } from "@openai/codex-security";--const exported = await exportArtifact({- source: { directory: "/path/to/scan-results" }, // Or { scanId: "SCAN_ID" }.- artifact: "threat-model",- output: "/path/to/threatmodel.md",-});-console.log(exported.path, exported.provenance);-```--`exportArtifact` also supports findings with `format: "csv" | "json" | "sarif"`.-For threat-model file exports, returned provenance belongs to the same saved-snapshot as the exported document. `output: "-"` streams to stdout and returns-null path/provenance. `pythonPath` selects the helper interpreter and `signal`-cancels the export. `export --help` lists the CLI options.--JSON preserves the sealed findings document. CSV marks findings as open,-omits local triage state, and cannot go to stdout when JSON output is requested.-CSV escapes spreadsheet formula prefixes and literal leading apostrophes with-an extra apostrophe; import removes that escape. Older CSV exports cannot-distinguish some literal apostrophes from escapes. Use the JSON export when-recovering those values from an older scan. Distinct CSV occurrence IDs are-retained even when their finding IDs match, including when publishing CSV.--For CI, save output outside the checkout and set a severity threshold:--```bash-SCAN_ROOT="$(mktemp -d)"-npx @openai/codex-security scan . \- --diff origin/main \- --output-dir "$SCAN_ROOT/results" \- --json \- --fail-on-severity high > "$SCAN_ROOT/findings.json"-```--Scan exit codes are `0` for a completed report-only scan or passing policy,-`1` for a policy violation, `2` for invalid input, incomplete coverage, or a-runtime/export error, `130` for interruption, and `143` for termination.-JSON scans do not use interactive controls. `validate`, `login`, and `logout`-reject `--json`.--`install-hook` adds an optional local Git pre-commit check for staged and-unstaged changes. It's advisory; use a required CI check to enforce a passing-scan. When Git runs the hook, it blocks commits if the scan can't finish or-finds an issue at or above the threshold (`high` by default). Set it when-installing with `--fail-on-severity`. The installer respects `core.hooksPath`-and leaves custom hooks alone.--We recommend installing the CLI outside the repository and running that copy-directly. For a global installation:--```bash-npm install --global @openai/codex-security-```--If the repository also has a local copy, `npx` may run it instead.--Before installing or replacing a hook, run-`git -C /path/to/repository rev-parse --git-path hooks/pre-commit`. Git may-return a path relative to `/path/to/repository`. Check the hook, if it exists,-and the path to its directory for symlinks or shared locations. Leave custom,-linked, shared, or unverified hooks alone. If they need to change, contact the-owner or use a required CI check. Check older generated hooks too; the installer-can update them automatically.--If the hooks directory belongs only to this repository and there is no hook,-run the global CLI from outside the repository:--```bash-codex-security install-hook /path/to/repository-```--To migrate a hook, confirm it's a regular file used only by this repository-and contains only the generated Codex Security command. Keep its severity.-The installer can update older hooks that invoke `npx` if you use the same-severity. Newer hooks store absolute paths to Node and the CLI. If either path-changes, the installer won't replace the hook: back it up, remove it, and rerun-`codex-security install-hook /path/to/repository` with the same-`--fail-on-severity` value (default: `high`). If reinstallation fails, restore-the backup and verify the hook before relying on it.--### Import alerts from the CLI--`import github OWNER/REPO` reads open code scanning alerts from the default-branch. Repeat `--github-alert NUMBER` for exact alerts. Filter with-`--github-state open|closed|dismissed|fixed|all` or select a reference with-`--github-ref REF`. Authentication follows the-[SDK import options](#import-github-code-scanning-alerts).--```bash-# Import all open alerts, or a selected subset, as complete JSON.-npx @openai/codex-security import github example/repository --format json \- > /path/outside/repository/github-alerts.json-npx @openai/codex-security import github example/repository \- --github-alert 12 --github-alert 18 --format json-# Run from the corresponding local repository; imported contents are data.-npx @openai/codex-security validate /path/outside/repository/github-alerts.json-```--Import is read-only and returns an array (`[]` when empty). `--json` aliases-`--format json`. Save validation inputs without output filters or token limits.-Use the SDK loop for a disposition per alert.--### Validate and patch findings+Use `suggest-owners` or the SDK's `suggestOwners()` to suggest contributors based+on source and Git history. Suggestions do not assign tickets. See+[owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.-`validate` assesses candidates; `patch` fixes and verifies them. Both accept-files or literal text and work in the current directory. Pass a saved finding-or occurrence ID to `patch` to use its original repository.--Add `--validation-prompt-file PATH` to supply custom dynamic validation-instructions, using the same UTF-8 prompt file format as `scan`. The patch task-uses these instructions to set up the environment, build or start the application,-exercise the fix, check legitimate behavior, and clean up. Include the commands,-authorized targets, expected results, and cleanup steps for your environment.-The task must report validation evidence or explain which checks failed or could-not run before claiming the patch is fixed or verified.--```bash-npx @openai/codex-security patch OCCURRENCE_ID --validation-prompt-file validation.md-npx @openai/codex-security patch issues.md --validation-prompt-file validation.md-```--The flag works with saved findings, issue text/files, and Linear inputs. Relative-prompt paths resolve from the directory where you invoke the CLI, including when-the saved finding belongs to another repository. The file is read once before-patching; missing, empty, or non-regular files fail before the patch task starts.-Without the flag, the usual fix-finding verification applies. The flag does not-change sandbox permissions and cannot be combined with `--resume-pr`.--Add `--assess-patch-risk` to a `patch` command to run the bundled patch-risk-assessment skill once on the completed patch. The assessment is advisory and-does not change the patch or its merge state. Human-readable commands print the-report after the patch results; saved-finding JSON output returns it as-`patchRisk.report` in the same result object. When combined with `--create-pr`,-the draft pull request or merge request body includes only the concise Markdown-summary from the assessment; the validated JSON remains in the command result.--```bash-npx @openai/codex-security validate "Possible SQL injection" --effort high-npx @openai/codex-security patch OCCURRENCE_ID-npx @openai/codex-security patch --scan SCAN_ID --severity high --json-npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr-npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr-npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr-```--`--scan latest` selects the current repository's latest completed scan. Patch-commands support `--json`, including literal-text and file inputs. Change-the model with `--model gpt-6.1-sol` or effort with `--effort high`.-The existing `--codex 'model="..."'` syntax is also supported.-Each finding gets its own saved Codex desktop task.--Before patching, the CLI runs a command with the task's sandbox policy. If the-sandbox cannot start, the command exits with a nonzero status and reports-`SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response-with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,-`filesChanged`, and `files`; existing local changes do not count as patch changes.-These fields report file changes, not proof that the security issue is fixed.-Saved findings still require a verified result from the patch task.--For a controlled container that provides its own isolation, explicitly opt in:--```bash-npx @openai/codex-security patch "Security issue" --external-sandbox --json-```--`--external-sandbox` defaults to false. It uses Codex's external-sandbox policy-and prints a warning: Codex does not enforce filesystem or network isolation for-the patch task. The container must enforce those boundaries. The CLI never-falls back to this mode automatically. Optional patch-risk assessment still uses-its read-only Codex sandbox.--`scan --patch` patches after a complete scan. `--patch-severity` defaults to-`low`; `high` selects high and critical findings. Use the interactive browser-to select findings and add patch instructions. Results include a `patches`-entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.-Verified and already-fixed findings no longer fail `--fail-on-severity`.-Patching shows each finding's position, elapsed time, and live Codex activity.-Progress goes to stderr; completed results stay in the terminal history.--`--create-pr` commits generated patch files and opens a draft GitHub pull request-with `gh` or a draft GitLab merge request with `glab`. Install and authenticate-the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is-selected from the `origin` push URL, including SSH URLs and subgroup projects.-For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate-with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`-aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain-the GitHub workflow.--```bash-GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr-```+### Publish findings to Cloud-Both providers use the existing `pullRequest: { branch, url }` JSON result.-Supplied-issue requests require a clean working tree before patching so-existing work is never included. If publication fails, run the printed-`patch --resume-pr BRANCH` command in the same repository. It reuses the saved-commit without rerunning Codex, but refuses to publish if the branch changed.-Use the same GitLab host setting when resuming a self-hosted merge request.--To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use-`--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.-Completed and canceled issues are excluded unless the filter sets `state`.-Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or-`LINEAR_ACCESS_TOKEN` for OAuth. `--linear-api-key KEY` overrides these; prefer-environment variables to keep keys out of shell history. Intake is read-only,-includes comments, and keeps Linear credentials out of the patch subprocess.-Issue URLs must match the selected workspace.--### Verify fixes--`verify-fix` checks fixes in a read-only sandbox. Pass a description, saved-finding ID, `--scan SCAN_ID`, `--linear-issue ISSUE`, or `--linear-project "PROJECT"`.-Linear credentials and filters work as for `patch`. To check a finished backlog,-explicitly filter for completed issues.--Results include evidence and a status: `fixed`, `still_vulnerable`, or-`inconclusive`. Use `--json` for structured output. Exit codes are `0` if all-findings are fixed, `1` if any remain vulnerable, and `2` if verification is-inconclusive or couldn't finish.--### Command discovery and integrations--The CLI uses [Incur](https://github.com/wevm/incur). Use `--llms` for the-command manifest, `scan --schema --format json` for a command schema, and-`completions bash|zsh|fish` for shell completions. Scan output supports-`--format toon|json|yaml|jsonl` and `--full-output`.--`skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.-MCP exposes only the read-only `info` command because the transport cannot-cancel active scans.+`publish scan --to cloud` uploads selected findings to Codex Security Cloud.+It requires ChatGPT credentials; inference API keys and AWS credentials do not+grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-cloud)+for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)+for issue creation.## Findings service (preview)-The findings API uses the same `ghcr.io/openai/codex-security` image as the-scanner, for Linux `amd64` and `arm64`. `compose.findings.yaml` starts the API-in a separate container with its own state volume and server configuration.-Once a release is published, it can be pulled without a GitHub login. See-[container release setup](../../docker/README.md) for the required maintainer-setup and publication process.--From the repository root, copy the example if you do not already have a `.env`:--```bash-cp .env.example .env-```--Set `OPENAI_API_KEY` in `.env`, then pull and start the findings API:--```bash-docker compose -f compose.findings.yaml pull-docker compose -f compose.findings.yaml up --no-build -d-curl -i http://127.0.0.1:3000/v1/findings-```--You can deploy with just `compose.findings.yaml` and a private `.env`; no source-checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`-defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published-version, `sha-<commit>` tag, or digest for repeatable deployments.--To build from a source checkout, first prepare the-[universal native payload](../../plugins/codex-security/native/README.md#package-inputs)-for that checkout. Then run from the repository root:--```bash-docker build --target scanner -t codex-security:local .-export CODEX_SECURITY_FINDINGS_IMAGE=codex-security:local-docker compose -f compose.findings.yaml up --no-build -d-```--For an existing deployment using the separate findings image or-`--target findings-service`, follow the [single-image migration guide](../../docker/README.md#migrating-the-findings-service).--### Read-only dashboard--Open `http://localhost:3000/dashboard` on the running findings service. The UI-uses the public OpenAI Apps SDK UI design system, follows the browser's light-or dark preference, and polls the service every five seconds. It never starts,-cancels, resumes, publishes, edits, or deduplicates anything.--The dashboard opens on Findings, followed by Duplicate groups. Both views-support search, repository filtering, sorting, pagination, and record details.-Click any column header to sort all matching records; click it again to reverse-the order. The arrow marks the active column and direction. Changing the sort-returns to the first page, and automatic refreshes keep the selected order.-By default, findings sort by last update descending, then severity descending,-then ID ascending to break ties. Groups sort by last update descending and ID-ascending.-Findings show stored content and links to their duplicate groups. Groups link-back to their member findings, preserving separate overlapping groups and the-original finding records.--The dashboard reads only findings, repository associations, and duplicate groups-stored in the service's configured database. It does not display scans or-workflows: publication sends findings, not remote scan or workflow history. It-does not read report or source paths from stored records. The UI retains the last-successful data on a refresh failure and shows a connection warning until polling-succeeds.--`GET /v1/dashboard` returns a consistent read snapshot with overview counts,-repository choices, a page of records, and optional selected-record details:--- `view`: `findings` (default) or `groups`.-- `query`, `repository`: optional search text and exact repository ID.-- `sort`: `activity` (default; last update), `newest` (created), `title`,- `repository`, `severity` (findings only), or `members` (groups only).-- `direction`: `asc` or `desc` (default). Text sorts alphabetically without- case sensitivity, severity by level, and member counts numerically.-- `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.-- `id`: optional exact record ID to include in `detail`; unknown IDs return- `detail: null` without hiding the list.--Overview counts are service-wide, not filtered page totals. Responses and UI-assets are served by the same Node process; no separate frontend server, CDN,-model credentials, or new CLI flags are needed to view the dashboard. Compiled-HTML, JavaScript, and CSS are included in the npm package and container. Frontend-source, build tools, and tests are not shipped as runtime dependencies.--The existing preview access boundary is unchanged. The dashboard contains-sensitive finding content: keep the service on a trusted local endpoint or behind-an authenticated proxy. It does not add authentication or broaden the default-network binding.--### API--Mutation requests to `POST /v1/bulk/findings` and `POST /v1/dedupe-groups` require-`Content-Type: application/json`; charset parameters are accepted. Other media-types, including a missing content type, return HTTP 400 `invalid_request`-before embedding or storage. The API remains unauthenticated and requires an-authenticated TLS proxy before sharing access.--`POST /v1/bulk/findings` accepts `{"findings": [...]}`, using the existing SDK-`Finding` model, including `findingId`, `occurrenceId`, and `fingerprints`.-A complete exported `findings.json` document is also accepted; only its-`findings` array is imported. No files or source paths referenced by the-findings are opened. Only the supplied JSON is processed.--Include `repositoryId` alongside `findings` to associate every imported finding-with a repository. For SDK/CLI scans, use `scan.target.targetId` from the sealed-`scan-manifest.json`. IDs are matched exactly; the service does not infer a-repository from titles, paths, or URLs. Reimports add associations without-removing earlier ones, so a finding can belong to more than one repository.-Imports without this metadata remain accepted, but unassociated findings are-only available to explicit all-repository retrieval until imported with an ID.--| Method | Path | Response |-| ------ | --------------------------------------- | ----------------------------------------------------------------------------------- |-| `POST` | `/v1/bulk/findings` | HTTP 201 with an array of stored finding IDs, in request order |-| `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200 with a page of complete findings |-| `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200 with the stored finding and up to 50 potential duplicates, without vectors |-| `POST` | `/v1/dedupe-groups` | HTTP 201 with the persisted duplicate groups |-| `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200 with every stored group containing this finding |--Bulk insertion generates embeddings and then writes the findings and vectors-in one SQLite transaction. If embedding generation fails or a finding identity-conflicts with another stored identity, no part of the batch is written.-Reusing a `findingId` updates that finding and replaces its embedding; retries-do not create extra rows. An existing ID's fingerprint, rule, and identity-anchor/instance cannot be replaced. Repeated IDs in one request are applied in order,-with the last supplied record retained. Stored scan occurrences are unchanged.--For example, add `repositoryId` to a copy of an exported findings document-saved as `findings-import.json` (leave the sealed scan artifacts unchanged),-then import it with the API key configured before starting Compose:--```bash-curl http://127.0.0.1:3000/v1/bulk/findings \- -H 'Content-Type: application/json' \- --data-binary @findings-import.json-```--```json-["csf_852f90d6e1177502ff113d4a"]-```--The potential-duplicates response contains `finding` (the complete stored-anchor) and `potentialDuplicates` (an array of complete `Finding` records).-Neither includes embedding vectors. The anchor is not repeated in the array.-Specify one scope explicitly on the request:--```text-GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example-GET /v1/finding/{id}/potential-duplicates?allRepositories=true-```--Repository scope requires the anchor and each candidate to be associated with-that repository. All-repository scope includes tagged and untagged findings.-Omitting scope or combining a repository with `allRepositories=true` returns-HTTP 400. Scope selects candidates; it is not an authorization boundary.--Candidates have cosine similarity at least 0.55 and the same embedding model-and dimensions as the anchor. They are ordered by descending similarity, with-ties resolved by insertion time and finding ID, and limited to 50. Each request-reads a current snapshot; separate requests do not share a database snapshot.-SQLite first filters repository associations, reads only IDs and embedding-vectors (plus the anchor's model), and performs exact cosine ranking. It then-loads complete documents only for the anchor and the selected top 50 candidates,-all within the same read transaction.-The API does not run Codex or decide whether candidates are duplicates.--### Publishing to a custom findings service--Publish a completed scan directly from the local CLI to the Docker service:--```bash-codex-security publish scan --scan SCAN_ID --to custom \- --findings-url http://localhost:3000 --json-```--`--findings-url` is required for `--to custom`, with no default. It is the-service base URL, including `http://` or `https://`; the client appends-`/v1/bulk/findings`, preserving any base path. A different endpoint must-implement that API and return the stored finding IDs. The command sends the-complete sealed findings and their manifest's `scan.target.targetId` as-`repositoryId`, without changing scan artifacts or forwarding model credentials.-The service creates embeddings and commits the batch before acknowledging it.--The existing saved-scan selector, external `--scan-dir`, and interactive picker-work with custom publication. Custom publication accepts one scan, not CSV-input or Linear options. Add `--dry-run` to validate and preview the payload-without making an HTTP request. Existing Linear and Cloud destinations are-unchanged. Upload failures and incomplete receipts fail the command; uploads-are not automatically retried because a lost response may have been committed.--```typescript-import { publishScanToCustom } from "@openai/codex-security";--const receipt = await publishScanToCustom("/path/to/completed-scan", {- findingsUrl: "http://localhost:3000",- // dryRun: true,- // signal: controller.signal,-});-console.log(receipt.repositoryId, receipt.findingIds);-```--### Deduplication from the SDK and CLI--Publish the scan with `--to custom` (or import it through the bulk API with its-`repositoryId`) before deduplicating. The-workflow reads a completed saved scan, queries candidates by finding ID, and-runs Luna and Sol in the calling SDK/CLI process. Once all reviews finish,-it posts accepted groups to the service. It does not re-upload findings or-change scan artifacts.--```bash-codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json-```--Deduplication runs up to 8 jobs concurrently by default. Set `--concurrency N`-to choose a positive integer, or `--concurrency 1` for serial execution. The SDK-equivalent is `concurrency: N`. Candidate neighborhoods are fetched first, with-the same concurrency limit. Luna screenings and ready Sol pair reviews then use-two queues sharing one worker pool, with at most 8 jobs running in total by-default. Each available worker takes a ready job as soon as its current job-finishes; it does not wait for a batch to finish.--A Sol pair review becomes ready once every Luna screening covering that pair-has finished and none voted `DISTINCT`. It can run while unrelated Luna-screenings continue. Results are combined in input order so completion timing-does not change the groups.--An explicit model refusal keeps the affected pairs separate and allows unrelated-reviews to continue. It is recorded as `NO_DECISION`, not a reviewed `DISTINCT`-verdict. A screening refusal applies to every anchor/candidate pair in that-screening; a pair-review refusal applies only to its assigned pair. Neither pair-can be merged indirectly through other findings. Recognized policy errors and-explicit refusal responses are not retried or sent to another model.--If another kind of job fails after its retries, queued jobs stop and already running jobs-finish before the command reports the failure. No groups are posted from an-incomplete review. To retain completed reviews across runs, use a-`--workflow-id` as described below.--The default scope is the saved scan's repository, identified by-`scan.target.targetId` in its manifest. Add `--all-repositories` to search the-entire stored corpus explicitly; the flag defaults to false. The SDK has the-equivalent optional `allRepositories: true` setting. This narrows the previous-preview's implicit all-repository behavior.--Provide `--findings-url` and either `--scan` or `--workflow-id`, with no implicit-scan or service URL. As with `publish scan --scan`, the scan selector accepts a full ID, unique-prefix, or `latest` for the current repository. The saved scan must be complete-and its sealed artifacts must be available.--```typescript-import { deduplicateScan } from "@openai/codex-security";--const result = await deduplicateScan("scan_example_001", {- findingsUrl: "http://127.0.0.1:3000",- // concurrency: 8, // Shared worker limit for Luna and Sol; use 1 for serial.- // allRepositories: true, // Omit to search only this scan's repository.- // signal: controller.signal,-});-console.log(result.duplicateGroups);-```--For a complete, sealed scan directory that is not registered in local scan-history, provide the repository checkout separately:--```typescript-import { deduplicateScanDirectory } from "@openai/codex-security";--const result = await deduplicateScanDirectory("/path/to/completed-scan", {- repository: "/path/to/repository",- findingsUrl: "http://127.0.0.1:3000",- // concurrency: 8,- // expectedScanId: "scan_example_001",- // allRepositories: true,- // signal: controller.signal,-});-console.log(result.duplicateGroups);-```--The CLI and SDK return the same result:--```json-{- "scanId": "scan_example_001",- "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],- "duplicateGroups": [],- "deduplicationStatus": "completed"-}-```--`uniqueFindingIds` contains one representative for each selected finding after-accepted duplicate groups are collapsed. A representative can be an existing-stored finding outside the scan. Each `duplicateGroups` entry contains all-members of an accepted group, with its canonical finding first. The canonical-has the highest reported severity; ties use finding ID. Results do not delete,-merge, or change stored finding documents. Accepted groups are saved as durable-associations in the service before `deduplicationStatus` becomes `completed`.--When any review is refused, the result instead has-`deduplicationStatus: "completed_with_refusals"` and a `refusals` array. Each-entry contains `decision: "NO_DECISION"`, `stage`, `model`, `findingIds`, and-`reason`. For screening, the first finding ID is the anchor and the remaining-IDs are its candidates. The CLI logs each refusal to stderr and exits-successfully after saving the accepted groups. SDK callers can inspect and log-the same structured entries. Findings retained because of a refusal are not-confirmed unique. Successful runs without refusals keep their existing output-shape. No command, flag, or default changes are required.--This behavior applies to post-scan Luna/Sol deduplication. Deep Scan's internal-reducer uses a separate workflow.--### Host-provided records deduplication--`codex-security dedupe --records` accepts a versioned JSON-RPC run over stdin-and emits serial `review.run` requests on stdout for a host-provided model-backend. It requires no saved scan or Findings API and performs no local model-execution or persistence. The SDK exposes `deduplicateRecords(input,-{ reviewRunner, signal })`. The input contains original observations and explicit candidate links. Results-contain groups of observation IDs and unresolved observations.--See the [records protocol and Python fake-host example](docs/dedupe-records.md)-for the complete input, review contract, cancellation, and persistence rules.--### Stored duplicate groups--`POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:--```json-{- "groups": [- ["csf_000000000000000000000001", "csf_000000000000000000000002"],- ["csf_000000000000000000000002", "csf_000000000000000000000003"]- ]-}-```--Each group must contain at least two distinct, existing finding IDs. The entire-batch is committed in one transaction; a missing finding returns HTTP 409 and-writes none of the batch. A response contains `groupId`, `findingIds`, and-`createdAt` for each group. Group identity depends on membership, not member-order, so submitting the same set again returns its original ID and timestamp.--SQLite stores groups in `finding_dedupe_groups` and memberships in-`finding_dedupe_group_members`. A finding may belong to multiple groups:-`[A, B]`, `[B, C]`, and `[C, A]` are three separate reviewed sets. Overlapping-groups are not automatically united or promoted into an unreviewed larger-group. Stored members are sorted by ID; their order does not designate a-canonical. The CLI result retains its existing canonical-first ordering.--`GET /v1/finding/{id}/dedupe-groups` returns every group containing that finding,-including each group's full membership, or `[]` if it has no groups. These-associations do not rewrite original findings, fingerprints, scan artifacts,-embeddings, or external tickets. They do not require an embedding API key or-trigger model calls. Review-generated merged findings remain review outputs;-they do not replace stored documents.--### Resuming a local findings workflow--Add `--workflow-id` to opt into durable state shared by `scan`, `publish scan---to custom`, and `dedupe`. The SDK equivalents are the optional `workflowId`-fields on `ScanOptions`, `PublishScanToCustomOptions`, and `DeduplicateScanOptions`.-Without a workflow ID, existing command behavior and output shapes are unchanged.--```bash-codex-security scan /path/to/repository --workflow-id run-001-codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000-codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json-```--Repeat this sequence with the same ID after a process stops. Completed scans and-acknowledged publications are reused; unfinished stages run again. If the scan-completed before the workflow recorded its receipt, recovery verifies the saved-scan and its sealed artifacts instead of scanning again. Scan IDs and artifact-locations are recorded in the scan-registration transaction. This resumes between-completed steps; it does not resume individual model turns inside an unfinished-scan. Existing output-directory and archive safeguards still apply to scan retries.--Publication and dedupe can use the workflow ID in place of `--scan`; an explicit-scan selector must identify that same scan. A workflow can also begin at custom-publication of a completed scan. The CLI and `deduplicateScan` require local scan-history to locate the approved source checkout; `deduplicateScanDirectory` uses-the supplied repository. For a workflow, dedupe first completes publication-if its receipt is missing. `--all-repositories` retains its existing default of-false. Changing a workflow's scan, destination, or bound scope is an error: choose-a different workflow ID. Use one coordinating process per workflow.--Workflow metadata, stage statuses, errors, publication receipts, and results live-in the local workbench SQLite database under `CODEX_SECURITY_STATE_DIR`, outside-the sealed scan artifacts. Identity, scan/artifact references, destination, scope,-hashes, stage statuses, and errors use explicit columns; only receipts and result-payloads use JSON. Review source, scope, model settings, and contract/hash bindings-also use columns; review results remain JSON. Existing workflows and checkpoints-are migrated atomically in place without changing their review keys.-Successful empty results are stored as completed-results, not treated as missing work. An empty scan can complete workflow-publication with an empty receipt. Dry-run never advances a workflow stage.--A completed `dedupe --workflow-id` returns its saved result without repeating-reviews or group writes. A publication whose acknowledgement was lost is retried-using the service's existing idempotent upsert.--Concurrent jobs save their validated reviews independently. Resuming with the-same workflow ID reuses completed reviews and retries unfinished jobs. The-concurrency setting is not part of a review's checkpoint identity, so it is safe-to change `--concurrency` when resuming. Cancellation stops active reviews and-leaves their completed checkpoints available for the next run.--Each validated screening and pair review is checkpointed locally,-including DISTINCT decisions. Screening checkpoints retain pair recommendations-and rationales under host-assigned pair slots bound to the original records.-Every SAME pair-review checkpoint retains its-required `canonicalFindingId` and generated `mergedFinding`; the merged record-must satisfy the Finding schema and preserve the canonical finding ID. Validation-still happens through `review_validator.submit_decisions`; invalid submissions-are corrected in the same review conversation. A completed turn without an-accepted submission receives one corrective turn in that same conversation.-If formatting remains invalid, the job retries in a fresh review session.-Explicit transient Codex failures and unexpected process exits also retry, with-at most three fresh sessions per review. Transient findings-service failures, including-rate limits and network errors, receive up to three request attempts. Retries use-exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to retry-occupies the job's concurrency slot.--Cancellation, authentication or configuration errors, permanent HTTP errors, and-required-source-access blockers are not retried. Model refusals continue with-`NO_DECISION` as described above. Other exhausted retries fail deduplication;-invalid or unfinished reviews are not cached. Completed checkpoints remain-available when the workflow resumes.--Refusals are not saved as validated review checkpoints. A completed workflow-retains its final `completed_with_refusals` result, including all refusal entries,-and returns it on subsequent calls. To attempt those reviews again after-resolving the refusal, run dedupe without that workflow ID or with a new one.--Checkpoints bind to the exact original records and ordering, approved source path,-Git revision and current file contents (including ignored files), repository scope,-model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed-inputs cause a new review rather than reusing a decision. Source changes during-review stop that attempt before group writes; restart with the same ID to review-the changed source. Original findings, never prior rationales or merged findings,-are supplied to later independent reviews. Source snapshots do not follow directory-links outside the approved checkout.--Before posting groups, the workflow saves the exact final result and write payload.-If posting fails or its acknowledgement is lost, rerunning dedupe replays that-payload without looking up candidates or running models. Group persistence reuses-the existing membership identity, so replay does not create another group. The-dedupe stage completes only after acknowledgement. Empty results are also retained.-A completed workflow or pending write represents its already reviewed snapshot;-use another workflow ID for a fresh review rather than changing that saved result.--### Deduplication workflow--1. For each distinct finding ID in the scan, request- `/v1/finding/{id}/potential-duplicates` with the selected repository or- explicit all-repository scope. Use the complete stored anchor and- candidates returned by that request. Fetch all neighborhoods before starting- reviews so every pair's screening dependencies are known.-2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning- effort. The review covers every anchor-neighbor pair; nominations between- neighbors are rejected.-3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`- reasoning effort after all Luna screenings covering that pair finish without- a `DISTINCT` decision. Luna and ready Sol jobs share the configured worker- pool and can run together. Only accepted pairs contribute to duplicate groups.-4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`- decision contradicts the resulting component. Contradicted components are- split deterministically, preferring legal subgroups that preserve more- accepted-pair support. There is no additional whole-group review.-5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result- only after the service accepts the write. An empty result requires no write.--Each review uses a fresh, ephemeral Codex app-server thread with the complete-original finding records, not earlier model rationales, vector scores, or-summaries. Reviews can inspect source in the saved scan's local checkout,-starting with cited paths and revisions. Source inspection establishes duplicate-identity and shared remediation. Reviews preserve the originals' severity and-priority metadata without reassessment or normalization. The baseline-filesystem profile is read-only and excludes credentials-and Codex state. Screening denies approval requests; final reviews use Codex's-automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.-Finding content never authorizes access to another target.--Pair reviews cover exactly the two supplied findings. Linked parent tickets,-duplicate targets, and related-ticket records are metadata, not additional-findings to fetch or prerequisites for a verdict. An unsupplied duplicate target-is neither automatically canonical nor an error; source-code investigation for-the supplied pair remains allowed.--Incomplete supplied finding content can produce `DISTINCT` with the limitation-explained. An execution, tool, or source-access blocker that prevents a required-check instead uses `review_validator.submit_error` with a nonempty `reason`.-That submission fails the review without a verdict or review checkpoint, so it-cannot become a `DISTINCT` veto or a completed duplicate-group result. A failed-optional lookup does not force failure or `DISTINCT` when other evidence suffices.--Decisions must arrive through the direct `review_validator.submit_decisions`-tool; invalid submissions can be corrected in the same session. A final text-answer alone is insufficient. Luna screening returns a `SAME` or `DISTINCT`-decision and rationale under each required host-assigned slot (`pair-1`,-`pair-2`, and so on). The host binds each slot to its corresponding-anchor-neighbor pair, so the model does not submit finding IDs. Luna does not-select a canonical or generate a merged finding. Every-Sol `SAME` decision requires an assigned `canonicalFindingId` and-a generated, inclusive `mergedFinding`; missing or null values are rejected.-Sol reviews use only the complete originals, never earlier model rationales or-merged findings. These review fields do not change the command's ID-only result-or stored findings.--Non-cancellation review failures throw `DeduplicationReviewError`. Its `metadata`-contains only the review stage, model, failure category, attempt count, and a-sanitized reason for diagnostics or an external support bundle; it does not-contain findings, prompts, paths, thread IDs, or credentials.--If a completed turn has no accepted submission, whether it ended with text only-or after rejected submissions, the runner sends one corrective instruction in-the same conversation. This preserves the original assignment, source work, and-tool feedback. Reviews are limited to two turns; `metadata.attempts` counts-those turns (or the initial attempt if setup fails). Accepted results are not-replayed. Cancellation, accepted `submit_error` reports, and model or transport-failures remain terminal.--The SDK does not retain private review transcripts, subprocess stderr, or full-provider/RPC error payloads, and ephemeral review state is removed after the-session. The public metadata is a limited diagnostic summary, not a complete-troubleshooting trace; it intentionally omits the original error cause. Private-diagnostic retention is not currently implemented.--Model calls run sequentially on the SDK/CLI host using its Codex sign-in or-`OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model-credentials are not sent to the findings API. Larger scans can take time and-incur multiple model calls per finding. Empty scans and findings without-eligible neighbors do not invoke review models. `completed` means this-retrieval, review, and group persistence completed, not that every possible pair in the-database was compared or that model decisions are infallible. An API, review, or write-back-failure fails the command without claiming a completed result. Retry after-fixing the failure; stored findings remain unchanged. A lost write-back response-may have committed groups; retrying the same memberships does not duplicate-them. Failed or interrupted reviews write no groups. The CLI supports Ctrl-C-and SIGTERM, and the SDK accepts an `AbortSignal`.--### Listing and errors--Listing defaults to `limit=50` and `offset=0`; `limit` must be a positive-integer and `offset` a non-negative integer. Records are ordered by their first-insertion time, then finding ID. Follow `nextOffset` until it is `null`:--```json-{- "findings": [],- "limit": 50,- "offset": 0,- "total": 0,- "nextOffset": null-}-```+The findings service stores findings and duplicate groups in SQLite and provides+a read-only dashboard. It has no built-in authentication; keep it on loopback or+behind an authenticated TLS proxy. Imports send complete finding JSON to the+configured embeddings endpoint.-The list includes API imports and complete finding documents from existing CLI-scan history. It returns the latest stored document for each finding ID,-without embedding vectors. Legacy identities without a complete document are-not included. Pagination reflects current database contents, not a snapshot-held between HTTP requests.--Malformed JSON, invalid finding objects, repository metadata, groups, scopes, and pagination return HTTP-400 (`invalid_request`). Identity conflicts or missing dedupe group members return 409 (`finding_conflict`),-embedding provider failures or unusable vectors return 502 (`embedding_failed`),-and missing embedding credentials return 503 (`embedding_unavailable`). A-potential-duplicates query without a current embedding returns 404-(`finding_not_indexed`), including findings outside the requested repository or-whose embedding was invalidated by an update; import the finding with the-matching `repositoryId` before retrying. This is an error, not an-empty candidate list. Unknown routes return 404 (`not_found`); unexpected-server failures return 500 (`internal_error`). Errors have an `error` code and,-for expected failures, a `message`. Request bodies and provider error bodies-are not logged.--### Embeddings and storage--Set `OPENAI_API_KEY` in the repository-root `.env`, using `.env.example` as a-template, or export `OPENAI_API_KEY` or `CODEX_API_KEY` in the host environment.-Compose passes the key to the service; exported values override `.env` values.-The `.env` file is excluded from Git and Docker builds. `OPENAI_API_KEY` takes-precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using-`CODEX_API_KEY` instead. Listing and empty imports do not require a key.-A Codex ChatGPT login is not an embedding API credential.--Set `CODEX_SECURITY_EMBEDDINGS_URL` to override the full embeddings endpoint URL,-including its path and any query parameters. Unset or empty values use-`https://api.openai.com/v1/embeddings`. Export it before `codex-security serve`,-or set it in `.env` for Docker Compose, which passes it to the service. For example:--```bash-CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve-```--The configured endpoint receives the finding inputs and the API key as a bearer-token and must support the same OpenAI embeddings request and response format.--The service calls the OpenAI embeddings API with `text-embedding-3-large` and-1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s-bundled `cl100k_base` encoding. Long inputs are split without truncation;-their vectors are combined by token weight and normalized. Requests respect-the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.-See the [embedding API contract](https://developers.openai.com/api/reference/resources/embeddings/methods/create).--Storage initializes before the server listens. The SQLite adapter reuses the-bundled workbench's schema and migrations at-`$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. An append-only migration adds-complete finding documents and an embedding table, while retaining the existing-finding identity table and scan history. Both the API and current CLI indexing-use the same finding upsert operation. Changing a stored document invalidates-its old embedding so later matching cannot use a stale vector. Historical-findings are not automatically embedded; submit them to a bulk endpoint first.--The `findings-state` named volume persists `/state`, including the database,-across container replacements. Keep the same Compose project name to reuse it.-The image runs as UID/GID `10001:10001`; a bind mount must be writable by that-UID/GID if used instead of the named volume.--Stop the service with-`docker compose -f compose.findings.yaml down`; add `--volumes` only when you-intend to delete the stored data.--The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and-`CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if-changing these settings. Compose binds only to host loopback; the API has no-authentication. Use an authenticated TLS proxy before sharing access. Finding-JSON is sent to the configured embeddings endpoint (`api.openai.com` over HTTPS-by default); the database and generated embeddings stay in the local volume.--### Upgrades and backups--Read the release notes and stop the service before backing up the entire-`/state` directory. For the published-image Compose configuration:--```bash-docker compose -f compose.findings.yaml stop findings-mkdir -p backups-chmod 700 backups-docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \- --entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz-chmod 600 backups/findings-state.tgz-```--Keep backups separately; this command overwrites an existing backup of the same-name. Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest and repeat-the pull/start commands above, retaining the volume. Startup applies SQLite-migrations automatically. To roll back, stop the service, restore the pre-upgrade-backup, and select the previous image digest; an older image may not support the-migrated database.+See the [findings service guide](docs/findings-service.md) for its HTTP API,+Docker setup, publishing, and deduplication. For records stored in your own+system, see [SDK records deduplication](docs/dedupe-records.md).### Running without Docker-With Node.js and Python 3 installed:-```bash-npm install -g @openai/codex-security-CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000+npx @openai/codex-security serve --port 3000```-`--port` overrides `PORT` (default: `3000`). Open-`http://127.0.0.1:3000/dashboard`. Stop with Ctrl+C or SIGTERM.--Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.-Startup and listing need no key. The service does not load `.env` or authenticate-requests; keep it on loopback or behind an authenticated TLS proxy.--For a source build, first prepare the-[universal native payload](../../plugins/codex-security/native/README.md#package-inputs)-for that checkout. Then run from its `sdk/typescript` directory:+Open `http://127.0.0.1:3000/dashboard`. Startup and listing need no API key;+imports that generate embeddings need `OPENAI_API_KEY` or `CODEX_API_KEY`.+A ChatGPT login is not an embedding API credential. See+[local service setup](docs/findings-service.md#run-without-docker) for storage settings.-```bash-pnpm install --frozen-lockfile-pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile-pnpm run build:plugin-pnpm run build-node bin/codex-security.mjs serve --port 3000-```+### Upgrades and backups-`pnpm run start:server` and `node dist/server/index.js` still work.--Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing-`CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;-without a state override, the service uses the same default state directory as-the CLI. These settings also work on Windows.--HTTP routing, embedding generation, and the SQLite adapter live-separately under `src/server/`. `startFindingsServer` receives a `FindingEmbedder`-whose `embed(findings)` method returns one `{ model, vector }` per finding in-input order. `OpenAiFindingEmbedder` handles tokenization, batching, API calls,-and vector normalization; it does not access storage. The `FindingsStore`-interface stores findings and vectors and exposes-`findPotentialDuplicates(findingId, scope)`. Repository filtering, vector ranking,-and fetching selected documents stay inside the store implementation; replacing-SQLite with an indexed store does not change the service or SDK/CLI. Repository-associations are stored separately from finding documents, with an append-only-migration that also imports known associations from stored scan occurrences.-New scan findings retain their target associations when indexed locally.-The server entrypoint selects the concrete-embedder and store, so either can be replaced independently.--For renewable embeddings credentials, import `OpenAiFindingEmbedder`,-`SqliteFindingsStore`, and `startFindingsServer` from-`@openai/codex-security/server`. The embedder's first argument accepts a static-key or `() => string | Promise<string>`. It calls the callback before every-HTTP batch, including subsequent calls to `embed`; callers own token acquisition.-Pass `fetch` as the second argument and-`process.env.CODEX_SECURITY_EMBEDDINGS_URL || undefined` as the third to use-the same full endpoint URL and default as `codex-security serve`. Importing the-server API does not start a listener.--The local workflow lives under `src/deduplication/`. `FindingDeduplicator`-receives a candidate API client and a `DeduplicationReviewer`, keeping grouping-separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts-and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.-`deduplicateScan` validates saved scan artifacts before running the workflow;-`deduplicateScanDirectory` performs the same validation for an explicit sealed-scan directory without consulting local scan history.-The SDK reuses the existing Codex runtime and credentials without additional-runtime dependencies.+Stop the service and back up its entire state directory before upgrading.+Keep the state volume when replacing a container. See+[backup and restore instructions](docs/findings-service.md#storage-upgrades-and-backups).## Containerized bulk scans-Create `repositories.csv` as described under [Bulk scans](#bulk-scans).-Use device login only if your workspace allows it.-With a published image, run from the Codex Security repository root:--```bash-mkdir -p results state-chmod 700 results state-export CODEX_SECURITY_USER="$(id -u):$(id -g)"-export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest-docker compose pull codex-security-docker compose run --rm codex-security login --device-auth-docker compose run --rm codex-security-```--Results go to `results/`; device login stays in `state/`. For unattended scans,-set `OPENAI_API_KEY` or `CODEX_API_KEY`. Private GitHub checkouts use `GH_TOKEN`-or `GITHUB_TOKEN`; GitHub Enterprise uses `CODEX_SECURITY_GIT_HOST`. The container-requires CSV input, without interactive discovery.--Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,-`CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and-`CODEX_SECURITY_STATE` for the image, user, seccomp profile, and mounts.--Codex 0.156.1 requires Bubblewrap for filesystem-restricted execution on Linux.-On Ubuntu hosts that restrict unprivileged user namespaces, an administrator-must install the AppArmor profile and use the Compose override:--```bash-sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container-sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container-docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security-```--The override keeps the nonroot user, dropped capabilities, no-new-privileges,-and seccomp policy. It enables the nested namespaces required by Bubblewrap.-The legacy Landlock fallback is no longer supported for these scans. Other-Docker hosts that permit nested user namespaces do not need this override.+Use the scanner image and Compose files to scan a list of repositories with+persistent results and authentication. See+[containerized bulk scans](docs/cli.md#containerized-bulk-scans) for setup, or the+[workflow runner](https://github.com/openai/codex-security/blob/main/docker/README.md#workflow-runner)+for individual CLI stages in containers.## Local security model-Codex Security runs with your operating-system permissions. Only scan-repositories you trust and are authorized to assess. Local tools and scans-under the same account aren't separate security principals.+Codex Security runs with your operating-system permissions. Scan subprocesses+can inherit your environment, so start them with only the credentials they need.+Local tools running under the same account are trusted.-The `codex_security_scan` profile allows reads across the local filesystem and-writes to workspace roots. Execution approvals are reviewed automatically and-may grant extra permissions for one operation. Set-`--codex 'approval_policy="never"'`, directly or in a selected profile, to deny-requests. Other overrides can't replace the reviewer or filesystem profile.-Saved scans keep their approval policy; older scans stay deny-all on rerun.+The scan profile allows reads across the local filesystem and writes to workspace+roots. Execution approvals are reviewed automatically and may grant extra+permissions for an operation. Set `codexOverrides.approval_policy: "never"`+(or CLI `--codex 'approval_policy="never"'`) to deny permission requests.Host and network restrictions still apply.-Start scans with only the credentials they need. Scan and workbench subprocesses-can inherit your environment, including unrelated API tokens and cloud credentials.-Repository contents, model output, and imported artifacts do not authorizeaccess to other targets, disclosure of credentials, or writes outside approved-paths. See the security policy below for the full threat model.+paths. Keep state and scan artifacts private and outside the repository.## Documentation and security-- [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+- [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)+- [CLI reference](docs/cli.md)+- [Findings service guide](docs/findings-service.md)+- [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 reportingdiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdnew file mode 100644index 000000000..fe94d7d54--- /dev/null+++ b/sdk/typescript/docs/cli.md@@ -0,0 +1,1352 @@+# CLI and workflows++Use `npx @openai/codex-security` without a global install. The examples below+use `codex-security`, which is available after+`npm install --global @openai/codex-security`.++```bash+codex-security --help+codex-security scan --help+codex-security --version+codex-security info --json+```++`--help` lists commands by task; `<command> --help` lists its options.+`info --json` reports package, plugin, runtime, and model details.+`scans` and `findings` default to their `list` subcommands.++## Authentication++Sign in with ChatGPT, or supply an API key for CI:++```bash+codex-security login+codex-security scan .++# Save an API key from the environment.+printenv OPENAI_API_KEY | codex-security login --with-api-key+```++`OPENAI_API_KEY` and `CODEX_API_KEY` also work without saving a login.+Environment keys apply to the current command; only `login --with-api-key`+saves them. `login --with-access-token` accepts a Codex access token on stdin.+Access-token environment variables are not scan API keys.++On remote or headless machines, use `login --device-auth` if your workspace+allows it. If device auth is disabled, use SSH forwarding below.++On Windows, set a key in PowerShell:++```powershell+$env:OPENAI_API_KEY = "<your-api-key>"+codex-security scan C:\code\repository+```++### Remote login with SSH forwarding++On your local machine, open a tunnel to the remote host:++```bash+ssh -L 1455:localhost:1455 user@remote-host+```++Run `codex-security login` in that SSH session and open its sign-in URL in+your local browser. Keep SSH connected until login finishes.++### OpenAI credentials++Interactive scans ask which credentials to use when both ChatGPT and an+environment API key are available. Noninteractive commands prefer+`OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly+with `--auth`:++```bash+codex-security scan . --auth chatgpt+codex-security scan . --auth api-key+codex-security patch OCCURRENCE_ID --auth chatgpt+codex-security verify-fix OCCURRENCE_ID --auth api-key+```++`--auth chatgpt` ignores environment API keys. `--auth api-key` requires a key.+The default is `auto`. Scans, validation, patching, and fix verification share+the stored login. Patch follow-up assessments and `scan --patch` retain the+chosen authentication. Environment keys do not replace the saved login.+The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.++Stored OpenAI credentials live in+`$CODEX_SECURITY_STATE_DIR/codex-home`, or+`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home+outside the target and every enclosing Git worktree. It also serves providers+with `requires_openai_auth = true`.++Codex carries credential-storage, forced-login, and workspace settings from the+ambient configuration into this home. Managed-device policies still apply;+workspace-managed policies may require ChatGPT credentials even with an API key.+If the home has no credentials, it imports an existing file-based Codex login.+Logout disables imports until the next login.++If credentials cannot refresh, run `login status`. Retry if the sign-in recently+changed; otherwise run `logout`, then `login`.+Some cybersecurity requests and protected findings require+[Trusted Access for Cyber](https://chatgpt.com/cyber).++### Select a Cyber access program++For the built-in OpenAI provider, choose `standard`, `daybreak_blue`, or+`daybreak_red`:++```bash+codex-security scan . --auth api-key --cyber-access-program daybreak_blue+```++```ts+await security.run("/path/to/repository", {+ auth: "api-key",+ cyberAccessProgram: "daybreak_blue",+});+```++`scan-components` accepts the same flag. Project files use+`scan.cyber_access_program`, including for bulk scans. Explicit CLI or SDK values+override the file; omission preserves Codex defaults. `standard` explicitly+selects the standard program.++The selection applies to workers, resumed scans, planning, matching, and scan+follow-ups. Recipes retain it for resume and rerun. API-key selection enables+Codex's experimental Cyber support unless native configuration explicitly disables+`features.api_key_cyber_access_programs`. A selection does not grant entitlement;+explicit disables and access denials remain errors.++### Native command authentication and other providers++SDK callers can select a native command provider through+`codexOverrides.model_providers.<id>.auth` and `model_provider`, including a+selected profile. Codex runs the credential helper and renews its token. Scans,+comparisons, and deduplication preserve that selection. Relative helper paths and+`auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews+also honor the selected command provider in that home's `config.toml`.++For other providers, set their key and select a model the provider supports:++```bash+export OPENROUTER_API_KEY="<your-openrouter-api-key>"+codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5++export FIREWORKS_API_KEY="<your-fireworks-api-key>"+codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b+```++### Amazon Bedrock++Use AWS credentials and a region with access to the exact Bedrock model ID:++```bash+export AWS_PROFILE="security-scan"+export AWS_REGION="us-east-2"+codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna+```++Run credential setup and the scan in the same shell or job. Bedrock scanning+uses AWS authentication, including in Deep Scan workers; it does not need an+OpenAI API key or separate CLI login. Publishing to Cloud requires separate+ChatGPT credentials. `info` and `--dry-run` do not verify AWS access.++See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)+for credential alternatives, restricted-model access, cost estimates, and+reasoning-summary configuration.++## Generate a security policy++`policy` drafts `SECURITY.md` guidance for later scans. Review the draft before+copying it into the checkout; the command saves it outside the repository.++```bash+codex-security policy .+codex-security policy . --path services/api+codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high+codex-security policy . --dry-run --json+```++The repository defaults to the current directory. `--path` selects a component,+which inherits policies from its Git root, with the closest policy taking+precedence. Targets and links stay within the checkout and outside Git metadata.+Inherited policies may refer to ancestor `SECURITY.md` files or the checkout's+`.github/SECURITY.md` and `docs/SECURITY.md`; they cannot widen a component's scope.+Linked worktrees and initialized submodules use their own roots. For a separate+Git directory, set `core.worktree` to the checkout's absolute path; use+`git worktree repair` for moved linked worktrees.++Generation describes the system, builds a threat model, then drafts the policy.+In a terminal it asks about facts the source cannot establish and previews the+diff. `--headless` skips questions; unanswered questions remain in review notes.+The command uses scan authentication and read-only access to the selected source.+It denies Git metadata and sibling-component access, disables network, web, apps,+and MCP, and uses only Codex's core shell environment. Knowledge-base text stays+in private review artifacts during generation and is removed afterward.++| Invocation | Result |+| ---------------------------- | --------------------------------------------------------- |+| `policy .` | Generate documents, ask questions, and preview the draft. |+| `policy . --headless --json` | Generate without prompts; return paths and review notes. |+| `policy . --format md` | Generate and write the draft to stdout. |+| `policy . --dry-run --json` | Check local inputs without calling Codex. |++Generation currently fails on Unix directories with non-UTF-8 names. On macOS,+the bundled runtime does not fully enforce write restrictions under `/tmp`+(including `/private/tmp`); keep source and artifacts elsewhere when read-only+enforcement is required. See the+[upstream sandbox issue](https://github.com/openai/codex/issues/32395).++### Review the draft++Preserve reporting instructions and obtain owner approval for exclusions,+accepted risks, and severity decisions. Check linked `.github/SECURITY.md` and+`docs/SECURITY.md` files: installing the draft can affect their guidance too.+Regenerate if relevant source or neighboring policies changed during generation.++Use an empty output directory outside every enclosing checkout and its Git+metadata, or keep the default location in the Codex Security state directory:++```bash+codex-security policy . --path services/api --headless \+ --output-dir /path/outside/repository/api-policy --json+```++| Artifact | Contents |+| ---------------------- | ----------------------------------------------- |+| `SECURITY.md` | Policy draft. |+| `threatmodel.md` | Threat model with source references. |+| `project-spec.md` | System description and security boundaries. |+| `previous-SECURITY.md` | Original policy used for the diff. |+| `policy-draft.json` | Target, hashes, stage status, and review notes. |++Keep supporting documents private until reviewed for disclosure. If governing+policies change during generation, the documents remain for inspection but no+completed-draft manifest is written. A preview failure reports saved paths.++`--max-cost` applies to the whole generation. Progress goes to stderr;+`--json` includes status and estimated cost. `--full-output` reports failures+with `ok: false`. If a stage cannot inspect required evidence, generation stops+and keeps completed documents. Fix the problem and retry in a new directory.++### Generate a policy from TypeScript++```ts+import { CodexSecurity } from "@openai/codex-security";++const security = new CodexSecurity();+try {+ const draft = await security.generatePolicy("/path/to/repository", {+ path: "services/api",+ knowledgeBasePaths: ["/path/to/architecture.md"],+ onStage: (stage) => console.error(stage),+ });+ console.log(await security.previewPolicy(draft));+ // Review the saved policy at draft.draftPath before installing it.+} finally {+ await security.close();+}+```++`preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied+in-memory draft and escapes terminal controls; editing its saved file does not+change that object. `securityPolicyDiff()` returns a raw diff for files and other+non-terminal uses, with an optional Python interpreter.++`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,+`maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives+groups of up to three owner questions and a cancellation signal. Without the+callback, questions remain unresolved.++## Scan options and output++```bash+codex-security scan .+codex-security scan . --path src --path tests+codex-security scan . --diff origin/main --json+codex-security scan . --working-tree+codex-security scan . --output-dir /path/outside/repository/results --dry-run+```++`--diff` scans committed changes; `--working-tree` scans staged and unstaged+changes. Deep scans support whole repositories and path scopes. Working-tree+snapshots include untracked nested Git repositories. Initialized submodules must+be clean and at the commit recorded by the parent.++Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and+SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;+explicit unsupported binary files are rejected. Bulk scans share this context+with every repository.++Output directories must be empty and outside the scanned directory and enclosing+Git worktree. On macOS/Linux, existing directories must be private (`chmod 700`).+`--archive-existing` moves earlier output to+`<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.+SARIF, when produced, is saved at `<scan-dir>/exports/results.sarif`.++Scans are report-only by default. `--fail-on-severity high` exits with `1` for+high or critical findings. Incomplete scans exit with `2`, returning available+results and a coverage warning. Runtime failures with JSON or JSONL output produce:++```json+{ "status": "failed", "code": "SCAN_FAILED", "message": "..." }+```++With `--full-output`, the error appears under `error` in an `ok: false` envelope.+Diagnostics stay on stderr. `scan --schema --format json` describes the output.+See [Exports and CI](#exports-and-ci) for exit codes and CI examples.++### Project files++```bash+codex-security init+codex-security scan . -c codex-security.yaml --dry-run --json+codex-security info -c codex-security.yaml --json+```++Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.+Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,+`scan-components`, and `info` accept project files. SDK calls and saved reruns+do not load them automatically.++Treat the selected file as trusted operator configuration: native settings can+start MCP processes and choose model-service destinations. Keep CI scanner+configuration outside the untrusted checkout being assessed.++See [Project configuration](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)+for settings, precedence, paths, schemas, and SDK loading. File paths resolve+from the config directory; scope paths resolve from the repository.++### Import findings as a saved scan++```bash+codex-security scan import --csv /path/to/findings.csv+codex-security scan import --json /path/to/findings.json --format json+codex-security scan import --csv /path/to/findings.csv --dry-run+```++Supply exactly one input. CSV follows the+[findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).+JSON accepts a complete `codex-security.findings` document or+`{ "findings": [...] }` matching the findings schema. For this command, `--json`+selects the input file; use `--format json` for JSON output. The input must be a+regular file with no symlinks or directory junctions in its path.++Each import creates a completed scan in local history, retains the input under+`artifacts/import/`, and preserves each occurrence, including duplicates.+Original identifiers live in `extensions.import`; referenced writeup paths are+metadata only. Completion means import finished; no security analysis occurred.+Import needs no model calls or authentication. `--dry-run` validates without+saving; `--output-dir` and `--archive-existing` control output. `scans rerun`+reimports the retained input.++### Generate mock scan results++```bash+codex-security scan /path/to/repository --mock+```++The SDK equivalent is `security.run(repository, { mock: true })`. Mock scans+save synthetic results through the normal reporting and history flow without+model calls or authentication. Each contains 12 findings: eight stable across+runs, four with new identities, and two duplicate pairs for testing deduplication.+Paths and snippets are fictional; repository files remain unchanged.++Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,+archiving, and severity thresholds work normally. Reruns preserve mock mode.+Separate matching or deduplication commands still make their usual model calls.++Mock mode supports Standard repository, path, and diff scans. It cannot combine+with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan prompts.+Scan prompts and knowledge bases do not change the fixtures.++### Attribute scans to end users++Pass a stable hashed ID when scanning on behalf of users:++```bash+codex-security scan . --auth api-key --safety-identifier hashed-user-id+```++```ts+await security.run("/path/to/repository", {+ auth: "api-key",+ safetyIdentifier: hashedUserId,+});+```++Use 1–64 characters, with no NUL or personal data such as email addresses.+The ID applies to workers, retries, and follow-ups. Supply it again for reruns.++The bundled runtime does not yet support native `--safety-identifier`; select a+compatible build with `CODEX_CLI_PATH` and a plugin that forwards it to workers.+The SDK checks the format, not runtime/plugin compatibility. Older versions may+omit the ID.++### Scan project components++`scan --path` runs one scan over selected paths. `scan-components` runs a separate+scan for each component:++```bash+codex-security scan-components /path/to/project \+ --component apps/api --component apps/web --component packages/shared \+ --workers 4 --output-dir /path/outside/project/results+```++Use `-c FILE` to share scan settings, including Deep mode, context, cost limits,+and severity policy. Component plans override the file's scope. Use `--auto` to+propose a split, then review the saved plan:++```bash+codex-security scan-components . --auto --plan-only \+ --output-dir /path/outside/project/plan+codex-security scan-components . \+ --components-file /path/outside/project/plan/components.json \+ --output-dir /path/outside/project/results+```++Plans use repository-relative paths:++```json+{+ "components": [+ { "name": "API", "paths": ["apps/api", "packages/auth"] },+ { "name": "Web", "paths": ["apps/web"] }+ ]+}+```++Automatic planning respects Git ignore rules and includes omitted inventory+files in `Other files` components. Large inventories require multiple planning+calls and may produce more components. Planning leaves source unchanged.++Each component saves artifacts under `component-N/`. Combined `findings.json`+groups high-confidence root-cause matches, keeping original IDs and the highest+severity. Uncertain matches stay separate. `summary.json` records coverage and+matching status; `report.md` links to component reports. Export or publish each+individual scan folder.++Failures do not stop other components. Failed scans, incomplete coverage, or+failed matching return `2`; severity-policy violations return `1`. Retry with+`--components-file retry-components.json` and a new empty output directory.+The retry report covers only those components.++`--max-cost` applies per component, excluding planning and matching. `--model`+and `--effort` also apply to matching; `--auth` applies throughout. Planning and+matching reject ambient command providers that conflict with explicit ChatGPT+or API-key auth. SDK-selected command providers retain their authentication.++From TypeScript, use `runComponentScans({ repository, outputDir, components })`.+Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding+planning and authentication choices.++### Configure deep scans++```ts+await security.run("/path/to/repository", {+ mode: "deep",+ workers: 2,+ subagents: 0,+ stopAfterNoNew: 3,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 10,+ maxTimeHours: 1.5,+});+```++For `scan --mode deep`, `--workers` controls discovery concurrency and+`--subagents` controls subagents per worker. `--stop-after-no-new`,+`--max-discovery-runs`, and `--max-time-hours` stop discovery by novelty, count,+or duration. At the deadline, discovery stops; the scan then combines and returns+completed findings.++Use project-file `scan.deep` settings or legacy+`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except+that `subagents` can be zero. Time accepts positive fractional hours up to 96.+`stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.+`--codex` does not configure deep-scan settings. See+[Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).++`bulk-scan --workers` controls concurrent repositories; `scan --workers` controls+workers within one Deep Scan. New recipes save all resolved deep settings so+resume and rerun do not depend on later changes to legacy defaults.++### Runtime configuration and worker limits++Scans use an isolated Codex configuration. The default model and effort are+`gpt-5.6-sol` and `xhigh`. Multi-agent v2 allows nine concurrent threads: the+parent and up to eight delegated workers. That limit is separate from Deep Scan+and bulk worker counts.++```bash+codex-security scan . --model gpt-6.1-sol --effort high \+ --codex features.multi_agent_v2.max_concurrent_threads_per_session=4+```++Model IDs and `--effort` values pass through to Codex unchanged, including values+such as `minimal`, `none`, and `high`. Supported combinations depend on the model,+provider, Codex version, and credentials. Codex and provider errors are reported+without substituting another model or effort.+The flags also work with bulk/component scans, policy, validation, patching,+verification, owner suggestions, severity classification, and scan matching.+Matching and severity classification default to Codex's configured model and+`medium` effort. `dedupe` has separate screening and review models.++Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:+`--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are+rejected, including a `--model` or `--effort` flag plus its native equivalent.+Choose plugins with `--plugin-path`; native plugin and marketplace overrides are+rejected. Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.++`validate`, `patch`, and `verify-fix` limit native overrides to `model`,+`model_reasoning_effort`, `model_provider`, `model_providers`, and+`analytics.enabled`. For a custom provider:++```bash+codex-security patch "Security issue" --model gateway-model \+ --codex 'model_provider="gateway"' \+ --codex 'model_providers.gateway.name="Gateway"' \+ --codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \+ --codex 'model_providers.gateway.wire_api="responses"' \+ --codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'+```++Set the provider's key environment variable before running. Patching and+verification preserve unspecified provider settings from Codex configuration.+With `auto` or `api-key`, the provider's `env_key` takes precedence over OpenAI+account authentication. Explicit `--auth chatgpt` selects stored account auth,+omits the provider key, and clears any configured experimental bearer token for+that command. Model, effort, and provider choices carry into patch-risk assessment.++Disable Codex usage analytics and built-in metrics with+`--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`+and patch-risk assessment. It does not control configured OpenTelemetry exporters,+integrations, authentication, or CLI update checks. Validation uses isolated+configuration; patching and verification preserve ambient project trust.++For filesystem and approval behavior, see the+[local security model](../README.md#local-security-model).++### Environment variables++| Variable | Effect |+| --------------------------------------------------------------------------- | ------------------------------------------------------------------ |+| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |+| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |+| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |+| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |+| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |+| `PYTHON` | Python interpreter unless an explicit option overrides it. |+| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |+| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |+| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |+| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |+| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service embeddings endpoint. |+| `GH_HOST` | GitHub Enterprise host for bulk discovery. |+| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |+| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |+| `CI` | Disable interactive update notices. |+| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |++Custom Codex executables need thread source attribution for `exec` and+`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;+command shims such as `codex.cmd` fall back to the bundled executable.++Python lookup: `--python` (scan, bulk scan, export) or SDK `pythonPath`, then+`PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also+works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.++### Troubleshooting++Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,+retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,+saved failures, receipts, and patch-risk summaries. Review it for sensitive+information before sharing; upstream Codex output may already be redacted.++Keep state and reports when recovering authentication or locking problems.+Finish older-version operations before upgrading. Never remove+`.codex-security-scan.sqlite3` during an operation. Stop all operations using the+credential home before manually removing an old `.codex-security-scan.lock`.++On Windows, an older sandboxed run can leave invalid ACLs on a credential-home+ancestor. Preserve that state, then select a new private `CODEX_SECURITY_STATE_DIR`+outside the old state and repository. Sign in again if needed; the new directory+has separate scan history.++### Progress and cost++Interactive scans show full-screen progress. CI, redirected output, `--headless`,+and `--verbose` use plain status lines. Results go to stdout; progress and+diagnostics go to stderr. Press `d` in the dashboard for details, then `a` for+all sources, `m` for the main scan, or `1`–`9` for a worker.++Token totals include input plus output; cache reads and writes are subsets of+input. Missing cache-write usage makes the uncached/cache-write breakdown+unavailable. The CLI cannot recover missing information already recorded as zero+by the runtime.++Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)+and show a short/long-context range. They estimate model usage, excluding other+tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT+subscription allowance. Models without known prices have no estimate.++JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,+and `context: "unknown"`). A null maximum means no upper estimate is available.+`cost.pricing` records source, verification date, tier, and rates. Older results+keep their legacy estimates. `cost.estimatedUsd` is the short-context baseline+used for spending limits; use the range for reporting. Missing cache-write usage+is recorded by `cacheWriteInputTokensReported: false`.++`--max-cost USD` stops the scan and workers after estimated cost exceeds the+limit; in-flight requests can finish above it. Bulk limits apply per repository+attempt. Post-scan prompts run after cost tracking and are outside this limit.+Automatic history matching gets at most one extra call with a limit; if more+work is needed, the scan is preserved and you can run `scans match --all`.++When Deep discovery has finished at a cost stop, the scan returns a sealed+partial report and lists unvalidated candidates as follow-up work.++At 80% of a single interactive scan's limit, the dashboard offers a higher total+budget. Enter a larger total, or leave it blank/press Escape to keep the limit.+Work continues while you decide; the old limit remains active until saved.+CI, JSON/JSONL, headless, and verbose scans do not offer increases.++SDK callers can use `onBudgetApproaching({ maxCostUsd, cost, signal })`, returning+a larger total or `undefined`. It runs once per limit without blocking the scan.+Late responses after cancellation/completion are ignored; invalid increases or+save failures keep the existing limit. `onCost(cost, maxCostUsd)` reports changes.++## Bulk scans++Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub+selection. It lists repositories pushed in the last 90 days, excluding forks+and archives, asks for output, and saves the selection as `repositories.csv`.+Private checkouts use your GitHub CLI login.++For CI, provide CSV with `id`, `repository`, and a full commit `revision`.+Optional `scope`, `mode`, and `prompt` customize each row:++```csv+id,repository,revision,scope,mode,prompt+service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authentication and authorization.+```++```bash+codex-security bulk-scan repositories.csv \+ --output-dir /path/outside/repositories/results --workers 4+```++Bulk scans use clean shallow checkouts and support repository/path scopes.+Configured diff or working-tree scopes are rejected unless every affected row+overrides them with a path scope. `--output-dir` requires CSV input.++Use `-c FILE` for shared settings; CSV mode/scope override file values.+`--scan-prompt-file` adds shared instructions before each row's prompt.+`--post-scan-prompt-file` runs a follow-up even after failure or incomplete+coverage, but not after cancellation or a cost stop.++Concurrency defaults to four repositories. `--max-attempts` defaults to one+attempt per pending repository per invocation. Repeating the command continues+the campaign, skips completed results, and starts pending attempts. Occupied+attempt directories stop that repository and suggest `--recover`.+Changed project configuration requires a new output directory.++### Recovering failed or interrupted bulk scans++Use the original CSV, output directory, and options:++```bash+codex-security bulk-scan repositories.csv \+ --output-dir /path/outside/repositories/results --recover+```++Recovery requires a matching campaign manifest. It skips completed results+(including partial coverage) and repositories never started. For each latest+failed or interrupted attempt:++- A sealed scan is recorded in `results.jsonl` without scanning again.+- An eligible running Deep Scan resumes its original session, keeping its ID,+ workers, artifacts, settings, and accumulated cost.+- An unavailable, failed, or canceled scan starts a new attempt at the pinned+ revision, preserving old artifacts and checkouts.++New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four+workers and one recovery/new attempt per repository. A resume connection failure+stops only that repository for this invocation. Failed recovery checkouts remain;+fresh completed checkouts are removed after recording their result.++Same-scan resume needs the original checkout, session logs, and state directory.+Recovery cannot reconstruct deleted checkpoints or fix execution failures.+New attempts incur new costs. Remaining failures or partial coverage return `2`;+completed severity-policy violations return `1` without retrying the scan.++## Custom validation++Replace the final validation step of a Standard or diff scan with a prompt:++```bash+codex-security scan . --validation-prompt-file validation.md+```++```ts+const result = await security.run(repository, {+ validationPrompt:+ "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",+});+```++Source review still runs; discovery workers do not receive this prompt. Include+setup, authorized targets, required evidence, and cleanup. Use environment+variables for credentials. Deep scans reject custom validation; scans with no+candidates skip it. The SDK also accepts `validationPromptFile`.++The model must return a `CustomValidationResult` with one entry per candidate:++```json+{+ "status": "complete",+ "reason": null,+ "validations": [+ {+ "candidateId": "candidate-1",+ "validation": {+ "disposition": "reportable",+ "method": "integration test",+ "confidence": "high",+ "confidence_rationale": "The test reproduced the reported behavior.",+ "rubric": "Check the protected operation.",+ "evidence": ["The unauthorized request succeeded."],+ "counterevidence_or_proof_gap": "",+ "remaining_uncertainty": "",+ "artifact_paths": []+ },+ "severity": null,+ "impact": null+ }+ ]+}+```++Dispositions are `reportable`, `suppressed`, `not_applicable`, or `deferred`.+Set severity/impact to `{ "level": "medium", "rationale": "..." }` to revise+them, or null to retain them. Identity and source locations stay unchanged.++Candidates and results remain under `artifacts/custom-validation/`. Setup+failure, incomplete/invalid output, or any deferred candidate means incomplete+coverage. An incompatible plugin stops the scan. Supply the validation prompt+again when rerunning.++## Publish findings to Cloud++Preview selected completed scans before uploading:++```bash+codex-security publish scan --to cloud --dry-run --json+codex-security publish scan --scan SCAN_ID_A --scan SCAN_ID_B \+ --to cloud --dry-run --json+```++The interactive picker starts with nothing selected; press Space to select and+Enter to submit. Find IDs with `scans list --json`. Select by full ID, unique+prefix of at least eight characters, or `latest` for the current repository.+Local sealed artifacts are required. Dry runs need no login or network access.++Uploads require ChatGPT credentials saved to a file. Set+`cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.+Cloud publication rejects automatic/keyring storage even when `auth.json` exists,+because that file may be stale or belong to another account.++Use a positional scan directory or repeated `--scan-dir PATH` for artifacts+outside history. Each must contain one completed sealed scan, not a bulk-run+directory or `results.jsonl`. Do not mix directories with `--scan`.+Cloud also accepts exported CSV:++```bash+codex-security publish scan --to cloud --csv /path/outside/repository/findings.csv+```++CSV cannot combine with scan selectors. Use the+[CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)+or `export --export-format csv` output.++One scan returns a receipt directly. Multiple scans return `results`, `failed`,+and `notAttempted` arrays. Uploads run sequentially and continue after individual+failures, returning `2` if any fail. Cancellation returns results so far with+`130` (Ctrl-C) or `143` (SIGTERM), unless every upload was already confirmed.++Save receipts: Cloud does not store them in local history. IDs are Cloud finding+IDs in request order. Uploads are not retried automatically. A missing receipt+can still mean the upload succeeded; check Cloud before retrying and do not+resend a confirmed upload.++## Publish completed scans to Linear++```bash+codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID+```++Select one completed scan by ID, prefix, `latest`, or directory; omit the selector+for the picker. Live publication and `--skip-existing` require local history.+A directory-only dry run does not.++`--linear-project PROJECT_ID` (`--project`) selects a project. Flags override+`CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`+previews titles offline; `--json` returns structured output.++Sign in to Codex and connect Linear, or set `CODEX_SECURITY_LINEAR_API_KEY` to+use its API directly. Direct API publication leaves issues unassigned unless+`--linear-assignee` gives a user ID or email. Prefer the environment variable+over `--linear-api-key`, which exposes the key in shell history/process listings.+Keys are omitted from saved results; diagnostic messages remain unchanged.++```bash+codex-security publish check /path/to/completed-scan \+ --to linear --linear-team TEAM_ID --json+```++`publish check` verifies artifacts and recorded publications. With an API key,+it also checks authentication and destination access. It does not test issue+creation; connected-app access is reported as `not-checked`.++Each finding becomes an issue with severity, source, evidence, and remediation.+Choose a destination authorized to receive that content. Local history records+successful issue IDs separately from sealed artifacts.++Republishing creates duplicates unless `--skip-existing` finds a recorded success+for that occurrence, team, and project. It does not check remote issues or cover+unrecorded/concurrent publication. After interruption, inspect the handoff,+evidence, and destination before retrying.++```ts+import { publishScan } from "@openai/codex-security";++const publication = await publishScan("/path/to/completed-scan", {+ destination: "linear",+ teamId: "TEAM_ID",+ skipExisting: true,+});+console.log(publication.scanId, publication.created.length);+```++Options also include `projectId`, `linearApiKey`, and `assigneeId` (ID or email).+`checkScanPublication()` takes the same destination options for a read-only check.++## Classify finding severity++Apply a rubric to completed findings without repeating discovery:++```bash+codex-security classify-severity --scan latest --rubric /path/to/policy.md --json+codex-security classify-severity --scan-dir /path/to/completed-scan --json+```++Use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.+Omitting `--rubric` inherits original severity without model calls. Rubrics and+repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.+Each finding is classified in a separate read-only turn using its report and+supplied context, without tools or source inspection. `--model` and `--effort`+override Codex's configured model and the default medium effort.++Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,+the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for+missing facts that could change the result. Exclusions have a null level.+Finding/occurrence IDs and input hashes bind each assessment to its evidence.++Successful assessments checkpoint immediately in local SQLite. Retries reuse+matching evidence, rubric, and context hashes; failed/canceled runs keep completed+work. Use `--reprocess` to replace assessments, including when changing only model+or effort. A successful run also writes `severity-classification.json`, but+publication reads the database. Original findings and sealed artifacts remain+unchanged.++Repeat `--finding-id ID` for a subset, such as dedupe's `uniqueFindingIds`.+Linear publication defaults to saved classification selection, omits exclusions,+and uses assessed severity for title and priority. Descriptions retain original+severity and add the classification rationale. Publication rejects incomplete or+stale assessments. It never reclassifies or rereads the rubric at publication time.++```bash+codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \+ --finding-id FINDING_ID+codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run+```++Linear publication also accepts `--finding-id`. If a classification exists, every+selected finding needs an assessment. Existing tickets are not changed;+`--skip-existing` preserves recorded tickets and human priority edits.++```ts+import {+ classifySeverity,+ classifyScanSeverity,+ classifyScanDirectorySeverity,+ publishScan,+} from "@openai/codex-security";++// Assess supplied reports in memory.+const classification = await classifySeverity(findings, {+ rubricPath: "/path/to/policy.md",+ knowledgeBasePaths: ["/path/to/context.md"],+});++// Save assessments for a scan ID or sealed directory.+await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });+await classifyScanDirectorySeverity(scanDirectory, {+ rubricPath: "/path/to/policy.md",+ findingIds: dedupeResult.uniqueFindingIds,+});++// Or supply an in-memory assessment directly to publication.+await publishScan(scanDirectory, {+ destination: "linear",+ teamId: "TEAM_ID",+ classification,+ findingIds: classification.assessments.map(({ findingId }) => findingId),+ dryRun: true,+});+```++`classifySeverity()` accepts `findingId`, `title`, `summary`, and available+evidence/metadata. Imported reports may lack severity or occurrence IDs; missing+severity requires a rubric. Scan wrappers persist checkpoints (including for+external directories), accept `reprocess: true`, and treat `findingIds: []` as an+empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and+publication. Older JSON-only assessments need reclassification once. All+classification methods accept `signal`; keep human overrides in your workflow.++## Suggest finding owners++```bash+codex-security suggest-owners findings.json --source-root /path/to/repo --json > owners.json+```++Input is a findings document or `{ "findings": [...] }`. The source root+defaults to the current directory. The command reads committed `HEAD`, relevant+source, blame, and history; it does not read uncommitted source or assign tickets.+Linked worktrees and bound separate Git directories are supported; borrowed+external object stores such as `git clone --shared` are rejected.++Results preserve IDs and report `identified`, `abstained`, or `error`. Identified+owners include an observed Git name/email, reason, and checked citations.+Git identities do not establish current employment or tracker accounts; match+accounts before assigning. Use a checkout matching the findings.++The command uses scan-default model/effort; override with `--model` and `--effort`.+The model receives collected evidence with tools/network disabled. Exit `0`+includes abstentions; `2` means invalid input or a failed recommendation, while+retaining other results. Cancellation uses `130` or `143`.++```ts+import { suggestOwners } from "@openai/codex-security";++const owners = await suggestOwners("/path/to/repo", result.findings.findings, {+ reasoningEffort: "high",+});+```++SDK inputs can include `sourceRevision`. If it differs from `HEAD`, the collector+ignores stale line ranges and reports the mismatch. Reports remain separate from+scan artifacts and record the analyzed revision and limitations.++## Feedback++```bash+codex-security feedback --reason "The scan stopped before it finished"+codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs+```++Share the returned ID with support. Without a selector, `feedback` uses the most+recently started scan in the current repository, including failed/active scans,+or sends a general report if none exist. Reports include your description,+versions, and selected scan/session IDs. `--json` returns structured output.++Logs are off by default. `--include-logs` sends Codex diagnostics and saved scan/+worker activity, potentially including source, prompts, findings, and tool output.+Include only logs you can share with OpenAI. `feedback.enabled = false` disables+the service.++For Desktop-plugin scans, run on the machine where the scan ran with the same+Codex home and state directory. The command searches active/archived sessions and+recorded worker descendants. Standard scans in an existing Codex conversation+attach only their owner's session. Unrecorded earlier retry sessions may be absent.++## Scan history and reruns++Commands default to the current repository. IDs accept unique prefixes of at+least eight characters.++| Command | Purpose |+| ----------------------------------------------------- | ---------------------------------------------------------- |+| `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |+| `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |+| `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |+| `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |+| `scans rerun [SCAN_ID]` | Repeat on the current checkout. |+| `scans match BEFORE AFTER` | Link findings with the same root cause. |+| `scans match --all` | Match completed scans across worktrees/clones. |+| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |+| `findings list [REPOSITORY]` | List open findings. |+| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |++Recipes save settings and authentication choice, not credentials. Reruns use the+current checkout/context files and do not reload project files. Supply replacement+scan and custom-validation prompts when the original used them:++```bash+codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md+```++History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or+`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Keep it private,+writable, and outside the target repository. Session logs may contain sensitive+data even though scan recipes do not store credentials.++### Resuming an interrupted Deep Scan++```bash+codex-security scans list --scan-root /path/to/security-scans+codex-security scans resume SCAN_ID+```++The scan must still be `running`, with its original checkout, output directory,+and Codex session in the same state directory. Checkout identity, revision, and+contents must match. Completed, failed, and canceled scans need a rerun instead.++Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved+settings/instructions. New records save the authentication mode, explicit safety+identifier, and post-scan prompt; older records cannot reconstruct missing values.+A failed connection leaves the scan available for another resume attempt.+Compatible scans can resume after plugin updates; sealed results keep their+original producer version. Unsupported artifacts are rejected without rewriting them.++For bulk scans, use [bulk recovery](#recovering-failed-or-interrupted-bulk-scans)+to update campaign receipts. Individual resume does not update `results.jsonl`.++### Matching saved scans++Matching uses sealed artifacts and cached decisions unless `--force` is supplied.+Comparisons classify findings as new, persisting, reopened, resolved, or unknown.+An absent finding is not resolved when the later scan is incomplete or excludes+its scope. One comparison ID is compared with the latest completed scan.++```bash+codex-security scans match --all --force --model gpt-6.1-sol --effort high+```++Only high-confidence root-cause matches are grouped. Uncertain and related+findings remain separate. Rebuilding retains stable identities, triage, and+sealed artifacts; interruption preserves completed comparisons. Model/effort+changes alone do not invalidate cached decisions.++```ts+import { readFile } from "node:fs/promises";+import {+ matchScanFindings,+ type FindingsDocument,+} from "@openai/codex-security";++const before = JSON.parse(+ await readFile("/path/to/earlier-scan/findings.json", "utf8"),+) as FindingsDocument;+const after = JSON.parse(+ await readFile("/path/to/later-scan/findings.json", "utf8"),+) as FindingsDocument;++const comparison = await matchScanFindings(+ { before: before.findings, after: after.findings },+ { workingDirectory: "/path/to/repository" },+);+console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);+```++This SDK method does not save a workbench comparison. `knownFindingGroups` can+reuse confirmed stable `findingId` groups; results identify original occurrence+IDs. Options include model, reasoning effort, `signal`, and `onProgress`.+Progress callback failures do not stop matching.++## Exports and CI++`export` reads saved results without Codex or credentials. It defaults to the+current repository's latest completed scan. Choose either a positional result+directory or `--scan ID`. Findings require sealed results and support+`--export-format csv|json|sarif` (default SARIF). `--source-root PATH` adds SARIF+source-line fingerprints.++```bash+codex-security export --scan SCAN_ID --export-format json --output findings.json+codex-security export --artifact threat-model --output docs/threatmodel.md+codex-security export /path/to/policy-results --artifact threat-model --output -+```++Threat-model exports use Markdown and default to `./threatmodel.md`. Standard,+Deep, Diff, and policy workflows retain models when available; component/bulk+runs save one per child. Explicit results may expose a model before completion+or after later failure. Missing models return an error rather than generating+or substituting one. Historical models in sealed scans need a matching manifest+digest.++`--output -` emits only artifact content, with diagnostics on stderr. Markdown+and CSV stdout cannot combine with JSON command output. Exporting into a checkout+does not make the model scan input; pass it with `--knowledge-base`.++`ScanResult.threatModel` and `threatModelPath` expose the retained model and+document, or null. Export still works if the document could not be written.++```ts+import { exportArtifact } from "@openai/codex-security";++const exported = await exportArtifact({+ source: { directory: "/path/to/scan-results" }, // Or { scanId: "SCAN_ID" }.+ artifact: "threat-model",+ output: "/path/to/threatmodel.md",+});+console.log(exported.path, exported.provenance);+```++Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.+`output: "-"` streams stdout and returns null path/provenance. `pythonPath`+selects an interpreter; `signal` cancels.++JSON preserves sealed findings. CSV marks them open, omits local triage state,+and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and+leading apostrophes; import removes the escape. Use JSON to recover ambiguous+apostrophes from older CSV exports.++For CI, place output outside the checkout and set a severity threshold:++```bash+SCAN_ROOT="$(mktemp -d)"+codex-security scan . --diff origin/main \+ --output-dir "$SCAN_ROOT/results" --json --fail-on-severity high \+ > "$SCAN_ROOT/findings.json"+```++| Exit code | Meaning |+| ------------- | --------------------------------------------------------------------- |+| `0` | Complete report-only scan or passing severity policy. |+| `1` | Severity policy violation. |+| `2` | Invalid input, incomplete coverage, runtime error, or export failure. |+| `130` / `143` | Interrupt / termination. |++JSON scans have no interactive controls. `validate`, `login`, and `logout` reject+`--json`. For GitHub Actions setup, see the+[Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md)+or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md).++### Local pre-commit checks++`install-hook` checks staged and unstaged changes, blocking the commit on scan+failure or findings at/above its threshold (`high` by default). Use required CI+for enforcement; local hooks are optional.++Install the CLI outside the target repository and run that copy directly. `npx`+can select a repository-local package. Before installation, inspect:++```bash+git -C /path/to/repository rev-parse --git-path hooks/pre-commit+```++Resolve relative output against the repository. Leave custom, linked, shared, or+unverified hooks/directories alone; contact their owner or use CI. If the directory+belongs only to this repository and no hook exists, run from outside the checkout:++```bash+codex-security install-hook /path/to/repository+```++To migrate an existing generated hook, verify it is a regular file used only by+this repository and contains only the generated command. Preserve its severity.+The installer can update older `npx` hooks when the severity matches. New hooks+record absolute Node/CLI paths. If those change, back up and remove the verified+generated hook, then reinstall with the same threshold. Restore the backup if+installation fails. The installer respects `core.hooksPath`.++## Import alerts from the CLI++```bash+codex-security import github example/repository --format json > /path/outside/repository/alerts.json+codex-security import github example/repository --github-alert 12 --github-alert 18 --format json+codex-security validate /path/outside/repository/alerts.json+```++Run validation from the matching local repository. Import defaults to open alerts+on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or+`--github-ref REF` to filter. Exact alert numbers ignore state and reject a+nondefault state.++Import is read-only and returns an array. Save validation inputs without output+filters or token limits. It includes third-party SARIF uploads, does not start+Codex, and does not check out code. Each record contains `source`, `repository`,+`number`, `url`, and the full upstream `alert`.++For a disposition per alert, import and validate through the SDK:++```ts+import {+ CodexSecurity,+ importGitHubCodeScanningAlerts,+} from "@openai/codex-security";++const findings = await importGitHubCodeScanningAlerts({+ repository: "example/repository",+ alertNumbers: [12, 18], // Omit for all open alerts on the default branch.+ githubToken: process.env["GH_TOKEN"],+});++const security = new CodexSecurity();+try {+ for (const finding of findings) {+ const result = await security.validate({+ repositoryPath: "/path/to/repository",+ finding,+ });+ console.log(finding.url, result.disposition, result.outputDir);+ }+} finally {+ await security.close();+}+```++SDK options include `state` (default `"open"`), `ref`, and `signal`.+Supply `githubToken` or use `gh auth token` credentials, including GitHub CLI+token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.+The token needs code-scanning read access; access failures reject the import.++## Validate and patch findings++`validate` assesses candidates; `patch` fixes and verifies them. Both accept files+or literal text and work in the current directory. Saved finding/occurrence IDs+select their original repository for patching.++```bash+codex-security validate "Possible SQL injection" --effort high+codex-security patch OCCURRENCE_ID+codex-security patch --scan SCAN_ID --severity high --json+codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr+```++`--scan latest` uses the current repository's latest completed scan. Patching+supports JSON for saved findings, literal text, and files. Each finding gets a+saved Codex desktop task. `--model` and `--effort` control the model.++`--validation-prompt-file PATH` supplies setup, authorized targets, expected+results, and cleanup for dynamic validation. It works with saved findings,+text/files, and Linear inputs. Paths resolve from the invocation directory, even+when the finding belongs to another repository. The file must be nonempty and+regular, is read before patching, and cannot combine with `--resume-pr`.++`--assess-patch-risk` runs an advisory assessment after patching. Human-readable+output prints its report; saved-finding JSON includes `patchRisk.report`.+With `--create-pr`, the draft description includes the concise Markdown summary.+The assessment does not change the patch or merge state.++Patching first checks that its sandbox can start. Failure reports+`SANDBOX_UNAVAILABLE`; no file changes from the task reports `NO_PATCH_APPLIED`.+Results list `applied`, `filesChanged`, and `files`, excluding preexisting edits.+File changes alone do not prove a fix; saved findings require a verified result.++For a controlled container providing its own isolation:++```bash+codex-security patch "Security issue" --external-sandbox --json+```++This explicit option disables Codex filesystem/network enforcement for the patch+task. The container must provide it. There is no automatic fallback; optional+patch-risk assessment still uses its read-only sandbox.++`scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;+`high` selects high and critical findings. Interactive users can select findings+and add instructions. Patch results are `verified`, `no_change`, `blocked`, or+`failed`. Verified/already-fixed findings no longer fail the severity threshold.++### Create or resume a draft pull request++`--create-pr` commits generated patch files and opens a draft GitHub PR with `gh`+or a GitLab merge request with `glab`. Authenticate the appropriate CLI first.+The `origin` push URL selects GitLab.com, including SSH and subgroup projects.+For self-hosted GitLab, set `GITLAB_HOST` to that host and authenticate with+`glab auth login --hostname HOST`. `GITLAB_URI` and `GL_HOST` are fallback aliases.++```bash+GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr+```++Both providers return `pullRequest: { branch, url }`. Supplied-issue patching+requires a clean tree. If publication fails, run the printed+`patch --resume-pr BRANCH` command in the same repository. It reuses the saved+commit and refuses changed branches. Retain the GitLab host setting on resume.++### Patch Linear issues++Repeat `--linear-issue ISSUE` (ID or URL), or select `--linear-project "PROJECT"`+with optional native JSON `--linear-filter`. Completed/canceled issues are+excluded unless the filter sets `state`.++Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or+`LINEAR_ACCESS_TOKEN` for OAuth. Prefer environment variables over+`--linear-api-key`. Intake is read-only, includes comments, and keeps Linear+credentials out of the patch subprocess. URLs must match the selected workspace.++## Verify fixes++`verify-fix` checks fixes in a read-only sandbox. It accepts descriptions, saved+finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly+filter for completed Linear issues to check a finished backlog.++Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.+`--json` returns structured output. Exit codes are `0` when all findings are+fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.++## Command discovery and integrations++Use `--llms` for the command manifest, `scan --schema --format json` for its+schema, and `completions bash|zsh|fish` for shell completions. Scan output supports+`--format toon|json|yaml|jsonl` and `--full-output`.++`skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.+MCP exposes only read-only `info`, because the transport cannot cancel scans.++For a local findings API and deduplication, see the+[findings service guide](findings-service.md).++## Containerized bulk scans++Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run+from the repository root with the published image:++```bash+mkdir -p results state+chmod 700 results state+export CODEX_SECURITY_USER="$(id -u):$(id -g)"+export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest+docker compose pull codex-security+docker compose run --rm codex-security login --device-auth+docker compose run --rm codex-security+```++Use device login only if your workspace permits it. For unattended scans, set+`OPENAI_API_KEY` or `CODEX_API_KEY`. Results go to `results/`; login stays in+`state/`. Private GitHub checkouts use `GH_TOKEN` or `GITHUB_TOKEN`; Enterprise+uses `CODEX_SECURITY_GIT_HOST`. The container requires CSV input.++Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,+`CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and+`CODEX_SECURITY_STATE` for its image, user, seccomp policy, and mounts.++Codex requires Bubblewrap for filesystem-restricted Linux execution. On Ubuntu+hosts that restrict unprivileged user namespaces, an administrator must install+the AppArmor profile and use the Compose override:++```bash+sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container+sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container+docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security+```++The override enables nested namespaces while keeping the nonroot user, dropped+capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested user+namespaces do not need it. The legacy Landlock fallback is unsupported.+See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)+for deployment and source-build instructions.diff --git a/sdk/typescript/docs/findings-service.md b/sdk/typescript/docs/findings-service.mdnew file mode 100644index 000000000..74606c736--- /dev/null+++ b/sdk/typescript/docs/findings-service.md@@ -0,0 +1,490 @@+# Findings service (preview)++Store findings from multiple scans, browse them in a dashboard, and review+possible duplicates with the CLI or SDK. The service stores findings and+duplicate groups; scans and model reviews run on the calling machine.++The API has no authentication. Keep it on loopback or behind an authenticated+TLS proxy. Imports send the complete finding JSON to the configured embeddings+endpoint. The database and generated embeddings stay in local storage.++CLI examples use `codex-security`. With a local npm installation, use+`npx @openai/codex-security` instead.++## Start the service++Use the repository's+[Compose file](https://github.com/openai/codex-security/blob/main/compose.findings.yaml)+and [.env example](https://github.com/openai/codex-security/blob/main/.env.example).+From the repository root, copy the example if you do not already have a `.env`:++```bash+cp .env.example .env+```++Set `OPENAI_API_KEY` in `.env`, then start the service:++```bash+docker compose -f compose.findings.yaml pull+docker compose -f compose.findings.yaml up --no-build -d+curl -i http://127.0.0.1:3000/v1/findings+```++Open [the dashboard](http://localhost:3000/dashboard) to browse stored findings+and duplicate groups.++You can deploy with just `compose.findings.yaml` and a private `.env`; no source+checkout or Node.js installation is required. The public image supports Linux+`amd64` and `arm64`. Set `CODEX_SECURITY_FINDINGS_IMAGE` to a published version,+`sha-<commit>` tag, or digest for repeatable deployments. Its default is+`ghcr.io/openai/codex-security:latest`.++Compose binds port 3000 to host loopback and stores `/state` in the+`findings-state` volume. Keep the same Compose project name to reuse the volume.+The image runs as UID/GID `10001:10001`; a replacement bind mount must be writable+by that user. Inside the container, `HOST=0.0.0.0`, `PORT=3000`, and+`CODEX_SECURITY_STATE_DIR=/state`.++Stop with `docker compose -f compose.findings.yaml down`. Add `--volumes` only+when you intend to delete the stored data. For source builds or older deployments,+see the [container guide](https://github.com/openai/codex-security/blob/main/docker/README.md).++## Credentials and embeddings++Compose reads the embedding credentials and endpoint from `.env` or the host+environment. For a service started outside Docker, export any of these settings:++| Setting | Purpose |+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |+| `OPENAI_API_KEY` | API key for embeddings; takes precedence over `CODEX_API_KEY`. |+| `CODEX_API_KEY` | Alternative embedding API key. Remove `OPENAI_API_KEY` when using it. |+| `CODEX_SECURITY_EMBEDDINGS_URL` | Full embeddings endpoint URL, including its path and any query parameters. Defaults to `https://api.openai.com/v1/embeddings` when unset or empty. |+| `CODEX_SECURITY_STATE_DIR` | State directory containing `workbench.sqlite3`; Compose uses `/state`. |+| `HOST` / `PORT` | Listen address and port; outside Compose, defaults are `127.0.0.1` and `3000`. |+| `PYTHON` | Python interpreter used by the storage adapter. |++Exported values override Compose's `.env` values. The repository excludes `.env`+from Git and Docker builds. Startup, listing, duplicate-group operations, and+empty imports need no embedding key. A Codex ChatGPT login cannot supply+embedding API credentials.++The endpoint receives the complete finding JSON and the API key as a bearer+token. It must support the OpenAI embeddings request and response format. For+example, to use a compatible endpoint outside Docker:++```bash+CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve+```++The service uses `text-embedding-3-large` with 1,536 dimensions. It tokenizes+the complete JSON with `cl100k_base`, splits long inputs without truncation,+then combines the vectors by token weight and normalizes them. Requests observe+the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.++## Publish a scan++Send a completed scan to the service:++```bash+codex-security publish scan --scan SCAN_ID --to custom \+ --findings-url http://localhost:3000 --json+```++`--findings-url` is required. The client appends `/v1/bulk/findings` to this+base URL, preserving any base path. Custom endpoints must implement that API+and return the stored finding IDs.++Publication sends the complete sealed findings and the manifest's+`scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged+and does not forward model credentials. The service creates embeddings and+commits the batch before acknowledging it.++Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or+the interactive picker. Custom publication accepts one scan; CSV input and+Linear options do not apply. Add `--dry-run` to preview the payload without an+HTTP request. Upload failures and incomplete receipts fail the command. Uploads+are not automatically retried because a lost response may have been committed.++```typescript+import { publishScanToCustom } from "@openai/codex-security";++const receipt = await publishScanToCustom("/path/to/completed-scan", {+ findingsUrl: "http://localhost:3000",+ // dryRun: true,+ // signal: controller.signal,+});+console.log(receipt.repositoryId, receipt.findingIds);+```++## HTTP API++Both POST endpoints require `Content-Type: application/json`; charset parameters+are accepted. Other or missing content types return HTTP 400 before embedding+or storage.++| Method | Path | Response |+| ------ | --------------------------------------- | ----------------------------------------------------------------------- |+| `POST` | `/v1/bulk/findings` | HTTP 201; stored finding IDs in request order. |+| `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200; a page of complete findings. |+| `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200; the anchor finding and up to 50 candidates. Requires a scope. |+| `POST` | `/v1/dedupe-groups` | HTTP 201; persisted duplicate groups. |+| `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200; every group containing the finding. |+| `GET` | `/v1/dashboard` | HTTP 200; counts, repository choices, records, and optional details. |++### Import findings++`POST /v1/bulk/findings` accepts `{"findings": [...]}` using the SDK `Finding`+model, including `findingId`, `occurrenceId`, and `fingerprints`. A complete+exported `findings.json` document is also accepted; only its `findings` array is+imported. The service does not open files or source paths referenced by a finding.++Include `repositoryId` beside `findings` to associate every imported finding+with that repository. For SDK/CLI scans, use `scan.target.targetId` from+`scan-manifest.json`. IDs match exactly; the service does not infer them from+titles, paths, or URLs. Reimports add associations without removing earlier ones.+Findings imported without an ID are available only to all-repository candidate+searches until imported with an association.++Add `repositoryId` to a copy of the export, leaving the sealed artifacts intact:++```bash+curl http://127.0.0.1:3000/v1/bulk/findings \+ -H 'Content-Type: application/json' \+ --data-binary @findings-import.json+```++The response is an array such as `["csf_852f90d6e1177502ff113d4a"]`.++A batch is atomic: failed embedding generation or an identity conflict writes+none of it. Reusing a `findingId` updates its document and embedding without+creating another row. It cannot replace the existing fingerprint, rule, or+identity anchor/instance. Repeated IDs in one request are applied in order;+the last record remains. Stored scan occurrences are unchanged.++### List findings++Listing defaults to `limit=50` and `offset=0`. `limit` must be a positive integer+and `offset` a non-negative integer. Results sort by first insertion time, then+finding ID. Follow `nextOffset` until it is `null`:++```json+{+ "findings": [],+ "limit": 50,+ "offset": 0,+ "total": 0,+ "nextOffset": null+}+```++The list includes imports and complete documents from existing CLI scan history,+using the latest document for each ID. Legacy identities without complete+documents are omitted. Responses exclude embedding vectors. Separate requests+reflect the current database rather than one shared snapshot.++### Find potential duplicates++Choose exactly one scope:++```text+GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example+GET /v1/finding/{id}/potential-duplicates?allRepositories=true+```++Repository scope requires both the anchor and candidates to belong to that+repository. All-repository scope includes associated and unassociated findings.+Missing or combined scopes return HTTP 400. Scope filters candidates; it does+not control access.++The response contains `finding` and `potentialDuplicates`, both using complete+`Finding` records without vectors. The candidates exclude the anchor, have cosine+similarity of at least 0.55, and use the same embedding model and dimensions.+Up to 50 are returned in descending similarity order, with ties resolved by+insertion time and finding ID. Each request uses a consistent read snapshot.+The service retrieves candidates; model review decides whether they are duplicates.++### Store duplicate groups++`POST /v1/dedupe-groups` accepts reviewed member sets:++```json+{+ "groups": [+ ["csf_000000000000000000000001", "csf_000000000000000000000002"],+ ["csf_000000000000000000000002", "csf_000000000000000000000003"]+ ]+}+```++Each group needs at least two distinct, existing finding IDs. A missing member+returns HTTP 409 and writes none of the batch. The response contains `groupId`,+`findingIds`, and `createdAt` for each group. Resubmitting the same membership+in any order returns the original ID and timestamp.++Overlapping groups stay separate; the service does not infer a larger group.+Stored members sort by ID and do not designate a canonical finding.+`GET /v1/finding/{id}/dedupe-groups` returns full membership for every containing+group, or `[]`. These associations do not rewrite findings, fingerprints,+artifacts, embeddings, or tickets, and require no model calls or embedding key.++### API errors++Errors contain an `error` code and, for expected failures, a `message`.++| HTTP status | Code | Meaning |+| ----------- | ----------------------- | -------------------------------------------------------------------------------------- |+| 400 | `invalid_request` | Invalid JSON, finding, repository metadata, group, scope, pagination, or content type. |+| 409 | `finding_conflict` | Conflicting identity or missing group member. |+| 502 | `embedding_failed` | Embedding provider failure or unusable vectors. |+| 503 | `embedding_unavailable` | Missing embedding credentials. |+| 404 | `finding_not_indexed` | The anchor has no current embedding in the requested repository scope. |+| 404 | `not_found` | Unknown route. |+| 500 | `internal_error` | Unexpected server failure. |++For `finding_not_indexed`, import the finding with the matching `repositoryId`+before retrying. Updating a document can invalidate its earlier embedding.+This error does not mean that the finding has no duplicates.++## Browse the dashboard++The dashboard has Findings and Duplicate groups views with search, repository+filters, sorting, pagination, and record details. Click a column header to sort+all matching records; click again to reverse it. It refreshes every five seconds,+keeping the selected order and the last successful data if a refresh fails.++It reads only the service database, not local source files or scan directories.+It displays no remote scan or workflow history and cannot modify findings or+start scans, publication, or deduplication.++`GET /v1/dashboard` accepts:++| Parameter | Values and defaults |+| --------------------- | ---------------------------------------------------------------------------------------------------- |+| `view` | `findings` (default) or `groups`. |+| `query`, `repository` | Search text and exact repository ID. |+| `sort` | `activity` (default), `newest`, `title`, `repository`, `severity` (findings), or `members` (groups). |+| `direction` | `asc` or `desc` (default). |+| `limit`, `offset` | Positive limit and non-negative offset; defaults are 50 and 0. |+| `id` | Record ID to include in `detail`; an unknown ID returns `detail: null`. |++Overview counts cover the whole service, regardless of filters. The default+order is last update descending, then severity descending for findings, then ID+ascending. Text sorts ignore case; severity and member counts use their natural+order. The dashboard uses the same unauthenticated endpoint as the API.++## Deduplicate a scan++Publish the scan first, or import its findings with `repositoryId`. Then run:++```bash+codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json+```++Both `--findings-url` and a scan or workflow selector are required. `--scan`+accepts a full ID, unique prefix, or `latest` for the current repository. The+scan must be complete, with sealed artifacts and a local checkout available.+By default, candidates come from its manifest's `scan.target.targetId`. Use+`--all-repositories` to search the whole service.++```typescript+import { deduplicateScan } from "@openai/codex-security";++const result = await deduplicateScan("scan_example_001", {+ findingsUrl: "http://127.0.0.1:3000",+ concurrency: 8,+ // allRepositories: true,+ // signal: controller.signal,+});+console.log(result.duplicateGroups);+```++For a sealed scan directory outside local history, supply the checkout:++```typescript+import { deduplicateScanDirectory } from "@openai/codex-security";++const result = await deduplicateScanDirectory("/path/to/completed-scan", {+ repository: "/path/to/repository",+ findingsUrl: "http://127.0.0.1:3000",+ // expectedScanId: "scan_example_001",+ // concurrency: 8,+ // allRepositories: true,+ // signal: controller.signal,+});+console.log(result.duplicateGroups);+```++The CLI and SDK return the same result:++```json+{+ "scanId": "scan_example_001",+ "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],+ "duplicateGroups": [],+ "deduplicationStatus": "completed"+}+```++`uniqueFindingIds` contains one representative for each selected finding after+accepted groups are collapsed. A representative can come from outside the scan.+Each group lists its canonical finding first: highest reported severity, then+finding ID to break ties. Group associations are saved before returning success;+the original findings and scan artifacts remain unchanged.++If a model refuses a review, the result uses `completed_with_refusals` and adds+`refusals`. Each entry contains `decision: "NO_DECISION"`, `stage`, `model`,+`findingIds`, and `reason`. Screening entries list the anchor first, then its+candidates. Refused pairs stay separate, including through indirect groups;+their findings are not confirmed unique. The CLI logs refusals to stderr and+exits successfully after saving the other accepted groups.++### Reviews, concurrency, and failures++Deduplication retrieves all candidate neighborhoods, screens them with+`gpt-5.6-luna` at `xhigh`, then independently reviews nominated pairs with+`gpt-5.6-sol` at `high`. A pair review can start after all screenings that cover+it finish without a `DISTINCT` decision. Accepted pairs form groups only when+no reviewed `DISTINCT` decision or refusal contradicts the group.++The default concurrency is 8. Set `--concurrency N` or SDK `concurrency: N` to+change it; use 1 for serial execution. Candidate retrieval uses that limit, and+screenings and ready pair reviews share one worker pool. Results are combined+in input order, independent of completion order.++Reviews run on the SDK/CLI host using its Codex sign-in or environment API key;+credentials are not sent to the findings service. Each review receives complete+original findings and may inspect the approved local checkout. Reviews preserve+severity and priority rather than reassessing them. The baseline filesystem is+read-only and excludes credentials and Codex state. Screening denies approval+requests; pair reviews use Codex's automatic approval reviewer. Web, plugins,+and inherited MCP servers are disabled. Finding content and linked tickets do+not authorize access to another target.++Models must submit a validated decision. A session that ends without one gets+one corrective turn. Invalid output and eligible transient failures can retry+in fresh sessions, up to three sessions per review. Transient service failures+allow up to three request attempts; HTTP retries honor `Retry-After`. Backoff+occupies the job's concurrency slot.++Cancellation, authentication/configuration errors, permanent HTTP errors, and+required-source-access blockers are not retried. Refusals are not retried or+sent to another model. If candidate retrieval or review still fails, queued jobs+stop and running jobs finish before the operation fails without posting groups.+A failed group-write request may already have committed; resubmitting the same+memberships does not create duplicate groups. Non-cancellation review failures+throw `DeduplicationReviewError`, with diagnostic text and `metadata` for the+stage, model, category, attempt count, and reason.++Empty scans and findings without eligible candidates make no review calls.+Other scans can require multiple calls per finding. Completion means the+retrieval, review, and group write finished; it does not mean that every pair+in the database was compared. Use Ctrl-C or SIGTERM in the CLI, or an+`AbortSignal` in the SDK, to cancel. This workflow is separate from Deep Scan's+internal reducer.++### Resume a findings workflow++Use one workflow ID across scanning, custom publication, and deduplication:++```bash+codex-security scan /path/to/repository --workflow-id run-001+codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000+codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json+```++The SDK equivalents are `workflowId` on `ScanOptions`,+`PublishScanToCustomOptions`, and `DeduplicateScanOptions`. Repeat the sequence+with the same ID after an interruption. Completed scans, acknowledged uploads,+and validated reviews are reused. This resumes completed stages, not model+turns inside an unfinished scan. Normal output-directory checks still apply.++A workflow can begin by publishing an existing completed scan. Publication and+dedupe can use its ID instead of `--scan`; an explicit scan must match. Dedupe+completes publication if its receipt is missing. Changing the bound scan,+destination, or repository scope requires a different ID. Use one coordinating+process per workflow. Dry runs do not advance it.++Workflow state and checkpoints live in the local workbench database under+`CODEX_SECURITY_STATE_DIR`, outside the sealed artifacts. Completed reviews are+reused only when their findings, source checkout and contents, scope, model+settings, Codex configuration/version, and review contract still match. Source+changes during review stop the attempt before group writes. Resume to review+the changed source. You can change concurrency without invalidating checkpoints.++Before posting groups, the workflow saves the reviewed result and write payload.+If acknowledgement is lost, resuming replays that payload without new model+calls. Membership-based group IDs prevent duplicates. Completed workflows,+including empty results and `completed_with_refusals`, return their saved result.+Use a new ID for a fresh review or to retry a refusal after resolving its cause.++### Use a host-provided model backend++`codex-security dedupe --records` accepts a JSON-RPC run over stdin and emits+serial `review.run` requests on stdout. The SDK equivalent is+`deduplicateRecords(input, { reviewRunner, signal })`. These entry points need+no saved scan or findings service and perform no local model execution or+persistence. The host supplies original observations and candidate links.+See the [records protocol and Python example](dedupe-records.md).++## Storage, upgrades, and backups++Storage initializes before the server listens. The service uses the workbench+SQLite database at `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`; startup applies+append-only migrations and retains existing finding identities and scan history.+Changing a stored document invalidates its old embedding. Historical findings+are not embedded automatically; import them through the bulk endpoint first.++Before an upgrade, read the release notes, stop the service, and back up all of+`/state`:++```bash+docker compose -f compose.findings.yaml stop findings+mkdir -p backups+chmod 700 backups+docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \+ --entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz+chmod 600 backups/findings-state.tgz+```++Keep backups separately. This overwrites an existing backup of the same name.+Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest, then pull and+start it while retaining the volume. To roll back, stop the service, restore+the pre-upgrade backup, and select the previous image digest. Older images may+not support the migrated database.++## Run without Docker++With the package's supported Node.js and Python versions installed:++```bash+npm install -g @openai/codex-security+CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000+```++`--port` overrides `PORT`. The service does not load `.env`; export the embedding+key before importing findings. Without a state override, it shares the CLI's+default state directory. `HOST`, `PORT`, `CODEX_SECURITY_STATE_DIR`, and `PYTHON`+also work on Windows. Stop with Ctrl-C or SIGTERM.++For source builds, prepare the+[universal native payload](https://github.com/openai/codex-security/blob/main/plugins/codex-security/native/README.md#package-inputs),+then run from `sdk/typescript`:++```bash+pnpm install --frozen-lockfile+pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile+pnpm run build:plugin+pnpm run build+node bin/codex-security.mjs serve --port 3000+```++`pnpm run start:server` and `node dist/server/index.js` also start the service.++For renewable embedding credentials, import `OpenAiFindingEmbedder`,+`SqliteFindingsStore`, and `startFindingsServer` from+`@openai/codex-security/server`. The embedder accepts a static key or a callback+`() => string | Promise<string>` as its first argument. It calls the callback+before every HTTP batch; the caller handles token acquisition. Pass `fetch` as+the second argument and the full endpoint URL as the third; omitting the URL+uses the OpenAI endpoint. `startFindingsServer({ store, embeddings, host, port })`+returns a Node HTTP server. Importing the module does not start a listener.diff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex b4b4bfd2a..d7d3ecba6 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -40,6 +40,8 @@"_bundled_plugin","LICENSE","README.md",+ "docs/cli.md",+ "docs/findings-service.md","docs/dedupe-records.md"],"publishConfig": {diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjsindex e2dad2db3..665308b93 100644--- a/sdk/typescript/scripts/check-package.mjs+++ b/sdk/typescript/scripts/check-package.mjs@@ -115,6 +115,8 @@ if (files.size !== entries.length) {const required = ["package/package.json","package/README.md",+ "package/docs/cli.md",+ "package/docs/findings-service.md","package/docs/dedupe-records.md","package/LICENSE","package/bin/codex-security.mjs",diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 200d07c7d..372a7beac 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -13,7 +13,6 @@ import { PassThrough, Writable } from "node:stream";import { fileURLToPath } from "node:url";import { stripVTControlCharacters } from "node:util";import { describe, expect, test, mock } from "bun:test";-import { parse as parseToml } from "smol-toml";import type {CodexSecurityConfig,JsonObject,@@ -60,7 +59,6 @@ import {failingSecurity,fakeInterval,} from "./cli-fixtures.js";-import { PLUGIN_ROOT } from "./plugin-root.js";import { runCommand } from "./support/shell.js";import { temporaryDirectory } from "./support/temporary-directories.js";import { fail, throwing } from "./support/errors.js";@@ -365,144 +363,6 @@ describe("CLI", () => {}});- test("documents user-facing environment and deep-scan configuration", async () => {- const readme = await readFile(new URL("../README.md", import.meta.url), {- encoding: "utf8",- });- const publicReadme = await readFile(- new URL("../../../README.md", import.meta.url),- { encoding: "utf8" },- );-- for (const documentation of [readme, publicReadme]) {- expect(documentation).toContain("https://chatgpt.com/cyber");- }-- for (const setting of [- "OPENAI_API_KEY",- "CODEX_API_KEY",- "CODEX_SECURITY_LOG_LEVEL",- "LOG_LEVEL",- "CODEX_SECURITY_STATE_DIR",- "CODEX_HOME",- "PYTHON",- "GH_HOST",- "GH_TOKEN",- "GITHUB_TOKEN",- "CODEX_SECURITY_GIT_HOST",- "CODEX_SECURITY_IMAGE",- "CODEX_SECURITY_USER",- "CODEX_SECURITY_SECCOMP",- "CODEX_SECURITY_CSV",- "CODEX_SECURITY_RESULTS",- "CODEX_SECURITY_STATE",- "CODEX_SECURITY_NO_UPDATE_NOTICE",- "NO_UPDATE_NOTIFIER",- "CODEX_SECURITY_NPM_REGISTRY",- "npm_config_registry",- "NPM_CONFIG_REGISTRY",- "NO_COLOR",- "TERM",- "CI",- "features.multi_agent_v2.max_concurrent_threads_per_session",- "agents.max_threads",- "$CODEX_HOME/codex-security/config.toml",- "[deep_scan]",- "stop_after_no_new",- "max_discovery_runs",- "max_time_hours",- ]) {- expect(readme).toContain(setting);- }- expect(readme).toMatch(- /\|\s*`CODEX_SECURITY_LOG_LEVEL`\s*\|\s*CLI-only\b/u,- );- expect(readme).toMatch(/\|\s*`LOG_LEVEL`\s*\|\s*CLI-only\b/u);- });-- test("keeps documented runtime and deep-scan defaults accurate", async () => {- const readme = await readFile(new URL("../README.md", import.meta.url), {- encoding: "utf8",- });- const documentedConfigs = [- ...readme.matchAll(/^```toml\s*\n([\s\S]*?)\n```\s*$/gmu),- ].map(([, config]) => parseToml(config!));- const documentedRuntime = documentedConfigs.find(- (config) => "cli_auth_credentials_store" in config,- );- expect(documentedRuntime).toMatchObject({- cli_auth_credentials_store:- DEFAULT_CODEX_CONFIG["cli_auth_credentials_store"],- model: DEFAULT_SCAN_MODEL_CONFIGURATION.model,- model_reasoning_effort: DEFAULT_SCAN_MODEL_CONFIGURATION.reasoningEffort,- });-- const features = DEFAULT_CODEX_CONFIG["features"] as JsonObject;- const multiAgent = features["multi_agent_v2"] as JsonObject;- expect(documentedRuntime).toMatchObject({- features: {- multi_agent_v2: {- max_concurrent_threads_per_session:- multiAgent["max_concurrent_threads_per_session"],- },- },- });-- const python = Bun.which("python3") ?? Bun.which("python");- expect(python).not.toBeNull();- const root = await temporaryDirectory("codex-security-deep-defaults-");-- try {- const { status, stdout, stderr } = await runCommand(- python!,- [- join(PLUGIN_ROOT, "scripts", "deep_scan_config.py"),- "--available-parallelism",- "12",- ],- {- env: {- ...process.env,- CODEX_HOME: join(root, "codex-home"),- PYTHONDONTWRITEBYTECODE: "1",- },- timeout: 30_000,- },- );-- expect(status, stderr).toBe(0);- expect(stderr).toBe("");-- const defaults = JSON.parse(stdout) as {- workers: number;- subagents: number;- stopAfterNoNew: number;- stopAfterConsecutiveErrors: number;- maxDiscoveryRuns: number;- maxTimeHours: number;- };- expect(defaults.workers).toBe(4);- const documentedDeepScan = documentedConfigs.find(- (config) =>- typeof config["deep_scan"] === "object" &&- config["deep_scan"] !== null &&- "stop_after_consecutive_errors" in config["deep_scan"],- );- expect(documentedDeepScan).toMatchObject({- deep_scan: {- workers: 4,- subagents: defaults.subagents,- stop_after_no_new: defaults.stopAfterNoNew,- stop_after_consecutive_errors: defaults.stopAfterConsecutiveErrors,- max_discovery_runs: defaults.maxDiscoveryRuns,- max_time_hours: defaults.maxTimeHours,- },- });- } finally {- await rm(root, { recursive: true, force: true });- }- });-test("marks findings as false positives without starting Codex", async () => {const reason = " Not reachable from untrusted input. ";const expectedReason = reason.trim();