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.4.0 (#1655)
github-actions[bot]559b492b22bb
diff --git a/.github/release-notes.md b/.github/release-notes.mdindex 799de3fa1..3dea8f1e7 100644--- a/.github/release-notes.md+++ b/.github/release-notes.md@@ -1,99 +1,42 @@-<!-- release-version: 0.3.0 -->+<!-- release-version: 0.4.0 --><!-- release-section: highlights:start -->## Highlights-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))+Codex Security 0.4.0 adds hosted Standard scan execution and improves token+accounting, bulk-scan recovery, and report formatting. The minor version marks+the removal of obsolete ranking helpers; direct helper users should follow the+migration guidance below.++- Hosts can run Standard repository or path scans through the TypeScript+ `runHostedScan(input, { executor, signal, onEvent })` API or the+ `codex-security scan --host` JSON-RPC adapter. Hosted execution is opt-in and+ requires a host-provided executor, frozen checkout, and explicit model and+ storage settings. Hosts own authorization, cancellation, and durable execution+ state. See the [hosted scan guide](https://github.com/openai/codex-security/blob/npm-v0.4.0/sdk/typescript/docs/hosted-scans.md).+ ([#1559](https://github.com/openai/codex-security/pull/1559))+- Scan token totals include recorded usage from earlier Deep Scan worker+ attempts and context compaction without counting resumed history twice.+ The SDK and compatible hosts can finish accounting for the final response+ after report generation. Missing records remain marked incomplete or+ unavailable rather than being presented as an exact total.+ ([#1657](https://github.com/openai/codex-security/pull/1657))+- Bulk scans preserve successful results and original scan failures when+ temporary-checkout cleanup fails. Cleanup errors are reported separately, and+ reusing a completed scan can retry its recorded cleanup without another scan.+ ([#1433](https://github.com/openai/codex-security/pull/1433))+- Reports render malformed evidence ranges as a valid single line or just the+ path. Finding text beginning with tilde fences or parenthesized list markers+ no longer changes the formatting of surrounding report sections. These fixes+ preserve the underlying findings.+ ([#1656](https://github.com/openai/codex-security/pull/1656),+ [#1604](https://github.com/openai/codex-security/pull/1604))+- The package includes Codex CLI/SDK 0.163.0 and restores the **Codex Security**+ display name in plugin listings, prompts, and tool labels. The npm package+ remains `@openai/codex-security`, with the `cs` and `codex-security` commands.+ ([#1670](https://github.com/openai/codex-security/pull/1670),+ [#1681](https://github.com/openai/codex-security/pull/1681))<!-- release-section: highlights:end -->@@ -101,111 +44,41 @@ authentication. Action releases follow the verified npm release. See the## Upgrade notes-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))+### Scripts and custom workflows that invoke ranking helpers++The following plugin helper commands are removed:++- `make-repo-rank-input` and `select-deep-review-input`+- `make-rank-shards`, `validate-rank-shard`, and `merge-rank-outputs`+- `make-rank-pool-plan`, `validate-rank-worker`, and `validate-rank-pool`++Remove the ranking, shard/pool scheduling, and ranked-selection stages from+custom workflows. Generate the scoped inventory and review every selected file:++1. For explicit repository scopes, use+ `scripts/generate_rank_input.py make-repo-scope-input --repo <repo_root> --scopes-file <scopes_json> --out <output_jsonl>`+ with your Python interpreter and the script from the installed plugin.+ The scopes file is a JSON array, such as `["src", "tests"]`; use `["."]`+ for the whole repository instead of the old default `--scope .`.+ Output rows contain only `path`, for example `{"path":"src/example.ts"}`.+ Update your consumer to resolve each path against the repository root and+ read that file directly. If it requires a `path`/`area` review worklist,+ convert every row to `{"path":"src/example.ts","area":"repository"}`.+ This inventory contains no `area` or `preview` fields and cannot be passed+ directly to `copy-deep-review-input`.+2. For Git diffs, retain `make-diff-rank-input` with its existing revision or+ local-patch arguments. Copy all candidate rows into the review worklist with+ `scripts/launch_codex_security_mcp --helper copy-deep-review-input --rank-input <input_jsonl> --out <review_jsonl>`.+ On Windows, use the `.cmd` launcher.+3. Review the entire resulting worklist instead of selecting a ranked subset.+ `bind-repo-scopes` and the retained diff helpers keep their existing+ arguments and worklist formats.++See the [scoped review reference](https://github.com/openai/codex-security/blob/npm-v0.4.0/plugins/codex-security/skills/security-scan/references/scan-artifacts-and-ledger.md#scoped-deep-review)+for commands, scope inputs, and Windows invocation details.+([#1607](https://github.com/openai/codex-security/pull/1607))++Normal CLI and SDK scans do not need this helper migration. Hosted execution is+opt-in; existing local scans continue to use their current execution path.<!-- release-section: upgrades:end -->diff --git a/.github/release-pr-state.json b/.github/release-pr-state.jsonindex 20c06620c..b7a1ea80c 100644--- a/.github/release-pr-state.json+++ b/.github/release-pr-state.json@@ -1,14 +1,14 @@{- "baseVersion": "0.2.0",- "baseCommit": "4949af70fcfadff154f6e8fdf100faa5bf2f8169",+ "baseVersion": "0.3.0",+ "baseCommit": "5c5239dd8062a7d00916c4bc0d5aeaa3ed0c5477","sections": {"highlights": {- "generatedHash": "e93f207d9fdc726ae4c467e0c8cd88ca89904316180bc1566903287b12e73570",- "humanOwned": false+ "generatedHash": "ed7fb1027c60901424f054c5b4b1e7ee19485193f00d37e2ae74f3fb4ba6f2bb",+ "humanOwned": true},"upgrades": {- "generatedHash": "f5f5a865a61bfbbe4a3844071fcf18bba7a8e21b1bba2abb2960a3e3969c5a7e",- "humanOwned": false+ "generatedHash": "1b370c365d6e8307d660a71b96785ce8cd8d046a893dc4c3dacc37da4d85e27e",+ "humanOwned": true}}}diff --git a/github-action/package-lock.json b/github-action/package-lock.jsonindex 98cff9acb..fb448b092 100644--- a/github-action/package-lock.json+++ b/github-action/package-lock.json@@ -1,12 +1,12 @@{"name": "codex-security-action",- "version": "0.3.0",+ "version": "0.4.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "codex-security-action",- "version": "0.3.0",+ "version": "0.4.0","dependencies": {"@actions/artifact": "6.3.1","@actions/core": "3.0.1",diff --git a/github-action/package.json b/github-action/package.jsonindex 9b5a9128e..609a45dcc 100644--- a/github-action/package.json+++ b/github-action/package.json@@ -1,6 +1,6 @@{"name": "codex-security-action",- "version": "0.3.0",+ "version": "0.4.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/package.json b/sdk/typescript/package.jsonindex 022cf7d67..771340ef3 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -1,6 +1,6 @@{"name": "@openai/codex-security",- "version": "0.3.0",+ "version": "0.4.0","description": "TypeScript SDK and CLI for Codex Security","license": "Apache-2.0","author": "OpenAI",