Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

chore(release): 0.3.0

github-actions[bot]5c5239dd8062
diff --git a/.github/release-notes.md b/.github/release-notes.md
index 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.json
index 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.json
index 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.json
index 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.md
index 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 sessions
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 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",