OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
chore(release): 0.3.0
github-actions[bot]5c5239dd8062
diff --git a/.github/release-notes.md b/.github/release-notes.mdindex 0d0dde4cc..799de3fa1 100644--- a/.github/release-notes.md+++ b/.github/release-notes.md@@ -1,45 +1,99 @@-<!-- release-version: 0.2.0 -->+<!-- release-version: 0.3.0 --><!-- release-section: highlights:start -->## Highlights-- Threat models are now saved with Standard, Deep, and Diff scan results and- generated security policies. Export a saved model without another model call- using `codex-security export --artifact threat-model` or the SDK's- `exportArtifact` helper.- ([#1133](https://github.com/openai/codex-security/pull/1133))-- Scans now check for exposed credentials in source code, including unused code- and tests, and distinguish suspected exposures from placeholders. This check- runs offline, without trying discovered credentials against a service.- ([#1134](https://github.com/openai/codex-security/pull/1134))-- Use `--model` and `--effort` when generating patches, validating findings,- verifying fixes, or matching and comparing saved scans. Deep Scan workers and- patches generated during a scan also respect your selected service tier.- ([#1143](https://github.com/openai/codex-security/pull/1143),- [#1238](https://github.com/openai/codex-security/pull/1238),- [#1274](https://github.com/openai/codex-security/pull/1274))-- Patch, validation, and fix-verification commands now respect custom model- providers and their authentication settings. Amazon Bedrock users get clearer- authentication errors and cost estimates for Daybreak Blue and Red. Eligible- OpenAI API-key users can select a Cyber access program for each scan.- ([#1131](https://github.com/openai/codex-security/pull/1131),- [#1187](https://github.com/openai/codex-security/pull/1187),- [#1188](https://github.com/openai/codex-security/pull/1188),- [#1185](https://github.com/openai/codex-security/pull/1185))-- Scans include previously overlooked C++ headers (`.hh` and `.hxx`),- server-rendered templates (EJS, ERB, and PHTML), and Vyper source files when- selecting code to review.- ([#1079](https://github.com/openai/codex-security/pull/1079),- [#1197](https://github.com/openai/codex-security/pull/1197),- [#1306](https://github.com/openai/codex-security/pull/1306))-- On Unix, scans check that the sandbox works before starting paid model calls.- Completed results are kept if you cancel follow-up work. CSV exports can now be- reimported without rejecting multiple occurrences of a finding or losing- leading apostrophes.- ([#1084](https://github.com/openai/codex-security/pull/1084),- [#1057](https://github.com/openai/codex-security/pull/1057),- [#1247](https://github.com/openai/codex-security/pull/1247))+Codex Security Local 0.3.0 reduces unnecessary work in Deep Scan, includes more+source files, and makes scan exit codes easier to use in scripts. It also improves+recovery when scans are interrupted.++- Deep Scan waits for earlier results to be checked before starting more reviews,+ avoiding extra reviews when it already has enough information to stop. Fresh+ API-key and Amazon Bedrock scans also skip a model step during startup when+ using the bundled plugin and default Node runtime.+ ([#1630](https://github.com/openai/codex-security/pull/1630),+ [#1555](https://github.com/openai/codex-security/pull/1555))+- Source selection now includes text files without recognized extensions, build+ and test files, and JSP and ASP.NET templates. Fixes also preserve unusual+ filenames and the original contents of saved Git-diff and directory scans.+ ([#1347](https://github.com/openai/codex-security/pull/1347),+ [#1414](https://github.com/openai/codex-security/pull/1414),+ [#1345](https://github.com/openai/codex-security/pull/1345),+ [#1280](https://github.com/openai/codex-security/pull/1280))+- Resumed scans preserve their original knowledge context, model/provider+ settings, and selected paths. Interrupted scans retain usable results, and+ Deep Scan cancellation waits for worker cleanup and state updates before+ returning. Exhausted usage stops workers instead of triggering more retries.+ ([#1556](https://github.com/openai/codex-security/pull/1556),+ [#1501](https://github.com/openai/codex-security/pull/1501),+ [#1602](https://github.com/openai/codex-security/pull/1602),+ [#1260](https://github.com/openai/codex-security/pull/1260),+ [#1638](https://github.com/openai/codex-security/pull/1638))+- The terminal dashboard batches updates during busy scan replays and avoids+ rereading unchanged logs. It shows token usage even when pricing is unavailable+ for the selected model. Cost reporting adds Cyber pricing, restores GPT-6 Sol+ estimates, and includes Codex context-compaction usage.+ ([#1276](https://github.com/openai/codex-security/pull/1276),+ [#1336](https://github.com/openai/codex-security/pull/1336),+ [#1585](https://github.com/openai/codex-security/pull/1585),+ [#1590](https://github.com/openai/codex-security/pull/1590))++### Scan exit codes++Coverage warnings no longer turn a completed scan into a failure. Deep Scans can+also finish when an optional detailed writeup is missing; the findings remain+in the report.++| Exit code | Meaning |+| --------- | ------------------------------------------------------------------- |+| `0` | The scan completed without a configured severity-threshold failure. |+| `1` | Findings met the configured `--fail-on-severity` threshold. |+| `2` | Execution, result integrity, or required output failed. |++A successful exit does not mean every file was reviewed. Check coverage details+when your workflow requires that information.+([#1633](https://github.com/openai/codex-security/pull/1633),+[#1624](https://github.com/openai/codex-security/pull/1624))++### Other CLI and SDK additions++- Use `cs` as a shorter alias for `codex-security`. Policy drafting now+ works when Codex is installed under your home directory, and app clients can+ rename and search saved scans.+ ([#1415](https://github.com/openai/codex-security/pull/1415),+ [#1416](https://github.com/openai/codex-security/pull/1416),+ [#1180](https://github.com/openai/codex-security/pull/1180))+- Generate and verify fixes from TypeScript with `security.patch()`, using+ the SDK client's authentication, model settings, and cancellation support.+ Your application controls review, commits, and publication. When you request a+ pull request for a supplied issue, CLI results now include its branch and URL.+ ([#1635](https://github.com/openai/codex-security/pull/1635),+ [#1645](https://github.com/openai/codex-security/pull/1645))+- Owner suggestions prefer committed CODEOWNERS before falling back to Git+ history. In Codex, the new `$cloud-findings` skill reads findings, reports,+ and recorded validation from existing Codex Security Cloud scans.+ ([#1519](https://github.com/openai/codex-security/pull/1519),+ [#1422](https://github.com/openai/codex-security/pull/1422))++Other fixes cover GitLab merge-request publication, Windows process launch and+network-share database paths, configuration errors, YAML error messages, and+plugin integrity checks after Python creates cache files. The package includes+Codex CLI/SDK 0.162.1. Display names now say **Codex Security Local**; the package+remains `@openai/codex-security`.++## GitHub Action++A new GitHub Action runs repository and pull-request scans in CI. Set the source+scope and time and cost budgets, review job summaries, and download saved results.+You can upload findings to GitHub code scanning as SARIF and fail a job at a+chosen severity.++The initial Action supports GitHub.com, Linux x64 runners, and API-key+authentication. Action releases follow the verified npm release. See the+[Action guide](https://github.com/openai/codex-security/blob/npm-v0.3.0/github-action/README.md).+([#1015](https://github.com/openai/codex-security/pull/1015),+[#1418](https://github.com/openai/codex-security/pull/1418))<!-- release-section: highlights:end -->@@ -47,28 +101,111 @@## Upgrade notes-- If your integration reads threat models, check `SecurityPolicyDraft.threatModelPath`- for `null` before opening the file. Policy generation now writes `threatmodel.md`- instead of `THREAT_MODEL.md`; use the returned path. Saved models can contain- Markdown (`format: "markdown"`, `content`) or the previous structured format, so- readers must handle both. Existing models remain readable and exportable- without migration.- ([#1133](https://github.com/openai/codex-security/pull/1133))-- Findings service clients must send `Content-Type: application/json` to- `POST /v1/bulk/findings` and `POST /v1/dedupe-groups`. Missing or other content- types return HTTP 400 `invalid_request`. A charset parameter is accepted.- ([#1277](https://github.com/openai/codex-security/pull/1277))-- Codex Security no longer masks diagnostic text that looks like credentials.- CLI output and saved error, publication, and patch-risk summaries can contain- sensitive values. Review them before sharing.- ([#1179](https://github.com/openai/codex-security/pull/1179))-- SDK types and CLI schemas now accept any nonempty string for reasoning effort.- Update integrations that assume a fixed list. The chosen value must still be- supported by Codex and your model provider.- ([#1237](https://github.com/openai/codex-security/pull/1237))-- Older CSV exports may have ambiguous leading apostrophes that cannot be- recovered from the CSV alone. Export the original saved results as JSON if you- need those exact values.- ([#1247](https://github.com/openai/codex-security/pull/1247))+Read the sections that apply to your scripts, saved scans, or integrations before+updating from 0.2.0.++### Scripts and integrations that read scan results++If you consume scan JSON or SDK types, replace `coverage.completeness`,+`CoverageCompleteness`, bulk/component `incomplete` counters, comparison+`comparable`, and Action `scan-status: incomplete` handling with+`manifest.scan.status` and exit codes. Action `scan-status` now uses+`completed`, `failed`, or `skipped`. If a later scan does not find a previously+reported finding in the code it scanned, comparison returns `not_observed`.+Excluded paths and uncertain matches remain `unknown`; `resolved` requires+explicit closure as already fixed.++New drafts, imports, worker output, and custom-validation results must use the+current `codeEvidence`, `rootCause`, `attackPath.dataflow`, and+`evidenceRefs` fields. Migrate unfinished drafts or finish them with their+original version. Completed historical reports remain readable and exportable.+([#1633](https://github.com/openai/codex-security/pull/1633))++### Standalone validation++`validate` now assesses source in a read-only sandbox. It does not build or+execute the target, run tests or proofs of concept, or contact services.+Save the assessment from CLI stdout or SDK `result.report`; the validator+no longer writes report files:++```bash+codex-security validate findings.json > assessment.md+```++Run a separate reproduction when you need runtime proof. Validation within+Standard, Deep, and Diff scans keeps its existing behavior.+([#1423](https://github.com/openai/codex-security/pull/1423))++### Resuming existing scans++Keep the private `.scan-knowledge.json` file with scan artifacts. Resume+uses this captured knowledge-base context even if the original documents change+or disappear. Older individual scans that used knowledge bases but lack this+snapshot require a new scan. Scans without knowledge bases and bulk scans with+captured context remain resumable. Reruns use current inputs.+([#1556](https://github.com/openai/codex-security/pull/1556))++Reading compressed `.jsonl.zst` sessions requires Node 22.15+ within 22.x,+or Node 24/26. Node 22.13–22.14 still supports plain logs but cannot resume+compressed sessions.+([#1428](https://github.com/openai/codex-security/pull/1428))++### Owner suggestion consumers++The owner-suggestion JSON report now uses `schemaVersion: 2`. Owners can be GitHub users, teams, or+email-only identities. Check for a non-null owner, then use `"handle" in owner`+before reading `owner.handle` or `owner.email`. Do not assume every owner+has a Git name/email pair.+([#1519](https://github.com/openai/codex-security/pull/1519))++### Installation and Windows settings++Global installs now create the `cs` alias. If npm reports `EEXIST`+because another tool owns that name, use `npx @openai/codex-security`.+Windows defaults to the elevated sandbox backend and honors an explicit backend+selection.+([#1415](https://github.com/openai/codex-security/pull/1415),+[#1281](https://github.com/openai/codex-security/pull/1281))++### Custom plugins and direct helper users++Upgrade custom plugins to the current archive/comparison protocols. New and+resumed Deep scans also require `directDeepScanEngine: 1`,+`workerProviderSnapshot: 4`, and isolated workers. Alternatively, omit+`pluginPath`/`--plugin-path` to use+the bundled plugin. Replace direct `node ./mcp/server.mjs` launches with+the current plugin launcher.++For retained findings-storage and severity operations, replace direct calls to+retired Python helpers with+`scripts/launch_codex_security_mcp --helper COMMAND` (the `.cmd` launcher+on Windows). Pass JSON on stdin with an absolute `stateDirectory` and the+helper payload. Normal CLI/SDK callers need no helper migration. The selected+state directory must be writable; the temporary-state fallback is removed.+See the [SDK compatibility notes](https://github.com/openai/codex-security/blob/npm-v0.3.0/sdk/typescript/README.md)+and [helper reference](https://github.com/openai/codex-security/blob/npm-v0.3.0/sdk/typescript/docs/findings-service.md#direct-storage-helpers).+([#1548](https://github.com/openai/codex-security/pull/1548),+[#1408](https://github.com/openai/codex-security/pull/1408),+[#1543](https://github.com/openai/codex-security/pull/1543))++### Local deduplication and findings service removal++Saved-scan deduplication now uses local SQLite storage by default, without a+running service. It caches embeddings and review progress so interrupted work+can resume.++The `serve` command, its `--port` option, `start:server`,+`startFindingsServer`, browser dashboard, and findings-service Compose+deployment are removed. Use `codex-security dedupe --scan SCAN_ID` locally, or supply `--findings-url` for an independently hosted compatible+service.++Keep existing state directories and volumes. Select the local database through+`CODEX_SECURITY_STATE_DIR`; a separate service volume is not selected+automatically. Generating or refreshing embeddings with the built-in embedder+requires an API key. The `@openai/codex-security/server` entrypoint retains+its storage and embedding exports. See the+[findings guide](https://github.com/openai/codex-security/blob/npm-v0.3.0/sdk/typescript/docs/findings-service.md).+([#1340](https://github.com/openai/codex-security/pull/1340),+[#1338](https://github.com/openai/codex-security/pull/1338))<!-- release-section: upgrades:end -->diff --git a/.github/release-pr-state.json b/.github/release-pr-state.jsonindex f5b3a8301..20c06620c 100644--- a/.github/release-pr-state.json+++ b/.github/release-pr-state.json@@ -1,14 +1,14 @@{- "baseVersion": "0.1.32",- "baseCommit": "7c19cce7224af29628cd10c218444d5c0e8fdd1c",+ "baseVersion": "0.2.0",+ "baseCommit": "4949af70fcfadff154f6e8fdf100faa5bf2f8169","sections": {"highlights": {- "generatedHash": "f65d8fae76964a512b64091b27881c1618ccb0399e3438d6396c0090a5564fbe",- "humanOwned": true+ "generatedHash": "e93f207d9fdc726ae4c467e0c8cd88ca89904316180bc1566903287b12e73570",+ "humanOwned": false},"upgrades": {- "generatedHash": "e4d70417d0224b264a39eb96709c1e22c5ee1b95d30ad4aafb3f531e077791a7",- "humanOwned": true+ "generatedHash": "f5f5a865a61bfbbe4a3844071fcf18bba7a8e21b1bba2abb2960a3e3969c5a7e",+ "humanOwned": false}}}diff --git a/github-action/package-lock.json b/github-action/package-lock.jsonindex 3ccbd40aa..98cff9acb 100644--- a/github-action/package-lock.json+++ b/github-action/package-lock.json@@ -1,12 +1,12 @@{"name": "codex-security-action",- "version": "0.2.0",+ "version": "0.3.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "codex-security-action",- "version": "0.2.0",+ "version": "0.3.0","dependencies": {"@actions/artifact": "6.3.1","@actions/core": "3.0.1",diff --git a/github-action/package.json b/github-action/package.jsonindex 10b8d5794..9b5a9128e 100644--- a/github-action/package.json+++ b/github-action/package.json@@ -1,6 +1,6 @@{"name": "codex-security-action",- "version": "0.2.0",+ "version": "0.3.0","private": true,"type": "module","description": "Run Codex Security in GitHub Actions with explicit scope, budgets, and scan health reporting",diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex d811b41c9..939597366 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -25,8 +25,7 @@ Supported runtimes:- 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`. The findings server (`serve`) uses- Node’s built-in SQLite and does not require Python.+ findings. Python 3.10 also needs `tomli`.Reading compressed Codex session logs (`.jsonl.zst`) requires Node.js 22.15.0+within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14, compressed sessionsdiff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex 3ca673045..2e899583f 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -1,6 +1,6 @@{"name": "@openai/codex-security",- "version": "0.2.0",+ "version": "0.3.0","description": "TypeScript SDK and CLI for Codex Security","license": "Apache-2.0","author": "OpenAI",