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

docs: make scan and integration guides evergreen (#2350)

Michael D'Angelo258d7a6c3372
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 88b6dfb80..6925bf18e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,11 +2,11 @@
## Summary
-<!-- Describe the technical problem and outcome without identifying customers or private systems. -->
+<!-- What problem does this solve, and what can users or maintainers do after this change? Use public, synthetic examples. -->
## Changes
-<!-- Summarize the changes reviewers should understand. If maintainers need to update
+<!-- Identify implementation decisions or affected interfaces that need reviewer attention. If maintainers need to update
https://learn.chatgpt.com/docs/security, you can name the affected page or workflow and suggest an edit. -->
## Testing
diff --git a/.github/release-notes.md b/.github/release-notes.md
index f9b445ee3..32e1ef799 100644
--- a/.github/release-notes.md
+++ b/.github/release-notes.md
@@ -4,119 +4,9 @@
## Highlights
-- update SDK and MCP parser dependencies ([#2141](https://github.com/openai/codex-security/pull/2141))
-- do not split surrogate pairs in truncated report text ([#2133](https://github.com/openai/codex-security/pull/2133))
-- update vulnerable triage dependencies ([#2142](https://github.com/openai/codex-security/pull/2142))
-- defer CLI and plugin validators until first use ([#2140](https://github.com/openai/codex-security/pull/2140))
-- explain package provenance ([#361](https://github.com/openai/codex-security/pull/361))
-- speed up plugin setup and defer CLI prompts ([#2146](https://github.com/openai/codex-security/pull/2146))
-- track Black Duck SCA project-version vulnerabilities ([#2098](https://github.com/openai/codex-security/pull/2098))
-- avoid claiming output was kept after scan failures ([#359](https://github.com/openai/codex-security/pull/359))
-- track Veracode static application policy flaws ([#2099](https://github.com/openai/codex-security/pull/2099))
-- accept UTF-8 BOM in JSON project files ([#980](https://github.com/openai/codex-security/pull/980))
-- avoid duplicate plugin setup inspection and defer CLI YAML ([#2149](https://github.com/openai/codex-security/pull/2149))
-- accept UTF-8 BOMs in scan inputs and calibration datasets ([#2151](https://github.com/openai/codex-security/pull/2151))
-- preserve IPv6 verification URL brackets ([#232](https://github.com/openai/codex-security/pull/232))
-- bump the third-party group across 2 directories with 2 updates ([#2157](https://github.com/openai/codex-security/pull/2157))
-- bump ruff from 0.17.1 to 0.17.2 in /plugins/codex-security ([#2153](https://github.com/openai/codex-security/pull/2153))
-- bump docker/login-action from 4.6.0 to 4.7.0 ([#2155](https://github.com/openai/codex-security/pull/2155))
-- bump the codex group across 3 directories with 2 updates ([#2154](https://github.com/openai/codex-security/pull/2154))
-- keep whole characters when shortening publish progress ([#2158](https://github.com/openai/codex-security/pull/2158))
-- preserve local scan startup diagnostics ([#2115](https://github.com/openai/codex-security/pull/2115))
-- name the outermost rejected Windows ancestor ([#2065](https://github.com/openai/codex-security/pull/2065))
-- count only CR and LF as assessment line breaks ([#2147](https://github.com/openai/codex-security/pull/2147))
-- retain the reviewed surface count for completed Deep scans ([#2161](https://github.com/openai/codex-security/pull/2161))
-- show highest-severity findings first ([#2160](https://github.com/openai/codex-security/pull/2160))
-- bump taiki-e/install-action from 2.87.30 to 2.87.31 ([#2156](https://github.com/openai/codex-security/pull/2156))
-- align Unicode repository columns ([#2148](https://github.com/openai/codex-security/pull/2148))
-- link Markdown evidence to plain source lines ([#2032](https://github.com/openai/codex-security/pull/2032))
-- update MCP SDK to 1.32.2 and Stryker to 10.1.1 ([#2170](https://github.com/openai/codex-security/pull/2170))
-- import SonarQube Cloud security findings ([#2162](https://github.com/openai/codex-security/pull/2162))
-- share saved coverage logic and checkpoint fixtures ([#2185](https://github.com/openai/codex-security/pull/2185))
-- organize external scanner integration guides ([#2189](https://github.com/openai/codex-security/pull/2189))
-- index SARIF artifact URIs once per run ([#2191](https://github.com/openai/codex-security/pull/2191))
-- normalize GitHub scanner evidence for its destination ([#2192](https://github.com/openai/codex-security/pull/2192))
-- reuse Wiz replay projections for package reports ([#2193](https://github.com/openai/codex-security/pull/2193))
-- share local Git metadata discovery ([#2194](https://github.com/openai/codex-security/pull/2194))
-- require exhaustive scanner reader dispatch ([#2195](https://github.com/openai/codex-security/pull/2195))
-- normalize selected Semgrep Code findings for local import ([#2164](https://github.com/openai/codex-security/pull/2164))
-- share optional field parsing across GitHub and Wiz ([#2198](https://github.com/openai/codex-security/pull/2198))
-- share scanner Cloud publication and recovery guidance ([#2199](https://github.com/openai/codex-security/pull/2199))
-- share SARIF rule indexing and reference checks ([#2200](https://github.com/openai/codex-security/pull/2200))
-- isolate rejected publication progress callbacks ([#2203](https://github.com/openai/codex-security/pull/2203))
-- share connection and error handling for finding imports ([#2204](https://github.com/openai/codex-security/pull/2204))
-- avoid duplicate Git metadata discovery ([#2205](https://github.com/openai/codex-security/pull/2205))
-- skip Cloud number formatting for local evidence ([#2202](https://github.com/openai/codex-security/pull/2202))
-- give each scanner import a focused guide ([#2201](https://github.com/openai/codex-security/pull/2201))
-- reuse native record checks for Black Duck components ([#2207](https://github.com/openai/codex-security/pull/2207))
-- reduce Sonar issue collection requests ([#2208](https://github.com/openai/codex-security/pull/2208))
-- show the SDK fallback for finding imports ([#2209](https://github.com/openai/codex-security/pull/2209))
-- show how to retrieve selected scanner evidence ([#2210](https://github.com/openai/codex-security/pull/2210))
-- share SARIF result context for Semgrep and Endor ([#2219](https://github.com/openai/codex-security/pull/2219))
-- share the repository scope for external finding reads ([#2221](https://github.com/openai/codex-security/pull/2221))
-- choose configured tools for scanner and Cloud findings ([#2213](https://github.com/openai/codex-security/pull/2213))
-- parse fenced triage results in one pass ([#2214](https://github.com/openai/codex-security/pull/2214))
-- simplify publication progress and scan selection ([#2218](https://github.com/openai/codex-security/pull/2218))
-- share the latest remediation attempt query ([#2215](https://github.com/openai/codex-security/pull/2215))
-- share patch and verify-fix input selection ([#2217](https://github.com/openai/codex-security/pull/2217))
-- share smoke inputs and native artifact upload settings ([#2220](https://github.com/openai/codex-security/pull/2220))
-- share artifact path validation during finalization ([#2222](https://github.com/openai/codex-security/pull/2222))
-- remove private Wiz finding type re-exports ([#2229](https://github.com/openai/codex-security/pull/2229))
-- remove unreachable component dashboard status cases ([#2230](https://github.com/openai/codex-security/pull/2230))
-- reuse validated patch risk summaries in draft reviews ([#2228](https://github.com/openai/codex-security/pull/2228))
-- remove unused permissive Git-tree lookup ([#2227](https://github.com/openai/codex-security/pull/2227))
-- remove retired GitHub publication commands ([#2226](https://github.com/openai/codex-security/pull/2226))
-- share SARIF rule reference validation ([#2235](https://github.com/openai/codex-security/pull/2235))
-- simplify provider import examples ([#2234](https://github.com/openai/codex-security/pull/2234))
-- skip Cloud replay projections for local Wiz findings ([#2236](https://github.com/openai/codex-security/pull/2236))
-- accept imported evidence in records deduplication ([#2241](https://github.com/openai/codex-security/pull/2241))
-- use the singular for one finding or reviewed file ([#2239](https://github.com/openai/codex-security/pull/2239))
-- preserve PDF line breaks during text extraction ([#2196](https://github.com/openai/codex-security/pull/2196))
-- skip index paths under directories replaced by files ([#2182](https://github.com/openai/codex-security/pull/2182))
-- use the singular for one repository in bulk scan prompts ([#2174](https://github.com/openai/codex-security/pull/2174))
-- spell numeric ranges with en dashes, not tildes ([#2095](https://github.com/openai/codex-security/pull/2095))
-- keep every scroll step in the finding details pane ([#2016](https://github.com/openai/codex-security/pull/2016))
-- align the component cost column with its header ([#2004](https://github.com/openai/codex-security/pull/2004))
-- bump taiki-e/install-action from 2.87.31 to 2.87.32 ([#2244](https://github.com/openai/codex-security/pull/2244))
-- distinguish library defaults from caller obligations ([#2245](https://github.com/openai/codex-security/pull/2245))
-- preserve boxed numeric evidence across retries ([#2224](https://github.com/openai/codex-security/pull/2224))
-- restore concrete discovery guidance for Standard and Deep scans ([#2246](https://github.com/openai/codex-security/pull/2246))
-- reuse repository membership checks across scans ([#2249](https://github.com/openai/codex-security/pull/2249))
-- preserve permission errors from plugin installation ([#2247](https://github.com/openai/codex-security/pull/2247))
-- share terminal grapheme handling ([#2232](https://github.com/openai/codex-security/pull/2232))
-- prepare Veracode selection filters once per report ([#2248](https://github.com/openai/codex-security/pull/2248))
-- index saved sessions by parent when reading scan logs ([#2237](https://github.com/openai/codex-security/pull/2237))
-- share SARIF evidence projection for Semgrep and Endor ([#2233](https://github.com/openai/codex-security/pull/2233))
-- share projection and validation logic ([#2183](https://github.com/openai/codex-security/pull/2183))
-- reconcile unacknowledged findings uploads ([#2211](https://github.com/openai/codex-security/pull/2211))
-- reuse scoped GitHub connections for finding intake ([#2223](https://github.com/openai/codex-security/pull/2223))
-- clarify the post-scan findings review prompt ([#2255](https://github.com/openai/codex-security/pull/2255))
-- remove Daybreak latest alias pricing ([#2165](https://github.com/openai/codex-security/pull/2165))
-- opt in to the remote rubric for standalone reclassification ([#2257](https://github.com/openai/codex-security/pull/2257))
-- accept a host-supplied severity rubric for Standard scans ([#2253](https://github.com/openai/codex-security/pull/2253))
-- submit selected scanner findings to the private inbox ([#2177](https://github.com/openai/codex-security/pull/2177))
-- apply native profiles across scan workflows ([#1018](https://github.com/openai/codex-security/pull/1018))
-- share sealed scan reads with tracking ([#1846](https://github.com/openai/codex-security/pull/1846))
-- skip the old position of moved DOCX text ([#2256](https://github.com/openai/codex-security/pull/2256))
-- honor signed-in tracker connections for finding reads ([#2212](https://github.com/openai/codex-security/pull/2212))
-- inherit the launching turn's Deep Scan speed ([#2231](https://github.com/openai/codex-security/pull/2231))
-- reconcile live and saved parent updates ([#1596](https://github.com/openai/codex-security/pull/1596))
-- review agent skills before installation ([#2088](https://github.com/openai/codex-security/pull/2088))
-- show Git errors for unreadable tracked files ([#2058](https://github.com/openai/codex-security/pull/2058))
-- prepare hosted runners and require completed PR checks ([#1580](https://github.com/openai/codex-security/pull/1580))
-- share the host adapter for records commands ([#2259](https://github.com/openai/codex-security/pull/2259))
-- preserve the severity rubric across standalone scan attempts ([#2258](https://github.com/openai/codex-security/pull/2258))
-- share bundled severity grading with the SDK ([#2260](https://github.com/openai/codex-security/pull/2260))
-- report the exact rubric used for severity classification ([#2262](https://github.com/openai/codex-security/pull/2262))
-- support AWS Continuum code findings ([#2264](https://github.com/openai/codex-security/pull/2264))
-- recognize Windows drive and UNC host casing ([#545](https://github.com/openai/codex-security/pull/545))
-- verify large saved scans in bounded requests ([#2251](https://github.com/openai/codex-security/pull/2251))
-- save generated patches for completed scans ([#2033](https://github.com/openai/codex-security/pull/2033))
-- prepare local deduplication in Node ([#1840](https://github.com/openai/codex-security/pull/1840))
-- bump ruff from 0.17.2 to 0.17.3 in /plugins/codex-security ([#2267](https://github.com/openai/codex-security/pull/2267))
-- preserve caller tool settings across scan turns ([#2012](https://github.com/openai/codex-security/pull/2012))
-- count changed files when registering diff scans ([#1916](https://github.com/openai/codex-security/pull/1916))
-- run local scans without connecting an app ([#2100](https://github.com/openai/codex-security/pull/2100))
+- **Scans and reporting.** Run a local scan without connecting an app. Standard and Deep scans include more concrete guidance for finding issues in source. The GitHub Action lists the highest-severity findings first in its job summary and annotations. Published evidence links to Markdown files open the cited source lines on GitHub.
+- **Scanner imports.** Import Black Duck SCA project-version vulnerabilities, Veracode static policy flaws and AWS Continuum code findings. The [scanner guides](https://github.com/openai/codex-security/tree/npm-v0.8.3/docs/scanner-imports) describe the accepted formats and destinations.
+- **Severity and remediation.** Standard scans can use a host-supplied severity rubric. Standalone classification reports the rubric it used. Generated patches for completed scans can be saved with the scan.
<!-- release-section: highlights:end -->
@@ -124,11 +14,6 @@
## Upgrade notes
-Review migration steps for these breaking changes:
-
-- remove Daybreak latest alias pricing ([#2165](https://github.com/openai/codex-security/pull/2165))
-- share sealed scan reads with tracking ([#1846](https://github.com/openai/codex-security/pull/1846))
-- prepare hosted runners and require completed PR checks ([#1580](https://github.com/openai/codex-security/pull/1580))
-- prepare local deduplication in Node ([#1840](https://github.com/openai/codex-security/pull/1840))
+- See [Upgrading to 0.8.3](https://github.com/openai/codex-security/blob/main/CHANGELOG.md#upgrading-to-083) for changes to cost limits, required PR checks, and the tracking and deduplication helpers.
<!-- release-section: upgrades:end -->
diff --git a/.ona/README.md b/.ona/README.md
index cf5f9bf8f..954242c97 100644
--- a/.ona/README.md
+++ b/.ona/README.md
@@ -6,11 +6,6 @@ In the Ona project's Settings, set **Dev Container path** to
after changing the path. The Ona configuration uses the same image, feature
versions, and install script as the default Dev Container.
-Run `install`, `build`, or `test` from Ona's task list. Dependency installation
-and builds also run during prebuilds. Before running tests, download the
-source-matched native artifact described in [SDK testing](../sdk/typescript/TESTING.md).
+From the Ona task list, select **Install dependencies**, then **Build**. These tasks also run during prebuilds. To run **Run tests**, first [download the native payload for your checkout](../plugins/codex-security/native/README.md#package-inputs).
-For migration from the findings service, retain its data volume and follow
-the [local findings and dedupe guide](../sdk/typescript/docs/findings-service.md).
-Keep the shared and Ona feature definitions and lockfiles aligned when updating
-the toolchain.
+When updating the toolchain, keep the shared and Ona feature definitions and lockfiles aligned.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 54c5fb058..60548f724 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,14 +1,12 @@
# Changelog
-[GitHub Releases](https://github.com/openai/codex-security/releases) is the
-canonical changelog for Codex Security. Each release page combines a reviewed
-summary with the categorized pull requests included in that version.
-
-Use the [latest release](https://github.com/openai/codex-security/releases/latest)
-for current upgrade notes. The [complete release history](https://github.com/openai/codex-security/releases)
-links every version to its tag, package asset, contributors, and full Git
-comparison.
-
-Maintainers should follow [RELEASING.md](RELEASING.md) when preparing or
-repairing a release. Keeping the detailed history on GitHub avoids maintaining
-two changelogs that can drift apart.
+Find highlights and upgrade instructions on [GitHub Releases](https://github.com/openai/codex-security/releases). Open the [latest release](https://github.com/openai/codex-security/releases/latest) for the current version, or select the `npm-vX.Y.Z` tag for the version you use. Some older entries contain only the generated change list.
+
+For a GitHub Action pin, open the companion `action-vX.Y.Z` release. It lists the distribution commit SHA and links to the matching CLI changelog.
+
+## Upgrading to 0.8.3
+
+- **Daybreak budgets.** If you set `--max-cost` or the SDK’s `maxCostUsd` with `gpt-daybreak-blue-latest` or `gpt-daybreak-red-latest`, select an available model with built-in pricing. The CLI and SDK no longer have rates for those aliases. Select Blue or Red separately through `--cyber-access-program`. [Pricing change](https://github.com/openai/codex-security/pull/2165)
+- **Required GitHub Action checks.** When adopting the new PR workflow, let the target-specific check run, then replace the old required **Codex Security** check with `Codex Security / <target-branch>` on that branch. Protect against base changes at merge time as described in the [PR workflow guide](https://github.com/openai/codex-security/blob/npm-v0.8.3/github-action/README.md#scan-pull-requests). Put configuration-only runs in a separate job with `dry-run: 'true'` and `fail-on-severity: none`.
+- **Scripts that validate a tracking source.** Replace direct calls to `scripts/validate_tracking_source.py` with `scripts/launch_codex_security_mcp --helper validate-tracking-source SCAN_DIRECTORY` from the installed plugin directory. Use the `.cmd` launcher on Windows. Pass the same optional `--finding-id` or `--fingerprint` selector. The helper verifies the sealed scan and prints one matching finding ID per line. [Tracking change](https://github.com/openai/codex-security/pull/1846)
+- **Scripts that prepare local deduplication.** Replace direct calls to the bundled `workbench_db.py local-dedupe` with `scripts/launch_codex_security_mcp --helper local-dedupe` from the installed plugin directory. Supply the state directory and action payload as JSON on stdin. Keep Python available for saved-scan lookup and export. The [storage helper reference](https://github.com/openai/codex-security/blob/npm-v0.8.3/sdk/typescript/docs/findings-service.md#direct-storage-helpers) shows the request shape and Windows launcher.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8a58479fb..577d1f1b1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,19 +1,37 @@
# Contributing
-Thanks for helping improve Codex Security. We welcome bug reports, feature
-requests, documentation corrections, and feedback from open-source
-maintainers.
+Start with the [source map](#where-to-make-a-change) for a code or documentation change. For a bug or feature request, [search existing issues](https://github.com/openai/codex-security/issues) first. Report vulnerabilities through the [security policy](SECURITY.md).
+
+## Where to make a change
+
+Start with the owner of the behavior, then follow its callers when the change
+crosses a process, persistence, or package boundary.
+
+| Change | Source to start with | Relevant checks |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Documentation | [User guides](docs/), [SDK and CLI guides](sdk/typescript/README.md), and [examples](examples/README.md) | Run `node sdk/typescript/scripts/check-markdown.mjs` after [installing the SDK dependencies](sdk/typescript/TESTING.md#install-dependencies). Check examples from their stated working directory. |
+| Plugin instructions | [Skills](plugins/codex-security/skills/) and shared [references](plugins/codex-security/references/) | [Portable plugin source checks](AGENTS.md#keep-it-simple) |
+| Artifact contracts and generated SDK models | [Contract definitions](plugins/codex-security/mcp-app/src/artifact-contracts.ts), [canonical exports](plugins/codex-security/mcp-app/scripts/canonical-schemas.mts), and [model generator](sdk/typescript/scripts/generate-models.cjs) | [Canonical contract tests](plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts), [MCP wire tests](plugins/codex-security/mcp-app/tests/test_compact_artifact_wire.ts), and [schema generation checks](#how-this-repository-works) |
+| Deep Scan scheduling and workers | Shared [engine, coordinator, and executor](plugins/codex-security/mcp-app/src/deep-scan/), used by the MCP server and SDK launcher | [MCP tests](plugins/codex-security/mcp-app/tests/) and [direct SDK integration](sdk/typescript/tests-ts/direct-deep-scan.test.ts) |
+| Durable scan state, checkpoints, and completion | [Python workbench](plugins/codex-security/scripts/workbench_db.py) and [Deep Scan persistence](plugins/codex-security/scripts/deep_scan_workbench.py) | [Python tests](plugins/codex-security/tests/) and [SDK workbench integration](sdk/typescript/tests-ts/deep-scan-workbench.test.ts) |
+| Helper routing and stored-finding operations | SDK [runtime routing](sdk/typescript/src/runtime.ts), plugin [helper entrypoint](plugins/codex-security/mcp-app/helpers-main.ts), and [Node workbench commands](plugins/codex-security/mcp-app/src/workbench/commands.ts) | [SDK runtime tests](sdk/typescript/tests-ts/runtime.test.ts) and [MCP workbench tests](plugins/codex-security/mcp-app/tests/) |
+| Public CLI and SDK behavior | [CLI adapter](sdk/typescript/src/cli.ts), [SDK API](sdk/typescript/src/api.ts), and adjacent modules | [SDK tests](sdk/typescript/tests-ts/) and the [installed-package checks](sdk/typescript/TESTING.md) |
+| Markdown report rendering | [Scan report projection](plugins/codex-security/scripts/report_projection.py) and [threat-model projection](plugins/codex-security/scripts/threat_model_projection.py) | [Report tests](plugins/codex-security/tests/test_report_projection.py) and [threat-model tests](plugins/codex-security/tests/test_threat_model_projection.py) |
+| Native filesystem and process operations | [Native bindings and adapters](plugins/codex-security/native/README.md) | The native guide's platform proofs and package checks |
+| Packaged plugin contents | [Plugin manifest](plugins/codex-security/plugin-files.json) and [SDK plugin builder](sdk/typescript/scripts/build-plugin.mjs) | [Package inspection and installed consumers](sdk/typescript/TESTING.md) |
+
+The SDK routes selected stored-finding and classification commands to the Node
+helper; scan lifecycle commands still use the Python workbench. Trace the
+specific command before changing either implementation. Shared Deep Scan
+behavior belongs in the plugin engine, with adapter changes in the MCP server
+or SDK only when their entrypoint behavior differs.
## How this repository works
`plugins/codex-security/` is the canonical source for the Codex Security
plugin. Make plugin changes there.
-The npm runtime under `sdk/typescript/_bundled_plugin/` is generated from the
-plugin source by `pnpm run build:plugin` and automatically during `prepack` for
-packages and releases. Do not edit or commit files in that directory. See the
-[SDK testing guide](sdk/typescript/TESTING.md) for the generation and validation
-commands.
+To inspect the bundled npm plugin, [download the native package inputs](plugins/codex-security/native/README.md#package-inputs), then run `pnpm --dir sdk/typescript run build:plugin` from the repository root. The build writes `sdk/typescript/_bundled_plugin/`. Packaging also generates this directory during `prepack`. Edit the plugin source and leave generated files out of commits.
Compact artifact contracts are authored in `plugins/codex-security/mcp-app/src/artifact-contracts.ts`, with shared finding and threat-model definitions in `finding-detail-schemas.ts` and `threat-model-schema.ts`.
Canonical findings, scan-manifest, and coverage exports are defined in `mcp-app/scripts/canonical-schemas.mts`; patch-risk exports and their static type are defined in `mcp-app/src/patch-risk-schema.ts`.
@@ -35,32 +53,6 @@ publication tests in the MCP suite.
See the [CI guide](docs/ci.md) for check selection, platform/version coverage,
required status checks, and test-runner qualification.
-## Where to make a change
-
-Start with the owner of the behavior, then follow its callers when the change
-crosses a process, persistence, or package boundary.
-
-| Change | Source to start with | Relevant checks |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Plugin instructions | [Skills](plugins/codex-security/skills/) and shared [references](plugins/codex-security/references/) | [Portable plugin source checks](AGENTS.md#keep-it-simple) |
-| Artifact contracts and generated SDK models | [Contract definitions](plugins/codex-security/mcp-app/src/artifact-contracts.ts), [canonical exports](plugins/codex-security/mcp-app/scripts/canonical-schemas.mts), and [model generator](sdk/typescript/scripts/generate-models.cjs) | [Canonical contract tests](plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts), [MCP wire tests](plugins/codex-security/mcp-app/tests/test_compact_artifact_wire.ts), and the generation checks above |
-| Deep Scan scheduling and workers | Shared [engine, coordinator, and executor](plugins/codex-security/mcp-app/src/deep-scan/), used by the MCP server and SDK launcher | [MCP tests](plugins/codex-security/mcp-app/tests/) and [direct SDK integration](sdk/typescript/tests-ts/direct-deep-scan.test.ts) |
-| Durable scan state, checkpoints, and completion | [Python workbench](plugins/codex-security/scripts/workbench_db.py) and [Deep Scan persistence](plugins/codex-security/scripts/deep_scan_workbench.py) | [Python tests](plugins/codex-security/tests/) and [SDK workbench integration](sdk/typescript/tests-ts/deep-scan-workbench.test.ts) |
-| Helper routing and stored-finding operations | SDK [runtime routing](sdk/typescript/src/runtime.ts), plugin [helper entrypoint](plugins/codex-security/mcp-app/helpers-main.ts), and [Node workbench commands](plugins/codex-security/mcp-app/src/workbench/commands.ts) | [SDK runtime tests](sdk/typescript/tests-ts/runtime.test.ts) and [MCP workbench tests](plugins/codex-security/mcp-app/tests/) |
-| Public CLI and SDK behavior | [CLI adapter](sdk/typescript/src/cli.ts), [SDK API](sdk/typescript/src/api.ts), and adjacent modules | [SDK tests](sdk/typescript/tests-ts/) and the [installed-package checks](sdk/typescript/TESTING.md) |
-| Markdown report rendering | [Scan report projection](plugins/codex-security/scripts/report_projection.py) and [threat-model projection](plugins/codex-security/scripts/threat_model_projection.py) | [Report tests](plugins/codex-security/tests/test_report_projection.py) and [threat-model tests](plugins/codex-security/tests/test_threat_model_projection.py) |
-| Native filesystem and process operations | [Native bindings and adapters](plugins/codex-security/native/README.md) | The native guide's platform proofs and package checks |
-| Packaged plugin contents | [Plugin manifest](plugins/codex-security/plugin-files.json) and [SDK plugin builder](sdk/typescript/scripts/build-plugin.mjs) | [Package inspection and installed consumers](sdk/typescript/TESTING.md) |
-
-The SDK routes selected stored-finding and classification commands to the Node
-helper; scan lifecycle commands still use the Python workbench. Trace the
-specific command before changing either implementation. Shared Deep Scan
-behavior belongs in the plugin engine, with adapter changes in the MCP server
-or SDK only when their entrypoint behavior differs.
-
-Search [existing issues](https://github.com/openai/codex-security/issues)
-before opening a new one.
-
## Support for open-source projects
If you maintain an open-source project,
@@ -77,10 +69,7 @@ customer data, and security findings before posting.
## Suggest a feature or improve the documentation
Open an issue describing the problem and the workflow you want to support.
-Documentation corrections and safe examples are welcome.
-Use synthetic examples when documenting expected behavior.
-Keep example values fictional and safe to share.
-Do not include credentials or private information in examples.
+Use synthetic examples that contributors can reproduce and share publicly.
## Report a security issue
@@ -108,6 +97,16 @@ Use `platform:windows` only when Windows-specific behavior is material to the
change. Dependabot uses `dependencies` across all package ecosystems. Labels
are not required to open, test, review, or merge a pull request.
+## Testing plugin connectors
+
+For changes to [Jira intake or tracking](docs/plugin-connectors.md), use synthetic findings in a designated QA project.
+
+1. Verify the site, account and selected connection. Read a synthetic issue by key and through a project-scoped JQL search that spans more than one page.
+2. Track a finding through the Atlassian app. Create an issue, repeat the operation to verify reuse, then update the approved fields. Read the issue back after each write and check for duplicates.
+3. Try a missing connection and an account with insufficient access. Check that each failure explains how to recover and leaves the project without duplicate issues.
+
+Record live checks separately from static tests. Keep account and project details, issue keys and raw tool responses private. Report product vulnerabilities through [SECURITY.md](SECURITY.md).
+
## Investigate a CI failure
Open the `node-ci` run for the PR revision that failed. The `ci` job reports
diff --git a/README.md b/README.md
index a21c8913a..299487e78 100644
--- a/README.md
+++ b/README.md
@@ -29,10 +29,10 @@ then ask:
> Run a Codex Security scan on this repository, focusing on authentication and
> authorization. Return the saved report, source evidence, and coverage limits.
-A completed scan saves a report, findings, coverage, and a threat model when
-available. Use those results to investigate findings, request a patch, or verify
-an existing fix. See the [agent workflow guide](docs/agent-workflows.md) for plugin
-setup, task selection, and recovery when required tools are unavailable.
+A completed scan saves a report and findings. Read the report for source
+evidence and exclusions, then request a patch or ask Codex to verify an
+existing fix. See the [agent workflow guide](docs/agent-workflows.md) for setup,
+task selection, and recovery.
## Quick start
@@ -46,42 +46,24 @@ npm install --global @openai/codex-security
cs login
```
-`cs` is a short alias for `codex-security`; both commands run the same CLI.
-The installation creates both commands in npm's global executable directory,
-which must be on your `PATH`. If `cs` already resolves to another tool, use
-`codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
-`npx @openai/codex-security` without a global installation.
-
-Run your scan from the repository directory:
+Run your first scan from the repository directory:
```bash
cs scan .
```
-If you have Daybreak Blue access, add `--cyber-access-program daybreak_blue`
-to the scan command. Otherwise, omit the flag or use
-`--cyber-access-program standard`.
-
-To use Codex's Daybreak toggle, pass `--codex daybreak=true`. It defaults off
-and requires compatible access. See [Daybreak configuration](sdk/typescript/docs/cli.md#daybreak-opt-in)
-for SDK and plugin usage, including Deep Scan workers.
-
-Scans use your existing `SECURITY.md` guidance. You can optionally
-[draft or update a policy](#generate-securitymd) before scanning.
+When the scan completes, open the Markdown file at the **REPORT** path in the
+terminal. Run `cs scans show` from the same repository to find its latest
+completed scan again. See [scan scope and follow-up work](sdk/typescript/docs/cli.md#understand-scan-scope-and-follow-up-work)
+for how to interpret exclusions in the report.
-To run without a global installation, replace `cs` in these examples with
-`npx @openai/codex-security`, for example:
-
-```bash
-npx @openai/codex-security scan .
-```
+`cs` and `codex-security` run the same CLI. If the short name conflicts with
+another command, use `codex-security`. To skip the global install, or if npm
+reports an `EEXIST` conflict, use `npx @openai/codex-security` in place of
+`cs` for both login and scanning.
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, or [sign in over SSH](sdk/typescript/README.md#remote-login-with-ssh-forwarding).
-
-Some cybersecurity requests and protected findings require
-[Trusted Access for Cyber](https://chatgpt.com/cyber) approval.
+For a headless machine, see [device or SSH login](sdk/typescript/README.md#authentication).
### Scan options
@@ -110,9 +92,14 @@ For an application spread across repositories, see
Use [bulk scans](sdk/typescript/docs/cli.md#bulk-scans) for independent repository
reviews in one resumable campaign.
-After a scan, [inspect its scope and follow-up work](sdk/typescript/docs/cli.md#understand-scan-scope-and-follow-up-work)
-to understand recorded exclusions and decide whether to review the findings,
-run a focused scan, or recover an interrupted run.
+Scans use existing root and component `SECURITY.md` guidance. To write or
+revise it, see [Generate SECURITY.md](#generate-securitymd).
+
+Some cybersecurity requests and protected findings require
+[Trusted Access for Cyber](https://chatgpt.com/cyber). For accounts with Daybreak
+access, see [Daybreak opt-in](sdk/typescript/docs/cli.md#daybreak-opt-in) for the
+Codex toggle and [Cyber access programs](sdk/typescript/docs/cli.md#select-a-cyber-access-program)
+to select a program explicitly.
## TypeScript SDK
@@ -192,51 +179,20 @@ Vulnerability Response, see [Export findings for ServiceNow](sdk/typescript/docs
## GitHub Actions
-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 release that includes automatic Ubuntu sandbox setup.
-For older pins, including `action-v0.6.0`, keep the [manual sandbox setup](https://github.com/openai/codex-security/blob/action-v0.6.0/github-action/README.md#ubuntu-sandbox-setup).
-
-This workflow requests Daybreak Blue. Use an API key from a project with Blue
-enabled; without Daybreak access, omit `cyber-access-program` or set it to
-`standard`.
-
-```yaml
-name: Codex Security
-on:
- workflow_dispatch:
- schedule:
- - cron: "23 7 * * 1" # Mondays at 07:23 UTC
-
-permissions:
- contents: read
-
-jobs:
- security:
- runs-on: ubuntu-24.04
- steps:
- - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- with:
- persist-credentials: false
- - uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT
- with:
- model: gpt-5.6-sol
- effort: high
- cyber-access-program: daybreak_blue
- env:
- OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
-```
+To run a weekly repository scan on GitHub-hosted Ubuntu:
-The Action sets up and verifies the sandbox on GitHub-hosted Ubuntu 24.04 VMs.
-Self-hosted runners and job containers must provide a working Codex sandbox.
+1. Add an OpenAI API key as the repository secret `CODEX_SECURITY_API_KEY`.
+2. Copy the [weekly workflow](github-action/examples/repository.yml) to
+ `.github/workflows/codex-security.yml`. Replace `REPLACE_WITH_REVIEWED_COMMIT`
+ with the reviewed distribution commit SHA from an Action release.
+3. To try the workflow before the next scheduled run, open **Actions → Codex
+ Security repository → Run workflow**.
-Findings are report-only by default. Set a severity threshold to fail on reported
-findings at or above it. Scanner and required reporting errors fail the job;
-intentional file exclusions and investigation notes do not.
-See the [Action setup and input reference](github-action/README.md) for PR scans,
-severity thresholds, and report uploads.
+The example uses an estimated $5 limit per scan and reports findings without
+failing the job. Requests in progress can exceed the limit. For a severity
+threshold, pull request checks, or runner requirements, see the
+[Action guide](github-action/README.md). For eligible accounts, see
+[Daybreak access](github-action/README.md#daybreak-access-and-refusals).
## Containerized bulk scans
diff --git a/RELEASING.md b/RELEASING.md
index 5a8db1188..fc41cb3c4 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -12,6 +12,12 @@ exact CLI version. The npm release contains the package archive and canonical
changelog. The Action release contains its manifest and SBOM, links to that
changelog, and lists the full distribution commit SHA for consumers to pin.
+## Release checklist
+
+1. Review the [rolling release PR](#rolling-release-prs). Verify the version, edit the [highlights and migration steps](#editing-the-release-notes), and complete the [pre-merge checks](#prepare-a-release). Squash-merge the reviewed revision.
+2. Wait for CI on the merged commit and the release verification jobs. Approve the **npm** deployment for the [package and container release](#publish). Follow the progress comment on the merged PR through the installation checks and applicable Action and container jobs.
+3. If the release includes the Action, [publish its companion release to Marketplace](#publish-to-github-marketplace). [Verify the public artifacts](#verify) before announcing the version. For a partial publication, use the [recovery procedure](#recover-or-repair-a-release) with the original tag.
+
## Pull request titles and categories
Pull request titles must follow this form:
@@ -82,9 +88,6 @@ zero. For example, changes after `0.1.23` propose `0.1.24`, or `0.2.0` if any
included change is breaking. The category of a feature remains **Features**;
the category does not imply a minor version bump.
-[Release 0.8.3](https://github.com/openai/codex-security/pull/2144) uses a patch
-version as a one-time exception. Its upgrade notes list the compatibility changes.
-
The release PR updater recognizes breaking changes from a `!` in a
Conventional Commit title, a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer,
or the `breaking-change` label. `skip-release-notes` affects visibility, not
@@ -165,9 +168,7 @@ additional changes, then rerun the updater to resume.
### Editing the release notes
The committed `.github/release-notes.md` is authoritative. The updater
-drafts highlights from merged titles and lists marked breaking changes for
-migration review; it does not infer migration instructions from source code.
-Review and refine these suggestions before releasing.
+collects candidate highlights from merged titles in a disclosure and puts marked breaking changes in a separate draft section. Before merging, select the changes users will notice. Replace each breaking title with the affected audience, previous behavior and required action. Link to the versioned procedure when the migration needs several steps.
Keep the published notes easy to scan:
diff --git a/SECURITY.md b/SECURITY.md
index 0a5e4777c..26260090e 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -14,14 +14,13 @@ configuration. Examples include bypassing a filesystem or network restriction,
a required approval, or an administrator-enforced control.
Prompt injection or a model misusing access it already has does not qualify
-by itself, even if it leaks data or performs an unwanted action. A report must
-identify a separate flaw in an enforced security control. Model-behavior
+by itself, even if it leaks data or performs an unwanted action. Model-behavior
reports may qualify under the separate
[Safety Bug Bounty](https://bugcrowd.com/engagements/openai-safety).
Missed findings, false positives, incorrect scan results, and performance issues
are ordinary bugs unless they also demonstrate such a flaw. Report ordinary
-bugs through GitHub issues.
+bugs through [GitHub issues](https://github.com/openai/codex-security/issues) with a synthetic example that can be shared publicly.
## Scan permissions
diff --git a/action.yml b/action.yml
index a794f4680..c68c0adac 100644
--- a/action.yml
+++ b/action.yml
@@ -18,7 +18,7 @@ inputs:
description: 'standard or deep. Deep supports repository scans, including selected paths; not diff scans.'
default: standard
provider:
- description: "Inference provider, matching scan --provider: openai, openrouter, fireworks, or amazon-bedrock. Supply the selected provider's credentials to the step."
+ description: "Providers supported by the Action: openai, openrouter, fireworks, or amazon-bedrock. Pass the selected provider's credentials to the scan step."
default: openai
model:
description: Model to scan with, passed to scan --model. Defaults to gpt-5.6-sol for OpenAI; other providers require an explicit model ID. Cost limits require CLI pricing support for the model.
diff --git a/docker/README.md b/docker/README.md
index 8c99ddad2..8196b37a0 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -12,6 +12,11 @@ scanner CLI and use the runner's local SQLite database for saved-scan deduplicat
Version tags are immutable. Only the newest stable Debian release gets `latest`.
+- [Run the scanner with Compose](#workflow-runner) to scan a checkout and keep its results.
+- [Verify a Debian image](#image-metadata-and-verification) before deploying it.
+- To publish images, [prepare GHCR](#ghcr-administrator-setup), then follow the
+ [release and backfill procedure](#publishing). Wolfi also supports [OS-only updates](wolfi/README.md#wolfi-only-os-updates).
+
## Image metadata and verification
Debian release images include OCI metadata in each platform's image labels and in the
@@ -57,91 +62,20 @@ scan data, and credentials out of them. BuildKit's maximum-mode provenance
includes build arguments, so pass build credentials through secret mounts rather
than build arguments.
-## GHCR administrator setup
-
-Before the first release, an administrator must prepare the package:
-
-Prepare the [universal native payload](../plugins/codex-security/native/README.md#package-inputs) before building an image from source.
-
-1. Allow organization package creation and, if the package is missing, bootstrap
- it with a reviewed image and a non-release tag:
-
- ```bash
- docker build --target scanner -t ghcr.io/openai/codex-security:bootstrap .
- printf '%s' "$CR_PAT" | docker login ghcr.io --username YOUR_GITHUB_USER --password-stdin
- docker push ghcr.io/openai/codex-security:bootstrap
- docker logout ghcr.io
- ```
-
- Use a personal access token (classic) with `write:packages`, authorized for SSO
- if required; never commit it or pass it into the build.
-
-2. In the package's settings, link `openai/codex-security`, set visibility to
- **Public**, and grant the repository **Write** under **Manage Actions access**.
- The workflow uses `GITHUB_TOKEN` and refuses missing, private, or unreadable
- packages. Verify `docker pull` works after logging out of GHCR.
-3. Configure the protected `npm` environment with release reviewers authorized
- for both npm and GHCR and limit it to `npm-v*` tags. For image backfills
- and standalone Wolfi OS updates, protect the `container` environment with
- required reviewers and deployment rules for `main` and approved `container-v*` tags.
- Allow the workflow's pinned actions, package writes, and OIDC attestations.
- Update branch-protection check names if they reference the old release jobs.
-
-See GitHub's [registry authentication](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
-and [package access settings](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).
-
-## Publishing
-
-After verifying the published npm tarball and installation, `node-github-release`
-publishes the matching Action. Its immutable `action-vX.Y.Z` tag preserves the
-runtime lock for future backfills. The workflow passes the verified archive and
-lock to `container-publish`. Debian builds on amd64 and arm64 and Wolfi builds
-on amd64, both using recipes from the scanner release commit. Approving
-**Publish npm and container images** in the `npm` environment authorizes both
-images for that release. Publication uses the tested digests, verifies
-anonymous pulls, and attests the images before promoting their version tags.
-Debian carries BuildKit SBOMs and maximum-mode provenance. Wolfi carries build
-provenance and an SPDX inventory of its OS packages, installed npm packages,
-and native components.
-
-To backfill a release, dispatch `node-github-release` on protected `main` with
-the original `npm-vX.Y.Z` tag. A manual `container-release` run on `main`
-requests the coordinated release for the current package version. Pushing a
-`container-vX.Y.Z` tag runs the container workflow at the tagged commit.
-The release source determines which images are required.
-Sources from 0.5.0 onward with a Dockerfile but predating coordinated Wolfi
-builds use the original Debian release path. Earlier releases skip image
-publication. A default backfill uses the scanner release commit's recipes.
-If the Wolfi build needs updated OS pins, dispatch `node-github-release` with
-`refresh-wolfi-recipe=true` to use the recipe from protected `main` with the
-original scanner tarball and runtime lock. Review and approve the `container`
-deployment when publishing with a different recipe commit or recovering
-images for a release whose approval covered only npm. A backfill that
-verifies all existing tags finishes without a deployment approval.
-
-Promotion updates tags separately. If publication stops partway through, rerun
-the failed jobs to reuse the retained artifacts. The publisher verifies existing
-version tags and refuses to replace a different digest. The `release status`
-summary lists both digests when the coordinated release finishes. For a Wolfi
-OS update between scanner releases, see [Wolfi-only OS updates](wolfi/README.md#wolfi-only-os-updates).
-The `bootstrap` and `release-candidate-<commit>` tags are for registry setup
-and release validation.
-
## Workflow runner
-`compose.runner.yaml` runs the packaged CLI from the **scanner** image. It does
-not start a findings service or implement another workflow engine. It passes
-commands, output, and exit codes through the existing scanner entrypoint.
+[`compose.runner.yaml`](../compose.runner.yaml) runs the packaged CLI and returns
+its output and exit code. Keep the results and state directories between runs
+to look up saved scans and deduplicate findings.
Run these commands from the repository root after
[verifying an image](#image-metadata-and-verification). Keep the verified
-`reference` in the same shell. Prepare the output and state directories, keep
-state private, and choose the host user's UID/GID so the runner can write its
-bind mounts:
+`reference` in the same shell. Create private output and state directories,
+then choose the host user's UID/GID so the runner can write its bind mounts:
```bash
mkdir -p results state
-chmod 700 state
+chmod 700 results state
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
export CODEX_SECURITY_IMAGE="$reference"
docker compose -f compose.runner.yaml pull
@@ -154,7 +88,7 @@ disabled, skip that command and export `OPENAI_API_KEY` or `CODEX_API_KEY` in
your host shell. Compose passes the key to the runner. Use API keys for
unattended runs too.
-Git authentication uses the existing `GH_TOKEN`/`GITHUB_TOKEN` and optional
+Git authentication uses `GH_TOKEN`/`GITHUB_TOKEN` and optional
`CODEX_SECURITY_GIT_HOST` settings. Pass only the credentials the runner needs.
Use a version or digest in `CODEX_SECURITY_IMAGE` for repeatable deployments.
To test an unreleased checkout, build the same scanner target locally instead
@@ -168,7 +102,7 @@ export CODEX_SECURITY_IMAGE=codex-security:local
To build the Linux amd64 Wolfi image locally, see the
[melange and apko recipe](wolfi/README.md).
-The existing `CODEX_SECURITY_RESULTS` and `CODEX_SECURITY_STATE` settings select
+`CODEX_SECURITY_RESULTS` and `CODEX_SECURITY_STATE` settings select
the host directories (default `./results` and `./state`):
| Container path | Durable contents |
@@ -204,29 +138,23 @@ docker compose -f compose.runner.yaml run --rm codex-security \
dedupe --scan SCAN_ID --json
```
-For an independently operated compatible endpoint, pass its reachable base URL
-through `--findings-url`. Container loopback addresses refer to the runner, not
-the Docker host or another container. See the
-[findings guide](../sdk/typescript/docs/findings-service.md) for custom publication,
-remote deduplication, and the removed local service's compatibility changes.
+For a compatible endpoint you operate, pass a base URL the container can reach
+through `--findings-url`. Loopback addresses refer to the runner itself.
+See the [findings guide](../sdk/typescript/docs/findings-service.md) for remote
+deduplication and publication.
-Only commands supported by the selected image are available. Workflow resumption,
-custom publication, and dedupe write-back require a release containing those
-SDK/CLI capabilities; durable mounts alone do not add them. The runner does not
-schedule, retry, or skip stages on its own.
+Run `docker compose -f compose.runner.yaml run --rm codex-security --help` to
+see which commands your image supports. Your CI system controls stage order
+and retries.
### Sandbox and lifecycle
-The runner retains the scanner's nonroot user, dropped capabilities,
-no-new-privileges, and seccomp profile. It does not override Codex approval or
-filesystem settings. On hosts that restrict nested user namespaces, install the
-existing [AppArmor profile](../sdk/typescript/README.md#containerized-bulk-scans)
-and append `-f compose.apparmor.yaml` to the runner Compose commands. This override
-works because both examples use the `codex-security` service name. Codex 0.156.1
-requires Bubblewrap for filesystem-restricted execution; the legacy Landlock
-fallback is no longer supported. The entrypoint preserves Codex sandbox settings.
-Source inspection needs a host that supports Bubblewrap; do not disable sandboxing
-to work around host restrictions.
+The runner starts with a nonroot user, dropped capabilities,
+no-new-privileges, and the project's seccomp profile. On hosts that restrict
+nested user namespaces, install the [AppArmor profile](../sdk/typescript/README.md#containerized-bulk-scans)
+and add `-f compose.apparmor.yaml` after `-f compose.runner.yaml` in the
+Compose commands. Both files configure the `codex-security` service. Source inspection requires a host that supports
+Bubblewrap and permits its user namespaces.
The bundled Compose seccomp profile allows direct socket calls for Unix sockets,
IPv4, IPv6, and the route netlink sockets Bubblewrap uses to configure loopback.
@@ -243,3 +171,73 @@ for later stages and retries; use the same image version and source paths.
Stop active runners before backing up the entire results and state directories,
and keep backups separately. No service ports or Docker socket are exposed by
the runner example.
+
+## GHCR administrator setup
+
+Before bootstrapping a package with a source build, prepare the
+[universal native payload](../plugins/codex-security/native/README.md#package-inputs).
+An organization administrator can then configure GHCR for the first release.
+
+1. Allow organization package creation and, if the package is missing, bootstrap
+ it with a reviewed image and a non-release tag:
+
+ ```bash
+ docker build --target scanner -t ghcr.io/openai/codex-security:bootstrap .
+ printf '%s' "$CR_PAT" | docker login ghcr.io --username YOUR_GITHUB_USER --password-stdin
+ docker push ghcr.io/openai/codex-security:bootstrap
+ docker logout ghcr.io
+ ```
+
+ Use a personal access token (classic) with `write:packages`, authorized for SSO
+ if required; never commit it or pass it into the build.
+
+2. In the package's settings, link `openai/codex-security`, set visibility to
+ **Public**, and grant the repository **Write** under **Manage Actions access**.
+ The workflow uses `GITHUB_TOKEN` and refuses missing, private, or unreadable
+ packages. Verify `docker pull` works after logging out of GHCR.
+3. Configure the protected `npm` environment with release reviewers authorized
+ for both npm and GHCR and limit it to `npm-v*` tags. For image backfills
+ and standalone Wolfi OS updates, protect the `container` environment with
+ required reviewers and deployment rules for `main` and approved `container-v*` tags.
+ Allow the workflow's pinned actions, package writes, and OIDC attestations.
+ Use the release workflow’s job names for any required branch-protection checks.
+
+See GitHub's [registry authentication](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
+and [package access settings](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).
+
+## Publishing
+
+After verifying the published npm tarball and installation, `node-github-release`
+publishes the matching Action. Its immutable `action-vX.Y.Z` tag preserves the
+runtime lock for future backfills. The workflow passes the verified archive and
+lock to `container-publish`. Debian builds on amd64 and arm64 and Wolfi builds
+on amd64, both using recipes from the scanner release commit. Approving
+**Publish npm and container images** in the `npm` environment authorizes both
+images for that release. Publication uses the tested digests, verifies
+anonymous pulls, and attests the images before promoting their version tags.
+Debian carries BuildKit SBOMs and maximum-mode provenance. Wolfi carries build
+provenance and an SPDX inventory of its OS packages, installed npm packages,
+and native components.
+
+To backfill a release, dispatch `node-github-release` on protected `main` with
+the original `npm-vX.Y.Z` tag. A manual `container-release` run on `main`
+requests the coordinated release for the current package version. Pushing a
+`container-vX.Y.Z` tag runs the container workflow at the tagged commit.
+The release source determines which images are required.
+Sources from 0.5.0 onward with a Dockerfile but predating coordinated Wolfi
+builds use the original Debian release path. Earlier releases skip image
+publication. A default backfill uses the scanner release commit's recipes.
+If the Wolfi build needs updated OS pins, dispatch `node-github-release` with
+`refresh-wolfi-recipe=true` to use the recipe from protected `main` with the
+original scanner tarball and runtime lock. Review and approve the `container`
+deployment when publishing with a different recipe commit or recovering
+images for a release whose approval covered only npm. A backfill that
+verifies all existing tags finishes without a deployment approval.
+
+Promotion updates tags separately. If publication stops partway through, rerun
+the failed jobs to reuse the retained artifacts. The publisher verifies existing
+version tags and refuses to replace a different digest. The `release status`
+summary lists both digests when the coordinated release finishes. For a Wolfi
+OS update between scanner releases, see [Wolfi-only OS updates](wolfi/README.md#wolfi-only-os-updates).
+The `bootstrap` and `release-candidate-<commit>` tags are for registry setup
+and release validation.
diff --git a/docker/wolfi/README.md b/docker/wolfi/README.md
index a007a443d..3060180e5 100644
--- a/docker/wolfi/README.md
+++ b/docker/wolfi/README.md
@@ -5,14 +5,21 @@ Each new scanner release includes a Linux amd64 Wolfi image.
[apko](https://github.com/chainguard-dev/apko) assembles it
with packages from the [public Wolfi repository](https://github.com/wolfi-dev/os).
The image uses the same entrypoint, UID/GID 10001, and `/input`, `/output`, and
-`/state` directories as the [Debian image](../README.md). The local build below
-uses the scanner version pinned in [payload/package.json](payload/package.json).
+`/state` directories as the Debian image.
+
+To run a published version on amd64, select the Wolfi digest for your scanner
+version in the container release summary. Use
+`ghcr.io/openai/codex-security@sha256:…` with that digest as the image
+`reference` in the [Compose runner](../README.md#workflow-runner).
+To test a local change, [build the image](#build-and-inspect), then
+[run the offline smoke test](#run-the-offline-smoke-test).
## Build and inspect
-Use a Linux amd64 builder with user namespaces and Bubblewrap, apko 1.4.13,
-melange 0.61.1, Python 3.9 or later, Node.js with npm 11, OpenSSL,
-and Docker for runtime testing. From the repository root:
+The local build uses the scanner version in [payload/package.json](payload/package.json).
+Use a Linux amd64 builder with user namespaces, Bubblewrap, OpenSSL, and the
+tool versions listed by [`build.sh --help`](build.sh). Runtime tests also
+require Docker. Run these commands from the repository root:
```sh
docker/wolfi/build.sh /tmp/codex-security-wolfi
@@ -35,17 +42,6 @@ Each run generates a local signing key, adds its public half to the APK keyring,
and removes the private key at exit. The key identifies that build; it is not
an upstream release signature. A new key changes the APK and image digests.
-To test that the melange guest can be built without access to Wolfi, run a
-build with the [offline melange wrapper](tests/offline-melange.sh) on a Linux
-builder that permits `unshare --net`:
-
-```sh
-MELANGE="$PWD/docker/wolfi/tests/offline-melange.sh" docker/wolfi/build.sh /tmp/codex-security-offline-guest
-```
-
-The wrapper disconnects melange before it installs the guest packages. Staging
-the inputs and resolving the runtime lock still need the network.
-
## Run the offline smoke test
On a native Linux amd64 Docker host with AppArmor and user namespaces, load
@@ -59,13 +55,27 @@ docker/wolfi/tests/smoke.sh codex-security:wolfi-amd64
sudo apparmor_parser --skip-cache --remove docker/codex-security.apparmor
```
-The test uses the repository's seccomp profile with a read-only root filesystem,
-no capabilities, and no external network. It exercises the CLI, the native plugin,
+A successful smoke test exits with status 0. It uses the repository's seccomp
+profile with a read-only root filesystem, no capabilities, and no external
+network. It exercises the CLI, the native plugin,
artifact and SARIF output, saved history, and a model turn against a loopback
fixture. It also checks that a sandboxed child can read the test repository but
cannot modify it. A real scan needs a compatible model endpoint; the image
does not include a model.
+### Test an offline melange build
+
+To test that the melange guest can be built without access to Wolfi, run a
+build with the [offline melange wrapper](tests/offline-melange.sh) on a Linux
+builder that permits `unshare --net`:
+
+```sh
+MELANGE="$PWD/docker/wolfi/tests/offline-melange.sh" docker/wolfi/build.sh /tmp/codex-security-offline-guest
+```
+
+The wrapper disconnects melange before it installs the guest packages. Staging
+the inputs and resolving the runtime lock still need the network.
+
## Publish the amd64 variant
For a scanner release, `container-publish` supplies the same verified npm tarball
diff --git a/docs/agent-workflows.md b/docs/agent-workflows.md
index 3878e35b0..892132a9e 100644
--- a/docs/agent-workflows.md
+++ b/docs/agent-workflows.md
@@ -28,6 +28,32 @@ Codex plugin session.
## Choose a task
+| Task | In Codex | From the terminal |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Scan a repository or selected paths | Ask for a [Standard scan](../plugins/codex-security/skills/security-scan/SKILL.md) (`$security-scan`). | `cs scan .` or `cs scan . --path src` |
+| Review a PR, commit, branch diff, or working-tree patch | Ask for [`$security-diff-scan`](../plugins/codex-security/skills/security-diff-scan/SKILL.md) with the change to review. | `cs scan . --diff origin/main` for committed changes, or `cs scan . --working-tree` for local changes. |
+| Run repeated audits of the same target | Ask for [`$deep-security-scan`](../plugins/codex-security/skills/deep-security-scan/SKILL.md). Later audits use findings from earlier ones. | `cs scan . --mode deep` |
+| Assess supplied findings against the source | [`$triage-finding`](../plugins/codex-security/skills/triage-finding/SKILL.md) returns a verdict and any missing evidence for each claim. | `cs validate findings.json` returns a [validation report](../sdk/typescript/docs/cli.md#validate-and-patch-findings). |
+| Investigate a dependency alert | Give [`$resolve-dependency-alert`](../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md) the alert and the checkout or image. It traces the dependency and proposes an upgrade or dismissal where the evidence supports one. | To retrieve a saved alert for that review, see below. |
+| Prepare a fix | Ask [`$fix-finding`](../plugins/codex-security/skills/fix-finding/SKILL.md) to patch a specific finding in the affected repository. | [`cs patch --scan SCAN_ID`](../sdk/typescript/docs/cli.md#patch-existing-findings) |
+| Check an existing fix | Give [`$verify-fix`](../plugins/codex-security/skills/verify-fix/SKILL.md) the finding and current checkout. | [`cs verify-fix --scan SCAN_ID`](../sdk/typescript/docs/cli.md#verify-fixes) |
+| Track a validated finding | Give [`$track-findings`](../plugins/codex-security/skills/track-findings/SKILL.md) the finding and destination. See [plugin connectors](plugin-connectors.md). | For completed scans, see [publishing to Linear](../sdk/typescript/docs/cli.md#publish-completed-scans-to-linear). |
+| Inspect a downloaded skill | [Review the skill before installation](#review-a-skill-before-installation) in a trusted Codex chat. | Use the interactive Codex CLI with the plugin enabled. |
+
+**Read a saved dependency alert.** With `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`,
+run `cs findings imported ./project --format json` to list the repository's
+imported records. Give the relevant record to `$resolve-dependency-alert` when
+you want Codex to check the installed versions and upgrade options.
+
+A scan or triage request produces findings. Ask to fix a specific finding when
+you want a patch. A separate fix verification reports `fixed`,
+`still_vulnerable`, or `inconclusive` with evidence.
+
+Existing root and component `SECURITY.md` files already guide scans. Use
+[policy generation](../README.md#generate-securitymd) to draft or update one.
+
+### Review a skill before installation
+
To review a skill before giving it to a coding agent, ask
[`$check-skills`](../plugins/codex-security/skills/check-skills/SKILL.md) directly:
@@ -45,36 +71,17 @@ or **INCOMPLETE** with source evidence and coverage limits. A file review covers
only that file. Supply the folder to include helpers and references. The review
does not install the target or require the plugin MCP server.
-| Task | In Codex | From the terminal |
-| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Find vulnerabilities in a repository or selected paths | [`$security-scan`](../plugins/codex-security/skills/security-scan/SKILL.md): one Standard audit. | `cs scan .`, optionally `--path src`. |
-| Review a PR, commit, branch diff, or working-tree patch | [`$security-diff-scan`](../plugins/codex-security/skills/security-diff-scan/SKILL.md): review changes and trace their supporting code. | `cs scan . --diff origin/main` for committed changes, or `cs scan . --working-tree` for local changes. |
-| Investigate a repository or paths deeply | [`$deep-security-scan`](../plugins/codex-security/skills/deep-security-scan/SKILL.md): later batches use findings from earlier audits. | `cs scan . --mode deep`. |
-| Triage supplied reports or claims | [`$triage-finding`](../plugins/codex-security/skills/triage-finding/SKILL.md): one static-evidence verdict per finding, with proof gaps. | `cs validate findings.json` also assesses supplied claims using static evidence; its output contract differs from plugin triage. See [validation](../sdk/typescript/docs/cli.md#validate-and-patch-findings). |
-| Resolve a vulnerable dependency | [`$resolve-dependency-alert`](../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md) traces affected versions and prepares an upgrade or dismissal proposal. | With external imports enabled, read saved alerts with `cs findings imported ./project --format json`. |
-| Fix a security finding | Explicitly request [`$fix-finding`](../plugins/codex-security/skills/fix-finding/SKILL.md) with the finding and affected repository. | `cs patch --scan SCAN_ID`; see [patching](../sdk/typescript/docs/cli.md#patch-existing-findings) for individual findings and options. |
-| Check an existing security fix | Explicitly request [`$verify-fix`](../plugins/codex-security/skills/verify-fix/SKILL.md) with the original finding and current checkout. Verification leaves repository files unchanged. | `cs verify-fix --scan SCAN_ID`; see [fix verification](../sdk/typescript/docs/cli.md#verify-fixes). |
-
-A scan or triage request does not request a code change. Ask to fix a specific
-finding when you want a patch. Standalone fix verification is a separate request
-and reports `fixed`, `still_vulnerable`, or `inconclusive` with evidence.
-
-Policy generation is optional. Existing root and component `SECURITY.md` files
-already guide scans. Use [policy generation](../README.md#generate-securitymd)
-when that guidance needs to be drafted or updated.
-
## Read the result
-For a completed scan, start with the generated report and its saved findings,
-coverage, and threat model when present. Use the completion summary to locate the
-saved results. Use source locations and validation evidence to assess a finding;
-review coverage for assessed surfaces, exclusions, deferred candidates,
-and remaining questions.
+Open the report at the path in the completion summary. Read the source
+locations and validation evidence for each finding. Check the
+`scan.review.excludedPaths` list in `scan-manifest.json` for additional
+exclusions. To find the files selected for discovery, [check the retained
+scope list](#check-a-revision-range-scan-for-missing-files).
-A completed scan can retain unresolved questions. No reported findings does not
-establish that every path was reviewed or that the repository is secure. Static
-triage establishes what the source supports; it does not claim runtime testing.
-An inconclusive fix verification identifies the evidence still needed.
+A report with zero findings can still list exclusions or unresolved questions.
+Static triage reports what the source supports. An inconclusive fix verification
+identifies what evidence would resolve the question.
For automation, scan exit codes distinguish these outcomes:
@@ -98,6 +105,8 @@ the merge base and can show different files when the commits have diverged.
Current diff scans select regular text files regardless of extension. Git can
also list changes to binary files, symlinks, and submodules.
+#### Missing Perl files with plugin 0.1.32
+
Plugin 0.1.32 could omit changed Perl files (`.cgi`, `.pl`, `.pm`, and `.t`).
CLI 0.3.0 was the first release to bundle the fix. To repeat the scan with
that version or later, use a clean, full checkout at the original head.
@@ -127,16 +136,20 @@ cs scan --help
Use [the CLI reference](../sdk/typescript/docs/cli.md#command-discovery-and-integrations)
for integrations and output formats.
+## Troubleshoot setup
+
+| Symptom | Next step |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cs` is missing or opens another program | Check that npm’s executable directory is on `PATH`, or use `codex-security` or `npx @openai/codex-security`. See [CLI setup](../README.md#quick-start). |
+| Codex shows CLI guidance but no security workflow skills | Install and enable the full plugin in your host, then start a new chat. |
+| A skill is visible but its scan tools are unavailable | Check the plugin server’s setup error and resolve it before starting a scan. |
+| Authentication fails on a headless machine | Use [device or SSH login](../sdk/typescript/docs/cli.md#authentication), or configured API credentials for CI. |
+
## Recover an interrupted task
-| Symptom | Next step |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cs` is missing or resolves to another program | Check the npm executable directory on `PATH`, or use `codex-security` or `npx @openai/codex-security`. See [CLI setup](../README.md#quick-start). |
-| The session has CLI guidance but no security workflow skills | Install and enable the full plugin through your host when available, then start a new chat. `skills add` and `mcp add` do not install it. |
-| A skill is visible but required scan tools are unavailable | Resolve the plugin server/setup error before starting the scan. Preserve any existing scan identity and report the blocker. A skill alone does not establish working tools or a completed scan. |
-| Authentication fails on a headless machine | Use the documented [device or SSH login](../sdk/typescript/docs/cli.md#authentication), or configured API credentials for CI. |
-| A Deep Scan stops waiting in chat | Keep the existing scan ID. Ending a turn or detaching a waiter does not cancel the durable scan; ask Codex to continue that same scan. |
-| A scan fails or completion reports an error | Preserve its ID, output directory, and exact error. Inspect that run before choosing recovery; retained artifacts do not imply successful completion. |
+If Codex stops waiting for a Deep Scan in chat, ask it to continue the same
+scan ID. The scan can keep running after the turn ends. If a scan reports an
+error, keep its ID, output directory, and error message.
For terminal scans, inspect an explicit ID so history commands refer to the same
run:
diff --git a/docs/bedrock.md b/docs/bedrock.md
index d94a36708..57432c90e 100644
--- a/docs/bedrock.md
+++ b/docs/bedrock.md
@@ -1,10 +1,11 @@
# Amazon Bedrock setup and verification
-Codex Security uses Codex's native `amazon-bedrock` provider. Install
-`@openai/codex-security` normally; it includes the Codex executable and security
-plugin. No customer connector or API adapter is needed. Use the current release;
-version `0.1.27` and later includes the Bedrock reasoning-summary default and its
-propagation to Deep Scan workers.
+Codex Security's bundled Codex executable uses the `amazon-bedrock` provider.
+Choose an AWS identity, region, and Bedrock model ID the identity can invoke.
+For CI with short-lived credentials, use the
+[GitHub Action](../github-action/README.md#scan-with-amazon-bedrock),
+[direct CLI workflow for GitHub Actions](../examples/github-actions/README.md), or
+[Azure Pipeline](../examples/azure-pipelines/README.md).
## Select AWS credentials and a model
@@ -14,13 +15,16 @@ an existing AWS profile:
```bash
export AWS_PROFILE="security-scan"
export AWS_REGION="us-east-2"
+model="<your-bedrock-model-id>"
npx @openai/codex-security scan /path/to/repository \
- --provider amazon-bedrock --model openai.gpt-5.6-luna
+ --provider amazon-bedrock --model "$model"
```
-Choose the region and exact Bedrock model ID your AWS identity can invoke. The
-example region and model do not grant access. Do not reuse an OpenAI API model
-name unless it is also the Bedrock model ID.
+Replace the profile, region, model ID, and repository path with your own. This
+scan makes billable model requests. To inspect the local scan configuration
+first, add `--dry-run`. Only an inference call verifies that the AWS identity
+can invoke the model. For an access-denied response, check the identity,
+region, and permission to invoke that exact model.
Alternatively, use `AWS_BEARER_TOKEN_BEDROCK`, or export the credentials supplied
by your AWS credential workflow:
@@ -32,31 +36,19 @@ export AWS_SESSION_TOKEN="<temporary-session-token>"
export AWS_REGION="us-east-2"
```
-Temporary AWS credentials need the session token as well as the access key pair.
-Web identity, container credentials, and the default AWS credential chain are
-also supported. Avoid competing credential environment variables when selecting
-a profile. Exporting credentials in another terminal or child process does not
-configure an already-running shell. No AWS CLI installation is required by
-Codex Security itself.
-
-Once model access is provisioned, native Bedrock scanning uses AWS credentials
-without a separate `codex-security login` or OpenAI API key. Restricted models
-still require their approval and provisioning steps; see Daybreak Blue and Red below.
-Local Markdown/JSON reports, `scans show`, and `export` also
-need no cloud login. [Publishing to Cloud](../sdk/typescript/README.md#publish-findings-to-cloud)
-requires separate ChatGPT credentials and access to that destination.
-
-`info` and `scan --dry-run` check local state, not AWS authentication or model
-availability. A successful preflight is not a successful Bedrock invocation.
-Model-metadata and OpenAI access advisories are distinct from AWS authorization:
-check the actual inference response before concluding that access works or fails.
-For authentication or access-denied responses, check the chosen AWS identity,
-region, and permissions for that exact model.
-
-Model metadata comes from the bundled Codex executable. If it reports missing
-metadata, record that Codex version from `info --json`. An upstream metadata fix
-reaches installed users when a Codex Security release bundles the corrected
-Codex dependency; a successful inference alone does not verify all model metadata.
+When using temporary credentials, include the session token. Other options
+include web identity, container credentials, and the default AWS credential
+chain. When using a named profile, clear environment credentials for other
+identities from the scan process.
+
+Bedrock uses AWS credentials for inference. [Daybreak Blue and Red](#daybreak-blue-and-red)
+require separate approval and provisioning. Saved reports, `scans show`, and
+`export` are local. [Publishing to Cloud](../sdk/typescript/README.md#publish-findings-to-cloud)
+requires ChatGPT credentials and access to the destination.
+
+If Codex reports missing model metadata, record the bundled Codex version from
+`info --json`. The metadata comes from the executable shipped with the package.
+An AWS inference request can succeed even when the bundled metadata is incomplete.
Bedrock defaults `model_reasoning_summary` to `none` because some models reject
`reasoning.summary`. This setting reaches Deep Scan discovery workers,
@@ -66,6 +58,32 @@ override takes precedence over the default and does not change reasoning effort.
See [native configuration overrides](../sdk/typescript/docs/cli.md#runtime-configuration-and-worker-limits)
for the `--codex KEY=VALUE` syntax.
+## Check the sandbox on an Ubuntu CI runner
+
+The direct CLI workflows for GitHub and Azure need Bubblewrap and permission
+to create user namespaces. On Ubuntu 24.04, check the runner before assuming
+the AWS role. Run this command as the same user that will run the scan:
+
+```bash
+bwrap --unshare-user --unshare-net --ro-bind / / --dev /dev --proc /proc -- /usr/bin/true
+```
+
+A successful check exits with status 0. If `bwrap` is missing or creating a
+namespace fails on a hosted Ubuntu VM, add these commands to a trusted setup
+step before checkout, then rerun the check:
+
+```bash
+sudo apt-get update
+sudo apt-get install --yes bubblewrap apparmor-profiles
+sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict
+```
+
+On a self-hosted agent, have its administrator configure the sandbox in the
+runner image. A sandbox startup error points to the runner. A Bedrock
+access-denied response points to the AWS identity or its model permissions.
+The [GitHub Action](../github-action/README.md#ubuntu-sandbox-setup) includes its
+own Codex sandbox check and conditional setup on supported GitHub-hosted VMs.
+
## Daybreak Blue and Red
Use the exact Bedrock identifier for the model your account can invoke:
@@ -99,21 +117,20 @@ npx @openai/codex-security scan /path/to/repository \
--provider amazon-bedrock --model openai.gpt-5.6-cyber --effort high
```
-Neither command needs an additional OpenAI CLI sign-in after AWS model access
-is provisioned. The Bedrock reasoning-summary default remains `none` for both.
-
Cost estimates and `--max-cost` recognize both exact Bedrock IDs using their
AWS model cards' Standard commercial in-region rates, including the AWS fee.
Blue reports a short/long-context range because aggregate usage does not identify
each request's context tier. Red's card lists a 272K context window and only
short-context pricing, so its upper estimate remains unavailable. Spending limits
-use the short-context baseline; they do not guarantee the final AWS bill. Pricing
-for other Bedrock model IDs is unchanged.
+use the short-context baseline. AWS bills the actual usage.
+
+<a id="repeatable-live-smoke-test"></a>
-## Repeatable live smoke test
+## Maintainers: verify a Bedrock release
-This optional maintainer check makes real, billable Bedrock requests against a
-small synthetic repository. Use an installed, pinned package version or a built
+Run this check to verify Standard and Deep scans, worker settings, and local
+export for a release. It makes billable Bedrock requests against a synthetic
+repository. Use an installed, pinned package version or a built
package under test, with its bundled executable and plugin. Record `--version`
and `info --json`; avoid a `CODEX_CLI_PATH` or `--plugin-path` override when testing
the published package.
@@ -122,8 +139,7 @@ The following POSIX-shell recipe uses an existing profile. Keep these variables
in the same shell for all steps. Replace the executable path and profile with
your test installation and authorized identity. The model below tests Daybreak
Blue after access is granted. Set `model="openai.gpt-5.6-cyber"` for an approved
-Red test, or use `openai.gpt-5.6-luna` for a general Bedrock test if that is the
-model your account can invoke:
+Red test, or use the model ID your account can invoke for a general Bedrock test:
```bash
cli="/absolute/path/to/node_modules/.bin/codex-security"
diff --git a/docs/ci.md b/docs/ci.md
index 8b50da8c4..01e79d013 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,80 +1,25 @@
-# Continuous integration
-
-The `node-ci` workflow selects checks from the complete pull request diff. An
-ordinary documentation-only change runs static checks and the final `ci` gate.
-Static checks format the tracked Markdown in this route. The Action README also
-runs Action CI to check generated input documentation and usage examples.
-Plugin skills, references, schemas, examples, and unrecognized paths receive
-full qualification because plugin Markdown is part of the product.
-
-PRs limited to the SDK package manifest's Markdown files, optionally mixed with
-ordinary docs or `RELEASING.md`, require the native payload, the real package
-build and archive inspection, and one Ubuntu Node 24 installation. Removing or
-renaming a required guide must still pass archive inspection. The static job
-validates the canonical recovery example in `RELEASING.md` on docs-only PRs too.
-Mixing the release guide with product source selects full qualification.
-
-Product source changes run the complete SDK suite on Linux, macOS, and Windows,
-plus MCP, standalone-plugin, native-runtime, and installed-package checks. Tests
-are discovered from the source tree, including new files without timing data.
-Platform-specific filesystem, credential, process, cancellation, and resumed
-worker cases remain enabled.
-
-SDK shards wait for static checks and a successful package build. A failing
-static check skips the shards when a PR opens, reopens, or receives new commits.
-Pushes to `main`, nightly and manual runs, and PR edits that need full
-qualification still run the shards.
-
-The two Linux MCP jobs discover the same test files as local MCP testing. CI
-assigns files by observed runtimes and starts the longest files first on each
-job's two Node workers. Refresh the
-slow-file estimates in `run-mcp-test-shard.mts` when the jobs drift apart.
-
-Pull requests limited to `.ts` files under `sdk/typescript/src/`,
-`sdk/typescript/tests-ts/`, `plugins/codex-security/mcp-app/src/`, and
-`plugins/codex-security/mcp-app/tests/`, plus any ordinary docs or packaged SDK guides,
-use reduced version matrices. They test the minimum Node 22, 24, and 26 versions,
-current Node 24 for the Action adapter, macOS installation, and Windows Node 22
-installation. When selected, Python runs the full suite on 3.12 and the native
-subsets on macOS and Windows. Product source changes select container validation.
-
-PRs limited to top-level `sdk/typescript/tests-ts/*.test.ts` keep all SDK shards,
-static checks, native builds, and packaging. Docker excludes these top-level
-test modules, so these PRs skip container validation. Test support files used by
-package inspection remain in the build context. The test modules are outside the
-npm package, so one Ubuntu Node 24 install checks it and the Action adapter.
-These PRs skip the plugin suites and run evals only for `codex-dependency-pins.test.ts`.
-Mixed changes follow the usual source or full route.
-
-PRs limited to Action metadata, wrapper implementation, tests, npm manifests,
-locks, or checked-in bundles run Action CI. It verifies a clean rebuild, runs
-the published CLI integration, audits the wrapper and pinned runtime, and
-exercises the local Action on eligible events. Fork PRs run validation and
-both audits. Same-repository PRs also run the hosted dry-run smoke. Changes to
-these Action files keep the Linux Node 24 integration against the package built
-from the PR. The focused SDK Action release contracts run when the rest of the
-SDK suite is skipped. Changes to the shared SDK Git remote parser also select
-Action CI.
-
-PRs limited to Standard time-budget eval modules, experiment configuration or
-README, or to the triage eval's scripts, assertions, README, manifest or lock,
-run the deterministic eval job and static checks. The eval job builds the SDK
-and host plugin, checks the Codex version across the SDK, MCP and triage
-lockfiles, and runs the triage, secret-discovery, Standard time-budget and
-workflow-routing suites.
-
-Edits limited to existing top-level `plugins/codex-security/tests/test_*.py`
-modules keep all five Python jobs, static and workflow checks, MCP, plugin host,
-native builds, packaging, and Unix installs. Docker excludes these modules from
-the image. Adding, removing, or renaming modules, editing shared helpers, or
-including any other path selects full qualification.
-
-Inputs outside these routes select full qualification, including workflow checks,
-containers, current Node 26, Windows Node 24 installation, and Python 3.10 and
-3.14 Linux suites. This includes dependency configuration such as `.npmrc` and
-`pnpm-workspace.yaml`, build tooling, Python and native code, and unknown paths
-even when mixed with ordinary source or documentation. Mixing Action
-implementation or eval changes with product code also selects full qualification.
+# How this repository tests pull requests
+
+To scan your own repository in CI, follow the [GitHub Action guide](../github-action/README.md). For contributions to Codex Security, [`node-ci`](../.github/workflows/node-ci.yml) selects jobs from the complete PR diff. Static checks and the final `ci` gate run on every path. The [selection rules](../.github/scripts/select-ci-checks.mjs) define the individual paths and matrices.
+
+## Which checks run
+
+| Changes in the pull request | Checks selected | Exceptions |
+| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repository README, contributing guide, `docs/**/*.md`, Action or Docker README, or release guide | Static checks, including Markdown formatting and the release guide’s recovery example. | The Action README also selects Action CI to verify generated inputs and examples. |
+| Markdown listed in the [SDK package manifest](../sdk/typescript/package.json), optionally with ordinary docs or the release guide | Build with the universal native payload, inspect the archive and install it on Ubuntu with Node 24. | Removing or renaming a required guide still runs archive inspection. |
+| TypeScript sources or tests in the SDK or MCP app, optionally with ordinary or packaged docs | Full SDK suite on Linux, macOS and Windows. MCP, standalone plugin, native, deterministic eval and container checks also run. Installation covers the minimum supported Node majors and current Node 24 on Linux, plus macOS and Windows. | Python runs its full suite on Linux 3.12 and native subsets on macOS and Windows. The shared SDK Git remote parser also selects Action CI. |
+| Only top-level `sdk/typescript/tests-ts/*.test.ts` modules | All SDK shards, native builds, packaging and an Ubuntu Node 24 installation with the Action adapter. | Skips containers and plugin suites. The Codex dependency pin test additionally selects deterministic evals. |
+| Action metadata, wrapper sources, tests, npm manifests, locks or checked-in bundles | Action CI checks a clean rebuild, runs the published CLI integration, and audits wrapper and runtime dependencies. It tests the PR-built package on Ubuntu Node 24 and runs focused SDK Action release tests when the SDK suite is skipped. | Fork PRs run validation and both audits. Same-repository PRs also run a hosted dry run. |
+| Standard time-budget eval modules, configuration or README, or triage eval scripts, assertions, README, manifest or lock | Build the SDK and host plugin, verify the shared Codex version and run deterministic triage, secret-discovery, time-budget and workflow-routing tests. | Mixing these paths with product code selects full qualification. |
+| Only edits to existing top-level `plugins/codex-security/tests/test_*.py` modules | All five Python jobs, workflow checks, MCP, plugin host, native builds, packaging and Unix installation checks. | Adding, deleting or renaming modules, or changing helpers, selects full qualification. |
+| Other paths or changes outside these combinations | Full qualification adds workflow checks, containers, current Node 26, Windows Node 24, and the full Linux Python matrix. | Includes plugin skills, references, examples, schemas, build tooling and dependency configuration. Mixing the release guide or Action implementation with product source also takes this route. |
+
+SDK shards wait for static checks and a successful package build on opening, reopening or updating a PR. Pushes to `main`, nightly and manual runs, and PR edits requiring full qualification still run the shards after a static-check failure if the package build succeeded. Tests are discovered from the source tree, so a new test runs even before it has recorded timing data.
+
+The two Linux MCP jobs split the same test files as local MCP testing. Each starts the longest files first on its two Node workers. Refresh the slow-file estimates in [the MCP shard runner](../sdk/typescript/scripts/run-mcp-test-shard.mts) when shard durations drift apart.
+
+## Reusing checks after a PR edit
Every push to `main`, nightly run, manual `node-ci` dispatch, and pull-request
retarget runs the complete version matrices. Release automation still requires
diff --git a/docs/examples/codex-security.json b/docs/examples/codex-security.json
index 84eda53b6..e8059e319 100644
--- a/docs/examples/codex-security.json
+++ b/docs/examples/codex-security.json
@@ -1,5 +1,5 @@
{
- "$schema": "./node_modules/@openai/codex-security/schemas/project-config.schema.json",
+ "$schema": "../../sdk/typescript/schemas/project-config.schema.json",
"scan": {
"mode": "standard",
"scope": { "paths": ["sdk/typescript/src"] }
diff --git a/docs/examples/codex-security.yaml b/docs/examples/codex-security.yaml
index e7b888818..842e1b5d4 100644
--- a/docs/examples/codex-security.yaml
+++ b/docs/examples/codex-security.yaml
@@ -1,5 +1,5 @@
-# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
-# Schema path assumes this file is copied to the root of your project.
+# yaml-language-server: $schema=../../sdk/typescript/schemas/project-config.schema.json
+# Scope paths are relative to the repository you scan.
scan:
mode: standard
scope:
diff --git a/docs/plugin-connectors.md b/docs/plugin-connectors.md
index 80964dd83..644aebd46 100644
--- a/docs/plugin-connectors.md
+++ b/docs/plugin-connectors.md
@@ -1,45 +1,58 @@
# Plugin connectors
-Codex Security uses optional connected apps for Cloud reads, finding intake
-and tracking. The [app manifest](../plugins/codex-security/.app.json)
-declares each connection with `required: false` so users can run local scans
-without connecting an app.
+Connect an app when you want Codex Security to read findings from a service
+or track them in an issue. Local repository scans work without these apps.
-| App | Workflows |
-| -------------------- | --------------------------------------------------------- |
-| Codex Security Cloud | Read existing findings, evidence, reports and scan status |
-| Linear | Ticket intake and finding tracking |
-| GitHub | Finding intake, source lookup and issue tracking |
-| Atlassian | Jira Cloud ticket intake and finding tracking |
+| App | Use it to | Setup |
+| -------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Codex Security Cloud | Read findings, evidence, reports, and scan status in your workspace. | [Connect Cloud in Codex](../sdk/typescript/README.md#read-existing-cloud-findings) |
+| Linear | Read tickets and track findings in a team or project. | [Connect Linear](#linear-setup) |
+| GitHub | Read alerts and repository source, track issues, or draft a security advisory. | [Connect GitHub](#github-setup) |
+| Atlassian | Read Jira Cloud tickets and track findings in a project. | [Connect Jira](#jira-setup) |
-For scanner imports, use a connected tool or signed-in CLI to obtain the
-requested records. Follow the [scanner import guide](scanner-imports/README.md)
-to select and preview the evidence for your destination.
+## Linear setup
-Finding tracking and CLI publication share issue associations when they use the same local state directory, including reuse across scan occurrences. The tracking skill reads them with `get_codex_security_finding_issues` and records accepted writes or verified reuse with `record_codex_security_finding_issues`. Provider reads still confirm saved candidates and search for unrecorded duplicates. Accepted writes remain recorded even when follow-up reads fail. The tools accept sealed scan bundles without requiring their original local scan history and keep receipts outside those bundles.
+Connect **Linear** in the Codex app directory with the account that can access
+your team. Give Codex a ticket URL to triage, or name the team and optional
+project where you want to track a finding. To use an existing Linear MCP
+connection for reads, specify the account and workspace.
+See [ticket intake](../plugins/codex-security/skills/triage-finding/references/ticket-intake.md#retrieval).
-To replace `scripts/validate_tracking_source.py`, run the plugin launcher with `--helper validate-tracking-source <scan-directory> [--finding-id <id> | --fingerprint <fingerprint>]`. The Node helper validates the sealed scan before printing the selected finding IDs in scan order.
+## GitHub setup
-For GitHub triage, use a connected tool that can read the requested records and
-evidence. The [GitHub intake reference](../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md)
-covers scoped reads using an existing GitHub CLI login and how to handle an
-explicit choice of account or transport.
+Connect **GitHub** in the app directory with access to the repository and the
+type of alert you want to read. Give Codex the repository and an issue or alert
+URL. To use an existing GitHub CLI login for triage, specify the host and
+account. See [GitHub intake](../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md).
+When tracking a finding, specify whether it belongs in an issue or a
+[draft security advisory](../plugins/codex-security/skills/track-findings/references/github-security-advisories.md).
## Jira setup
-Connect the **Atlassian** app in the app directory. Existing Atlassian Rovo (Legacy) connections do not connect the new app; authorize it separately with the intended account and site.
-
-For user-selected Jira CLI or Linear MCP reads, see the [ticket intake guide](../plugins/codex-security/skills/triage-finding/references/ticket-intake.md#retrieval). Intake and duplicate checks need read and search access. Creating or updating issues also needs write access. Before creating an issue, the tracking skill resolves the project, issue type, and required fields.
-
-Use the app's live schemas and discover deferred operations when needed. See Atlassian's [supported tools](https://developer.atlassian.com/cloud/rovo-mcp/guides/supported-tools/) and the skill's [Jira workflow](../plugins/codex-security/skills/track-findings/references/jira.md).
-
-## QA
-
-Test the plugin build with synthetic findings in a selected QA project:
-
-- Verify that Jira tracking uses the Atlassian app and that intake reads use the selected connection and account on the intended site or workspace.
-- Read a synthetic issue directly and through project-scoped JQL, including pagination.
-- Create one issue, reuse it without creating a duplicate, and update approved fields. Verify each write by reading the issue back.
-- Verify that missing connections and insufficient access produce recovery guidance without duplicate creates.
-
-Record live results separately from static checks. Keep account and project details, issue keys, and raw tool responses out of public PRs.
+Connect **Atlassian** in the Codex app directory and authorize the account and
+site that contain your Jira project. If you already use Atlassian Rovo (Legacy), authorize
+the Atlassian app separately. Give Codex an issue key and site, or a Jira Query
+Language (JQL) query to select the tickets to read.
+See [Jira ticket intake](../plugins/codex-security/skills/triage-finding/references/ticket-intake.md#retrieval)
+for using an already signed-in Jira CLI.
+
+## Track a finding
+
+Give Codex the saved scan directory, the finding ID, and the destination. Ask
+it to check for an existing issue. The account needs read and search access to
+check for duplicates. To create or update an issue, it also needs write access.
+Review the destination, audience, and proposed changes before approving a write.
+If Codex cannot find a ticket you can see, check the signed-in account and the
+selected site, workspace, or repository.
+
+When the plugin and CLI use the same local state directory, both can find issue
+links saved by earlier tracking or publication runs. Codex checks a saved link
+against the tracker before reusing it and searches the destination for other
+matches. You can also track findings from a sealed scan bundle copied from
+another machine. Codex saves new issue associations outside the bundle, even
+if an issue was created but its follow-up read failed. On retry, check that
+issue before approving another write.
+See the [tracking workflow](../plugins/codex-security/skills/track-findings/SKILL.md).
+
+To import a scanner report instead, use the [scanner import guides](scanner-imports/README.md)
+to choose the input format, preview the records, and select a destination.
diff --git a/docs/project-configuration.md b/docs/project-configuration.md
index 294c57363..597fcf728 100644
--- a/docs/project-configuration.md
+++ b/docs/project-configuration.md
@@ -1,54 +1,53 @@
# Project configuration
-Use `scan [repository] -c FILE` or `scan [repository] --config FILE` to load one
-YAML or JSON file:
+Use a YAML or JSON file to reuse a scan scope, cost limit, or findings threshold.
+Select the file with `-c FILE` (or `--config FILE`) on `scan`, `bulk-scan`,
+`scan-components`, or `info`. The repository is a separate command argument.
-```sh
-codex-security scan . -c codex-security.yaml --dry-run --json
-codex-security scan . -c codex-security.json --model gpt-5.6-terra
-```
+**Choose a file you trust.** Native Codex settings in the file can start MCP
+servers and select where model requests go. In CI, keep the configuration in an
+operator-controlled location outside the checkout being scanned.
-The supported extensions are `.yaml`, `.yml`, and `.json`. `scan`, `bulk-scan`,
-`scan-components`, and `info` accept `-c` / `--config`. An operator can set
-`CODEX_SECURITY_PROJECT_CONFIG` instead; an explicit `-c` takes precedence. With
-neither, no file is loaded, even if `codex-security.yaml` exists. SDK `run()` calls
-and saved reruns do not read this environment variable or discover project files.
-The repository comes from the command's target selection, not the config file.
+## Configure your first scan
-**Treat the selected file as trusted operator configuration, with the same
-authority as CLI options and SDK `codexOverrides`.** Native Codex settings can
-start configured MCP server processes and select model-service destinations. Do not select a
-file controlled by an untrusted repository or pull request. In CI, keep the
-scanner configuration in an operator-controlled location outside the checkout
-being assessed. Explicit selection does not make a file safe to trust.
+From your project root, run `codex-security init` to create `codex-security.yaml`.
+To choose a different name, pass a path ending in `.yaml`, `.yml`, or `.json`.
+The command refuses to overwrite an existing file.
-Create a starter and inspect its settings without a repository or runtime:
-
-```sh
-codex-security init
-codex-security info -c codex-security.yaml --json
-```
-
-`init [file]` defaults to `codex-security.yaml`, refuses to overwrite an existing
-file, and accepts `.yaml`, `.yml`, or `.json`. YAML starters show current defaults
-as comments so future releases can still update defaults you have not overridden.
-The editor hint is relative to the chosen file and expects the package to be
-installed in the invocation directory's `node_modules`.
-
-For a project with a `src` directory:
+For a repository with a `src` directory, save these settings in the file:
```yaml
scan:
scope:
paths: [src]
- knowledge_base: [SECURITY.md, docs/architecture.md]
-codex:
- model: gpt-5.6-sol
- model_reasoning_effort: xhigh
policy:
fail_on_severity: high
```
+To supply additional context, add `knowledge_base: [SECURITY.md, docs/architecture.md]`
+under `scan` only if both files exist relative to the configuration file.
+Use the paths to your own documents or leave the list out.
+
+```sh
+# Inspect the settings and where each one came from.
+codex-security info -c codex-security.yaml --json
+
+# Check the target, paths, and settings locally.
+codex-security scan . -c codex-security.yaml --dry-run --json
+```
+
+Check that the preview shows your intended repository and scope. To start the
+scan with those settings, keep the same file selection:
+
+```sh
+codex-security scan . -c codex-security.yaml
+```
+
+Instead of passing `-c` each time, you can set `CODEX_SECURITY_PROJECT_CONFIG`.
+An explicit `-c` takes precedence. Without either, the CLI uses its defaults
+even if the current directory contains a project file. SDK `run()` calls and
+saved reruns do not discover files or read this environment variable.
+
All settings are optional; `{}` uses the existing defaults. No `version` field
is needed. Unknown wrapper keys and invalid types are errors. Values are literal:
the loader does not evaluate JavaScript, interpolate environment values, include remote files,
@@ -64,28 +63,24 @@ Deep Scan discovery workers, including resumes. An explicit
`scan.cyber_access_program` takes precedence for each turn. See
[Daybreak opt-in](../sdk/typescript/docs/cli.md#daybreak-opt-in).
-The [YAML example](examples/codex-security.yaml) and equivalent
-[JSON example](examples/codex-security.json) select this repository's TypeScript
-source. After [setting up the source checkout](../sdk/typescript/TESTING.md), try:
+### Try the checked-in examples
+
+The [YAML](examples/codex-security.yaml) and [JSON](examples/codex-security.json)
+examples both select this repository's `sdk/typescript/src` directory. From
+the root of the Codex Security checkout with the CLI installed, run:
```sh
-cd sdk/typescript
-pnpm run build:plugin
-pnpm run build
-cd ../..
-node sdk/typescript/bin/codex-security.mjs scan . -c docs/examples/codex-security.yaml --dry-run --json
+codex-security scan . -c docs/examples/codex-security.yaml --dry-run --json
```
-## Desktop and conversational Deep Scans
+To reuse either example in your own project, change `scan.scope.paths` to a
+directory in the repository you will scan. Both editor schema hints point to
+the schema in this checkout. For a copy at your project root with
+`@openai/codex-security` installed locally, change the hint to
+`./node_modules/@openai/codex-security/schemas/project-config.schema.json`.
+You can also omit the hint. The CLI validates the file using its bundled schema.
-When the Codex host supplies the launching turn’s speed, Deep Scan uses it for
-Standard scan workers, resumed workers, and finding comparisons. Selecting
-Default overrides a faster tier in the worker’s Codex config. On hosts that omit the
-turn’s speed, each worker uses the Codex configuration it loads. To keep a scan
-at Default on those hosts, leave `service_tier = "default"` in the worker’s
-config for the duration of the scan, including any resumes. Other scans that
-load the same config also use that setting. The usual config file is
-`$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when `$CODEX_HOME` is unset.
+## Desktop and conversational Deep Scans
Deep Scan setup accepts an explicitly selected `.yaml`, `.yml`, or `.json` project
file using the same format. For example:
@@ -101,12 +96,11 @@ scan:
max_discovery_runs: 4
```
-The plugin's `inspect_codex_security_setup` tool accepts `projectConfigPath` and
-returns `setup.deepScanConfig`: effective worker count, subagents per worker,
-novelty-stop threshold, consecutive-error threshold, review cap, and discovery
-time limit, with the source of each value. Desktop setup clients should display
-these values before starting a scan. Conversational scans inspect the same setup
-before passing `projectConfigPath` to `start_codex_security_deep_scan`.
+Include the path to the file when asking Codex to start a Deep Scan. To check
+what will run, ask for the effective worker count, subagents per worker, stop
+conditions, review cap, and discovery time limit. The plugin returns each value
+and its source in `setup.deepScanConfig` from `inspect_codex_security_setup`.
+Both setup and `start_codex_security_deep_scan` accept `projectConfigPath`.
Explicit project settings override per-user `[deep_scan]` settings, which override
built-in defaults. The per-user file remains
@@ -127,6 +121,17 @@ scan ID uses that snapshot even if the selected file or global defaults change.
The time limit bounds discovery; scans may stop sooner after novelty or review
limits, and aggregation and reporting can continue afterward.
+### Worker speed
+
+When the Codex host supplies the launching turn’s speed, Deep Scan uses it for
+Standard scan workers, resumed workers, and finding comparisons. Selecting
+Default overrides a faster tier in the worker’s Codex config. On hosts that omit the
+turn’s speed, each worker uses the Codex configuration it loads. To keep a scan
+at Default on those hosts, leave `service_tier = "default"` in the worker’s
+config for the duration of the scan, including any resumes. Other scans that
+load the same config also use that setting. The usual config file is
+`$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when `$CODEX_HOME` is unset.
+
## Settings
| Field | Meaning | Default |
@@ -190,7 +195,7 @@ 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);
+const result = await security.run(process.cwd(), options);
if (
options.failureSeverity !== undefined &&
result.hasFindingsAtOrAbove(options.failureSeverity)
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
index dc2b92673..08ed89ab1 100644
--- a/docs/scanner-imports/README.md
+++ b/docs/scanner-imports/README.md
@@ -32,33 +32,31 @@ Ask it to preview the report with your configured model.
## Choose your scanner
-Check your version with `codex-security --version`. Support for AWS Continuum,
-Black Duck, SonarQube Cloud, Veracode, the Semgrep Platform SDK example, and
-Cloud private inbox imports came after [version 0.8.2](https://github.com/openai/codex-security/blob/npm-v0.8.2/sdk/typescript/docs/cli.md#import-vendor-findings-locally).
-For AWS inbox imports, use a CLI and workspace that support v2 finding import
-jobs. The dry-run preview shows `privateImport` when that route is available.
-
-| Guide | Supported input |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [Amazon Inspector](inspector.md) | Inspector2 `ListFindings` JSON for one Code Security repository |
-| [AWS Continuum](continuum.md) | Summaries or selected code finding details for one verified repository |
-| [Black Duck SCA](blackduck.md) | BOM component vulnerabilities for one project version |
-| [Checkmarx SAST](checkmarx.md) | Checkmarx One CLI JSON or self-managed CxSAST XML for one scan |
-| [Endor Labs](endor.md) | Finding JSON from `endorctl`, or SARIF with finding UUIDs |
-| [GitHub code scanning](github-code-scanning.md) | Alerts selected for one repository and Git ref |
-| [GitHub Dependabot](github-dependabot.md) | Dependency alerts exported from one repository |
-| [GitHub Security Advisories](github-security-advisories.md) | Selected repository or global advisories |
-| [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |
-| [Semgrep](semgrep.md) | CLI/CI JSON, SARIF, selected Guardian findings, or Platform Web API reports |
-| [Snyk](snyk.md) | CLI JSON, plugin exports, SARIF, or monitored Code and Open Source issues |
-| [SonarQube Cloud](sonar.md) | Issues selected with the signed-in Sonar CLI, or saved issue-search pages |
-| [Trivy](trivy.md) | Native schema-v2 repository or filesystem JSON, optionally gzip-compressed |
-| [Veracode Static Analysis](veracode.md) | Findings API pages for one application's policy flaws |
-| [Wiz](wiz.md) | Native JSON, normalized JSONL, or detailed repository package vulnerability CSV |
+With imports enabled, run `codex-security publish findings --help` to check the
+providers in your installed CLI. The guides cover local and Cloud imports
+unless an input is marked local only. Cloud must support the selected provider. For AWS inbox imports, use a CLI and workspace that support v2 finding import jobs. Check for `privateImport` in the dry-run preview.
+
+| Guide | Supported input |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [Amazon Inspector](inspector.md) | Inspector2 `ListFindings` JSON for one Code Security repository |
+| [AWS Continuum](continuum.md) | Summaries or selected code finding details for one verified repository |
+| [Black Duck SCA](blackduck.md) | BOM component vulnerabilities for one project version |
+| [Checkmarx SAST](checkmarx.md) | Checkmarx One CLI JSON or self-managed CxSAST XML for one scan |
+| [Endor Labs](endor.md) | Finding JSON from `endorctl`, or SARIF with finding UUIDs |
+| [GitHub code scanning](github-code-scanning.md) | Alerts selected for one repository and Git ref |
+| [GitHub Dependabot](github-dependabot.md) | Dependency alerts exported from one repository |
+| [GitHub Security Advisories](github-security-advisories.md) | Selected repository or global advisories |
+| [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |
+| [Semgrep](semgrep.md) | CLI/CI JSON, SARIF, Platform Web API reports, or selected Guardian findings (local only) |
+| [Snyk](snyk.md) | CLI JSON, plugin exports, SARIF, or monitored Code and Open Source issues |
+| [SonarQube Cloud](sonar.md) | Issues selected with the signed-in Sonar CLI, or saved issue-search pages |
+| [Trivy](trivy.md) | Native schema-v2 repository or filesystem JSON, optionally gzip-compressed |
+| [Veracode Static Analysis](veracode.md) | Findings API pages for one application's policy flaws |
+| [Wiz](wiz.md) | Native JSON, normalized JSONL, or detailed repository package vulnerability CSV |
If you selected specific findings, compare the preview with your selection.
-Check for missing, duplicate, or unexpected occurrences and resolve any
-exclusions before importing.
+Check for missing, duplicate or unexpected occurrences. For OpenGrep, check
+`report.errors` as well as exclusions, even when the findings list is empty.
## Save or publish and verify
@@ -68,7 +66,9 @@ from the preview for your destination](sonar.md#import-and-verify).
**Save locally.** Remove `--dry-run` and confirm. In automation, use `--yes`
after reviewing the preview.
-**Send to Cloud.** Keep your file, provider, source key, and scanner options.
+**Send to Cloud.** Semgrep Guardian captures support local import only. For other
+supported files, keep the file, provider, source key and scanner options from
+your preview.
Set `--to cloud` and pass the connected repository URL or Cloud ID to
`--repository`. Preview again with `--dry-run`. Check the account, endpoint,
destination, findings, and exclusions. Remove `--dry-run` and confirm. [Cloud setup](../../sdk/typescript/docs/cli.md#preview-and-publish)
@@ -90,6 +90,15 @@ For a Cloud import, check the receipt for the destination shown in the preview.
If `publish findings` stops and returns `savedSubmission`, [resume from that checkpoint](schema-guide.md#retry-a-cloud-submission).
+## Troubleshoot Semgrep and Snyk collection
+
+If `import semgrep` or `import snyk` returns HTTP 429, check `Retry-After`.
+Both collectors retry the same GET once when the requested wait is at most
+10 seconds. They accept whole seconds or an HTTP date and retry immediately
+for zero or a past date. Cancellation stops the wait. A failed request reports
+its HTTP status and up to 64 KiB of the vendor response. After the indicated
+wait, rerun collection and preview the complete successful output.
+
## Work with imported findings
New local findings start as `not_assessed`. To check whether one affects your
diff --git a/docs/scanner-imports/blackduck.md b/docs/scanner-imports/blackduck.md
index 462a13c32..15973154e 100644
--- a/docs/scanner-imports/blackduck.md
+++ b/docs/scanner-imports/blackduck.md
@@ -1,9 +1,9 @@
# Import Black Duck SCA findings
-Use a BOM-6 export of vulnerable components from one Black Duck SCA project
-version. In the scan configuration, verify which Git repository that version
-represents. A project name or component download URL alone can't establish
-that link.
+Export the vulnerable components from the bill of materials for one Black Duck
+SCA project version. Request the BOM-6 JSON format. In the scan configuration,
+verify which Git repository the version represents. A project name or component
+download URL alone can't establish that link. [Export the collection](#export-the-bom-6-collection).
## Quick start
diff --git a/docs/scanner-imports/checkmarx.md b/docs/scanner-imports/checkmarx.md
index 2cc3bcc7b..7dba3291d 100644
--- a/docs/scanner-imports/checkmarx.md
+++ b/docs/scanner-imports/checkmarx.md
@@ -1,11 +1,13 @@
# Import Checkmarx SAST findings
Use `--provider checkmarx` for a completed Checkmarx One scan (CLI JSON) or
-self-managed CxSAST scan (XML). Both formats support gzip. [Enable external imports](README.md#preview-a-report).
+self-managed CxSAST scan (XML). Both formats support gzip. If you need the report,
+[collect an existing scan with Codex](#collect-an-existing-scan-with-codex) or
+[export one scan manually](#export-one-scan-manually).
## Preview, import and verify
-From the matching checkout, preview a saved report with its verified Git URL.
+[Enable external imports](README.md#preview-a-report). From the matching checkout, preview the report with its verified Git URL.
Choose a source key for the product, tenant or instance, project and ref.
Reuse it for later exports from that stream.
@@ -62,7 +64,7 @@ Review the result filters before generating the file. [Generate a CxSAST report]
## Identity and evidence
-One combines `similarityId` and `data.resultHash` to identify each occurrence.
+Checkmarx One combines `similarityId` and `data.resultHash` to identify each occurrence.
CxSAST uses the project, query, path similarity ID and ordered path nodes,
or the reported result location for a path without nodes. Moving a node can
create a new occurrence. [Checkmarx similarity IDs](https://docs.checkmarx.com/en/34965-205026-similarity-id.html)
diff --git a/docs/scanner-imports/continuum.md b/docs/scanner-imports/continuum.md
index ce84e2d3d..38553932d 100644
--- a/docs/scanner-imports/continuum.md
+++ b/docs/scanner-imports/continuum.md
@@ -12,9 +12,7 @@ repository supplied the scanned code, including the archive for an S3 source.
For a finding from another scanner, you can also check its repository in that
scanner. [AWS Continuum code sources](https://docs.aws.amazon.com/continuum/latest/userguide/cv-getting-started.html)
-**Saved report.** Set `report` to a native detail response, an array of detail
-responses, or a complete list response with its `items` array. Then skip to
-the preview.
+**Saved report.** Set `report` to a native detail response, an array of detail responses, or a complete list response with its `items` array. Then [preview the report](#preview-and-import).
```sh
report=/private/path/continuum.json
@@ -76,8 +74,7 @@ codex-security publish findings "$report" --to local --repository . \
Check the repository, finding ARNs, paths, and exclusions. In a
multi-repository environment, a customer-supplied path can begin with a
-repository name. The reader keeps that prefix. To save the findings in your
-local workbench, remove `--dry-run` and confirm.
+repository name. The reader keeps that prefix. For local repeat imports, a summary replaces richer evidence already saved for the same ARN and source key. Use the detail export to keep locations, mitigation and validation evidence. To save locally, remove `--dry-run` and confirm.
### Publish to your Cloud inbox
@@ -102,8 +99,7 @@ receipt, then open a finding in your inbox and compare its source ID with the AW
## Detail, summaries, and repeat imports
Both formats use the finding ARN. In the local workbench, importing a detail
-response under the same source key updates the existing summary. A later
-summary replaces the richer local evidence. In a private Cloud inbox,
+response under the same source key updates the existing summary. In a private Cloud inbox,
retrying identical evidence under the same source key preserves the finding.
The importer uses `statusUpdatedAt` for the source update time when available.
diff --git a/docs/scanner-imports/endor.md b/docs/scanner-imports/endor.md
index 860bd1ad2..47fca559f 100644
--- a/docs/scanner-imports/endor.md
+++ b/docs/scanner-imports/endor.md
@@ -3,7 +3,10 @@
Prefer Endor's native Finding JSON. It keeps the scanned commit,
severity, package and advisory details, and primary SAST or AI SAST locations
that Endor reports. You can also import self-contained `endorctl` SARIF 2.1.0
-with finding UUIDs.
+with finding UUIDs. A later SARIF import for the same UUID, destination
+and source key can replace the stored commit, package and
+advisory details, and leave severity `unknown`. Use native JSON for updates
+when you need those fields.
## Quick start
@@ -66,10 +69,8 @@ and dismissals come from Endor.
## SARIF and repeat imports
-Both formats identify findings by UUID. Importing SARIF after native JSON
-with the same destination and source key replaces the earlier evidence. You
-can lose the scanned commit, package and advisory details, and severity can
-become `unknown`. The local workbench keeps findings omitted from later exports.
+The local workbench keeps findings omitted from later exports. Use a separate
+source key if you want to retain both formats' evidence for a finding.
[Imported finding identity and evidence](schema-guide.md)
SARIF keeps finding links, direct repository paths and reported SAST or
diff --git a/docs/scanner-imports/github-code-scanning.md b/docs/scanner-imports/github-code-scanning.md
index 6b1a58576..e47a3b6f5 100644
--- a/docs/scanner-imports/github-code-scanning.md
+++ b/docs/scanner-imports/github-code-scanning.md
@@ -16,19 +16,21 @@ source_key="${GH_HOST:-github.com}/$repo/code-scanning"
```
**Saved report.** Set `report=/private/path/alerts.json` if you already have
-the collector's complete JSON array.
+the collector's complete JSON array. Continue with [Preview the report](#preview-the-report).
-**Export from GitHub.** Sign in to the selected host with `gh auth login`.
+### Export from GitHub
+
+Sign in to the selected host with `gh auth login`.
A fine-grained token needs **Code scanning alerts: read**. A classic token
needs `security_events`, or `public_repo` for a public repository.
[GitHub API permissions](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository)
-This command selects open alerts on the default branch. For another branch,
-add `--github-ref refs/heads/BRANCH`. Use `--github-state all` to include
-fixed and dismissed alerts, or repeat `--github-alert NUMBER` to select
-specific alerts across states. Omit output filters, token limits and
-`--full-output` so the reader gets the complete array. Use a private
-temporary directory outside the checkout.
+The command below selects open alerts on the default branch. For a different
+branch, add `--github-ref refs/heads/BRANCH` to the collector command. To
+include fixed and dismissed alerts, add `--github-state all`. For exact
+alerts across states, repeat `--github-alert NUMBER` and omit `--github-state`.
+Save the complete array without output filters, token limits or `--full-output`.
+Use a private temporary directory outside the checkout.
```sh
report=
@@ -37,13 +39,15 @@ out=$(mktemp -d) &&
report="$out/alerts.json"
```
-**Preview the report.**
+### Preview the report
```sh
codex-security publish findings "$report" --to local --repository . \
--provider github --source-key "$source_key" --dry-run --format json
```
+### Save and verify
+
Check the repository, ref and alert numbers against your selection. The alert
repository must match a comparable local Git remote when available, or the
selected Cloud repository. If the preview matches,
@@ -54,5 +58,77 @@ selected Cloud repository. If the preview matches,
The host, repository, alert number and ref identify a finding. The same alert
on two refs keeps separate evidence. Missing security severity stays `unknown`.
-To collect with the SDK instead of `gh`, pass `githubHost` and a `githubToken`
-for that host. [GitHub SDK examples](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud)
+A GitHub dismissal applies to the entire alert, even when a selected ref's
+instance is open or fixed. A GitHub connection in Codex can select records.
+The CLI collector authenticates separately with `gh`.
+
+## Use the SDK
+
+To collect with the SDK, use credentials from `gh` or supply `githubHost` and
+a `githubToken` issued for that host. This example previews a Cloud import.
+
+```ts
+import {
+ importGitHubCodeScanningAlerts,
+ normalizeGitHubCodeScanningAlerts,
+ prepareNormalizedExternalPublication,
+} from "@openai/codex-security";
+
+const alerts = await importGitHubCodeScanningAlerts({
+ repository: "example/project",
+});
+const prepared = await prepareNormalizedExternalPublication(
+ normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
+ {
+ provider: "github",
+ repository: "https://github.com/example/project",
+ sourceKey: "github.com/example/project/code-scanning",
+ },
+);
+console.log(prepared.preview);
+```
+
+After reviewing the Cloud preview, call `await prepared.publish()` to confirm.
+
+For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
+the original alerts to retain evidence that exceeds Cloud limits. Pass the result
+to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
+its preview, and call `import()`. Alternatively, pass the saved alert file directly
+to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
+
+### Validate the selected alerts
+
+To get a disposition per alert, validate the collected records against the matching checkout.
+
+```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.
+ githubHost: "github.com",
+ 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`.
+Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
+If you omit the token, the SDK asks the GitHub CLI for credentials, including
+its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
+The token needs code-scanning read access; access failures reject the import.
diff --git a/docs/scanner-imports/github-dependabot.md b/docs/scanner-imports/github-dependabot.md
index eeaabaa61..7eaa8b5cc 100644
--- a/docs/scanner-imports/github-dependabot.md
+++ b/docs/scanner-imports/github-dependabot.md
@@ -17,9 +17,17 @@ source_key=github.com/OWNER/REPO/dependabot
**Saved report.** If you already have the complete REST alert objects,
[preview the report](#preview-the-report).
-### Export repository alerts
+<a id="export-repository-alerts"></a>
-In Codex, replace the host, repository and private output path in this request.
+### Export from GitHub
+
+Use either an existing GitHub connection in Codex or an authorized REST client.
+Fetch all selected pages from the same repository and keep full REST alert
+objects, including `html_url`, `security_advisory` and `security_vulnerability`.
+Save each page as one compact JSON array per line. An empty page is `[]`.
+Only use the final file after every page succeeds.
+
+**In Codex**, replace the host, repository and private output path in this request.
> Export the native Dependabot alerts for https://HOST/OWNER/REPO across all
> states and classifications. Follow the scoped GitHub read procedure in the
@@ -27,19 +35,15 @@ In Codex, replace the host, repository and private output path in this request.
> array per line in a private temporary file beside /private/path/dependabot.jsonl.
> Rename it to that path once you've verified and saved every page.
-Keep every field, including `html_url`, `security_advisory` and
-`security_vulnerability`. Save an empty page as `[]`. Use the selected
-transport and identity, and ask before switching either.
-[Scoped GitHub read procedure](../../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md#github-finding-retrieval)
+Check that the connection returned complete REST objects and all selected pages.
+[Scoped GitHub read procedure](../../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md#github-finding-retrieval).
-- **Connected app.** Confirm it returned unmodified REST alert objects and
- enumerated every matching page.
-- **HTTPS.** Use a credential with Dependabot alerts read access. Request
- `GET /repos/OWNER/REPO/dependabot/alerts?per_page=100` on the selected
- host's API. Omit `state` and `classification` for all alerts the deployment
- exposes. Note any unknown malware coverage. Reject redirects and rebuild
- each page request on the same API origin and repository endpoint with the
- requested filters. [Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository)
+**With a REST client**, use a credential with Dependabot alerts read access.
+Request `GET /repos/OWNER/REPO/dependabot/alerts?per_page=100` on the selected
+host's API. Omit `state` and `classification` for all alerts the deployment
+exposes. Note any unknown malware coverage. Reject redirects and rebuild each
+page request on the same API origin and repository endpoint with the original
+filters. [Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository).
### Preview the report
@@ -48,6 +52,8 @@ codex-security publish findings "$report" --to local --repository . \
--provider github --source-key "$source_key" --dry-run --format json
```
+### Save and verify
+
Check the alert numbers, packages and manifest paths. The repository must
match a configured network remote when available. If the checkout has only
filesystem remotes or no remote, verify the export belongs to it. Then
diff --git a/docs/scanner-imports/github-security-advisories.md b/docs/scanner-imports/github-security-advisories.md
index 6742f5a43..a56276d20 100644
--- a/docs/scanner-imports/github-security-advisories.md
+++ b/docs/scanner-imports/github-security-advisories.md
@@ -17,14 +17,20 @@ source_key="${GH_HOST:-github.com}/$repo/security-advisories"
```
**Saved report.** Set `report=/private/path/advisories.json` if you already
-have the collector's complete JSON array.
+have the collector's complete JSON array. Continue with [Preview the report](#preview-the-report).
-**Export from GitHub.** Sign in to the selected host with `gh auth login`.
-Choose a repository or global export. Use a private temporary directory
-outside the checkout. Omit output filters, token limits and `--full-output`
-so the reader gets the complete array.
+### Export from GitHub
-For published repository advisories, run the command below. To list another
+Sign in to the selected host with `gh auth login`.
+Choose [repository disclosures](#repository-disclosures) for advisories issued
+by this repository or [global advisories](#global-advisories) to investigate
+specified GHSA IDs in the checkout. Use a private temporary directory outside
+the checkout. Omit output filters, token limits and `--full-output` to keep
+the collector's complete array.
+
+#### Repository disclosures
+
+The collector lists published advisories by default. To list another
state, add `--github-state draft`, `triage` or `closed`. To select specific
IDs, repeat `--github-advisory GHSA-xxxx-xxxx-xxxx` and omit `--github-state`.
Private advisories require repository advisory read permission and access to
@@ -37,7 +43,9 @@ out=$(mktemp -d) &&
report="$out/advisories.json"
```
-For global advisories, supply at least one GHSA ID. The repository argument
+#### Global advisories
+
+Supply at least one GHSA ID. The repository argument
names the repository where you'll investigate the advisory.
```sh
@@ -48,13 +56,15 @@ out=$(mktemp -d) &&
report="$out/advisories.json"
```
-**Preview the report.**
+### Preview the report
```sh
codex-security publish findings "$report" --to local --repository . \
--provider github --source-key "$source_key" --dry-run --format json
```
+### Save and verify
+
Check the GHSA IDs and whether each advisory came from the repository or the
global database. Repository disclosures must match a comparable local Git
remote when available, or the selected Cloud repository. If the preview
@@ -67,5 +77,17 @@ share a GHSA ID and source key. A global advisory has no source repository.
Compare the affected package ranges with the versions installed in your
checkout to decide whether the advisory applies.
-To collect with the SDK instead of `gh`, pass `githubHost` and a `githubToken`
-for that host. [Advisory SDK examples](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately)
+If you can access a draft repository advisory, selecting its exact GHSA ID
+can return it. A collection failure produces no partial selection.
+[GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
+
+## Use the SDK
+
+Collect the advisories with `importGitHubAdvisories()`. For Cloud,
+pass `normalizeGitHubAdvisories(advisories, "cloud")` to
+`prepareNormalizedExternalPublication()`. For local storage, pass
+`normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
+`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
+`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
+records. Both forms require `repository: "OWNER/REPO"` as source or target context.
+Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
diff --git a/docs/scanner-imports/inspector.md b/docs/scanner-imports/inspector.md
index 7e75fd4af..29b7de115 100644
--- a/docs/scanner-imports/inspector.md
+++ b/docs/scanner-imports/inspector.md
@@ -8,8 +8,8 @@ findings are excluded.
[Enable external imports](README.md#preview-a-report) and open the matching
checkout. Verify the repository's Git URL in your SCM integration. If
-Inspector identifies the repository by project ARN, set `VERIFIED_PROJECT_ARN`
-to the full ARN you verified there.
+the report identifies the repository only by an Inspector project ARN, verify
+that full ARN against the same URL in the SCM integration before importing.
**Saved report.** Use a complete repository export or select full native rows
by ARN within its `findings` array. Set `report` and skip to the preview.
@@ -55,13 +55,14 @@ Combine every batch's fully paginated `findings` array in one
### Import and verify
-Preview the report with your verified Git URL and source key. If the native
-findings already include the matching Git URL, omit `--inspector-project-arn`.
+Preview the report with the verified Git URL and a source key for the repository.
+This example assumes the native findings identify the repository by URL. For
+ARN-only findings, add `--inspector-project-arn FULL_PROJECT_ARN` using the ARN
+you independently matched to that URL.
```sh
codex-security publish findings "$report" --to local --repository . \
--provider inspector --source-repository-url https://github.com/example/project \
- --inspector-project-arn "$VERIFIED_PROJECT_ARN" \
--source-key inspector/account-alias/us-east-1/example/project \
--dry-run --format json
```
@@ -75,14 +76,13 @@ To save the selected findings in your local workbench, remove `--dry-run` and co
Sign in to a workspace with the GitHub repository connected and private
Inspector imports enabled. Preview the same file and source key, using your
-connected repository URL. Include the verified project ARN if the local
-preview required it.
+connected repository URL. If the local preview required a project ARN, add
+`--inspector-project-arn` with the same verified ARN to the command below.
```sh
repo=https://github.com/example/project
codex-security publish findings "$report" --to cloud --repository "$repo" \
--provider inspector --source-repository-url "$repo" \
- --inspector-project-arn "$VERIFIED_PROJECT_ARN" \
--source-key inspector/account-alias/us-east-1/example/project \
--dry-run --format json
```
diff --git a/docs/scanner-imports/opengrep.md b/docs/scanner-imports/opengrep.md
index b3112526a..5705248e5 100644
--- a/docs/scanner-imports/opengrep.md
+++ b/docs/scanner-imports/opengrep.md
@@ -36,8 +36,11 @@ codex-security publish findings "$opengrep_report" --to local --repository . \
```
Check the findings, exclusions and `report.errors`, even if the findings list
-is empty. A zero-result report with scanner errors fails the import. Keep `--provider opengrep`
-when you [save locally or publish to Cloud](README.md#save-or-publish-and-verify).
+is empty. A zero-result report with scanner errors fails the import. In the
+Cloud preview, check `excluded` again. If the traces grouped at one occurrence
+exceed the 256 KiB evidence limit, Cloud excludes that entire occurrence.
+Keep `--provider opengrep` for both destinations.
+[Save or publish and verify](README.md#save-or-publish-and-verify).
## Provider identity and evidence
@@ -48,9 +51,7 @@ record. [Imported evidence](schema-guide.md)
The reader groups traces at the same occurrence. It keeps the rule level,
snippets, ignored state and fingerprints when present. Severity is `unknown`
-because OpenGrep levels such as `ERROR` describe rule matches. Cloud excludes
-the whole occurrence if individually valid traces together exceed its 256 KiB
-evidence limit.
+because OpenGrep levels such as `ERROR` describe rule matches.
## Diagnostics and coverage
diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.md
index da13da9ae..d9addae57 100644
--- a/docs/scanner-imports/schema-guide.md
+++ b/docs/scanner-imports/schema-guide.md
@@ -7,21 +7,20 @@ mean and how to interpret the result.
## Choose the record and source key
-Private Cloud imports identify a record by its importing owner, provider, source
-key and vendor occurrence ID. Use a stable key for the vendor project or
-repository where those occurrence IDs are unique. Changing the assessment
-target preserves the record’s identity. The preview shows the format, size and
-digest of the report the CLI will upload. The receipt identifies a private job.
-Explicit assessment and publication produce a shared finding.
-
-The repository publisher identifies a record by destination repository,
-provider, source key and source finding ID. Use the same source key for each
-export of the same stream, such as an organization, project and branch. A
-date or run ID in the key creates a new set of records on each run.
-
-The reader derives the source finding ID from the export. The differences matter
-when a finding moves, an advisory affects several packages, or the export format
-changes.
+Keep the same provider and source key for later exports of the same vendor
+project and finding family. For example, use
+`github.com/OWNER/REPO/dependabot` for Dependabot alerts. An updated local import
+under that key replaces evidence for its existing record. A key containing
+today's date would create another record for the same alert.
+
+| Destination | What identifies the record |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Local workbench | The checkout path, stored provider, source key and source finding ID. For a repeat import, reuse the exact repository path and source key in the preview. |
+| Private Cloud inbox | The importing owner, provider, source key and vendor occurrence ID. The suggested repository for assessment can change without creating another record. The receipt identifies the private import job. |
+| Cloud repository publisher | The destination repository, provider, source key and source finding ID. |
+
+Each reader derives the source finding ID from the export. The table shows
+which changes can give an occurrence a different ID.
| Report | What identifies one record |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -33,6 +32,7 @@ changes.
| [GitHub advisories](github-security-advisories.md) | Host, repository or global scope, and GHSA ID. This identifies a disclosure. Check installed packages separately. |
| [Trivy](trivy.md) | Analyzer, advisory, package name, target and package path when available. Use the same source key for a repository, project and branch. |
| [Snyk Open Source](snyk.md) | Native CLI JSON distinguishes manifest, package manager, advisory, package name and version, and dependency path. Plugin and SARIF reports use different identities. |
+| [Snyk monitored project](snyk.md#existing-issues-from-snyk) | API origin, organization, project, product and issue key. |
| [Black Duck SCA](blackduck.md), [Veracode Static Analysis](veracode.md) | Black Duck combines project version, component version, origin and advisory identity. Veracode scopes a native issue ID to its API origin, application and context. |
| [Semgrep CLI or CI reports](semgrep.md), [OpenGrep](opengrep.md) | Semgrep prefers a fingerprint and falls back to rule, path and range. OpenGrep groups traces by rule, path and range. Both store provider `semgrep`. Use a separate OpenGrep source key. |
| [Semgrep Guardian selections](semgrep.md#import-selected-guardian-findings) | Deployment, repository name, Guardian tool, full ref and exact string ID. Guardian records stay separate from Web API occurrences. |
@@ -75,7 +75,12 @@ readers also apply the Cloud size limit to the evidence they return.
repository path from the preview. Each record includes
`sourceKey`, `sourceFindingId`, `version`, `evidence` and `assessment`.
-**Repository publisher.** Each item includes a `source_finding_id` and an `expected_version`.
+**Private Cloud inbox.** Check the format, size and digest under
+`privateImport` in the preview, then inspect the job receipt for errors and
+unprocessed findings. Open a finding in the inbox to assess it and publish
+the assessment when you're ready to share it.
+
+**Cloud repository publisher.** Each item includes a `source_finding_id` and an `expected_version`.
Check the per-item result for conflicts. The receipt's source-report,
observation and canonical-finding IDs identify Cloud records. Read the source
report for the imported evidence.
diff --git a/docs/scanner-imports/semgrep.md b/docs/scanner-imports/semgrep.md
index 5007c96d5..f3bb3b8f7 100644
--- a/docs/scanner-imports/semgrep.md
+++ b/docs/scanner-imports/semgrep.md
@@ -1,17 +1,18 @@
# Import Semgrep findings
-Use native Semgrep Code CLI or CI JSON to keep severity and available snippets.
-You can also import self-contained Semgrep SARIF 2.1.0. Either format can be
-gzipped. For selected SAST findings from the Platform API, use the
-[local SDK example](#import-selected-semgrep-platform-sast-findings-with-the-sdk).
+[Enable external imports](README.md#preview-a-report), then choose the report or
+account you have. Each route has a different source of finding IDs.
-## Quick start
+| Starting point | What to collect | Destination |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| [CLI or CI report](#quick-start) | A Code-only JSON or self-contained SARIF 2.1.0 file, optionally gzipped. Native JSON keeps Semgrep severity and available snippets. | Local or Cloud |
+| [Guardian in Codex](#import-selected-guardian-findings) | Selected Code or Supply Chain findings through the connected Guardian account. | Local only |
+| [Selected Web API IDs](#existing-platform-findings) | Original project response and SAST findings pages for one full Git ref. Use the SDK to save a selection or [import it directly](#import-selected-semgrep-platform-sast-findings-with-the-sdk). | Local or Cloud |
+| [Whole Platform project](#collect-a-platform-project-and-branch) | All findings for one project, full ref and product using a Web API token. | Local or Cloud |
-In Codex, [import selected Guardian findings](#import-selected-guardian-findings) with your existing Semgrep sign-in.
-For a whole project and ref, use the [Web API collector](#collect-a-platform-project-and-branch).
+## Quick start
-[Enable external imports](README.md#preview-a-report). From the scanned checkout
-root, choose a saved report or run Semgrep in the same shell.
+From the scanned checkout root, choose a saved report or run Semgrep in the same shell.
**Saved report.** Set the path to your Code report. For a `semgrep ci`
artifact, check that the job scanned only Code. The policy and baseline
@@ -46,9 +47,35 @@ Check the findings, exclusions and source URL. If the preview has no accepted
findings, verify the URL against the checkout's Git remote yourself. Keep the
same URL and key when you [save locally or publish to Cloud](README.md#save-or-publish-and-verify).
+## Evidence and identity
+
+Native JSON retains the result, rule, CWE IDs, range, snippets and ignored
+state when present. SARIF retains the selected rule and result, including
+traces and fixes. SARIF `error` imports as high even if Semgrep assigned
+critical severity. Check Cloud exclusions for deeply nested traces.
+[Semgrep output fields](https://docs.semgrep.dev/semgrep-appsec-platform/json-and-sarif)
+
+The match ID comes from JSON `extra.fingerprint` or SARIF `matchBasedId/v1`.
+Under the same source key and repository, the fingerprint lets you update a
+match when it moves. If the fingerprint is missing or says `requires login`,
+the ID comes from the rule, literal path and range. Moving that match
+creates a new record. [Imported evidence and identity](schema-guide.md)
+
+For CLI/CI JSON and SARIF, use SAST-only rules. The reader excludes results
+it recognizes as Supply Chain or Secrets, but SARIF can omit product metadata.
+Scan errors or an unsuccessful SARIF invocation stop the import. Direct artifact URIs and native
+`%SRCROOT%` paths can supply locations. Indexed artifacts and unresolved bases
+stay in the raw evidence and need a fingerprint for identity. Keep the original
+report for run-wide inventories and timing.
+
+If you call the JSON or SARIF normalizer from the SDK, pass `sourceRepositoryUrl`.
+When calling `prepareNormalizedLocalImport` directly, pass the original SARIF
+repository references in the third argument's `sourceRepositories`. Use
+`{ url, platform: "github" }` for a verified custom GitHub host.
+
## Import selected Guardian findings
-Enable [external imports](README.md#preview-a-report) and sign in to
+Guardian captures can be saved only to the local workbench. Sign in to
[Semgrep Guardian for Codex](https://docs.semgrep.dev/semgrep-guardian/quickstart).
Ask Codex to import the selected Code or Supply Chain findings from Guardian
into the local workbench. Specify the deployment, repository and full Git ref.
@@ -91,7 +118,7 @@ await writeFile("guardian.json", JSON.stringify(capture), {
});
```
-Preview before confirming the import. Use the same file and source key on replay.
+Preview the local import. After review, repeat the command without `--dry-run` and confirm. Reuse the same file and source key for a retry.
```sh
codex-security publish findings /path/to/private/guardian.json --provider semgrep \
@@ -111,16 +138,14 @@ preserving every digit.
## Existing Platform findings
-Use the SDK to select exact Web API IDs from **Semgrep Code (SAST)** when you
-have original Web API responses. For this format, save the native
+Use these steps to select individual SAST findings by their Web API IDs.
+With a read-authorized Web API token, save the native
[project response](https://docs.semgrep.dev/api-reference/v1/projectsservice/get-project-details)
and the [Findings API pages](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings)
for that deployment, project ID and fully qualified Git ref (for example,
`refs/heads/release` or `refs/tags/release`), using `issue_type=sast` and
-`dedup=false`. Use a Web API token with read access. Read through the pages
-until you have the requested IDs. Use a project with an HTTP(S) repository URL.
-For Git fetch URLs on an IP address, use its canonical spelling in the checkout
-(for example, `127.0.0.1` or `[::1]`) so the HTTP host identifies the same source.
+`dedup=false`. Read through the pages until you have the requested IDs. Use a
+project with an HTTP(S) repository URL.
Each selected finding must match the requested ref. When the finding includes
a repository URL or project ID, each must match the selected project. If the URL
is absent, the native project ID and full repository name must match the decoded
@@ -129,13 +154,9 @@ path of the project URL.
Pass the response text directly to the selector to preserve numeric IDs and
other numeric evidence exactly. Keep the responses and selection together in a
private directory outside the checkout. Run this example in that directory
-with the SDK installed. Local preview compares the project URL with Git’s
-named fetch URLs offline. If a checkout only has legacy or unreadable Git remote
-metadata, configure a normal named fetch URL first, for example
-`git remote add scanner-origin <verified-url>`. Checkouts with empty or absent
-legacy remote directories can also use Git's default fetch source. With legacy
-metadata present, use a named remote with a nonempty final URL entry. The local
-Git and SSH clients control SSH command overrides and DNS routing.
+with the SDK installed. Local preview compares the project URL with the
+checkout's fetch URLs offline. If it cannot read the checkout's legacy remote
+metadata, add a named fetch URL you have verified against that project.
```js
import { readFile, writeFile } from "node:fs/promises";
@@ -154,228 +175,51 @@ await writeFile("selected.json", JSON.stringify(selected), {
});
```
-Preview and import the saved selection into the local workbench:
+From the directory that contains `selected.json`, preview the saved selection for the local checkout.
```sh
-codex-security publish findings /path/to/private/selected.json --to local --provider semgrep \
- --repository /path/to/project --source-key example/project/release/platform --dry-run
+codex-security publish findings selected.json --to local --provider semgrep \
+ --repository /path/to/project --source-key example/project/release/platform --dry-run --format json
```
-After review, repeat without `--dry-run` and confirm the import. Reusing the
-same source key updates the same records, keyed by deployment, project ID,
-product, ref and finding ID. Semgrep's native signed 64-bit IDs match across the SDK
-and file workflows. For synthetic IDs above that range, the two workflows can
-produce different keys, even from a new capture. To replay those IDs, use the
-same workflow and preserve the original ID spelling and JSON type (number or
-string).
-
-Replay preserves the exact ref of an existing selection, including an older
-short ref. The archive reader compares the stored ref as literal identity text
-and never evaluates it as a Git revision. For URL-less rows with a matching
-native repository ID and ref, the saved-file reader also accepts the complete
-percent-encoded repository path. New captures require the decoded path.
-Importing the same findings reports unchanged
-records even if the API reordered JSON object keys. Use a separate source key
-for CLI scans. The selected native finding is retained as JSON text in
-`source_data.semgrepPlatformFindingJson`, including locations that cannot be mapped to the repository.
-Projected code locations retain the original spelling of a valid relative
-`location.file_path`, including literal backslashes. The API row does not
-identify the path convention. For a custom GitHub Enterprise host, supply the trusted
-repository URL and `platform: "github"` in the SDK `sourceRepositories` option
-when selecting and preparing the records. For an independently known self-managed
-GitLab instance, `platform: "gitlab"` allows its HTTPS web and clone URLs to
-differ by the usual `.git` suffix. For an internationalized hostname, use its
-ASCII (Punycode) spelling in the Git SSH remote. OpenSSH can send the literal
-UTF-8 hostname to DNS while the HTTPS project URL uses its ASCII spelling.
-
-When passing normalized findings to the SDK, keep each generated Semgrep
-`source_finding_id` with the native row it identifies. To migrate a row to a
-caller-managed identity, use an opaque ID of your own. The generated Semgrep ID
-requires the original scoped evidence on every import.
-
-In a marked Platform export or selection, a partial legacy v1 object in
-`source_data.finding` must retain its original collection scope when it
-contains a repository ID, URL or name, a `ref` value (including `null`), or a
-recognized `product` or `issue_type` (`sast`, `code`, `sca`, or `ai_sast`).
-A non-null `found_dependency` or `vulnerability_identifier` also identifies
-a Supply Chain finding, even when the row omits its product.
-Keep the deployment, project, ref and product alongside the native finding,
-including when you change its storage ID. For rows with canonical
-`source_data.semgrepPlatformFindingJson`, the SDK checks that serialized
-native finding. If unrelated SDK metadata uses the same v1 fields, move it to
-another key such as `source_data.ticket`, or submit those rows in an ordinary
-normalized batch without the Platform report marker or scope.
-
-To publish the selection to Cloud, use the same file and source key:
+For Cloud, preview the same file and source key against the connected repository.
```sh
codex-security publish findings selected.json --to cloud --provider semgrep \
- --repository https://github.com/example/project --source-key example/project/release/platform --dry-run
+ --repository https://github.com/example/project --source-key example/project/release/platform --dry-run --format json
```
-The publisher checks the original project's repository against the authorized destination, including
-Supply Chain findings with no typed repository field. After reviewing the
-preview, repeat without `--dry-run`.
-
-New marked approvals that include caller-managed rows record the collection
-scope for retry. On older approvals, the publisher checks the repository and
-any scope retained by the original native records. A caller-managed row can
-lack the original collection scope. Changing supplemental display metadata on
-a retry cannot change the approved request bytes, account or destination.
+Check the repository, finding IDs and exclusions for the destination you chose.
+Cloud verifies the project's repository. After review, repeat the matching
+command without `--dry-run` and confirm. [Verify the import](README.md#verify-the-import).
-To preview a Cloud publication in the SDK, append this to the script that
-created `selected`. Set `repository` to the verified URL of the destination.
+To preview the saved file with the SDK, run this in the same private directory.
+After checking the destination and exclusions, call `await publication.publish()`
+on the prepared object to confirm.
```js
-import {
- normalizeSemgrepPlatformFindings,
- prepareNormalizedExternalPublication,
-} from "@openai/codex-security";
+import { prepareExternalPublication } from "@openai/codex-security";
-const repository = "https://github.com/example/project";
-const findings = normalizeSemgrepPlatformFindings(
- selected,
- repository,
- "cloud",
-);
-const publication = await prepareNormalizedExternalPublication(findings, {
+const publication = await prepareExternalPublication("selected.json", {
provider: "semgrep",
- repository,
+ repository: "https://github.com/example/project",
sourceKey: "example/project/release/platform",
});
console.log(JSON.stringify(publication.preview, null, 2));
```
-Review the destination, findings and exclusions. To publish the approved
-selection, call `await publication.publish()` on the prepared object. Reuse
-the same source key for subsequent imports.
-
-## Collect a Platform project and branch
-
-With a Web API token in `SEMGREP_APP_TOKEN`, collect all findings returned for a
-project, exact ref and product. The collector looks up the project ID, requests
-every page with server-side deduplication disabled, and stops on a failed or
-overlapping page. Offset pagination does not provide a point-in-time snapshot.
-For a multi-page result the collector also checks whether the first page's
-membership has changed. Retry the collection if it reports a change.
-
-On HTTP 429, the collector retries the same GET once if `Retry-After` specifies
-a wait of 10 seconds or less, in whole seconds or as an HTTP date. Zero or a
-past date triggers an immediate retry. Cancellation stops the wait. Failed requests report
-the HTTP status and up to 64 KiB of the vendor response.
-
-A finding that identifies its repository only by name can use the project name,
-the Git URL path, or the final path component of either. For any other name,
-at least one finding in the collection must pair that name with the project's
-repository ID or a matching repository URL. That finding can appear on any
-page. Collection fails if the name has no such match. When one finding proves another
-finding’s alias, the importer saves the verified label and resolved project ID in
-`source_data.repositoryWitnessJson` on the name-only finding. The proving finding
-retains its original repository fields in `source_data.semgrepPlatformFindingJson`.
-
-SDK callers can pass a verified GitHub Enterprise repository as
-`sourceRepositories: [{ url, platform: "github" }]` to
-`collectSemgrepPlatformFindings` and the local reader. The reference must match
-the selected project. It allows equivalent GitHub path casing, `.git` suffixes
-and supported SSH URLs on that host.
-
-Run the following commands from a trusted working directory outside the project
-checkout. Each collection gets a new owner-only file. A failed collection
-leaves earlier exports available for replay.
-
-```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-report=$(mktemp ./semgrep-backlog.XXXXXX) &&
- codex-security import semgrep example/project --semgrep-deployment example \
- --semgrep-ref refs/heads/topic --semgrep-product sast --format json > "$report" &&
- codex-security publish findings "$report" --to local --repository /path/to/project \
- --provider semgrep --source-key example/project/topic --dry-run --format json
-```
-
-To preview this saved backlog in Cloud, keep its source key and choose the authorized repository.
-
-```sh
-codex-security publish findings "$report" --to cloud --provider semgrep \
- --repository https://github.com/example/project --source-key example/project/topic --dry-run
-```
-
-Use `--semgrep-product sca` for Supply Chain or `ai_sast` for AI-powered
-detection. The default is `sast`. Use `--source-repository-url` on collection
-when the project has no repository URL. The report records that mapping in
-`sourceRepositoryUrl`, and stored finding evidence retains a null native project URL.
-For SSH projects, the report stores the original address in `nativeProjectUrl` and the resolved HTTP(S) address in `project.url`.
-It records any supplied mapping separately. Save the complete output from a successful
-command. The importer checks the recorded finding count and repository/ref
-claims. It retains each original finding as JSON text so large IDs survive replay. The reader also accepts saved v1 project exports with native object rows and decimal type witnesses.
-
-To import a collected backlog with the TypeScript SDK, pass the normalized
-report to the local importer. Reuse the source key when replaying the report.
-You may filter the normalized findings array and retain the original read count.
-Only submitted findings are imported.
-
-```ts
-const findings = normalizeSemgrepPlatformFindings(report);
-const prepared = await prepareNormalizedLocalImport(findings, {
- provider: "semgrep",
- sourceKey: "example/project/topic",
- repository: checkout,
-});
-await prepared.import();
-```
-
-Supply Chain findings include native package versions, matching fix recommendations
-and advisory IDs when Semgrep supplies them. With the same source key, importing identical Code findings that qualify for individual
-selection reports them as unchanged when switching between a selection and a full collection.
-See the [Semgrep Findings API](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings).
-
-If you previously imported a v1 export with the development version that stored
-each finding as an object, the first replay updates the existing SQLite record
-to store the native finding as JSON text. Its local ID and source finding ID stay
-the same, and its version increases once. Replaying the same evidence again
-reports it as unchanged.
-
-## Evidence and identity
-
-Native JSON retains the result, rule, CWE IDs, range, snippets and ignored
-state when present. SARIF retains the selected rule and result, including
-traces and fixes. SARIF `error` imports as high even if Semgrep assigned
-critical severity. Check Cloud exclusions for deeply nested traces.
-[Semgrep output fields](https://docs.semgrep.dev/semgrep-appsec-platform/json-and-sarif)
-
-The match ID comes from JSON `extra.fingerprint` or SARIF `matchBasedId/v1`.
-Under the same source key and repository, the fingerprint lets you update a
-match when it moves. If the fingerprint is missing or says `requires login`,
-the ID comes from the rule, literal path and range. Moving that match
-creates a new record. [Imported evidence and identity](schema-guide.md)
-
-For CLI/CI JSON and SARIF, use SAST-only rules. The reader excludes results
-it recognizes as Supply Chain or Secrets, but SARIF can omit product metadata.
-Scan errors or an unsuccessful SARIF invocation stop the import. Direct artifact URIs and native
-`%SRCROOT%` paths can supply locations. Indexed artifacts and unresolved bases
-stay in the raw evidence and need a fingerprint for identity. Keep the original
-report for run-wide inventories and timing.
-
-If you call the JSON or SARIF normalizer from the SDK, pass `sourceRepositoryUrl`.
-When calling `prepareNormalizedLocalImport` directly, pass the original SARIF
-repository references in the third argument's `sourceRepositories`. Use
-`{ url, platform: "github" }` for a verified custom GitHub host.
+If you already have an in-memory selection, call
+`normalizeSemgrepPlatformFindings(selected, repositoryUrl, "cloud")` and
+pass the result to `prepareNormalizedExternalPublication()`.
## Import selected Semgrep Platform SAST findings with the SDK
-**Collect the selection.** Request `issue_type=sast` and save the original
-project lookup and each findings page as response text. On any page with a
-selected ID, the SDK checks every row for conflicting product information.
-When rows contain only fields shared across products, the request filter
-establishes that the findings are SAST.
+Use the [project and SAST responses](#existing-platform-findings) described above.
+On each page containing a selected ID, the SDK checks every row for conflicting
+product information. Where rows contain only shared fields, the request's
+`issue_type=sast` filter establishes the product.
-Use the IDs from the original Web API results for this SDK import. The SDK
-accepts saved responses from an authorized operator. Fetching new Web API
-responses requires read access. For selections made in Codex, use the
-[Guardian workflow](#import-selected-guardian-findings).
-[Findings Web API](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings)
-
-**Check the project and ref.** Use the full ref from the findings, such as
-`refs/heads/main` or `refs/tags/v1`. Verify the checkout's credential-free
+**Check the project and ref.** Use the full ref from the findings. Verify the checkout's credential-free
HTTP(S) URL. The native `project.url` must match it exactly. Check the
repository fields on each selected finding.
@@ -403,19 +247,19 @@ const [checkout, projectFile, ...findingsFiles] = process.argv.slice(2);
const sourceRepositoryUrl = "https://github.com/example/project";
const selected = normalizeSelectedSemgrepPlatformFindings({
deployment: "example",
- ref: "refs/heads/main",
+ ref: "refs/heads/release",
sourceRepositoryUrl,
projectResponse: await readFile(projectFile, "utf8"),
findingsResponses: await Promise.all(
findingsFiles.map((file) => readFile(file, "utf8")),
),
- findingIds: ["123"],
+ findingIds: ["101", "103"],
});
const prepared = await prepareNormalizedLocalImport(
selected,
{
provider: "semgrep",
- sourceKey: "example/project/platform/main",
+ sourceKey: "example/project/release/platform",
repository: checkout,
},
{ sourceRepositories: [{ url: sourceRepositoryUrl }] },
@@ -444,3 +288,123 @@ spellings (such as `2` and `2.0`) leave the stored record unchanged.
The preview excludes findings that lack both a native rule name and a message.
Only repository-relative files become locations. URI-like and directory-only
paths stay in the native evidence.
+
+## Collect a Platform project and branch
+
+With a Web API token in `SEMGREP_APP_TOKEN`, collect all findings returned for a
+project, exact ref and product. The collector looks up the project ID, requests
+every page with server-side deduplication disabled, and stops on a failed or
+overlapping page. Offset pagination does not provide a point-in-time snapshot.
+For a multi-page result the collector also checks whether the first page's
+membership has changed. Retry the collection if it reports a change.
+
+[Troubleshoot collection errors and rate limits](README.md#troubleshoot-semgrep-and-snyk-collection).
+
+Run the following commands from a trusted working directory outside the project
+checkout. Each collection gets a new owner-only file. A failed collection
+leaves earlier exports available for replay.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+report=$(mktemp ./semgrep-backlog.XXXXXX) &&
+ codex-security import semgrep example/project --semgrep-deployment example \
+ --semgrep-ref refs/heads/topic --semgrep-product sast --format json > "$report" &&
+ codex-security publish findings "$report" --to local --repository /path/to/project \
+ --provider semgrep --source-key example/project/topic --dry-run --format json
+```
+
+To preview this saved backlog in Cloud, keep its source key and choose the authorized repository.
+
+```sh
+codex-security publish findings "$report" --to cloud --provider semgrep \
+ --repository https://github.com/example/project --source-key example/project/topic --dry-run --format json
+```
+
+Check the finding IDs and exclusions, then [confirm the import for the chosen
+destination](README.md#save-or-publish-and-verify).
+
+Use `--semgrep-product sca` for Supply Chain or `ai_sast` for AI-powered
+detection. The default is `sast`. Use `--source-repository-url` on collection
+when the project has no repository URL. The report records that mapping in
+`sourceRepositoryUrl`, and stored finding evidence retains a null native project URL.
+For SSH projects, the report stores the original address in `nativeProjectUrl` and the resolved HTTP(S) address in `project.url`.
+It records any supplied mapping separately. Save the complete output from a successful
+command. The importer checks the recorded finding count and repository/ref
+claims. It retains each original finding as JSON text so large IDs survive replay. The reader also accepts saved v1 project exports with native object rows and decimal type witnesses.
+
+A finding that identifies its repository only by name can use the project name,
+the Git URL path, or the final path component of either. For any other name,
+at least one finding in the collection must pair that name with the project's
+repository ID or a matching repository URL. That finding can appear on any
+page. Collection fails if the name has no such match. When one finding proves another
+finding’s alias, the importer saves the verified label and resolved project ID in
+`source_data.repositoryWitnessJson` on the name-only finding. The proving finding
+retains its original repository fields in `source_data.semgrepPlatformFindingJson`.
+
+SDK callers can pass a verified GitHub Enterprise repository as
+`sourceRepositories: [{ url, platform: "github" }]` to
+`collectSemgrepPlatformFindings` and the local reader. The reference must match
+the selected project. It allows equivalent GitHub path casing, `.git` suffixes
+and supported SSH URLs on that host.
+
+To import a collected backlog with the TypeScript SDK, pass the normalized
+report to the local importer. Reuse the source key when replaying the report.
+You may filter the normalized findings array and retain the original read count.
+Only submitted findings are imported.
+
+```ts
+const findings = normalizeSemgrepPlatformFindings(report);
+const prepared = await prepareNormalizedLocalImport(findings, {
+ provider: "semgrep",
+ sourceKey: "example/project/topic",
+ repository: checkout,
+});
+await prepared.import();
+```
+
+Supply Chain findings include native package versions, matching fix recommendations
+and advisory IDs when Semgrep supplies them. With the same source key, importing identical Code findings that qualify for individual
+selection reports them as unchanged when switching between a selection and a full collection.
+See the [Semgrep Findings API](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings).
+
+When replaying v1 exports whose findings were stored as objects, the first
+replay converts the stored finding to JSON text and increments its version.
+Its local and source IDs stay the same.
+
+## Replay saved Platform findings
+
+Semgrep's native signed 64-bit finding IDs match across file and SDK imports.
+For synthetic IDs above that range, repeat the original workflow and preserve
+the ID's spelling and JSON type. A saved selection keeps its literal ref,
+including older short refs. For a row without a URL but with a matching
+project ID and ref, saved files also accept the complete percent-encoded
+repository path. New selections require the decoded path.
+
+**Repository mapping.** Local preview compares the project URL with the checkout's
+named fetch URLs. For an IP address, use its canonical spelling, such as
+`127.0.0.1` or `[::1]`. For an internationalized SSH hostname, use its ASCII
+(Punycode) spelling. A verified custom host can be supplied in the
+SDK's `sourceRepositories` option when selecting and preparing findings.
+Use `platform: "github"` for GitHub Enterprise or `platform: "gitlab"` for a
+self-managed GitLab instance. The latter allows the usual `.git` suffix.
+
+**Native evidence.** Each selection keeps the native row as JSON text under
+`source_data.semgrepPlatformFindingJson`, including locations that cannot be
+mapped to the checkout. A valid relative `location.file_path` preserves its
+spelling, including literal backslashes. Reordering JSON keys leaves stored
+evidence unchanged. Use a separate source key for CLI scans.
+
+**Normalized SDK records.** Keep each generated `source_finding_id` with its
+native row and original deployment, project, ref and product. If you assign
+your own opaque ID, retain that scope in a marked Platform batch. The SDK checks
+the serialized native row when present. In legacy v1 `source_data.finding`,
+repository fields, `ref` (even `null`), recognized `product` or `issue_type`,
+and non-null `found_dependency` or `vulnerability_identifier` can establish
+scope. Put unrelated metadata under a different key, such as
+`source_data.ticket`, or submit it in a batch without a Platform marker.
+
+**Cloud retries.** Cloud checks the original project's repository, including
+for Supply Chain findings without a typed repository field. New approvals
+retain the collection scope of caller-managed rows. Older approvals check
+the repository and the scope retained in their evidence. Retry the original
+input with the same account and destination. [Retry a Cloud submission](schema-guide.md#retry-a-cloud-submission).
diff --git a/docs/scanner-imports/snyk.md b/docs/scanner-imports/snyk.md
index a4c3d4357..95ba121aa 100644
--- a/docs/scanner-imports/snyk.md
+++ b/docs/scanner-imports/snyk.md
@@ -4,115 +4,13 @@ Prefer native `snyk test` JSON for dependency vulnerabilities. It keeps
individual dependency paths and remediation details. You can also import a
`snyk-findings-export/v1` plugin bundle or self-contained Open Source SARIF.
-For existing monitored projects, collect Open Source or Code issues through the Snyk Issues API.
+- **I have a file or want to scan my checkout.** [Preview a saved report](#quick-start).
+ Choose a separate source key for each file format. [Native CLI JSON](#native-cli-json)
+ · [Plugin export](#snyk-plugin-export) · [SARIF](#sarif-compatibility).
+- **I need issues from a monitored project.** [Collect from Snyk](#existing-issues-from-snyk)
+ with a read-authorized token. Both Open Source and Code projects are supported.
-## Existing issues from Snyk
-
-To import a monitored project's existing issues into the local workbench, set
-`SNYK_TOKEN` to a read-authorized token for the selected region. See the
-[Snyk API access requirements](https://docs.snyk.io/developer-tools/snyk-api/authentication-for-api)
-and [Issues API permissions](https://docs.snyk.io/developer-tools/snyk-api/reference/issues).
-Select the organization ID, project ID and source repository URL. Open Source
-is the default. For a Snyk Code project, add `--snyk-product code`. For a
-regional deployment, set `--snyk-api-origin` to its documented API origin.
-
-Run the commands from a trusted directory outside the project checkout. The
-example saves a fresh report there and imports it into the checkout at `./project`.
-
-```sh
-report=$(mktemp ./snyk-issues.XXXXXX) &&
- codex-security import snyk PROJECT_ID --snyk-org ORG_ID \
- --source-repository-url https://github.com/example/project \
- --format json > "$report" &&
- codex-security publish findings "$report" --to local --provider snyk \
- --source-key ORG_ID/PROJECT_ID --repository ./project --dry-run
-```
-
-Confirm the preview, then repeat the publish command without `--dry-run`.
-Collection reads open and resolved issues across all pages, including ignored issues.
-For Open Source it requests package vulnerabilities. For Code it requests code issues.
-The SDK's `collectSnykIssues` defaults to Open Source and returns the same report.
-Passing the configured `SNYK_TOKEN` explicitly retains its configured regional
-API origin. Pass independently verified `sourceRepositories` in its
-dependencies when a private repository uses an SSH target. The offline reader
-`readSnykFindings(path, "local")` accepts `snyk-rest-issues/v1` and
-`snyk-rest-issues/v2` reports from Snyk REST API version `2026-03-25`.
-The collector writes v2 and preserves the original project and issue evidence.
-For open Snyk Code issues from an SCM integration, both versions import
-repository-relative paths from open coordinates. V2 also imports each
-coordinate's reported start line when available. V2 keeps URI and SSH addresses
-in the original evidence and uses only repository file paths for code locations
-and package manifests. For resolved issues, closed
-coordinates, and projects monitored through the CLI or API, read the original
-location from `evidence.source_data.issue` in v1 or from the JSON text in
-`evidence.source_data.issueJson` in v2.
-
-On HTTP 429, the collector retries the same GET once if `Retry-After` specifies
-a wait of 10 seconds or less, in whole seconds or as an HTTP date. Zero or a
-past date triggers an immediate retry. Cancellation stops the wait. Failed requests report
-the HTTP status and up to 64 KiB of the vendor response.
-
-Use the same source key on later imports. The issue key within the API
-origin, organization, project and product identifies the finding. Replaying the
-same evidence leaves the version unchanged. Whitespace, object key order and
-equivalent JSON number spellings in v2 native records do not affect replay.
-JSON strings remain distinct from numbers. Importing a different capture for
-that issue updates the same row, even if the capture is older.
-
-To select a subset in the SDK, filter the normalized report’s `findings`
-array. Keep the report’s `snykRestContext` and each selected finding’s
-`source_finding_id` and `evidence.source_data`. Every hosted row must retain
-the native issue and its generated ID. The verified report context can supply
-the monitored project for a row that retains only its original issue. The Cloud
-preview includes the verified project and any captured target in the evidence it
-will publish.
-
-For a v1 row, keep `source_data.issue` and the original `source_data.numericFields`
-when present. If you trim the metadata, keep its matching entries for every
-`issue`, `project`, and `target` object you retain. V1 uses those entries to
-distinguish exact numbers from strings with the same spelling. For a v2 row,
-keep `source_data.issueJson`.
-The local workbench stores the verified project and target with that issue,
-so the stored row can be imported again. All selected issues must share the
-report’s API region, organization, project and product. Keep SCM-integrated
-findings separate from CLI- or API-monitored findings. If the report identifies
-a native target or its repository URL, retain that evidence in the selected
-project and target. Snyk’s optional integration relationship is retained when
-the target supplies it.
-
-SDK readers that define their own findings and IDs can use the ordinary
-normalized Snyk import with their own evidence and no hosted report context.
-
-The offline reader can interpret SCM aliases recorded in an archived project.
-Local import compares the source to the checkout’s configured external Git
-remotes. For a checkout with only filesystem remotes or none, the selected
-directory is the import destination.
-For private source-control hosts, use the same repository URL as the checkout.
-SDK callers that have independently verified a GitHub Enterprise or GitLab
-repository can pass its canonical HTTPS URL and platform to local or Cloud
-preparation. Cloud checks that source against the selected repository.
-This allows that repository's standard SSH clone URL and `.git` suffix. For
-example, a GitLab repository uses
-`sourceRepositories: [{ url: sourceRepositoryUrl, platform: "gitlab" }]`
-in the SDK dependencies. Use `platform: "github"` for GitHub Enterprise.
-When reading the saved file directly, pass the same verified sources as the
-third argument to `readSnykFindings(path, "local", sourceRepositories)`.
-
-To preview the saved issues in Cloud, use the same source key and an authorized repository:
-
-```sh
-codex-security publish findings "$report" --to cloud --provider snyk \
- --source-key ORG_ID/PROJECT_ID --repository https://github.com/example/project --dry-run
-```
-
-Review the preview and repeat without `--dry-run` to publish. The original Snyk
-project must match the selected Cloud repository. If Cloud accepted a request
-but the response was lost, repeat the same command to resume the saved request.
-
-For a new normalized SDK import, keep the original Snyk issue and project
-evidence alongside its generated finding ID. If you build a projection without
-that evidence, supply your own stable finding ID and the source repository URL.
-An already approved, pending request resumes with its saved evidence.
+Both routes support local and Cloud imports.
## Quick start
@@ -208,6 +106,115 @@ with direct URIs for any manifest locations. Indexed and base-relative
manifest locations are unsupported.
[Snyk Open Source SARIF formatter](https://github.com/snyk/cli/blob/main/src/lib/formatters/open-source-sarif-output.ts)
+## Existing issues from Snyk
+
+[Enable external imports](README.md#preview-a-report) and set
+`SNYK_TOKEN` to a read-authorized token for the selected region. See the
+[Snyk API access requirements](https://docs.snyk.io/developer-tools/snyk-api/authentication-for-api)
+and [Issues API permissions](https://docs.snyk.io/developer-tools/snyk-api/reference/issues).
+Select the organization ID, project ID and source repository URL. Open Source
+is the default. For a Snyk Code project, add `--snyk-product code`. For a
+regional deployment, set `--snyk-api-origin` to its documented API origin.
+
+Run the commands from a trusted directory outside the project checkout. The
+example saves a fresh report there and imports it into the checkout at `./project`.
+
+```sh
+report=$(mktemp ./snyk-issues.XXXXXX) &&
+ codex-security import snyk PROJECT_ID --snyk-org ORG_ID \
+ --source-repository-url https://github.com/example/project \
+ --format json > "$report" &&
+ codex-security publish findings "$report" --to local --provider snyk \
+ --source-key ORG_ID/PROJECT_ID --repository ./project --dry-run --format json
+```
+
+Check the repository, issue keys and exclusions. To save locally, repeat the
+publish command without `--dry-run` and confirm.
+
+To preview the saved issues in Cloud, use the same source key and an authorized repository:
+
+```sh
+codex-security publish findings "$report" --to cloud --provider snyk \
+ --source-key ORG_ID/PROJECT_ID --repository https://github.com/example/project --dry-run --format json
+```
+
+Review the preview and repeat without `--dry-run` to publish. The original Snyk
+project must match the selected Cloud repository. If Cloud accepted a request
+but the response was lost, repeat the same command to resume the saved request.
+
+Collection reads open and resolved issues across all pages, including ignored issues.
+For Open Source it requests package vulnerabilities. For Code it requests code issues.
+[Troubleshoot collection errors and rate limits](README.md#troubleshoot-semgrep-and-snyk-collection).
+
+### Monitored project evidence and SDK selection
+
+The SDK's `collectSnykIssues` defaults to Open Source and returns the same report.
+Passing the configured `SNYK_TOKEN` explicitly retains its configured regional
+API origin. Pass independently verified `sourceRepositories` in its
+dependencies when a private repository uses an SSH target. The offline reader
+`readSnykFindings(path, "local")` accepts `snyk-rest-issues/v1` and
+`snyk-rest-issues/v2` reports from Snyk REST API version `2026-03-25`.
+The collector writes v2 and preserves the original project and issue evidence.
+For open Snyk Code issues from an SCM integration, both versions import
+repository-relative paths from open coordinates. V2 also imports each
+coordinate's reported start line when available. V2 keeps URI and SSH addresses
+in the original evidence and uses only repository file paths for code locations
+and package manifests. For resolved issues, closed
+coordinates, and projects monitored through the CLI or API, read the original
+location from `evidence.source_data.issue` in v1 or from the JSON text in
+`evidence.source_data.issueJson` in v2.
+
+Use the same source key on later imports. The issue key within the API
+origin, organization, project and product identifies the finding. Replaying the
+same evidence leaves the version unchanged. Whitespace, object key order and
+equivalent JSON number spellings in v2 native records do not affect replay.
+JSON strings remain distinct from numbers. Importing a different capture for
+that issue updates the same row, even if the capture is older.
+
+To select a subset in the SDK, filter the normalized report’s `findings`
+array. Keep the report’s `snykRestContext` and each selected finding’s
+`source_finding_id` and `evidence.source_data`. Every hosted row must retain
+the native issue and its generated ID. The verified report context can supply
+the monitored project for a row that retains only its original issue. The Cloud
+preview includes the verified project and any captured target in the evidence it
+will publish.
+
+For a v1 row, keep `source_data.issue` and the original `source_data.numericFields`
+when present. If you trim the metadata, keep its matching entries for every
+`issue`, `project`, and `target` object you retain. V1 uses those entries to
+distinguish exact numbers from strings with the same spelling. For a v2 row,
+keep `source_data.issueJson`.
+The local workbench stores the verified project and target with that issue,
+so the stored row can be imported again. All selected issues must share the
+report’s API region, organization, project and product. Keep SCM-integrated
+findings separate from CLI- or API-monitored findings. If the report identifies
+a native target or its repository URL, retain that evidence in the selected
+project and target. Snyk’s optional integration relationship is retained when
+the target supplies it.
+
+SDK readers that define their own findings and IDs can use the ordinary
+normalized Snyk import with their own evidence and no hosted report context.
+
+The offline reader can interpret SCM aliases recorded in an archived project.
+Local import compares the source to the checkout’s configured external Git
+remotes. For a checkout with only filesystem remotes or none, the selected
+directory is the import destination.
+For private source-control hosts, use the same repository URL as the checkout.
+SDK callers that have independently verified a GitHub Enterprise or GitLab
+repository can pass its canonical HTTPS URL and platform to local or Cloud
+preparation. Cloud checks that source against the selected repository.
+This allows that repository's standard SSH clone URL and `.git` suffix. For
+example, a GitLab repository uses
+`sourceRepositories: [{ url: sourceRepositoryUrl, platform: "gitlab" }]`
+in the SDK dependencies. Use `platform: "github"` for GitHub Enterprise.
+When reading the saved file directly, pass the same verified sources as the
+third argument to `readSnykFindings(path, "local", sourceRepositories)`.
+
+For a new normalized SDK import, keep the original Snyk issue and project
+evidence alongside its generated finding ID. If you build a projection without
+that evidence, supply your own stable finding ID and the source repository URL.
+An already approved, pending request resumes with its saved evidence.
+
## Identities and provenance
Native JSON, plugin bundles and SARIF produce different source IDs. Give
@@ -216,5 +223,6 @@ plugin scan's `issueCount`, can update a stored snapshot of the same
occurrence. [Imported evidence and identity](schema-guide.md)
Known source Git URLs must match a comparable local remote when available,
-or the selected Cloud repository. Snyk Code, Container, IaC, SBOM results
-and hosted backlog responses use other formats.
+or the selected Cloud repository. For Snyk Code, use the
+[monitored project collector](#existing-issues-from-snyk). Container, IaC and
+SBOM results fall outside these import routes.
diff --git a/docs/scanner-imports/sonar.md b/docs/scanner-imports/sonar.md
index 8fddda6fe..e4cf36f84 100644
--- a/docs/scanner-imports/sonar.md
+++ b/docs/scanner-imports/sonar.md
@@ -1,8 +1,9 @@
# Import SonarQube Cloud findings
Use `import sonar` to collect security issues for one project and branch or
-pull request. Replay its saved capture without signing in to Sonar. For
-issue-search JSON, [preview the native export](#use-a-native-json-export).
+pull request. A live `--dry-run` writes a private capture and returns its path.
+Replay it without signing in to Sonar. If you already have issue-search JSON,
+[preview the native export](#use-a-native-json-export).
## Quick start
@@ -25,11 +26,14 @@ ref. For a pull request, replace `--sonar-branch main` with
Check the repository and ref. Compare the issue keys in
`local.findings[].source_finding_id` and any `local.excluded` entries with
-your selection. Keep the private path returned in `capture`.
+your selection. Keep the private path returned in `capture` to
+[save locally](#save-locally) or [save locally and publish to Cloud](#save-locally-and-publish-to-cloud).
## Import and verify
-**Save locally.** From the same checkout, pass the local preview's `capture`
+### Save locally
+
+From the same checkout, pass the local preview's `capture`
path. Omit `--yes` for an interactive prompt. In a script, use `--yes`
after review.
@@ -37,7 +41,9 @@ after review.
codex-security import sonar "/path/from/local-preview.json" --yes
```
-**Save locally and publish to Cloud.** [Sign in to Cloud](../../sdk/typescript/docs/cli.md#preview-and-publish)
+### Save locally and publish to Cloud
+
+[Sign in to Cloud](../../sdk/typescript/docs/cli.md#preview-and-publish)
on a deployment that accepts the `sonar` provider. Preview the connected
repository from the local capture.
diff --git a/docs/scanner-imports/trivy.md b/docs/scanner-imports/trivy.md
index e3bfe1a97..2e917139a 100644
--- a/docs/scanner-imports/trivy.md
+++ b/docs/scanner-imports/trivy.md
@@ -4,15 +4,19 @@ Use a saved Trivy schema-v2 JSON or gzip report from a repository or filesystem
## Preview the report
-Enable external imports and select the checkout that Trivy scanned. Set `--trivy-scan-root` to the scanned directory relative to the checkout, for example `.` for the whole checkout or `apps/web` for a subtree.
+[Enable external imports](README.md#preview-a-report). If you need a report,
+run `trivy fs --scanners vuln --format json --output /private/path/trivy.json .`
+from the checkout root. Use a private output directory outside the checkout.
+
+Set `--trivy-scan-root` to the directory Trivy scanned, relative to the checkout.
+Use `.` for the whole checkout or, for example, `apps/web` for a subtree.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings trivy.json.gz --to local --repository /path/to/checkout \
+codex-security publish findings /private/path/trivy.json --to local --repository /path/to/checkout \
--provider trivy --trivy-scan-root . --source-key example/project/main --dry-run --format json
```
-Check the repository, manifest paths, versions and exclusions in the preview. Keep the same source key across scans of the same project and branch. [Save locally, publish to Cloud and verify the import](README.md#save-or-publish-and-verify). Cloud requires a deployment that accepts the `trivy` provider.
+Check the repository, manifest paths, versions and exclusions in the preview. Keep the same source key across scans of the same project and branch. Cloud requires a deployment that accepts the `trivy` provider. [Save or publish and verify](README.md#save-or-publish-and-verify).
## Match the report to its checkout
@@ -29,4 +33,4 @@ Use credential-free repository URLs. If the importer reports ambiguous or confli
If a private-inbox upload is interrupted and the connected repository is renamed, check the existing job before retrying. The new catalog URL can fail the original report’s source check.
-If an earlier development build left a pending Cloud upload, verify the destination and finish it with that build. A change to finding IDs or evidence can prevent the newer build from recognizing the pending request.
+When changing CLI versions with a Cloud upload pending, finish the upload with the version that created it. A change to finding IDs or evidence can prevent another version from recognizing the request.
diff --git a/docs/scanner-imports/veracode.md b/docs/scanner-imports/veracode.md
index e15903568..e6042ff88 100644
--- a/docs/scanner-imports/veracode.md
+++ b/docs/scanner-imports/veracode.md
@@ -15,9 +15,10 @@ pages for your selection. Preserve each page's HAL links and pagination fields.
report=/private/path/policy-findings.json
```
-**Export from Veracode.** With read access to the application and Results API,
-save and configure the [export script](#export-findings-api-pages). Capture
-the path it prints when the export succeeds.
+**Export from Veracode.** You need Bash, `jq`, HTTPie with the Veracode HMAC
+plugin, and Veracode credentials with read access to the application and
+Results API. Configure the [export script](#export-findings-api-pages), then
+capture the path it prints when the export succeeds.
```sh
report=$(bash "/private/path/export-veracode.sh")
diff --git a/docs/scanner-imports/wiz.md b/docs/scanner-imports/wiz.md
index d02b03bac..966b830d9 100644
--- a/docs/scanner-imports/wiz.md
+++ b/docs/scanner-imports/wiz.md
@@ -13,7 +13,7 @@ repository package vulnerabilities.
**Saved report.** Choose the file for your repository and branch or build.
With a connected Wiz account, list findings for the repository and family,
then retrieve the selected records by Wiz finding ID. If a pull request
-scan event omits occurrence IDs, request a scoped native capture.
+scan event omits occurrence IDs, request a native export of the selected findings. Raw Code & Build Scan events contain scan metadata. Summaries and Wiz Issues use different formats.
**Export from Wiz.** In **Vulnerability Findings**, filter by repository,
branch or build, and findings where available. Choose **Save as → Report**,
@@ -33,7 +33,9 @@ codex-security publish findings "$report" \
Check the assets, builds and exclusions. For selected IDs, verify that
`findings[].source_finding_id` lists each requested occurrence once and no
-others, and that `excluded` is empty. Include the family prefix shown below.
+others, and that `excluded` is empty. Compare the exact IDs. A package uses
+the bare Wiz finding ID. SAST, repository secrets and IaC use the prefixes in
+the [format table](#finding-formats-and-ids).
[Save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify)
## Finding formats and IDs
@@ -53,7 +55,126 @@ repository, include all inventory pages' nodes under
`data.versionControlResources.nodes`. Keep the final page info for each
collection.
-**CSV and normalized JSONL.** Detailed package CSV requires a GitHub
-repository-branch URL and preserves each original cell. For other families,
-use their named JSON collection or map the fields to normalized JSONL.
-[Wiz format reference and repository mapping](../../plugins/codex-security/skills/publish-findings/references/wiz-import.md#finding-formats)
+## Package vulnerability inputs
+
+JSON can contain a single finding, an array of selected findings, a detailed
+vulnerability report or a complete `data.vulnerabilityFindings.nodes`
+collection. JSONL can hold one package record per line. Preserve `id`, `name`,
+`detailedName`, `vulnerableAsset.id` and `vendorSeverity` or `severity`, plus
+available package, image and repository metadata. Use the Wiz finding ID for
+identity. Many package occurrences can share a CVE.
+
+Detailed package CSV requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
+`CloudPlatform` and `CloudProviderURL`. The platform must be GitHub and the
+provider URL must identify a repository branch. That repository must match a
+comparable checkout remote, when present, or the selected Cloud repository.
+The same check applies when replaying parsed CSV rows as normalized JSONL.
+
+CSV rows use `ID` as their occurrence ID. Severity comes from `Severity`, then
+`VendorSeverity`, then `CVSSSeverity`. The reader preserves every cell under
+`source_data.row`, including extra columns and quoted multiline values. A Git tree URL does not establish the branch or revision. The last-detected time does not establish when the record was updated.
+Duplicate headers, malformed CSV, invalid UTF-8 and duplicate IDs among
+importable rows stop the import. Review any excluded rows.
+
+Raw package findings retain their reported severity and source data. Only
+repository-branch file paths become source locations. Container and workload
+paths stay in the vendor evidence. External network scans fall outside this
+mapping.
+
+## SAST, repository secrets, and IaC inputs
+
+Keep findings under the [named collections](#finding-formats-and-ids). Bare
+arrays of these families are ambiguous. An export can include several named
+collections. For secrets, the resource must have `type: "REPOSITORY_BRANCH"`.
+
+Each finding needs a verified repository URL. Keep its `repository.url` or
+include the matching inventory under `data.versionControlResources.nodes`.
+For secrets, the repository is under `resource.typedProperties.repository`.
+The reader joins on `repository.id` and takes `repository.url` from the
+matching inventory record. Inventory node IDs, `providerID`, names and Wiz
+UUIDs cannot serve as Cloud repository IDs. When the finding and inventory
+both supply a URL, they must agree. Cloud checks this source against the
+connected repository.
+
+Keep the inventory node's `platform` field. `GITHUB` allows case-insensitive
+repository matching on custom GitHub Enterprise hosts. Duplicate inventory
+entries for a repository ID must agree on platform and URL. Branch names are
+preserved literally.
+
+```json
+{
+ "data": {
+ "sastFindings": {
+ "nodes": [
+ {
+ "id": "finding-42",
+ "name": "Untrusted query construction",
+ "severity": "HIGH",
+ "repository": { "id": "source-repository-1" },
+ "filePath": "src/query.ts",
+ "startLine": 10,
+ "endLine": 12
+ }
+ ]
+ },
+ "versionControlResources": {
+ "nodes": [
+ {
+ "repository": {
+ "id": "source-repository-1",
+ "url": "https://github.com/example/project"
+ }
+ }
+ ]
+ }
+ }
+}
+```
+
+## Preserved evidence
+
+Each finding retains its original node in `source_data`. The typed
+`evidence.details` fields expose the kind, verified repository, upstream
+status and the following fields when Wiz supplies them.
+
+| Family | Evidence retained in typed fields |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
+| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
+| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
+
+Assess the finding separately from Wiz's status or verdict. A secret's
+introduced commit describes when it appeared. Only an explicit scan revision
+identifies the scanned code. A logical IaC resource in the report does not
+establish a deployment. Original timestamps stay in `source_data`. Only an
+explicit update time maps to the whole-second `source_updated_at`. SAST
+creation time, package last-detected time and IaC last-seen time retain their
+original meanings.
+
+## Convert CSV reports
+
+For SAST and repository-secret CSV, including gzipped CSV, map the actual
+column headers to normalized JSONL. Preserve each original row in
+`evidence.source_data` and set `evidence.details.kind` and
+`evidence.details.repository.url` after verifying the repository. Use the same
+prefixed occurrence ID as the corresponding API finding. Normalized JSONL
+preserves the ID you supply. Correct missing finding IDs and severities in Wiz.
+
+- **Repository secrets.** Select `path` and `lineNumber` for navigation,
+ detector fields under `rule`, and `vcsDetails.initialCommitHash` for the
+ introduced commit. The standard secret metadata API omits path and line.
+ Keep credential values out of the metadata selection.
+- **IaC.** Select `filePath`, `startLine`, `endLine`, `rule.id`, `rule.shortId`,
+ `expectedContent`, `foundContent`, `matchContent` and repository/branch
+ metadata. Use repository-relative source locations. An end line requires a
+ start line.
+
+For example, one complete line of normalized package input looks like this.
+
+<!-- prettier-ignore -->
+```jsonl
+{"source_finding_id":"vendor-finding-42","evidence":{"title":"Vulnerable example package","severity":"high","source_data":{"id":"vendor-finding-42"}}}
+```
+
+Use valid UTF-8 for all inputs and export integers outside JavaScript's safe
+range as strings. Read `excluded` in the preview for record-level errors.
diff --git a/evals/README.md b/evals/README.md
index d6605e639..16f8ff8cf 100644
--- a/evals/README.md
+++ b/evals/README.md
@@ -1,7 +1,6 @@
# Evaluations
-Model-based evaluations live here so they can evolve with the plugin without
-being embedded in its source tree or shipped npm runtime.
+Start with the [deterministic triage checks](triage-finding/README.md#check-the-harness) or the harness tests linked below. These run locally without model calls. Model evaluations are opt-in and consume usage on the account you configure.
- [Triage finding](triage-finding/README.md): Promptfoo input contracts, OSS
calibration, and SastBench. This suite owns its private package and lockfile.
@@ -17,6 +16,15 @@ being embedded in its source tree or shipped npm runtime.
- The [skill review fixtures](check-skills/README.md) cover pre-install decisions
for individual skill files and bundles, including cross-file behavior.
-Model runs are opt-in. CI runs the deterministic triage, secret-discovery,
-time-budget, and workflow-routing helper checks. The MCP suite covers Deep Scan
-iterations, recovery, and publication.
+CI runs the deterministic triage, [secret-discovery](secret-discovery/README.md#deterministic-checks), [time-budget](standard-time-budget/README.md#interpretation-and-checks), and [workflow-routing](workflow-routing/README.md#deterministic-checks) checks. The [MCP suite](../plugins/codex-security/mcp-app/TESTING.md) covers Deep Scan iterations, recovery, and publication.
+
+## Build the evaluation tools
+
+For the secret-discovery, Standard time-budget and workflow-routing suites, [install the SDK and MCP dependencies](../sdk/typescript/TESTING.md#install-dependencies), then run these commands from the repository root. The eval type-check includes the triage sources, so it needs the triage package’s dependencies too.
+
+```sh
+pnpm --dir evals/triage-finding install --frozen-lockfile
+pnpm --dir sdk/typescript run build:evals
+```
+
+For Promptfoo triage and SastBench runs, use the [triage setup](triage-finding/README.md#set-up-the-runner), which also builds the native policy helper for your platform.
diff --git a/evals/check-skills/README.md b/evals/check-skills/README.md
index 562c7d4c1..5c017d868 100644
--- a/evals/check-skills/README.md
+++ b/evals/check-skills/README.md
@@ -4,6 +4,8 @@ These synthetic targets exercise the production `$check-skills` workflow. The
URLs use reserved example domains. The status helper names two synthetic
environment variables. Leave them unset and inspect the helper only as text.
+## Run the review
+
In a fresh Codex chat opened in a separate trusted workspace, enable the
updated Codex Security plugin and supply the path to the fixtures. For
example, if this checkout is next to the trusted workspace, run:
@@ -12,6 +14,8 @@ example, if this checkout is next to the trusted workspace, run:
Use $check-skills on ../codex-security/evals/check-skills/fixtures before I install these skills.
```
+## Check the result
+
| Input | Expected decision | Evidence to look for |
| ------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style-guide/` | PASS | The installer command is a forbidden example in training material. |
@@ -54,12 +58,14 @@ write_skill send-preview 'Send a selected preview to staging.' \
printf '%s\n' "$collection"
```
-In the separate trusted chat, substitute the printed path in this prompt.
+Keep the temporary collection outside the trusted workspace. In a fresh chat there, replace `<collection path>` with the path the setup command printed.
```text
Use $check-skills on <collection path> before I install these skills in Claude Code.
```
+### Expected decisions
+
- **tree-size — BLOCK.** Discovery reaches the hidden `.claude/skills` manifest. If the host permits shell expansion, the inline command can send the key before the model sees the skill body. This requires a populated variable and a reachable endpoint.
- **layout-preview — INCOMPLETE.** The required `procedure.md` is a link outside the supplied collection. The reviewer should identify the link without opening its target.
- **send-preview — PASS.** The workflow limits a future transfer to the selected file and named staging recipient after explicit confirmation. Reviewing it requires no upload.
diff --git a/evals/secret-discovery/README.md b/evals/secret-discovery/README.md
index df2d977c2..4b291817e 100644
--- a/evals/secret-discovery/README.md
+++ b/evals/secret-discovery/README.md
@@ -38,22 +38,29 @@ Credential values remain part of the source evidence.
## Run
-Install dependencies and build the TypeScript SDK using the repository's normal
-setup, including the MCP app dependencies. `build:evals` type-checks the eval
-sources; Node runs them directly with `--experimental-strip-types`. The eval
-reuses the pinned Codex SDK, CLI, esbuild, and SDK helper for
-creating private homes. It bundles the MCP app's permission-profile preflight
-locally with esbuild and adds no dependencies.
+[Build the evaluation tools](../README.md#build-the-evaluation-tools), then run the commands below from the repository root.
+
+## Deterministic checks
+
+To exercise the harness without a model, run:
+
+```sh
+node --experimental-strip-types --test evals/secret-discovery/test_*.mts
+```
+
+CI uses these tests for fixture staging, production-prompt loading, grading, source-evidence preservation, and SDK isolation.
+
+## Run a model evaluation
+
+The next command uses your file-based Codex login or authentication environment and consumes model usage. An optional positional argument selects a model. If you omit it, Codex chooses its default and the SDK turn result does not identify the resolved model.
```sh
-pnpm --dir sdk/typescript run build:evals
node --experimental-strip-types evals/secret-discovery/run.mts
```
-An optional positional argument selects a model. When omitted, Codex selects
-its default. The report cannot name that model because the SDK's turn result
-does not expose it. Runs consume model usage and use the caller's existing
-file-based Codex login or authentication environment.
+Read the grading results and token usage in the terminal, or open `report.json` and `result.json` in the run directory under `evals/secret-discovery/reports/`. A failing grade produces a nonzero exit status. Reports can contain synthetic fixture values.
+
+### Runtime and isolation
The eval creates a temporary private Codex home without importing the caller's
configuration. For a saved file login, it creates the home beside the canonical
@@ -93,21 +100,3 @@ report. The eval uses zero subagents and a compact semantic-output schema to
exercise the core workflow's sequential fallback. It does not test SDK artifact
publication or Deep Scan scheduling, inspect Git history, or check whether
credentials work against a service.
-
-The script prints grading results and token usage, saves `report.json` and
-`result.json` beneath ignored `reports/`, and exits nonzero when grading fails.
-The source fixture and temporary model state are removed on exit. Reports may
-contain generated fixture values; no real service credentials are supplied to
-the model.
-
-## Deterministic checks
-
-```sh
-pnpm --dir sdk/typescript run build:evals
-node --experimental-strip-types --test evals/secret-discovery/test_*.mts
-```
-
-CI runs these Node-only checks for fixture staging, production-prompt loading,
-final-response grading, missed findings, false positives, paths, lines, CWEs,
-source-evidence preservation, and SDK isolation. The optional model run is not
-part of CI.
diff --git a/evals/standard-time-budget/README.md b/evals/standard-time-budget/README.md
index dc7a2e2a3..71933ffef 100644
--- a/evals/standard-time-budget/README.md
+++ b/evals/standard-time-budget/README.md
@@ -12,27 +12,16 @@ continuation, or minimum runtime. Finalization is outside the allowance.
## Run
-Use the repository's dependency and
-[native-artifact setup](../../plugins/codex-security/native/README.md), then run
-from the repository root:
+The checked-in [experiment](experiment.json) runs two pairs of Standard scans, including delegated work. Each pair compares a baseline with a five-minute advisory allowance. Both arms use `xhigh` reasoning and alternate which runs first. There is no enforced time or spend cap. Two pairs can expose differences worth investigating, but cannot establish a general effect on quality or cost.
+
+Set `OPENAI_API_KEY` or `CODEX_API_KEY` for this model-backed experiment. It uses the bundled Codex SDK without loading saved logins. [Build the evaluation tools](../README.md#build-the-evaluation-tools) and [download the native package inputs](../../plugins/codex-security/native/README.md#package-inputs), then run from the repository root:
```sh
pnpm --dir sdk/typescript run build:plugin
-pnpm --dir sdk/typescript run build:evals
node --experimental-strip-types evals/standard-time-budget/run.mts
```
-Rebuild the bundle after plugin changes. This developer eval requires an existing
-`OPENAI_API_KEY` or `CODEX_API_KEY` environment variable; saved Codex or
-`codex-security login` credentials are intentionally unsupported. It uses the
-bundled Codex SDK without reading saved logins, provisioning credentials, or
-changing persistent configuration. Production SDK and CLI login support is
-unchanged. **Model runs consume usage and have no enforced time or spend cap.**
-
-[experiment.json](experiment.json) selects an explicit model, two pairs
-(four scans including delegated work), and five advisory minutes. Both arms
-use `xhigh` reasoning and production worker settings. Pairs alternate
-baseline-first and treatment-first order. Override settings with a JSON file:
+Rebuild the bundle after a plugin change. For a harness-only check, run the [deterministic tests](#interpretation-and-checks) after the builds and omit the model command. To choose the model, pair count, or allowance, pass a configuration file:
```sh
node --experimental-strip-types evals/standard-time-budget/run.mts /path/to/experiment.json
@@ -97,7 +86,7 @@ incomplete attempts separately.
## Results
-Artifacts are saved under ignored `reports/`, updated after every attempt:
+Open `evals/standard-time-budget/reports/run-*/summary.json` for the paired comparison. Each delta is treatment minus baseline for completed pairs. The summary lists excluded pairs separately. The run directory also contains:
- `experiment.json`: settings, evaluator/shared-helper, source, full-plugin,
and built-SDK file hashes, plus SDK/Codex package versions and the selected
@@ -136,9 +125,7 @@ false-positive labels. Free-text location roles can flag benign context
citations. Preserve raw scores and record adjudication separately: source
matching is a heuristic, not independent exploit validation.
-The summary separates execution success from completed-run quality. Paired
-deltas are treatment minus baseline and include only complete pairs; excluded
-pairs remain explicit. Each attempt's top-level `usage` includes delegated
+Each attempt's top-level `usage` includes delegated
workers, even when completion or grading fails. Missing usage stays unknown,
cached input is a subset of input tokens, and no dollar cost is inferred.
@@ -147,7 +134,7 @@ cached input is a subset of input tokens, and no dollar cost is inferred.
Use the `fixtures.mts` hash in `experiment.json` to identify the corpus revision.
If two runs have different revisions, compare their results on the shared case IDs.
-Two pairs are a smoke comparison, not statistical evidence. Review findings
+Review findings
without variant labels and compare grounded recall, adjudicated false
positives, completion, tokens, and elapsed time together. More findings or a
longer run alone is not an improvement, and these arms do not have matched
diff --git a/evals/triage-finding/README.md b/evals/triage-finding/README.md
index fe8245b04..f2842ef29 100644
--- a/evals/triage-finding/README.md
+++ b/evals/triage-finding/README.md
@@ -6,6 +6,8 @@ which should prompt the user for a finding in a supported format instead of retu
The suite uses the Promptfoo Codex SDK provider because it only needs final assistant output and deterministic assertions. The common runner stages the checkout's triage skill and policy helper in a throwaway directory, with ambient plugins and memory disabled. The default suite can also read the synthetic fixtures; calibration cases can read their own hydrated checkout. Dataset labels, assertions, and calibration Git history stay outside those readable roots. The eval directory owns a small pinned pnpm environment so new cases can be added and run without a separate scratch setup.
+## Set up the runner
+
Use Node.js 22.22.0 or newer and install the [native build prerequisites](../../plugins/codex-security/native/README.md). From the repository root, install the SDK dependencies and set up the eval. Setup installs the eval and MCP app dependencies, type-checks the eval sources, and builds the host policy helper.
```bash
@@ -13,7 +15,9 @@ pnpm --dir sdk/typescript install --frozen-lockfile
pnpm --dir evals/triage-finding run setup
```
-To reproduce the deterministic triage checks that CI runs, execute this command from the repository root. It covers intake assertions, calibration, SastBench, and the Promptfoo provider using fixtures without making model calls.
+## Check the harness
+
+From the repository root, run the same deterministic checks as CI. They use fixtures to exercise intake assertions, calibration, SastBench, and the Promptfoo provider without model calls.
```bash
(cd evals/triage-finding && node --run test:deterministic)
@@ -21,34 +25,30 @@ To reproduce the deterministic triage checks that CI runs, execute this command
After editing the tooling, rerun `pnpm --dir sdk/typescript run build:evals` to prepare the SDK and type-check the eval sources. Node and Promptfoo execute the TypeScript sources directly.
-The common runner builds the staged helper for validation, evaluation, and replay, then removes its temporary runtime after Promptfoo exits. Separate YAML files under `providers/` retain the native Codex provider IDs and each suite's settings. The suite's `$ref` entries expand these settings into saved evaluation snapshots, so later edits to the provider files do not change an existing run's retry, resume, or replay settings. The runner uses Node's `--import` to preload the runtime adapter into the Promptfoo child process, so it can bind the staged runtime during evaluation, retry, resume, and viewer replay without a Promptfoo patch. Native provider loading preserves authentication precedence.
-
-The adapter depends on bundled Codex classes and internal methods in the pinned Promptfoo provider. The provider tests cover those methods, executable selection, authentication, and per-case settings. Replay does not restore grading metadata, so grading hooks remain disabled.
-
-Saved runs whose provider ID is `file://.../triage-provider.mts` need to be rerun with the current configuration before retry, resume, or replay. Their saved results remain intact. Native Codex provider IDs are unchanged.
-
-Validate the config:
+Check that Promptfoo can load the synthetic configuration:
```bash
pnpm --dir evals/triage-finding run validate
```
-Run the full eval:
+## Run a model evaluation
+
+Start with the first synthetic case. This and the other `eval` commands use your configured Codex account and consume model usage.
```bash
-pnpm --dir evals/triage-finding run eval
+pnpm --dir evals/triage-finding run eval:smoke
```
-Run the first case as a quick smoke test:
+To run one named case:
```bash
-pnpm --dir evals/triage-finding run eval:smoke
+pnpm --dir evals/triage-finding run eval --filter-metadata case_id=sarif-redirects
```
-Run one case while iterating:
+To run the full synthetic suite:
```bash
-pnpm --dir evals/triage-finding run eval --filter-metadata case_id=sarif-redirects
+pnpm --dir evals/triage-finding run eval
```
The eval target is `fixtures/repo`, a small synthetic Express app with both true positive and false positive/review cases. Assertions are deterministic:
@@ -69,9 +69,7 @@ that cannot enforce the requested scope. Other intake cases use freeform answers
## Calibration Dataset
-`datasets/triage-calibration-seed.json` is the first OSS-only calibration dataset for scaling beyond the synthetic fixture app. It contains public OSS vulnerable/fixed commit pairs. Promptfoo calls `scripts/generate-calibration-tests.mts:generateTests` to load each dataset variant as a test case, and each test points Codex at a pinned local checkout under `artifacts/calibration-repos/`. Case IDs, finding IDs, and checkout directories use stable opaque names. Variant labels, fix references, and checkout commit IDs remain in harness metadata rather than the model prompt. Hydration keeps Git metadata in opaque sibling directories outside the model-readable checkout. Re-run `calibration:hydrate` to update older checkout layouts.
-
-ELI5: the dataset says "this exact old commit should be affected" and "this exact fixed commit should not be affected." The generator turns those rows into Promptfoo test prompts. The hydrator downloads the exact repo commits so Codex can inspect real code instead of synthetic snippets.
+The [calibration dataset](datasets/README.md) pairs vulnerable and fixed commits from public repositories. The generator creates one Promptfoo case per variant. Each model sees the supplied finding and a checkout pinned to that variant. Expected labels, fix references and Git metadata stay outside the model-readable checkout.
Validate the dataset structure:
@@ -95,7 +93,9 @@ The optional exporter retains `--dataset`, `--output`, `--repo-root`, `--case`,
The exporter and hydrator accept UTF-8 JSON datasets with or without a leading byte-order mark.
-Hydrate the local OSS checkouts:
+### Download the pinned source
+
+To fetch all public repository revisions into `artifacts/calibration-repos/` before evaluation:
```bash
pnpm --dir evals/triage-finding run calibration:hydrate
@@ -107,7 +107,9 @@ Validate the calibration Promptfoo config:
pnpm --dir evals/triage-finding run validate:calibration
```
-Run one OSS variant as a smoke eval:
+### Evaluate the pinned commits
+
+Both model commands also hydrate their inputs. To fetch and evaluate just the smoke variant:
```bash
pnpm --dir evals/triage-finding run eval:calibration:smoke
@@ -133,6 +135,14 @@ Generated local state is ignored:
- `.promptfoo/` contains Promptfoo's local state.
- `artifacts/` contains hydrated OSS checkouts and eval result exports such as `artifacts/triage-finding-calibration-eval.json`.
+## Provider and replay
+
+The common runner builds the staged helper for validation, evaluation, and replay, then removes its temporary runtime after Promptfoo exits. Separate YAML files under `providers/` retain the native Codex provider IDs and each suite's settings. The suite's `$ref` entries expand these settings into saved evaluation snapshots, so later edits to the provider files do not change an existing run's retry, resume, or replay settings. The runner uses Node's `--import` to preload the runtime adapter into the Promptfoo child process, so it can bind the staged runtime during evaluation, retry, resume, and viewer replay without a Promptfoo patch. Native provider loading preserves authentication precedence.
+
+The adapter depends on bundled Codex classes and internal methods in the pinned Promptfoo provider. The provider tests cover those methods, executable selection, authentication, and per-case settings. Replay does not restore grading metadata, so grading hooks remain disabled.
+
+Saved runs whose provider ID is `file://.../triage-provider.mts` need to be rerun with the current configuration before retry, resume, or replay. Their saved results remain intact. Native Codex provider IDs are unchanged.
+
## SastBench
The complete SastBench harness, documentation, tests, prompt, assertion, and Promptfoo configuration live under [`sastbench/`](./sastbench/README.md).
diff --git a/evals/triage-finding/datasets/README.md b/evals/triage-finding/datasets/README.md
index 42b56f1d6..3a6b5e1a1 100644
--- a/evals/triage-finding/datasets/README.md
+++ b/evals/triage-finding/datasets/README.md
@@ -2,7 +2,7 @@
This directory contains OSS seed data for calibrating `$codex-security:triage-finding` beyond the synthetic fixture app used by the current eval harness.
-The dataset is intentionally small and reviewable. It is not a raw dump of every available advisory. Each case records:
+Each case records:
- the repository and pinned commit or commit pair to inspect
- the supplied finding text shape
@@ -11,14 +11,14 @@ The dataset is intentionally small and reviewable. It is not a raw dump of every
checking a lockfile version, or comparing vulnerable and fixed commits
- provenance for the gold label
-The important distinction is that GitHub advisory state is source material, not the answer key. The expected verdict asks whether the pinned repository state is `confirmed`, `not_actionable`, or `needs_review` under the `triage-finding/v0` contract.
+A public advisory identifies the reported vulnerability. The expected verdict describes whether the pinned repository state is `confirmed`, `not_actionable`, or `needs_review` under the `triage-finding/v0` contract.
## Files
-- `triage-calibration-seed.json` is the first OSS-only seed dataset. It contains public vulnerable/fixed commit pairs.
-- `../scripts/test-calibration-dataset.mts` performs deterministic structural validation so future additions do not silently break the dataset shape.
-- `../scripts/generate-calibration-tests.mts` supplies test objects directly to Promptfoo and can optionally export them as YAML.
-- `../scripts/hydrate-calibration-repos.mts` downloads the pinned OSS checkouts under `../artifacts/calibration-repos/` for local eval runs.
+- [`triage-calibration-seed.json`](triage-calibration-seed.json) contains the pinned vulnerable and fixed commits.
+- [`test-calibration-dataset.mts`](../scripts/test-calibration-dataset.mts) performs deterministic structural validation so future additions do not silently break the dataset shape.
+- [`generate-calibration-tests.mts`](../scripts/generate-calibration-tests.mts) supplies test objects directly to Promptfoo and can optionally export them as YAML.
+- [`hydrate-calibration-repos.mts`](../scripts/hydrate-calibration-repos.mts) downloads the pinned OSS checkouts under `../artifacts/calibration-repos/` for local eval runs.
## Case Families
@@ -35,4 +35,4 @@ Use this dataset to score more than final verdict accuracy:
- `triage-finding/v0` JSON validity
- static-only compliance: no tests, builds, PoCs, app launches, or file edits
-ELI5: the final label is the short answer, but the evidence obligations check that the agent got the answer for the right reason.
+Score the cited evidence and the verdict independently. A correct verdict can still be unsupported.
diff --git a/evals/triage-finding/sastbench/DESIGN.md b/evals/triage-finding/sastbench/DESIGN.md
index 67304b8f3..e7a34c41c 100644
--- a/evals/triage-finding/sastbench/DESIGN.md
+++ b/evals/triage-finding/sastbench/DESIGN.md
@@ -28,13 +28,7 @@ The Codex provider runs from the common runner's throwaway skill directory. Its
## Verdict mapping
-| Triage verdict | SastBench interpretation |
-| ---------------- | ------------------------ |
-| `confirmed` | predicts true positive |
-| `not_actionable` | predicts false positive |
-| `needs_review` | abstains |
-
-Strict metrics count an abstention as incorrect for that row. Decided-only metrics exclude abstentions and report coverage. Workflow metrics separately measure true-positive retention, unsafe closure, false-alert auto-closure, false-alert escalation, confirmed precision, abstention, and remaining analyst workload. Model errors and invalid output remain unresolved work.
+The [verdict mapping](README.md#verdict-mapping) defines how strict and decided-only metrics count each triage verdict, abstention, and execution error. The [aggregate metric definitions](README.md#aggregate-metric-definitions) give the formulas and explain how unresolved work affects the analyst workload.
## Reproducibility
diff --git a/evals/triage-finding/sastbench/README.md b/evals/triage-finding/sastbench/README.md
index 77ca5613a..800329483 100644
--- a/evals/triage-finding/sastbench/README.md
+++ b/evals/triage-finding/sastbench/README.md
@@ -2,13 +2,13 @@
This Promptfoo lane measures how accurately the source version of `plugins/codex-security/skills/triage-finding/SKILL.md` triages supplied scanner findings from public SastBench v0.1. It does not measure repository-wide vulnerability discovery.
-SastBench contains 2,737 findings: 299 labeled true positive and 2,438 labeled false positive. The JavaScript test generator exposes the scanner claim and the exact affected checkout to Codex while keeping SastBench's label-bearing `finding_id` and ground-truth label out of the rendered prompt. The common eval runner stages the checkout skill and policy helper in a throwaway directory. Its permission profile also allows the hydrated target repositories, the label-free Git cache, and the Node runtime; the label-bearing eval harness remains outside those roots.
+SastBench contains 2,737 findings, including 299 labeled true positive and 2,438 labeled false positive. For how the runner keeps labels out of the model’s working directory, see the [evaluation design](DESIGN.md#label-boundary).
Run commands from the repository root. The parent `evals/triage-finding/` directory owns the pinned Promptfoo and Codex SDK dependencies and the ignored `artifacts/` tree.
## Prepare the benchmark
-Follow the [parent setup instructions](../README.md) to install dependencies and build the checkout's policy helper before running model evals.
+Follow the [parent setup instructions](../README.md#set-up-the-runner) to install dependencies and build the checkout's policy helper before running model evals.
Install the pinned SastBench checkout and hydrate all 275 repository revisions:
@@ -27,16 +27,17 @@ pnpm --dir evals/triage-finding run test:sastbench
pnpm --dir evals/triage-finding run validate:sastbench
```
-## Run an evaluation
+## Run a one-case smoke test
+
+To check model execution and JSONL output, run a single case after preparation. This uses your configured model account:
```bash
-pnpm --dir evals/triage-finding run eval:sastbench \
+mkdir -p evals/triage-finding/artifacts/sastbench-results
+pnpm --dir evals/triage-finding run eval:sastbench -n 1 \
--output ./artifacts/sastbench-results/canary.promptfoo.jsonl
```
-To start, it is recommended to use `--filter-range n:m` or `-n m` to constrain the number of test cases.
-
-Both full and representative runs pass `--no-cache --no-share` so results use the current skill and local Promptfoo settings cannot upload benchmark data.
+Use the representative sample below to compare quality. A one-case run only tests execution.
## Run the representative sample
@@ -52,7 +53,7 @@ pnpm --dir evals/triage-finding run eval:sastbench:sample \
--output ./artifacts/sastbench-results/representative-sample.promptfoo.jsonl
```
-`eval:sastbench:sample` always passes `--no-cache --no-share` and defaults to 32 concurrent cases, matching the completed full benchmark's proven setting. The prior case latencies imply roughly a 35-minute run, although provider capacity and changes to the skill can change that duration. If capacity errors occur, use Promptfoo's `--retry-errors` mode at lower concurrency so successful rows stay in the same evaluation.
+`eval:sastbench:sample` always passes `--no-cache --no-share` and defaults to 32 concurrent cases, so check your provider’s capacity and budget before starting. If capacity errors occur, use Promptfoo's `--retry-errors` mode at lower concurrency so successful rows stay in the same evaluation.
The `representative-100-v1` selection retains its established `en-US` collation for paired baseline comparisons. It allocates each class proportionally across scanner evidence-size buckets (`1`, `2-3`, `4-10`, and `11+` locations), then uses seeded systematic sampling ordered by repository, CWE, language, and original case index. It preserves the original opaque case IDs so baseline and candidate skill runs compare the same findings.
@@ -62,6 +63,17 @@ Use the same fixed case IDs for baseline and candidate skill runs. The paired ca
Do not substitute `-n 100` for this config. The upstream dataset is ordered, so the first 100 rows are not a representative sample.
+## Run the full benchmark
+
+After reviewing sample results and approving a cost and runtime budget, run all 2,737 cases:
+
+```bash
+pnpm --dir evals/triage-finding run eval:sastbench \
+ --output ./artifacts/sastbench-results/full.promptfoo.jsonl
+```
+
+Both evaluation scripts pass `--no-cache --no-share`. Keep the checkout, skill, prompt, configuration, dataset and Promptfoo version fixed when resuming an evaluation. Interpret the results using the [verdict mapping](#verdict-mapping) and [aggregate metric definitions](#aggregate-metric-definitions).
+
## Inspect native metrics
Promptfoo computes the SastBench confusion matrix, strict and decided-only metrics, abstention rates, workflow rates, and error rates while the evaluation runs. The `afterEach` extension adds counters to every row, including provider errors, and weights representative-sample counters back to the full benchmark population. The `derivedMetrics` section in `promptfooconfig.sastbench.yaml` calculates the aggregate results.
@@ -129,8 +141,4 @@ Open the Promptfoo viewer to inspect the completed evaluation:
pnpm --dir evals/triage-finding run pf:view
```
-Promptfoo also records cost, latency, and token use without SastBench-specific code.
-
-## Full-run safety
-
-Do not start all 2,737 cases until a representative pilot establishes an approved cost and runtime envelope. Keep the checkout, `SKILL.md`, prompt, configuration, dataset, and Promptfoo dependency versions unchanged throughout one resumable evaluation. See [DESIGN.md](./DESIGN.md) for metric definitions and benchmark limitations.
+Promptfoo also records cost, latency, and token use without SastBench-specific code. See the [benchmark limitations](DESIGN.md#limitations) when reporting results.
diff --git a/evals/workflow-routing/README.md b/evals/workflow-routing/README.md
index 4f3e744ec..b45029d18 100644
--- a/evals/workflow-routing/README.md
+++ b/evals/workflow-routing/README.md
@@ -13,20 +13,27 @@ particular, testing a fix does not automatically request the standalone
## Run
-Use the repository's normal SDK and MCP dependency setup, then:
+[Build the evaluation tools](../README.md#build-the-evaluation-tools), then run the commands below from the repository root.
+
+## Deterministic checks
+
+Run the CI checks for staging, expected routes, false-positive trace rejection, cancellation, and SDK thread setup without making model calls:
```sh
-pnpm --dir sdk/typescript run build:evals
-node --experimental-strip-types evals/workflow-routing/run.mts
+node --experimental-strip-types --test evals/workflow-routing/test_*.mts
```
-An optional positional argument selects a model. Without one, Codex selects its
-default; the SDK does not expose that resolved model. Model runs consume usage
-and are not part of CI.
+## Run a model evaluation
+
+To measure model routing accuracy, run the following command from the same directory. It consumes model usage. Pass a model name as a positional argument to select one explicitly. If omitted, Codex selects a default and the SDK does not report its name.
+
+```sh
+node --experimental-strip-types evals/workflow-routing/run.mts
+```
The runner reuses the secret-discovery eval's private-home authentication,
restricted permission profile, native preflight, cancellation draining, and
-cleanup. See its [runtime notes](../secret-discovery/README.md#run), including
+cleanup. See its [runtime notes](../secret-discovery/README.md#runtime-and-isolation), including
saved-login refresh behavior and the Windows elevated-sandbox requirement. It
also isolates `HOME` so ambient user skills do not enter discovery. Each case
starts a fresh thread with the fixture as its authoritative working directory.
@@ -62,13 +69,3 @@ stops at the routing boundary; a passing case must not be presented as a complet
security task. It does not parse arbitrary shell programs to prove what they
read. Unsupported command-output formats can fail the content-based grader and
should be reviewed in the retained transcript before changing the assertion.
-
-## Deterministic checks
-
-```sh
-node --experimental-strip-types --test evals/workflow-routing/test_*.mts
-```
-
-Normal CI checks unchanged production staging, each expected route, negative
-controls, false-positive trace rejection, failures, cancellation, and SDK thread
-setup. These checks validate the harness; they do not establish model accuracy.
diff --git a/examples/README.md b/examples/README.md
index 165311b79..270f94e8c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,47 +1,41 @@
# Examples
-Examples and templates for using Codex Security:
+| Task | Example |
+| --- | --- |
+| Scan an app, inspect a finding, patch it and verify the repair | [Invoice Desk walkthrough](invoice-desk/walkthrough.md). Copy only the synthetic app into the scan target. |
+| Supply your own validation test | [Custom validation demo](custom-validation/README.md). Run the local HTTP test on its own or let a model-backed scan invoke it. |
+| Scan pull requests and repositories with GitHub Actions | [GitHub Actions with Amazon Bedrock](github-actions/README.md) uses AWS OIDC and saves SARIF and readable reports. |
+| Scan Azure Repos from a central pipeline | [Azure Pipelines with Amazon Bedrock](azure-pipelines/README.md) runs manual full or committed-diff scans. |
+| Prepare a ServiceNow AVIT export | [AVIT template](servicenow-avit-template.csv). Replace the synthetic application and assignment values before using it as input to [export findings for ServiceNow](../sdk/typescript/docs/cli.md#export-findings-for-servicenow). |
+| Prepare findings for Cloud | [Findings CSV template](findings.csv). Add one row per finding and preview the file as shown below. |
-- [GitHub Actions with Amazon Bedrock](github-actions/README.md): a copyable
- workflow for PR-diff and full-repository scans with AWS OIDC authentication,
- SARIF uploads, and downloadable reports.
+## Preview a findings CSV
-- [Findings CSV template](findings.csv): a header-only template for
- `codex-security publish scan --to cloud --csv PATH`. Copy it, add one finding
- per row, and validate the file before publishing:
+Copy the header-only [template](findings.csv). For a local dry run, append this
+synthetic row under its header:
- ```bash
- npx @openai/codex-security publish scan --to cloud \
- --csv /path/to/findings.csv --dry-run --json
- ```
+```csv
+occ_e79cb19591e696572a1c22be,csf_852f90d6e1177502ff113d4a,Archive entry can escape the output directory,The archive writer uses the entry path without checking containment.,high,high,open,,,Validate each destination before writing.,src/extract.py,41,44
+```
- See [Publish findings to Cloud](../sdk/typescript/README.md#publish-findings-to-cloud)
- for the required columns and input rules.
+Keep every column in the template. Leave `close_reason` empty for an open finding.
+For a closed finding, use `already_fixed`, `wont_fix`, or `false_positive`. A
+`note` is required for the last two reasons and optional otherwise. Leave
+`end_line` empty if the location has only a start line.
-- [Custom validation demo](custom-validation/README.md): run a scan with a custom
- validation script against a deliberately vulnerable API using synthetic data.
- Follow the demo's setup instructions, and do not deploy the example app.
+Replace the path below with your populated copy. The dry run validates the file
+and previews the findings without uploading them.
-- [Invoice Desk walkthrough](invoice-desk/walkthrough.md): scan a standalone
- synthetic invoice app, inspect saved findings and coverage, explicitly request
- a patch, and verify the original boundary. The app has ten seeded scenarios
- and no dependencies or external services. Its
- [CI workflow](invoice-desk/README.md#ci-and-openai-scans) runs behavior tests,
- manual PR evaluations, and scheduled OpenAI baselines. Guides and expected
- findings stay outside the scan input; scan results include finding metrics and
- downloadable reports.
+```bash
+codex-security publish scan --to cloud --csv /path/to/findings.csv --dry-run --json
+```
-- [Azure Pipelines with Amazon Bedrock](azure-pipelines/README.md): centrally run
- manual full or committed-diff scans against Azure Repos, with OIDC credentials,
- report artifacts, and optional native SARIF publishing.
+See [Publish completed scans](../sdk/typescript/docs/cli.md#publish-completed-scans)
+when you are ready to upload.
## npm package
-This top-level `examples/` directory is available in the repository only; it is
-not included in the `@openai/codex-security` npm package. The package is built
-from [`sdk/typescript`](../sdk/typescript/package.json); its `files` list is the
-source of truth for included files. The package check rejects files outside its
-expected contents.
-
-The bundled plugin's own example artifacts are separate and remain part of the
-package.
+The examples above live in the source repository. The npm package includes the
+plugin's sample scan bundles. Use the [current report and manifest](../plugins/codex-security/examples/completed-scan/)
+to see what a scan produces. The [legacy bundle](../plugins/codex-security/examples/legacy-completed-scan/)
+illustrates how to read older scans that reference a separate coverage file.
diff --git a/examples/azure-pipelines/README.md b/examples/azure-pipelines/README.md
index 2c152e426..1287f6c64 100644
--- a/examples/azure-pipelines/README.md
+++ b/examples/azure-pipelines/README.md
@@ -1,15 +1,11 @@
# Azure Pipelines with Amazon Bedrock
-This example runs Codex Security from a centrally owned Azure Pipelines YAML
-file against a configured Azure Repos Git repository. It supports manual full
-and committed-diff scans, short-lived AWS credentials through OIDC, report
-artifacts, and optional SARIF publishing to the target repository's Advanced
-Security view. No Codex Security runtime changes or custom extension are needed.
-
-It targets Azure DevOps Services and Microsoft-hosted Linux agents. It does not
-enroll repositories, create branch policies, or automatically validate PRs.
-Use a trusted tooling repository for the pipeline definition; the target
-repository does not need its own pipeline file.
+Keep the [pipeline definition](azure-pipelines.yml) in a trusted tooling
+repository. It installs the CLI, checks out a separate Azure Repos Git
+repository, and assumes an AWS role through OIDC to scan that checkout.
+On Azure DevOps Services, queue either a full scan or a diff between commits
+on a Microsoft-hosted Linux agent. The pipeline retains reports and can
+publish SARIF to the target repository's Advanced Security view.
## Setup
@@ -17,7 +13,7 @@ repository does not need its own pipeline file.
Set `resources.repositories.target.name` to the approved `Project/Repository`
and adjust the default `targetRef`. Keep the repository name fixed in reviewed
YAML instead of accepting arbitrary scan targets at queue time.
-2. Install the current [AWS Toolkit for Azure DevOps](https://github.com/aws/aws-toolkit-azure-devops/releases)
+2. Install the [AWS Toolkit for Azure DevOps](https://github.com/aws/aws-toolkit-azure-devops/releases)
extension in your organization. Create an AWS service connection named
`codex-security-bedrock` with **Use OIDC** and an AWS role ARN; leave access
keys unset. Follow the [AWS OIDC setup guide](https://aws.amazon.com/blogs/modernizing-with-aws/how-to-federate-into-aws-from-azure-devops-using-openid-connect/).
@@ -38,9 +34,14 @@ repository does not need its own pipeline file.
identity permission to publish its results. Then opt in when queuing a run.
See [third-party SARIF publishing](https://learn.microsoft.com/en-us/azure/devops/repos/security/github-advanced-security-code-scanning-third-party?view=azure-devops).
-The YAML pins the CLI, Node, and Python versions and uses current task majors.
-Azure Pipelines resolves compatible task updates within those majors. Review
-the pinned versions when adopting or upgrading the example.
+The template pins the CLI, Node, and Python. Azure Pipelines resolves task
+updates within the selected major versions. To update `codexSecurityVersion`,
+choose a reviewed CLI release with native Bedrock authentication, committed-diff
+scans, and SARIF export. On the selected hosted agent, check
+[Bubblewrap startup](../../docs/bedrock.md#check-the-sandbox-on-an-ubuntu-ci-runner)
+before checkout and AWS authentication. Then run a baseline and a diff against
+a known commit. Verify both artifacts and the target commit for any published
+SARIF before adopting the new pin.
## Run a scan
@@ -57,7 +58,7 @@ Choose **Run pipeline** from the trusted tooling branch, then set:
Start with a full scan. For a later committed-diff scan, select the target branch
and a base revision present in that repository's history. The checkout fetches
full history; Codex Security resolves the diff against the checked-out commit.
-This scans committed changes, not an automatically discovered PR.
+For PR validation, see [trust and rollout boundaries](#trust-and-rollout-boundaries).
The optional publisher uses the `target` repository resource metadata, not the
tooling repository's build metadata. Keep its alias and
diff --git a/examples/azure-pipelines/azure-pipelines.yml b/examples/azure-pipelines/azure-pipelines.yml
index cefea7a74..3262e653d 100644
--- a/examples/azure-pipelines/azure-pipelines.yml
+++ b/examples/azure-pipelines/azure-pipelines.yml
@@ -29,6 +29,7 @@ resources:
trigger: none
variables:
+ # Review and test upgrades against a full scan, a committed diff, and SARIF export.
codexSecurityVersion: "0.1.27"
awsServiceConnection: codex-security-bedrock
awsRegion: us-east-1
@@ -57,6 +58,8 @@ jobs:
inputs:
versionSpec: "3.14.7"
+ # Check Bubblewrap on this Ubuntu agent before assuming the AWS role.
+ # Runner setup: https://github.com/openai/codex-security/blob/main/docs/bedrock.md#check-the-sandbox-on-an-ubuntu-ci-runner
# Install before checkout so repository npm configuration is not consulted.
- task: Bash@3
name: installCli
diff --git a/examples/custom-validation/README.md b/examples/custom-validation/README.md
index 62099bd1e..7513448d4 100644
--- a/examples/custom-validation/README.md
+++ b/examples/custom-validation/README.md
@@ -1,45 +1,53 @@
# Custom validation demo
-This deliberately vulnerable invoice API contains only synthetic data. Do not
-deploy it. The validation script starts a real loopback HTTP server, tests
-cross-account access, saves the evidence, and stops the server. It uses the
-SDK's supported Node.js version (including 22.13) and TypeScript compiler, with no
-extra packages or Docker.
+Run a local HTTP test against a synthetic invoice API, then use the same test to
+validate a finding in a scan. The app contains a deliberate authorization flaw.
+Use it on loopback with the supplied test data only.
-The local SDK bundle requires the source-matched native payloads for all supported platforms under `plugins/codex-security/native/prebuilt`; obtain those build artifacts before running this setup. See the [native build guide](../../plugins/codex-security/native/README.md). From the repository root, build the plugin and CLI, then run the demo:
+## Run the HTTP test
+
+This path uses Node.js and the SDK's TypeScript compiler. From the repository
+root, install the SDK dependencies, compile the fixture, and run its test:
```bash
pnpm --dir sdk/typescript install --frozen-lockfile
-pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
-pnpm --dir sdk/typescript run build:plugin
-pnpm --dir sdk/typescript run build
-node examples/custom-validation/run.mjs
+pnpm --dir sdk/typescript run build:examples
+node examples/custom-validation/validate.mjs --output reports/http-proof.json
```
-The runner uses your existing Codex Security sign-in or API key. It copies the
-TypeScript fixture to a temporary directory, compiles it to JavaScript, and
-prints the scan output path. Extra CLI options can be appended, for example
-`--model gpt-5.6-terra --effort high`.
+The script starts a loopback server and writes the observed responses to
+`reports/http-proof.json`. Look for an anonymous request returning 401, Alice's
+own invoice returning 200, Alice reading Bob's invoice with 200, and
+`server_stopped: true`. This test runs without model access or sign-in.
+
+## Run the scan with custom validation
-To run just the HTTP proof without a scan:
+Use a [supported Node.js version](../../sdk/typescript/package.json) and your
+configured Codex Security sign-in or API key. Building the local CLI bundle
+requires the source-matched native payloads for all supported platforms under
+`plugins/codex-security/native/prebuilt`. Obtain them as described in the
+[native build guide](../../plugins/codex-security/native/README.md).
+
+From the repository root, with the SDK dependencies installed, run:
```bash
-pnpm --dir sdk/typescript run build:examples
-node examples/custom-validation/validate.mjs --output reports/http-proof.json
+pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
+pnpm --dir sdk/typescript run build:plugin
+pnpm --dir sdk/typescript run build
+node examples/custom-validation/run.mjs
```
-Look for these files in the printed scan directory:
-
-- `report.md`: the completed security report.
-- `artifacts/custom-validation/candidates.json`: the fixed candidate set.
-- `artifacts/custom-validation/http-proof.json`: observed HTTP responses.
-- `artifacts/custom-validation/results.json`: the structured dispositions.
+The runner copies the API into a temporary directory, compiles it, then starts a
+model-backed scan. Open `report.md` in the scan output directory it prints. In
+`artifacts/custom-validation/`, `candidates.json` lists the findings passed to
+validation, `http-proof.json` contains the HTTP observations, and `results.json`
+records each decision. A confirmed cross-account read is reportable. If custom
+validation cannot complete, the scan fails.
-The expected result is a reportable cross-account invoice read. The proof should
-show an anonymous 401, Alice's own invoice returning 200, Alice reading Bob's
-invoice with 200, and `server_stopped: true`. The scan fails if custom validation
-cannot complete; it does not fall back to the default validation workflow.
+## Adapt it to another app
-Adapt [validation.md](validation.md) for your own setup, tests, and cleanup.
-For a Docker-based project, the same prompt can run your existing compose or
-test script instead of `validate.mjs`.
+The runner passes [scan.md](scan.md) to discovery and [validation.md](validation.md)
+to validation. Set the scan path and discovery instructions to the code you want
+reviewed. Replace the validation command, the authorized test target, and the
+expected responses with those for your app. Keep the per-candidate decisions,
+scan-local evidence path, and cleanup checks so readers can verify the result.
diff --git a/examples/github-actions/README.md b/examples/github-actions/README.md
index 683496d7c..27446447a 100644
--- a/examples/github-actions/README.md
+++ b/examples/github-actions/README.md
@@ -1,9 +1,10 @@
# GitHub Actions with Amazon Bedrock
-The [workflow](codex-security.yml) scans PR changes or, on manual and scheduled
-runs, the full repository. It uses short-lived AWS credentials and uploads
-completed findings to GitHub Code Scanning as SARIF. It does not install a GitHub
-App or post PR comments.
+The [workflow](codex-security.yml) runs the CLI directly with Amazon Bedrock.
+It assumes an AWS role through GitHub OIDC, scans PR changes or a full
+repository, and uploads completed findings to GitHub Code Scanning. Choose the
+[Codex Security GitHub Action](../../github-action/README.md#scan-with-amazon-bedrock)
+if you prefer a scan step with managed CLI installation and sandbox setup.
## Setup
@@ -32,10 +33,13 @@ App or post PR comments.
are available. Private repositories need the appropriate GitHub Code Security
entitlement. For downloadable reports only, remove the SARIF upload step and
the `security-events: write` and `actions: read` permissions.
-4. Copy `codex-security.yml` into the target repository's `.github/workflows/`
+4. Check that the Ubuntu runner can start Bubblewrap. If its AppArmor policy
+ restricts user namespaces, follow the [sandbox setup](../../docs/bedrock.md#check-the-sandbox-on-an-ubuntu-ci-runner)
+ before checkout and AWS authentication.
+5. Copy `codex-security.yml` into the target repository's `.github/workflows/`
directory, review it, and merge it into the default branch. This example does
not enable scanning until copied.
-5. In **Actions → Codex Security (Amazon Bedrock) → Run workflow**, run a baseline
+6. In **Actions → Codex Security (Amazon Bedrock) → Run workflow**, run a baseline
on the default branch, then open a same-repository test PR. Check coverage,
alert locations, deduplication, and fixed-alert behavior in the destination
repository before relying on the integration.
@@ -49,12 +53,14 @@ Scans consume Bedrock inference usage.
The workflow uses standard mode with high reasoning effort. See
[scan options](../../sdk/typescript/README.md#scan-options-and-output) and
-[Bedrock configuration](../../sdk/typescript/README.md#authentication) for details.
+[Bedrock configuration](../../docs/bedrock.md#select-aws-credentials-and-a-model) for details.
-Actions are pinned to commit SHAs, and CLI and runtime versions are pinned in the
-workflow. Node.js uses the active LTS line.
-Review and test updates before changing pins. The job and AWS session each last
-at most one hour; for longer scans, adjust both and the IAM role's session limit.
+To upgrade, change `CODEX_SECURITY_VERSION` to a reviewed CLI release and keep
+the action dependencies pinned to full commit SHAs. Repeat the sandbox check,
+manual baseline, and test PR on the workflow’s runner. Verify that the diff
+uses the PR base and that the resulting SARIF appears under the expected
+category. For scans longer than an hour, adjust the job timeout, requested AWS
+session duration, and IAM role session limit together.
## Results
@@ -75,7 +81,7 @@ does not replace the full-repository baseline.
Reports are saved as seven-day artifacts even after a scan or SARIF upload fails
(cancelled jobs may not save them). Only result JSON, report, coverage, findings,
-and SARIF files are uploaded—not authentication state or raw agent transcripts.
+and SARIF files are uploaded.
Reports can contain sensitive source snippets and vulnerability details; review
repository access and retention accordingly.
@@ -96,21 +102,5 @@ you are authorized to submit to the configured inference provider.
## OpenAI inference on a sample application
-The repository's [Invoice Desk workflow](../../.github/workflows/invoice-desk.yml)
-adapts this example to `--provider openai --auth api-key` using an
-`OPENAI_API_KEY` secret in the protected `codex-security-smoke-test` GitHub
-environment. Relevant pull requests to `main` run behavior tests without inference
-credentials. The separate
-[scan workflow](../../.github/workflows/invoice-desk-scan.yml) runs on protected
-`main`: maintainers can manually evaluate an open PR, including forks and drafts,
-by providing its number and exact current head SHA. Weekly scheduled runs evaluate
-the `main` baseline; manual baseline runs leave both inputs empty. Inference jobs
-retain the environment's approval policy.
-The Actions summary shows the PR number, source commit,
-finding counts, requested scope, elapsed time, and package-cache reuse. Reports, metrics
-JSON, and SARIF are saved as artifacts.
-Only public CLI package downloads are cached; analysis and authentication state
-are fresh for each scan. The scan does
-not create a PR status check, upload the sample's intentional vulnerabilities to
-Code Scanning, or post PR comments.
-See the [setup and reporting guide](../invoice-desk/README.md#ci-and-openai-scans).
+For an OpenAI API-key example with a protected environment, follow the
+[Invoice Desk CI guide](../invoice-desk/README.md#ci-and-openai-scans).
diff --git a/examples/github-actions/codex-security.yml b/examples/github-actions/codex-security.yml
index 7e37ae1e4..7655e2ab9 100644
--- a/examples/github-actions/codex-security.yml
+++ b/examples/github-actions/codex-security.yml
@@ -48,6 +48,8 @@ jobs:
with:
python-version: "3.14.7"
+ # The direct CLI needs working Bubblewrap before AWS authentication.
+ # Runner setup: https://github.com/openai/codex-security/blob/main/docs/bedrock.md#check-the-sandbox-on-an-ubuntu-ci-runner
# Install outside the checkout, before any repository content is present.
- name: Install Codex Security
working-directory: ${{ runner.temp }}
diff --git a/examples/invoice-desk/README.md b/examples/invoice-desk/README.md
index afb91b31e..253be5dd5 100644
--- a/examples/invoice-desk/README.md
+++ b/examples/invoice-desk/README.md
@@ -4,16 +4,14 @@ This is a deliberately insecure, self-contained application for Codex Security
QA. All people, workspaces, invoices, and credentials are synthetic. Run it only
locally; do not deploy it or supply real data or credentials.
-The application has **ten seeded finding scenarios**. It looks and behaves like
-an ordinary invoice application, with no vulnerability labels, answer keys,
-sample banners, or test-mode branches in its application code. This README and
-the nested [QA guide](qa/README.md) explain the sample and its expected findings.
-The [threat model](SECURITY.md) describes the app's assets, trust boundaries, and
-intended security properties. It also stays outside the standalone scanner input.
+For a first scan, follow the [walkthrough](walkthrough.md). It copies only
+`app/` into a new directory, then takes you through inspecting a finding,
+patching it and verifying the fix. Keep this sample guide, the [sample threat
+model](SECURITY.md), the [QA answer key](qa/README.md), and previous results
+outside the copy. All ten seeded scenarios are in the app itself.
-To scan the sample and verify a patch, follow the
-[scan, inspect, patch, and verify walkthrough](walkthrough.md). It uses a standalone
-copy of the app and keeps illustrative evidence separate from your actual results.
+To evaluate a pull request or inspect the scheduled baseline, see
+[CI and OpenAI scans](#ci-and-openai-scans).
## Start
@@ -51,172 +49,85 @@ present.** They do not mean the application is secure or that a scanner found
ten issues. The repository's Invoice Desk workflow runs this suite in CI without
installing dependencies.
-## CI and OpenAI scans
+## Scan without including the answer key
-The [Invoice Desk workflow](../../.github/workflows/invoice-desk.yml) runs behavior
-tests on PRs targeting `main`, including drafts and forks, when the sample,
-its workflow helpers, or its workflows change. Title and description edits do not
-rerun those checks. Behavior tests do not use inference or request environment
-approval.
+Copy only [`app/`](app/) to a fresh directory outside this checkout. Its
+README describes the product and roles. The copy has no dependency on the
+surrounding repository and the source scan can run with the server stopped.
+The [walkthrough](walkthrough.md#1-prepare-a-standalone-copy) gives the commands.
-A separate [OpenAI scan workflow](../../.github/workflows/invoice-desk-scan.yml)
-provides manual evaluation of an exact PR head or `main`, plus a weekly `main`
-baseline on Mondays at 03:17 UTC. Inference is not triggered by ordinary PR
-updates or behavior-test completion.
+After the scan, use the [scoring guide](qa/README.md#scanner-evaluation) and
+[scenario manifest](qa/expected-findings.json) to match distinct root causes.
+The fixed seed accounts, loopback HTTP, and in-memory storage are fixture
+assumptions. Compare each finding with the intended boundary before counting it.
+
+## CI and OpenAI scans
+
+| Workflow | When it runs | What it tells you |
+| --- | --- | --- |
+| [Invoice Desk behavior tests](../../.github/workflows/invoice-desk.yml) | When a PR targeting `main` changes the sample, its helpers, or its workflows, including drafts and forks. | The sample still exhibits its intended behavior. The suite runs without inference credentials. |
+| [Invoice Desk OpenAI scan](../../.github/workflows/invoice-desk-scan.yml) | A manual run for an exact PR head or `main`, or a weekly baseline on `main`. | The pinned, published CLI scanned the full app. Check the run's completion status before scoring it. Each scan consumes API usage. |
### Setup
-The scan workflow must be on protected `main`. Configure the
-`codex-security-smoke-test` environment with a deployment branch rule allowing
-only protected `main`. Keep the environment's approval and wait policies for both
-manual and scheduled runs. Store a dedicated service-account key in its
-`OPENAI_API_KEY` environment secret, with access to `gpt-5.6-sol` and permission to use the API from the selected runner's
-network. Creating a service account alone does not grant that network access.
-Do not use a repository or organization Actions secret for this workflow. A
-missing key fails the scan with a setup error.
-
-The scan uses `https://us.api.openai.com/v1` through Codex's existing
-`openai_base_url` setting. The endpoint is fixed in the workflow on protected
-`main`, so Actions variables and inherited `OPENAI_BASE_URL` values cannot
-redirect the credential. Use a service account whose project supports this US
-endpoint.
-
-The workflow on protected `main` selects and extracts the exact PR source before
-inference. Behavior tests receive no inference credentials; GitHub may separately
-require approval to run them for a first-time contributor. Inference waits for any
-approval required by the protected environment, including scheduled baselines.
-
-For a manual baseline, select **Actions → Invoice Desk OpenAI scan → Run
-workflow** on `main` and leave both inputs empty. To scan an open PR, provide its
-number and exact current head SHA.
-
-The scan adapts the existing [GitHub Actions example](../github-actions/README.md)
-to OpenAI inference. It uses CLI 0.1.30, standard mode, high effort, Node.js 24,
-and Python 3.12. This evaluates the sample with the pinned published CLI; it does
-not build or validate SDK changes from the PR. Candidate SDK behavior is covered
-by the repository's package and runtime checks. Each evaluation scans the full
-application so unchanged cases remain in scope. Inference consumes API usage.
+Run the scan workflow from protected `main`. Configure a deployment branch rule
+for the `codex-security-smoke-test` environment allowing only protected `main`.
+Store the dedicated service account's `OPENAI_API_KEY` in that environment.
+Manual and scheduled scans both wait for any required environment approval.
+
+The account needs access to the workflow's model and US endpoint from the
+runner's network. The workflow sets `openai_base_url` explicitly on protected
+`main`. Its version and inference settings apply even when evaluating a PR that
+changes the SDK. Use the package and runtime checks to test the proposed SDK.
### Triggers and source selection
-Manual runs on protected `main` accept an open PR number and its exact current
-head SHA, or empty inputs for a baseline. Scheduled runs use the trusted `main`
-workflow commit. PR events and behavior-test completion no longer dispatch
-inference.
-
-The scan checks the PR's base and exact head through GitHub's API before queuing
-and again immediately before inference. Closed, retargeted, and superseded PR
-revisions are skipped. After target validation succeeds, duplicate scan jobs for
-the same PR and exact SHA share a concurrency group, replacing any active or
-pending duplicate. Different revisions use separate groups so a delayed request
-cannot cancel a newer revision's scan. A superseded revision waiting for approval
-can be cancelled manually; if approved, it skips inference after the eligibility
-recheck. Invalid requests do not cancel an active scan. Manual and scheduled `main`
-baselines share a concurrency group only when they evaluate the same exact SHA.
-Updating a PR alone does not start a replacement scan; dispatch the new head when
-another evaluation is needed. Reports identify the source SHA that was scanned.
-
-The workflow installs the CLI outside the checkout and copies committed `app/`
-blobs into a fresh directory. Archive attributes cannot omit or substitute files;
-unsafe paths, links, and submodules fail extraction. The inference job does not
-install PR dependencies, run the application or its tests, or download artifacts
-produced by the PR.
-
-After rechecking eligibility, it removes both full checkouts so the scanner
-cannot read their sample guide, threat model, tests, or answer key. Previous
-reports are also outside the scan input. The API key is available only in the
-scan step, and no GitHub token is passed to the scanner.
+Select **Actions → Invoice Desk OpenAI scan → Run workflow** on `main`. Leave
+both inputs empty for a baseline. For an open PR targeting `main`, supply its
+number in `pr_number` and its exact head SHA in `source_sha`. After pushing
+another revision, dispatch a new run for the new head.
-### Results
+The workflow checks the PR base and head before queuing and immediately before
+inference. It skips closed, retargeted, and superseded PRs. Duplicate requests
+for the same PR and revision replace each other. Different revisions use separate
+concurrency groups. Manual and scheduled baselines share a group at the same SHA.
-Results appear under **Actions → Invoice Desk OpenAI scan**. This separate
-workflow does not create a PR status check or merge gate. Its summary identifies
-the PR and source commit, completion, finding and severity counts, requested scope,
-elapsed time, and package-cache reuse. Passing behavior tests alone does not
-mean a source scan completed.
-
-Reports are retained for seven days. The artifact includes Markdown, findings
-and coverage JSON, the scan manifest, CLI result JSON, SARIF, and
-`invoice-desk-metrics.json`. Metrics record source and workflow revisions,
-scanner settings, exit code, elapsed time, cache hits, and any token usage or
-cost estimates reported by the CLI. Failed or interrupted scans retain measurements
-that were emitted; missing measurements and recall remain unknown. Failed scans
-do not count as zero findings. Authentication state and agent transcripts are
-not uploaded. SARIF is downloadable; the workflow does not create Code Scanning
-alerts or post PR comments.
-
-Findings are report-only. Execution and required-reporting errors fail the job, with
-available reports retained. A successful job means the scan completed; it does
-not establish that the application is secure or that all ten scenarios were
-found. Compare distinct root causes with the QA manifest and review extra
-findings and duplicates separately. There is no exact-count or recall gate yet.
+The trusted workflow installs the published CLI outside the checkout and copies
+committed `app/` files into a fresh directory. It rejects links, submodules,
+and unsafe paths. It removes both checkouts before inference, keeping the guides
+and answer key out of the scan. Only the scan step receives the API key.
-### Cache persistence
+### Results
-The trusted preparation job restores and saves the npm content-addressed download
-cache for the pinned CLI and its bundled runtime dependencies. Its key includes a
-cache schema version, OS, architecture, Node major, and CLI version. The scan job
-restores that same cache and installs with `--prefer-offline`; a cache miss still
-allows a normal registry install. Cache population happens before PR source is
-checked out or an inference credential is available. The scan job has read-only
-cache access and never saves files produced during inference.
-
-Only `invoice-desk-npm-cache/_cacache` is cached. The private
-`CODEX_SECURITY_STATE_DIR`, `codex-home`, authentication files, session logs,
-workbench database, threat models, and previous findings stay out of the cache.
-Each scan starts with fresh analysis state so previous answers do not influence
-fixture evaluation. API prompt-cache token usage is reported separately by the
-CLI; saving the package cache does not preserve model responses. GitHub can
-[evict caches](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows),
-so cache availability is a performance signal, not a pass/fail condition.
+Open the workflow run to check completion, the selected source SHA, finding and
+severity counts, scope, elapsed time, and package-cache reuse. A completed scan
+passes regardless of its finding count. An execution or required-reporting error
+fails the run. Treat missing measurements from a stopped scan as unknown.
-### Establishing the first baseline
+Download the artifact within seven days. It contains the readable report,
+findings, manifest, CLI result JSON, SARIF, and `invoice-desk-metrics.json`.
+For the pinned CLI's older output layout, the manifest's `scan.coverageRef`
+identifies the additional coverage file. Metrics include the source and workflow
+revisions, CLI version, settings, exit code, elapsed time, cache hits, and any
+usage or cost estimate supplied by the CLI. The workflow makes SARIF available
+for download and keeps credentials and transcripts out of the artifact.
-After merging this setup, run a main baseline and inspect the completed reports.
-Run the same revision again to verify a cache hit and compare elapsed time and
-token use. Then select **Actions → Invoice Desk OpenAI scan → Run workflow** on
-`main`, enter an open PR's number in `pr_number` and its exact current head SHA in
-`source_sha`, and verify that the reports identify that source SHA.
+### Cache persistence
-Review actual findings against the ten root causes in the QA manifest. Record
-matched cases, misses, uncertain cases, duplicates, and additional findings;
-confirm secret exposure is matched by the crossed credential boundary. Start
-with report-only recall and cost measurements. Consider a regression gate only
-after repeated completed scans establish normal variation. The initial CI gate
-is operational completion, not zero vulnerabilities or exactly ten reports.
+The trusted preparation job caches public npm downloads for the pinned CLI
+before it checks out PR source or receives inference credentials. The scan job
+restores that cache read-only. Its key includes the cache schema, OS,
+architecture, Node major, and CLI version. On a miss, npm downloads the packages.
-## Scan without including the answer key
+Each scan starts with fresh analysis state. A package-cache hit explains time
+saved during setup. To assess inference costs, use the token and cost metrics
+reported by the CLI.
-The standalone application is `app/`. The harness, scenario labels, and findings
-manifest are siblings outside that directory:
-
-```text
-invoice-desk/
- README.md Sample instructions
- SECURITY.md Threat model and security assumptions
- app/ Standalone scanner input
- README.md Ordinary product and runtime documentation
- server.mjs
- ...
- qa/
- README.md Scenario and scoring guide
- expected-findings.json Expected root causes and source symbols
- app.test.mjs Behavior checks and secure controls
-```
+### Establishing the first baseline
-For an independent discovery run, copy only `app/` into a fresh directory outside
-this checkout and select that directory as the scan target. Keep this README,
-SECURITY.md, the QA directory, and prior reports outside the scanner's input. This
-also avoids inheriting the parent repository's instructions or exposing the answer
-key by walking to a neighboring directory inside the checkout.
-
-The app has no dependency on its surrounding example directory, and runs from
-the copied directory. Its own README describes the product and intended roles,
-without identifying the seeded defects. Source scanning does not require keeping
-a separate server running; the HTTP suite independently verifies runtime behavior.
-
-Review returned findings against the [manifest](qa/expected-findings.json).
-Count distinct matched root causes, missed cases, unexpected findings, and
-duplicates. Ten scenarios are a ground-truth design target, not a guaranteed raw
-finding count from every model run. The fixed seed accounts, loopback HTTP, and
-in-memory data are declared harness assumptions, not additional target findings.
+Run a baseline twice at the same revision. Check the source SHA, cache reuse,
+elapsed time, and reported token use. Then evaluate a PR and confirm that its
+artifact names the head you selected. For each completed scan, compare the
+distinct root causes with the [QA scoring guide](qa/README.md#scanner-evaluation).
+Record matches, misses, uncertain cases, duplicates, and additional findings
+before comparing recall across revisions.
diff --git a/examples/invoice-desk/SECURITY.md b/examples/invoice-desk/SECURITY.md
index 201ec52d9..dfbc230a6 100644
--- a/examples/invoice-desk/SECURITY.md
+++ b/examples/invoice-desk/SECURITY.md
@@ -1,5 +1,9 @@
# Invoice Desk threat model
+This sample threat model is for people evaluating Invoice Desk. For a security
+issue in Codex Security itself, follow the repository's [private reporting
+instructions](../../SECURITY.md).
+
Generated with Codex Security CLI 0.1.30 (`policy`, OpenAI `gpt-5.6-sol`, high
effort), then reviewed against the source and condensed. The CLI inspected a
standalone copy of `app/`. The local QA scope and intended properties below also
diff --git a/examples/invoice-desk/qa/README.md b/examples/invoice-desk/qa/README.md
index 37b3d9470..73d739fa3 100644
--- a/examples/invoice-desk/qa/README.md
+++ b/examples/invoice-desk/qa/README.md
@@ -20,7 +20,7 @@ scanner. The application contains no QA-specific branches or vulnerability label
| ID-010 | Stored HTML injection | Notes become unescaped HTML in another user's invoice view. |
These are ten distinct root causes, not ten disjoint OWASP Top Ten groups. Some
-share broader authorization or disclosure classifications. The manifest gives
+share broader authorization or disclosure classifications. The [scenario manifest](expected-findings.json) gives
suggested CWE tags and source symbols; equivalent, more precise classifications
are acceptable. Multiple reports of the same root cause count once.
diff --git a/examples/invoice-desk/walkthrough.md b/examples/invoice-desk/walkthrough.md
index 362030610..801734cd0 100644
--- a/examples/invoice-desk/walkthrough.md
+++ b/examples/invoice-desk/walkthrough.md
@@ -74,18 +74,24 @@ a later failed or active run is not confused with an earlier completed scan.
Start with `$invoice_run/scan/report.md`, then inspect the structured artifacts.
Paths in this table are relative to `$invoice_run`:
-| Artifact | What to inspect |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `scan/scan-manifest.json` | `scan.id`, `scan.status`, target identity, revision, and requested scope. |
-| `scan/findings.json` | The actual finding's `occurrenceId`, source evidence, root cause, attack path, confidence, and validation. |
-| `scan/coverage.json` | Assessed `surfaces`, their dispositions, `explicitExclusions`, `deferred` work, and any `openQuestions`. |
-| `saved-scan.json` | Saved scan settings and recipe, for reproducing or comparing the run. |
-
-When present, follow `rootCause.evidenceRefs` into `codeEvidence`; otherwise,
-inspect the finding's recorded source locations and evidence. Separate what the
-source proves from what runtime validation actually exercised. Missing runtime validation is a proof gap, not evidence that
-the issue is safe. An empty finding list also says nothing about excluded or
-deferred surfaces.
+| Artifact | What to inspect |
+| --- | --- |
+| `scan/scan-manifest.json` | `scan.id`, terminal `scan.status`, target revision, and the included and excluded paths in `scan.scope`. `scan.review.excludedPaths` lists any additional exclusions. |
+| `scan/findings.json` | Each finding's `occurrenceId`, source locations, confidence, and any recorded root cause, source evidence, attack path, or validation. |
+| `scan-result.json` | The CLI result, including the `review` summary for the current scan. |
+| `saved-scan.json` | Saved settings and the recipe for reproducing the run. |
+
+The manifest describes the scope. It does not measure which percentage of the
+source was read. Details such as deferred work or open questions may be
+available in retained checkpoints. When reading a historical scan, check for
+`scan.coverageRef` and open `coverage.json` only if the manifest references it.
+The [CI baseline](README.md#ci-and-openai-scans) uses its own pinned CLI.
+Compare the [current and legacy layouts](../../plugins/codex-security/references/scan-contract.md#canonical-documents)
+when reading its artifacts.
+
+Follow a finding's `rootCause.evidenceRefs` into `codeEvidence` when available.
+Compare the source evidence with what validation actually exercised. If runtime
+checks were unavailable, record that limit when deciding how to act on the finding.
### Illustrative example: a workspace boundary
diff --git a/github-action/README.md b/github-action/README.md
index 37c347c77..1552961ba 100644
--- a/github-action/README.md
+++ b/github-action/README.md
@@ -3,6 +3,8 @@
Run Codex Security scans in GitHub Actions. Scan a repository or pull request,
check findings against a severity threshold, and export JSON and SARIF reports.
+[Quick start](#quick-start) · [Pull requests](#scan-pull-requests) · [Inputs](#inputs) · [Outputs](#outputs) · [Troubleshooting](#troubleshooting)
+
## Quick start
Use a GitHub-hosted Ubuntu 24.04 x64 runner on GitHub.com or GitHub Enterprise
@@ -12,10 +14,12 @@ with access to the selected model. OpenAI is the default provider. See
Add your API key as a repository secret named `CODEX_SECURITY_API_KEY`, then
save this workflow in `.github/workflows/codex-security.yml`.
-Replace `REPLACE_WITH_REVIEWED_COMMIT` with the full distribution SHA from an
-`action-vX.Y.Z` release that includes automatic Ubuntu sandbox setup.
-For older pins, including `action-v0.6.0`, keep the [manual sandbox setup](https://github.com/openai/codex-security/blob/action-v0.6.0/github-action/README.md#ubuntu-sandbox-setup).
-When using a fork, replace `openai` with the fork owner.
+Open the [GitHub releases](https://github.com/openai/codex-security/releases) and
+select the `action-vX.Y.Z` release you have reviewed. Copy the **full distribution
+commit SHA** from its release notes into `REPLACE_WITH_REVIEWED_COMMIT`. The
+distribution commit contains the Action bundles and CLI dependency lock.
+When updating the SHA, review the new release and run the workflow manually
+before relying on its scheduled runs. For a fork, use its owner and release.
The [repository workflow](examples/repository.yml) below uses `gpt-5.6-sol` and
an estimated $5 cost limit. Change `max-cost` to adjust the budget, or remove it
@@ -44,6 +48,7 @@ jobs:
persist-credentials: false
- name: Scan the repository
id: security
+ # Choose the distribution SHA as described at https://github.com/openai/codex-security/tree/main/github-action#quick-start
uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT
with:
scope: repository
@@ -114,8 +119,8 @@ sandbox requirements apply on both supported GitHub Cloud hosts.
## Inference providers
`provider` and `model` map to `codex-security scan --provider` and `--model`.
-The CLI configures the provider and validates its model requirements. The Action
-uses the same provider names and forwards only the selected provider's credentials:
+The Action supports the four providers below and forwards credentials for the one
+you select. The pinned CLI configures the provider and validates the model.
| `provider` | Step environment |
| ------------------ | ------------------------------------------------------ |
@@ -124,9 +129,11 @@ uses the same provider names and forwards only the selected provider's credentia
| `openrouter` | `OPENROUTER_API_KEY` |
| `fireworks` | `FIREWORKS_API_KEY` |
-OpenAI retains the `gpt-5.6-sol` default. Other providers require an explicit
-model ID your credentials can access. For example, replace the scan step in the
-quick start with:
+OpenAI scans in the Action require an API key in the step environment. The
+standalone CLI can also use a saved ChatGPT login. The Action supplies
+`gpt-5.6-sol` when you omit the OpenAI model. For other providers, pass a model
+ID your credentials can access. For example, replace the quick-start scan step
+with:
```yaml
- name: Scan with OpenRouter
@@ -138,11 +145,10 @@ quick start with:
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
```
-Use `provider: fireworks` and `FIREWORKS_API_KEY` for Fireworks. These providers
-require a reviewed Action revision containing the `provider` input;
-`action-v0.3.0` supports OpenAI only. Installation and dry runs receive no provider
-credentials. For CLI settings beyond the Action's named inputs, use the
-[CLI workflow](../examples/github-actions/README.md).
+Use `provider: fireworks` and `FIREWORKS_API_KEY` for Fireworks. Installation and
+dry runs receive no provider credentials. For providers or settings outside the
+Action's inputs, use the [direct CLI workflow](../examples/github-actions/README.md)
+and check the options in your pinned CLI's `scan --help`.
## Scan with Amazon Bedrock
@@ -199,11 +205,9 @@ jobs:
AWS_SESSION_TOKEN: ${{ steps.aws.outputs.aws-session-token }}
```
-Replace the Action placeholder with a reviewed commit that includes Bedrock
-support and [automatic Ubuntu sandbox setup](#ubuntu-sandbox-setup). For older
-pins, keep the [manual setup step](https://github.com/openai/codex-security/blob/action-v0.6.0/github-action/README.md#ubuntu-sandbox-setup).
-This example is report-only; the usual severity thresholds, summaries,
-annotations, artifacts, and SARIF outputs also work with Bedrock.
+Follow the [quick start](#quick-start) to pin the Action. By default, the job
+reports Bedrock findings in its summary. You can also configure a severity
+threshold, annotations, artifacts, and SARIF uploads.
Both `mode: standard` and `mode: deep` use the selected AWS credentials. Allow
enough time in the AWS role session and job timeout for the scan to finish;
@@ -263,20 +267,20 @@ only for branches that do not use a merge queue. The Action
does not support `merge_group` events, so this workflow cannot provide the required
check for a merge queue.
-When migrating from the previous example, let the new target-specific check run,
-then replace the old **Codex Security** required check with the matching
-**Codex Security / <target-branch>** check. Keeping the old requirement leaves a
-check pending that this workflow no longer produces.
+If branch protection requires a check named **Codex Security**, let the
+target-specific check run once, then replace the old requirement with
+**Codex Security / <target-branch>**. Otherwise GitHub waits for the old check
+before allowing a merge.
The check name includes the target branch because GitHub can evaluate checks on
the shared head commit when a test merge commit has no status. The workflow uses
read-only pull request and Git-ref access on the triggering GitHub host to verify
the event's head, target branch, and live base SHA before the scan and before
accepting its result. The pull record's base SHA alone can lag the branch tip.
-Retargeted PRs get a new review. During a run, a changed snapshot fails verification;
-a stale rerun cannot cancel another event's scan.
-The concurrency group also includes the run ID because GitHub compares group
-names without case sensitivity. Separate workflow events can run concurrently.
+Retargeted PRs get a new review. During a run, a changed snapshot fails verification.
+Each push gets its own concurrency group through `github.run_id`. A new push
+can therefore start a scan while the previous one finishes. A rerun of an old
+event cannot cancel a newer review, even if the target branch changed only in case.
Run the workflow from the current PR event after retargeting. If the target has
advanced since that event, update the PR branch to trigger a fresh review.
See GitHub's [required-check evaluation](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks)
@@ -294,7 +298,8 @@ substitute for the protected-ref workflow requirement.
<!-- action-workflow:pull-request:start -->
```yaml
-# Required-check policy prerequisites, including merge-time freshness, are in the README.
+# Configure branch protection and merge-time freshness before requiring this check.
+# https://github.com/openai/codex-security/tree/main/github-action#scan-pull-requests
name: Codex Security PR
on:
pull_request:
@@ -305,7 +310,8 @@ permissions:
pull-requests: read
concurrency:
- # Group names are case-insensitive; the run ID also separates case-only retargets.
+ # Each push gets its own group. A rerun cannot cancel a newer scan, even
+ # when the target branch changed only in case.
group: codex-security-pr-${{ github.event.pull_request.number }}-${{ github.run_id }}
cancel-in-progress: true
@@ -532,8 +538,8 @@ setup and requirements for self-hosted runners and job containers.
npm and Python are found on the runner's `PATH`; `actions/setup-node` and `actions/setup-python` can select installations.
Python helpers preserve the selected virtual environment and library settings.
The runner's process tracking marker is retained by the scan coordinator and Deep Scan workers.
-OpenAI authentication uses `OPENAI_API_KEY`. With `provider: amazon-bedrock`,
-only the selected AWS credential and region settings are forwarded to the scan.
+See [inference providers](#inference-providers) for the environment variables
+to pass to the scan step.
Temporary runtime files are removed after the job; reports remain available to
downstream steps.
@@ -576,17 +582,20 @@ and artifact uploads retain their existing controls.
CLI diagnostics stream by default. Set `verbose: 'false'` for lifecycle and
elapsed-time messages only.
-## Upgrading from Action 0.2.0
+<a id="upgrading-from-action-020"></a>
-`dry-run: 'true'` now requires `fail-on-severity: none`; put configuration checks
-in a separate job. A dry run does not perform the security review required
-by a severity-enforcing job.
+## Update a pinned Action
-Once your Action pin includes automatic sandbox setup, remove the manual
-Bubblewrap/AppArmor step from jobs running directly on GitHub-hosted Ubuntu
-24.04 VMs. Self-hosted runners and job containers still require a preconfigured sandbox.
+Use the [quick start](#quick-start) to choose a new distribution SHA. Keep
+`dry-run: 'true'` in a separate setup job with `fail-on-severity: none`.
+Run a manual scan with the model, cost limit, and reporting options your
+production workflow uses. Confirm that the summary and any expected artifacts
+appear before using the new pin for a required check.
-The workflow examples use a model and cost limit supported by the pinned CLI.
+For GitHub-hosted Ubuntu VMs, check the sandbox instructions shipped with the
+release you pin. Remove a manual Bubblewrap setup step once your pin includes
+[automatic sandbox setup](#ubuntu-sandbox-setup). Self-hosted runners and job
+containers supply their own sandbox.
## Development
@@ -600,7 +609,8 @@ npm --prefix github-action audit --audit-level=high
npm --prefix github-action/runtime audit --omit=dev --audit-level=high
```
-After editing Action inputs, outputs, or the workflows in `examples/*.yml`, run
+After editing `action.yml` inputs or outputs, or workflows in
+`github-action/examples/`, run
`npm --prefix github-action run docs` to regenerate the README. After changing
bundled source or the runtime lock, run `npm --prefix github-action run build`.
Review the generated README and `dist/*.cjs` changes, rerun validation, and
@@ -626,12 +636,8 @@ the next product version. This development pin does not necessarily track the
latest CLI release. To upgrade it, update it and regenerate
`runtime/package-lock.json`, rebuild the bundles, and run validation.
-The `action-vX.Y.Z` release uses the same version as the corresponding
-`npm-vX.Y.Z` CLI release. Its distribution commit includes the built bundles and
-final runtime lock and differs from the CLI source commit. Pin the full Action
-distribution SHA listed in the Action release, which also includes its manifest,
-SBOM, and a link to the product changelog. See [the release process](../RELEASING.md)
-for publication, verification, and recovery instructions.
+See [the release process](../RELEASING.md) for publication, verification, and
+recovery. The [quick start](#quick-start) explains which commit consumers pin.
<!-- prettier-ignore-start -->
@@ -648,7 +654,7 @@ Inputs are strings. Quote booleans and use newline-separated literal paths for l
| `paths` | Unset | Newline-delimited literal repository-relative files or folders. Only for repository scope; no glob expansion. |
| `diff-base` | Unset | Diff base revision. Defaults to the PR merge base; required outside PRs when scope is diff. |
| `mode` | `standard` | standard or deep. Deep supports repository scans, including selected paths; not diff scans. |
-| `provider` | `openai` | Inference provider, matching scan --provider: openai, openrouter, fireworks, or amazon-bedrock. Supply the selected provider's credentials to the step. |
+| `provider` | `openai` | Providers supported by the Action: openai, openrouter, fireworks, or amazon-bedrock. Pass the selected provider's credentials to the scan step. |
| `model` | Unset | Model to scan with, passed to scan --model. Defaults to gpt-5.6-sol for OpenAI; other providers require an explicit model ID. Cost limits require CLI pricing support for the model. |
| `cyber-access-program` | Unset | Optional Cyber access program: standard, daybreak_blue, or daybreak_red. Unset preserves CLI defaults. Daybreak selections require approved organization and enabled API project access; model access is checked separately. |
| `effort` | `xhigh` | Reasoning effort passed to Codex; supported values depend on the model and provider. |
diff --git a/github-action/examples/pull-request.yml b/github-action/examples/pull-request.yml
index 9a1c4971f..3d5e3efe2 100644
--- a/github-action/examples/pull-request.yml
+++ b/github-action/examples/pull-request.yml
@@ -1,4 +1,5 @@
-# Required-check policy prerequisites, including merge-time freshness, are in the README.
+# Configure branch protection and merge-time freshness before requiring this check.
+# https://github.com/openai/codex-security/tree/main/github-action#scan-pull-requests
name: Codex Security PR
on:
pull_request:
@@ -9,7 +10,8 @@ permissions:
pull-requests: read
concurrency:
- # Group names are case-insensitive; the run ID also separates case-only retargets.
+ # Each push gets its own group. A rerun cannot cancel a newer scan, even
+ # when the target branch changed only in case.
group: codex-security-pr-${{ github.event.pull_request.number }}-${{ github.run_id }}
cancel-in-progress: true
diff --git a/github-action/examples/repository.yml b/github-action/examples/repository.yml
index 6624e4e47..a94449d0d 100644
--- a/github-action/examples/repository.yml
+++ b/github-action/examples/repository.yml
@@ -17,6 +17,7 @@ jobs:
persist-credentials: false
- name: Scan the repository
id: security
+ # Choose the distribution SHA as described at https://github.com/openai/codex-security/tree/main/github-action#quick-start
uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT
with:
scope: repository
diff --git a/github-action/patches/README.md b/github-action/patches/README.md
index 0be0a9513..c9d718226 100644
--- a/github-action/patches/README.md
+++ b/github-action/patches/README.md
@@ -1,8 +1,8 @@
# Action dependency patches
-- @actions/artifact: propagate archive and input-stream errors to the upload promise, cancel streams on upload failure, and hash the bytes forwarded to storage.
-- readable-stream: preserve missing-argument names and initialize the diagnostic before concatenating it.
+- [`@actions/artifact`](@actions+artifact+6.3.1.patch) propagates archive and input-stream errors to the upload promise, cancels streams on upload failure, and hashes the bytes forwarded to storage.
+- [`readable-stream`](readable-stream+4.7.0.patch) preserves missing-argument names and initializes the diagnostic before concatenating it.
-The build applies these patches explicitly with git apply because CI uses npm ci --ignore-scripts. The test pre-hook applies the same patches before testing the installed dependencies. Patch contents are included in the release build-input hashes.
+The build applies these patches explicitly with `git apply` because CI uses `npm ci --ignore-scripts`. The test pre-hook applies the same patches before testing the installed dependencies. Patch contents are included in the release build-input hashes.
-When updating either dependency, review whether upstream has fixed the behavior, refresh or remove its patch, regenerate the distribution, and run npm run validate. The regression tests cover the affected runtime behavior.
+When updating either dependency, review whether upstream has fixed the behavior, refresh or remove its patch, regenerate the distribution, and run `npm --prefix github-action run validate` from the repository root. The regression tests cover the affected runtime behavior.
diff --git a/plugins/codex-security/examples/completed-scan/findings.json b/plugins/codex-security/examples/completed-scan/findings.json
index 1bc33f591..964d48b06 100644
--- a/plugins/codex-security/examples/completed-scan/findings.json
+++ b/plugins/codex-security/examples/completed-scan/findings.json
@@ -2,10 +2,17 @@
"documentType": "codex-security.findings",
"findings": [
{
- "attackPath": null,
+ "attackPath": {
+ "dataflow": {
+ "summary": "The archive supplies an entry name. The extractor uses that name to select the file it writes."
+ },
+ "reachability": {
+ "summary": "The caller must be able to supply an archive for extraction. The service account must have write access to the destination."
+ }
+ },
"confidence": {
"level": "high",
- "rationale": "Direct source trace reaches the filesystem write without a containment check."
+ "rationale": "The destination passed to the file writer is visible in the reviewed code."
},
"extensions": {},
"findingId": "csf_852f90d6e1177502ff113d4a",
@@ -37,11 +44,13 @@
],
"ruleId": "path-traversal.archive-extraction",
"severity": {
+ "changeConditions": "A filesystem policy that confines writes to a disposable import directory would limit the impact.",
"level": "high",
+ "rationale": "The caller can alter files outside the import area with the permissions of the extraction service.",
"score": 8.1,
"scoringSystem": "CVSS:3.1"
},
- "summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
+ "summary": "Archive extraction can overwrite files outside the directory chosen for the import.",
"taxonomy": {
"category": "path-traversal",
"cwe": [
@@ -49,7 +58,10 @@
]
},
"title": "Unsafe archive extraction can escape the output directory",
- "validation": null
+ "validation": {
+ "method": "Static source review",
+ "summary": "The extractor combines the output directory with the entry name and passes the resulting path to the writer. It never checks that the destination stays inside the output directory."
+ }
}
],
"scanId": "scan_example_001",
diff --git a/plugins/codex-security/examples/completed-scan/report.md b/plugins/codex-security/examples/completed-scan/report.md
index 24ade7f13..fe044f757 100644
--- a/plugins/codex-security/examples/completed-scan/report.md
+++ b/plugins/codex-security/examples/completed-scan/report.md
@@ -11,6 +11,7 @@ The scan was configured for the include paths and exclusions listed below.
- Snapshot digest: codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb
- Included paths: .
- Excluded paths: none
+- Scan context: Illustrative scan of a synthetic archive importer.
### Scan Summary
@@ -20,7 +21,7 @@ The scan was configured for the include paths and exclusions listed below.
| Reportable findings | 1 |
| Severity mix | high: 1 |
| Confidence mix | high: 1 |
-| Validation mode | not recorded |
+| Validation mode | Static source review |
Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.
@@ -50,32 +51,34 @@ No explicit canonical threat-model summary was recorded.
| --- | --- |
| Severity | high |
| Confidence | high |
-| Confidence rationale | Direct source trace reaches the filesystem write without a containment check. |
+| Confidence rationale | The destination passed to the file writer is visible in the reviewed code. |
| Category | path-traversal |
| CWE | CWE-22 |
| Affected lines | src/extract.py:41-44 |
#### Summary
-An attacker-controlled path reaches a filesystem write without containment validation.
+Archive extraction can overwrite files outside the directory chosen for the import.
#### Validation
-Direct source trace reaches the filesystem write without a containment check. Validation details were not recorded separately.
+The extractor combines the output directory with the entry name and passes the resulting path to the writer. It never checks that the destination stays inside the output directory.
+
+Validation method: Static source review
#### Dataflow
-The canonical finding records the affected path at src/extract.py:41-44, but no expanded source-to-sink narrative was recorded.
+The archive supplies an entry name. The extractor uses that name to select the file it writes.
#### Reachability
-Reachability was not recorded beyond the canonical finding summary and affected locations.
+The caller must be able to supply an archive for extraction. The service account must have write access to the destination.
#### Severity
-**High** — The scan assigned high severity; no separate canonical severity rationale was recorded.
+**High** — The caller can alter files outside the import area with the permissions of the extraction service.
-Additional runtime or deployment evidence could raise or lower this severity.
+A filesystem policy that confines writes to a disposable import directory would limit the impact.
#### Remediation
diff --git a/plugins/codex-security/examples/completed-scan/scan-manifest.json b/plugins/codex-security/examples/completed-scan/scan-manifest.json
index 3d47f37ad..81298fcbb 100644
--- a/plugins/codex-security/examples/completed-scan/scan-manifest.json
+++ b/plugins/codex-security/examples/completed-scan/scan-manifest.json
@@ -5,7 +5,7 @@
{
"mediaType": "application/json",
"path": "findings.json",
- "sha256": "fea40b4d1f0b92090f1c0a06f43fa03da5bdf4e7f8bdf8e8a7953ae626600d5b"
+ "sha256": "3c63586ea38b07b1d5ad9004ba2afc27f67e79ed164da508c7beae72648eb3b7"
}
],
"completedAt": "2026-05-31T18:09:00Z",
@@ -20,10 +20,12 @@
"excludedPaths": []
},
"scope": {
+ "context": "Illustrative scan of a synthetic archive importer.",
"excludePaths": [],
"includePaths": [
"."
- ]
+ ],
+ "validationMode": "Static source review"
},
"sealedAt": "2026-05-31T18:09:00Z",
"startedAt": "2026-05-31T18:00:00Z",
diff --git a/plugins/codex-security/mcp-app/TESTING.md b/plugins/codex-security/mcp-app/TESTING.md
index e0283c7d1..7f176b5b4 100644
--- a/plugins/codex-security/mcp-app/TESTING.md
+++ b/plugins/codex-security/mcp-app/TESTING.md
@@ -1,12 +1,23 @@
# MCP tests
-From `sdk/typescript`, install both packages' dependencies, prepare the [universal native payload](../native/README.md#package-inputs), and run `pnpm run test:mcp`. That command builds the bundled plugin before testing it. To rerun only the tests after a build, run `pnpm run test:mcp` from this directory.
+[Install the SDK and MCP app dependencies](../../../sdk/typescript/TESTING.md#install-dependencies) and [download the universal native payload](../native/README.md#package-inputs). Run the following from the **repository root**.
-`pnpm run typecheck` checks the TypeScript tests and tooling. `pnpm run test:mcp` runs the sources directly with Node's `--experimental-strip-types` flag, including on Node 22.13.
+To rebuild the bundled plugin and run the MCP tests:
-Node's test runner discovers `tests/test_*.ts` and runs at most two files at once, each in a separate process. Assertions within a file remain sequential. Write new tests in TypeScript and keep shared helpers outside that filename pattern. A failing script fails the command. The reporter streams Node's TAP output and then tries to write Node's JUnit report to `reports/junit.xml`; an unavailable report path warns without changing the test result. CI uploads that file with the Node 22 reports.
+```sh
+pnpm --dir sdk/typescript run test:mcp
+```
+
+To rerun the MCP tests against that build or type-check the MCP sources and tooling:
+
+```sh
+pnpm --dir plugins/codex-security/mcp-app run test:mcp
+pnpm --dir plugins/codex-security/mcp-app run typecheck
+```
+
+The runner streams TAP to the terminal. Read the failing test and assertion there. It also writes `plugins/codex-security/mcp-app/reports/junit.xml` when the output path is available. A report-writing warning leaves the test exit status intact.
-For a serial comparison, run:
+Node runs up to two files at a time in separate processes. Tests inside each file run sequentially. Add tests as `tests/test_*.ts` and keep shared helpers outside that pattern. To compare a failure with serial execution, run this command **from `plugins/codex-security/mcp-app`**:
```sh
node --experimental-strip-types --test --test-concurrency=1 "tests/test_*.ts"
diff --git a/plugins/codex-security/native/README.md b/plugins/codex-security/native/README.md
index 5cea078f7..c0f9e39d7 100644
--- a/plugins/codex-security/native/README.md
+++ b/plugins/codex-security/native/README.md
@@ -2,6 +2,34 @@
These internal bindings supply OS operations that Node does not expose. The `resolve-security-md` helper uses native account lookup on Unix and native path, file, and directory operations on Windows.
+## Package inputs
+
+For universal builds, SDK tests, or Docker builds, select a successful run for the checkout's native sources. You can run [native-artifacts](../../../.github/workflows/native-artifacts.yml) manually on a pushed branch. From the repository root, substitute the run ID and the full artifact name shown on that run. Pull request artifacts use the tested merge commit.
+
+```sh
+gh run download RUN_ID --name native-universal-COMMIT --dir plugins/codex-security/native/prebuilt
+```
+
+The ignored `prebuilt` directory must contain all eight platform directories and the shared notices. Refresh it after changing the native source or build toolchain. Missing payloads fail the build, including on hosts that only load one of them. Installed-package checks load the matching artifact with an empty `PATH`.
+
+The `native-artifacts` workflow calls all three platform workflows and combines their eight verified payloads into `native-universal-<commit>`. PR validation jobs share one artifact assembled by `node-ci`; release and standalone validation runs assemble their own. By default, the standalone MCP builder and npm package include the same complete `mcp/native` tree with the default `--native universal` option; neither compiles nor downloads code at runtime.
+
+The GNU x64 job also runs `notices.mjs` against the locked Cargo metadata. It collects crate licenses and the pinned Rust standard-library notices for both package surfaces. The NAPI crates omit license files from their registry archives, so `licenses/napi.txt` preserves their [pinned upstream license](https://github.com/napi-rs/napi-rs/blob/8bab46ee5dfd48a7b51e8bad3d09aed315ada4df/LICENSE). Review that override when upgrading those dependencies.
+
+## Build the standalone plugin for this host
+
+Install the [pinned Rust toolchain](rust-toolchain.toml), then build the plugin from the repository root:
+
+```sh
+pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
+node plugins/codex-security/mcp-app/scripts/build_native.mjs
+node plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs --output plugins/codex-security/mcp --native host
+```
+
+`build_native.mjs` uses the MCP app's dependencies to compile the TypeScript tools, fetches the locked Cargo dependencies, and writes the host binary and license notices to `native/dist`. `--native host` packages those files for the current platform and architecture under `mcp/`, where the plugin launcher expects them. CI tests this build without the SDK on Linux, macOS, and Windows.
+
+## Build and verify the native bindings
+
The Unix Node-API 8 binding is typed in `binding.mts`. `userHome` looks up raw username bytes through the operating system and returns raw home-directory bytes or a missing result, without Git. `unixEnvironment` reads one named environment value as raw bytes, preserving the distinction between empty and unset values. This keeps configured filesystem locations such as `CODEX_HOME` intact when Node would replace undecodable bytes.
Install the pinned Rust toolchain and the existing TypeScript dependencies, then run from the repository root:
@@ -11,8 +39,7 @@ pnpm --dir sdk/typescript install --frozen-lockfile
pnpm --dir sdk/typescript run build:ci
node plugins/codex-security/native/build.mjs
node plugins/codex-security/native/proof.mjs
-cargo +1.97.1 fmt --check --manifest-path plugins/codex-security/native/Cargo.toml
-cargo +1.97.1 clippy --locked --manifest-path plugins/codex-security/native/Cargo.toml -- -D warnings
+(cd plugins/codex-security/native && cargo fmt --check && cargo clippy --locked -- -D warnings)
```
The proof runs without Python. It checks current and named account lookup, missing accounts, and embedded-NUL rejection. A shell-launched child verifies raw environment bytes, empty values and missing values. CI invokes it with an empty `PATH`.
@@ -29,13 +56,15 @@ The `native-unix` workflow builds Linux artifacts in digest-pinned manylinux 2.2
The `native-musl` workflow uses native x64 and arm64 Ubuntu workers with digest-pinned Rust 1.97.1 Alpine compiler images. Musl builds disable static CRT linkage so Node can load the shared library. After the ELF and private-path checks, each unchanged artifact runs the full proof in pinned Node 20.0.0 Alpine 3.17 and Node 22.13.0 Alpine 3.21 images, with musl 1.2.3 and 1.2.5 respectively. Compilation uses the locked registry offline; runtime containers mount only the source and artifact read-only. Python is absent, and proof processes receive an empty `PATH`.
+## Windows bindings and launcher
+
Windows uses `windows-binding.mts` and the same Rust crate. `WindowsHandle` owns a non-inheritable handle through Rust's `File`; explicit `close()` and garbage collection release it. Handles never cross into Node's CRT descriptor table. Paths and returned names are UTF-16LE buffers without a NUL terminator, preserving lone surrogates. Volume identities are decimal strings; file IDs retain all 128 bits in a buffer.
`scan-read-binding.mts` supplies the held read operations used by sealed-scan validation. `openScanReadRoot` holds a canonical directory; `openFile` traverses relative directory components without following links and opens only regular files. Unix uses descriptor-relative opens. Windows opens each ancestor with attribute-read and traversal access and holds it without delete sharing for the lifetime of the root and each open file. Files support chunked reads so consumers can check cancellation between chunks. `verify` checks that the root path still names the held directory. Explicit `close` and garbage collection release handles. Private-directory permissions and artifact path policy remain with the caller. The native proofs exercise nested reads, link rejection, root replacement, and handle lifetime on every target.
The binding exposes synchronous file and recursive directory creation, attributes and reparse tags, identity and final/opened names, read/write, and exact-handle rename and deletion. Rust's `File` supplies ordinary I/O. Calls return numeric Windows errors, including 6 for closed handles. Buffer ranges and path encoding are checked before use. Overlapped handles are unsupported because pending operations could retain native buffers beyond the call. Path authorization, ancestor traversal, and reparse-point policy remain the caller's responsibility.
-Four additional operations preserve Windows strings at the Node boundary. `windowsArguments` returns the complete OS argument vector, including the executable and Node options, using Rust's CRT-compatible parser. `windowsEnvironment` reads one wide environment name and distinguishes an absent value (`null`) from an empty buffer. `windowsAbsolutePath` resolves against the native current directory and drive directories without requiring the destination to exist. `windowsDirectoryEntries` uses `std::fs::read_dir` and cached `DirEntry::file_type()` values without opening each child; names remain UTF-16LE, and construction or iteration failures return their numeric Windows error and an empty array. Directory symlinks and junctions have both directory and symbolic-link flags. The typed adapter exposes this enumerator through `entriesWithTypes`, which `resolve-security-md --list` uses on Windows. Assessment validation, and deep-review worklists share the typed wide-path reader and writer.
+Four additional operations preserve Windows strings at the Node boundary. `windowsArguments` returns the complete OS argument vector, including the executable and Node options, using Rust's CRT-compatible parser. `windowsEnvironment` reads one wide environment name and distinguishes an absent value (`null`) from an empty buffer. `windowsAbsolutePath` resolves against the native current directory and drive directories without requiring the destination to exist. `windowsDirectoryEntries` uses `std::fs::read_dir` and cached `DirEntry::file_type()` values without opening each child; names remain UTF-16LE, and construction or iteration failures return their numeric Windows error and an empty array. Directory symlinks and junctions have both directory and symbolic-link flags. The typed adapter exposes this enumerator through `entriesWithTypes`, which `resolve-security-md --list` uses on Windows. Assessment validation and deep-review worklists share the typed wide-path reader and writer.
`windows-files.mts` uses native absolute and final paths, preserving raw UTF-16 and the returned device prefix. Non-strict `realpath` resolves the nearest existing ancestor of a missing path; dangling links and other access errors remain errors. Callers must check containment independently. It follows native Windows path behavior rather than emulating Python's special cases for device names, whitespace, verbatim dot segments, and prefix removal. `stat(path, false)` retains exact symbolic-link and reparse-point metadata so callers can reject junction traversal independently of the enumerator's link label. The SDK's public runtime floor remains Node 22.13.0. Node 20.0.0 is an additional native-foundation compatibility proof; it does not change the SDK engine requirement.
@@ -62,29 +91,3 @@ The `native-windows` workflow builds x64 and arm64 with MSVC and a static CRT. I
The build also compiles the test-only `windows-wide-launcher` Rust example. It starts a Node proof child with lone surrogates in arguments, environment values, and its working directory. That child checks complete directory iteration, distinct surrogate and replacement-character files, canonical paths, bounded reads, output truncation, and recursive long paths through the typed adapter. A Rust file guard with sharing disabled remains open while the child enumerates its name; an explicit data read fails with a sharing violation. Attribute-only access is not blocked by Windows file sharing. Adapter path and I/O tests run on the same matrix. Scope binding also reads raw requested-scope and contract paths, preserves ordered JSON and unrelated hash fields, truncates both outputs, and leaves documents unchanged when validation fails. The launcher cleans up the wide fixtures and is never included in the uploaded or bundled native payloads.
Creating file and directory symbolic links requires Windows Developer Mode or the symbolic-link privilege. Without it, the proofs still run their other assertions, including directory junctions, and report the skipped symbolic-link assertions as `false` in their JSON output. CI requires real symbolic links on both architectures and also forces the restricted case to exercise both paths.
-
-## Package inputs
-
-With the pinned Rust toolchain installed, build the plugin on its own:
-
-```sh
-pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
-node plugins/codex-security/mcp-app/scripts/build_native.mjs
-node plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs --output plugins/codex-security/mcp --native host
-```
-
-`build_native.mjs` uses the MCP app's dependencies to compile the TypeScript tools, fetches the locked Cargo dependencies, and writes the host binary and license notices to `native/dist`. `--native host` packages those files for the current platform and architecture under `mcp/`, where the plugin launcher expects them. CI tests this build without the SDK on Linux, macOS, and Windows.
-
-For plugin and npm releases, use the default `--native universal`. It requires all eight verified binaries in `native/prebuilt`.
-
-The `native-artifacts` workflow calls all three platform workflows and combines their eight verified payloads into `native-universal-<commit>`. PR validation jobs share one artifact assembled by `node-ci`; release and standalone validation runs assemble their own. By default, the standalone MCP builder and npm package include the same complete `mcp/native` tree; neither compiles nor downloads code at runtime.
-
-The GNU x64 job also runs `notices.mjs` against the locked Cargo metadata. It collects crate licenses and the pinned Rust standard-library notices for both package surfaces. The NAPI crates omit license files from their registry archives, so `licenses/napi.txt` preserves their [pinned upstream license](https://github.com/napi-rs/napi-rs/blob/8bab46ee5dfd48a7b51e8bad3d09aed315ada4df/LICENSE). Review that override when upgrading those dependencies.
-
-For universal builds, SDK tests, or Docker builds, select a successful run for the checkout's native sources. You can run `native-artifacts` manually on a pushed branch. Use the artifact name shown by that run; pull-request artifacts use the tested merge commit. From the repository root:
-
-```sh
-gh run download <run-id> --name native-universal-<commit> --dir plugins/codex-security/native/prebuilt
-```
-
-The ignored `prebuilt` directory must contain all eight platform directories and the shared notices. Refresh it after changing the native source or build toolchain. Missing payloads fail the build, including on hosts that only load one of them. Installed-package checks load the matching artifact with an empty `PATH`.
diff --git a/plugins/codex-security/references/default-severity-rubric.md b/plugins/codex-security/references/default-severity-rubric.md
index 3f31bb6dd..c1137b655 100644
--- a/plugins/codex-security/references/default-severity-rubric.md
+++ b/plugins/codex-security/references/default-severity-rubric.md
@@ -5,15 +5,20 @@ Judge the attacker's actual starting access, the security boundary crossed, and
## Critical
Reserve Critical for consequential, strongly supported compromise meeting all three conditions:
-- Access: an unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.
-- Impact: crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.
-- Evidence: demonstrated exploitation or strong source-backed validation establishes the complete attack path.
+
+- **Access.** An unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.
+- **Impact.** Crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.
+- **Evidence.** Demonstrated exploitation or strong source-backed validation establishes the complete attack path.
Second-order attacks can qualify: an external attacker plants data that a trusted user or system later processes, causing consequential unauthorized access or privileged actions.
## High
-Assign High when a realistic, evidenced path gives a lower-trust attacker a substantial unauthorized capability they did not already possess. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify; unauthenticated internet access is not required. Consequences include sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, or significant repeatable disruption of a critical or shared service. A dangerous function, production label, internal access, or the existence of a privileged credential alone is insufficient: identify the lower-trust actor, boundary crossing, and consequential new capability.
+Assign High when the evidence establishes all three conditions:
+
+- **Access.** A lower-trust actor can reach the affected operation. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify.
+- **Impact.** Crossing the boundary grants a substantial new capability. Examples include access to sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, and significant repeatable disruption of a critical or shared service.
+- **Evidence.** Identify a realistic path from the actor's existing access to the new capability. A dangerous function, production label, internal access, or privileged credential alone leaves that path unproven.
## Medium
diff --git a/plugins/codex-security/references/finding-detail-fields.md b/plugins/codex-security/references/finding-detail-fields.md
index dfbfd92b9..6d84b0122 100644
--- a/plugins/codex-security/references/finding-detail-fields.md
+++ b/plugins/codex-security/references/finding-detail-fields.md
@@ -37,11 +37,11 @@ The workspace **Evidence** section is an artifact navigator, not another source-
## Structured Example
-This fictional item-service fixture illustrates the field shape. Its paths, identifiers, snippets and scenario were invented for this example; they are not taken from a scan target or finding. Use the shape with your own validated source evidence.
+This fictional item service illustrates how several sections reference the same code evidence. Use source evidence from your scan when filling these fields.
```json
{
- "summary": "In this fictional item service, an authenticated caller can change another tenant's item title by supplying its item identifier. The write route never checks tenant ownership.",
+ "summary": "An authenticated caller can change another tenant's item title by supplying its item identifier. The write route never checks tenant ownership.",
"codeEvidence": [
{
"id": "request-fields",
@@ -52,7 +52,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
"language": "python",
"role": "user_input",
"code": "def rename_fields(body):\n return body[\"itemId\"], body[\"title\"]",
- "explanation": "The fictional request body selects both the item and its replacement title."
+ "explanation": "The request body selects both the item and its replacement title."
},
{
"id": "route-forward",
@@ -74,7 +74,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
"language": "python",
"role": "root_control",
"code": "def rename(self, item_id, title):\n self.items[item_id].title = title",
- "explanation": "The store updates the selected object without an ownership check. A caller can select another tenant's fictional item."
+ "explanation": "The store updates the selected object without an ownership check. A caller can select another tenant's item."
},
{
"id": "item-title",
@@ -96,7 +96,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
"language": "python",
"role": "expected_control",
"code": "def read_item(request, store, item_id):\n item = store.items[item_id]\n if item.tenant_id != request.tenant_id:\n raise PermissionError(\"Item belongs to another tenant\")\n return item",
- "explanation": "The fictional read route compares the stored owner with the authenticated tenant. The write route needs the same invariant."
+ "explanation": "The read route compares the stored owner with the authenticated tenant. The write route needs the same invariant."
}
],
"rootCause": {
@@ -110,8 +110,8 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
]
},
"validation": {
- "method": "static trace of the fictional fixture",
- "summary": "The illustrated request controls the item identifier. Neither the route nor the store checks its owner before replacing the title.",
+ "method": "static source trace",
+ "summary": "The request supplies the item identifier. Neither the route nor the store checks its owner before replacing the title.",
"evidenceRefs": [
"request-fields",
"route-forward",
@@ -122,11 +122,11 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
"The store updates the caller-selected item."
],
"limitations": [
- "This example is invented to demonstrate the field shape; it is not a scan result."
+ "The trace covers the route and store. Runtime middleware was outside the review."
]
},
"attackPath": {
- "summary": "A fictional authenticated caller submits item/rename with another tenant's item identifier and a replacement title.",
+ "summary": "An authenticated caller submits `item/rename` with another tenant's item identifier and a replacement title.",
"dataflow": {
"summary": "request body -> rename_fields() -> rename_item() -> ItemStore.rename() -> item_title()",
"source": "caller-selected item identifier and title",
@@ -140,10 +140,10 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
]
},
"reachability": {
- "summary": "The fictional caller needs access to the authenticated rename route and an item identifier belonging to another tenant.",
- "attacker": "authenticated caller in the invented service",
+ "summary": "The caller needs access to the authenticated rename route and an item identifier belonging to another tenant.",
+ "attacker": "authenticated caller",
"entrypoint": "item/rename",
- "outcome": "unauthorized modification of a fictional item"
+ "outcome": "another tenant's item title changes"
},
"evidenceRefs": [
"route-forward",
@@ -152,20 +152,20 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
],
"impact": {
"level": "medium",
- "why": "The fictional failure permits cross-tenant modification of an item title."
+ "why": "The caller can alter another tenant's title. The store operation changes only that field."
},
"likelihood": {
"level": "medium",
- "why": "The invented route accepts an item identifier from the caller."
+ "why": "The route accepts an item identifier from the caller."
},
"limitations": [
- "No real service, repository, scan target or finding is represented."
+ "The trace does not establish how easily callers can learn another tenant's item identifier."
]
},
- "remediation": "Check the selected item's tenant against the authenticated tenant before writing it; reuse the same ownership check on read and write routes.",
+ "remediation": "Check the selected item's tenant against the authenticated tenant before writing it. Reuse the same ownership check on read and write routes.",
"remediationTests": [
- "Reject a rename when the selected fictional item belongs to another tenant.",
- "Allow an owner to rename its own fictional item."
+ "Reject a rename when the selected item belongs to another tenant.",
+ "Allow an owner to rename its own item."
],
"preventiveControls": [
"Keep the tenant ownership invariant in a shared item-access operation."
diff --git a/plugins/codex-security/references/sarif-adapter.md b/plugins/codex-security/references/sarif-adapter.md
index 7d8ee6c0a..2a287c17b 100644
--- a/plugins/codex-security/references/sarif-adapter.md
+++ b/plugins/codex-security/references/sarif-adapter.md
@@ -1,6 +1,6 @@
# SARIF Adapter
-SARIF is a deterministic export, not the Codex Security source of truth.
+Use SARIF to send saved findings to a code scanning tool. Keep the [sealed scan bundle](scan-contract.md#canonical-documents) for complete finding records.
The adapter:
@@ -23,7 +23,13 @@ Lifecycle, rich validation evidence, attack-path context, and coverage are lossy
SARIF `executionSuccessful` reflects whether the scan reached a successful terminal status. Stopped scans retain findings and include their concrete limitations as warnings. Coverage describes scope and follow-up work; neither successful execution nor an empty finding set certifies exhaustive review.
-Automatic SARIF export during finalization is best-effort so projection errors cannot invalidate a canonical seal. Use the strict adapter entry point when a consumer requires SARIF and should surface export errors.
+When your pipeline requires SARIF, export it explicitly and check the exit status. The command writes the file on success and exits with code `2` on an export error. The scan remains available if automatic SARIF generation failed during finalization.
+
+```bash
+codex-security export /path/to/scan-results --export-format sarif --output results.sarif
+```
+
+See [Export findings](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#export-findings) for the scan selector and source-root options.
References:
diff --git a/plugins/codex-security/references/scan-artifacts.md b/plugins/codex-security/references/scan-artifacts.md
index 70399ed6a..ec18b927d 100644
--- a/plugins/codex-security/references/scan-artifacts.md
+++ b/plugins/codex-security/references/scan-artifacts.md
@@ -91,16 +91,25 @@ Standard scans and Deep Standard scan workers include attack-path analysis direc
## Final Report Paths
-- Workbench-owned Standard or workbench-backed diff draft: `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, reviewState })`
-- Bound Deep Standard worker result: `record_codex_security_scan_draft({ scanId, scope?, threatModel?, findings, reviewState })`; the Deep coordinator writes the aggregated parent draft
-- SDK-owned Standard draft: unsealed `scan-manifest.json` and `findings.json` under the SDK-provided scan directory
-- Deep, workbench-backed diff, or explicitly requested Standard completed results: `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`
-- Final scan report: `<scan_dir>/report.md`
-- Detailed vulnerability write-up: `<scan_dir>/findings/<slug>/<slug>.md`
-- Per-finding PoC and supporting files: `<scan_dir>/findings/<slug>/poc/...`
-- Structural hardening portfolio: `<scan_dir>/hardening/hardening.md`
-- Hardening analysis, proposals, and diagrams: `<scan_dir>/hardening/...`
-- Final report validation notes, when validation fails: `<scan_dir>/report_validation.md`
+All paths below are relative to the scan directory.
+
+| Output | Path |
+| --- | --- |
+| Canonical scan receipt and findings | `scan-manifest.json` and `findings.json` |
+| Readable report | `report.md` |
+| Threat model, when recorded | `threatmodel.md` |
+| Optional detailed finding write-up and supporting files | `findings/<slug>/<slug>.md` and `findings/<slug>/poc/` |
+| Optional structural hardening portfolio | `hardening/hardening.md` and supporting files under `hardening/` |
+| Report validation notes when validation fails | `report_validation.md` |
+| Legacy coverage document | `coverage.json` only when referenced by the manifest's `scan.coverageRef` |
+
+The current manifest stores additional excluded paths in `scan.review.excludedPaths`. See the [sealed scan contract](scan-contract.md#canonical-documents) for examples.
+
+### Draft submission and retrieval
+
+Workbench-owned Standard scans and workbench-backed diff scans submit drafts through `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, reviewState })`. Bound Deep workers submit their findings and review state through the same tool. The Deep coordinator writes the aggregated parent draft. SDK-owned Standard scans write unsealed manifest and findings files in the SDK-provided scan directory.
+
+For Deep, workbench-backed diff, or explicitly requested Standard completed results, call `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`.
## Fix Finding Paths
diff --git a/plugins/codex-security/references/scan-contract.md b/plugins/codex-security/references/scan-contract.md
index 374073dbc..3d6ef4782 100644
--- a/plugins/codex-security/references/scan-contract.md
+++ b/plugins/codex-security/references/scan-contract.md
@@ -4,17 +4,18 @@ This contract defines the canonical machine-readable documents for scans that re
## Canonical Documents
-A sealed terminal bundle contains these files under `<scan_dir>`:
+Open the [current example manifest](../examples/completed-scan/scan-manifest.json) alongside its [findings](../examples/completed-scan/findings.json) and [readable report](../examples/completed-scan/report.md).
-- `scan-manifest.json`: immutable terminal scan receipt after finalization
-- `findings.json`: semantic finding records retained when the scan reached its terminal outcome
-- `scan.review`: additional excluded paths, stored in the manifest
+| File or field | What it contains |
+| --- | --- |
+| `scan-manifest.json` | Immutable receipt with scan ID, target, scope, terminal status, seal time, and artifact digests. |
+| `findings.json` | Semantic finding records retained at the terminal outcome. The manifest's `scan.findingsRef` points to this file. See [finding detail fields](finding-detail-fields.md) for optional evidence and analysis. |
+| `scan.review` inside the manifest | Additional excluded paths (`excludedPaths`). |
+| `report.md` | Human-readable report generated from the canonical JSON. The [SARIF adapter](sarif-adapter.md) explains which fields survive export. |
-Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
+See [final report paths](scan-artifacts.md#final-report-paths) for the complete directory layout and optional outputs.
-Optional structured finding details used by rich consumers are documented in `finding-detail-fields.md`. They remain part of each semantic finding record, not a projection parsed from a readable report.
-
-The existing `report.md` output remains a readable projection. Generated exports such as SARIF are also downstream projections, not part of the canonical semantic source of truth.
+For a [legacy manifest](../examples/legacy-completed-scan/scan-manifest.json) with `scan.coverageRef`, read the [referenced coverage document](../examples/legacy-completed-scan/coverage.json) alongside the findings. Check for this field before opening a separate coverage file. Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
Deep-scan SARIF results and CSV rows preserve their existing instance-level presentation and add only the canonical candidate id needed to group child reports. Standard-scan CSV presentation remains unchanged.
@@ -24,7 +25,7 @@ Retention is an explicit consumer decision. Producing a sealed bundle must not s
## Manifest Semantics
-A sealed manifest records the terminal timestamp and hashes for the canonical documents and immutable evidence receipts included in that bundle. Readable reports and generated exports are projections and are not included in the canonical seal. Later adapters may read the sealed bundle to create projections, but must not mutate the sealed manifest or canonical documents. Store projections separately. Every sealed manifest includes exactly one artifact record for each canonical JSON document, and artifact paths must not repeat.
+The manifest records the terminal timestamp and a SHA-256 digest for each file listed in `scan.artifacts`. Each path appears exactly once. The current example lists `findings.json` alone. A legacy bundle also lists its referenced coverage file, and scans that retain immutable evidence receipts list those files too. The manifest carries these digests and does not hash itself. Adapters read the sealed files and write reports or exports separately from the seal.
Producers should use UTC ISO 8601 timestamps in the native SDK or plugin format. All schema-valid fractional widths remain readable on supported Python versions; parsing uses native microsecond precision. History and finding queries use native date precision and stable ID tie-breakers; ordering beyond millisecond precision is not guaranteed. Stored timestamp text remains unchanged.
@@ -116,14 +117,9 @@ For file-authored drafts, put `reviewState` inside `scan` in the unsealed manife
Comparison uses the later scan's execution status, configured scope and additional exclusions before classifying an absent finding as resolved.
-- scan mode and inventory strategy
-- included and excluded paths
-- reviewed surfaces
-- detailed receipt references
-- explicit exclusions
-- deferred work
+### Scan modes and inventory
-`mode` records the requested scan workflow:
+`scan.mode` (or `mode` in a legacy coverage document) records the requested scan workflow:
| Mode | Meaning |
| ----------------- | ------------------------------------------------------------- |
@@ -135,11 +131,7 @@ Comparison uses the later scan's execution status, configured scope and addition
| `working_tree` | Staged or unstaged local changes |
| `deep_repository` | Exhaustive repeated repository-wide scan |
-`inventoryStrategy` records how the producer enumerated the reviewed content, independently of the requested scan workflow:
-
-The discovery helper's `in_scope_files.txt` input contains one UTF-8 path per line. LF and CRLF separators are accepted; filenames containing CR or LF are unsupported. Other path whitespace and spelling are preserved.
-
-For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repeated discovery is workflow metadata, not a different inventory strategy.
+In a legacy coverage document, `inventoryStrategy` records how the producer enumerated the reviewed content:
| Inventory strategy | Meaning |
| ------------------ | --------------------------------------------------------- |
@@ -149,7 +141,11 @@ For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repe
| `directory` | Deterministic non-Git directory inventory |
| `custom` | Producer-defined inventory described by detailed receipts |
-Review state lists reviewed surfaces, exclusions, and follow-up work. The manifest records execution status. Existing sealed bundles retain legacy metadata unchanged.
+The discovery helper reads one UTF-8 path per line from `in_scope_files.txt`. It accepts LF and CRLF separators and preserves other whitespace. Filenames containing CR or LF are unsupported. For a whole-repository Deep scan, use `repository` for the inventory strategy and `deep_repository` for the mode.
+
+### Detailed review state in drafts, checkpoints, and legacy coverage
+
+These records can list reviewed surfaces, exclusions, and follow-up work. Use the terminal manifest for execution status.
Map detailed ledger closure into completed surface summaries in this order:
@@ -163,18 +159,18 @@ Map detailed ledger closure into completed surface summaries in this order:
Record each explicit exclusion with a `pattern` and `reason`. Record each deferred unit with a stable `id`, a `reason`, and optional `paths` or `surfaceIds`.
-Detailed ledgers remain under the numbered scan artifact directories.
+When retained, detailed ledgers live under the numbered scan artifact directories.
Receipt references must point to regular non-symlink files under `artifacts/`.
`scan.review` retains additional exclusions for adapters and comparison. Legacy sealed scans continue to reference their original `coverage.json`.
## Canonical Report Semantics
-The two canonical JSON files are also the only semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
+In the current format, the manifest and findings are the semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
Record report-specific semantics without duplicating data already represented elsewhere:
- `scan.scope`: optional narrative `summary`, reviewed artifact names, runtime/test status, validation mode, scan context, and limitations. Include/exclude paths remain the authoritative scope boundaries.
-- `scan.threatModel`: structured summary plus assets, trust boundaries, attacker capabilities, security objectives, and assumptions, or `{ "format": "markdown", "content": "<exact model text>" }` for a retained document. Optional model `scope` and `origin` identify the modeled paths and source separately from the scan's scope. When completed Deep reviews supply different models, the parent retains the first model here and the other models on their worker records in `scan.reviewState.reviews`. The host derives `<scan_dir>/threatmodel.md` from the primary model; it is an exportable projection, not an independently authored input.
+- `scan.threatModel`: structured summary plus assets, trust boundaries, attacker capabilities, security objectives, and assumptions, or `{ "format": "markdown", "content": "<exact model text>" }` for a retained document. Optional model `scope` and `origin` identify the modeled paths and source separately from the scan's scope. When completed Deep reviews supply different models, the parent retains the first model here and the other models on their worker records in the retained draft or checkpoint review state. The host derives `<scan_dir>/threatmodel.md` from the primary model; it is an exportable projection, not an independently authored input.
- finding `validation`: validation method, direct evidence, counterevidence, and the conclusion used by the report.
- finding `codeEvidence`: stable, exact source snippets with labels, locations, language, and explanations; `rootCause`, `validation`, and `attackPath` select the snippets they need through `evidenceRefs`.
- finding `rootCause`: the violated invariant and the code that breaks it. Do not substitute a path/line restatement for the explanation.
@@ -187,12 +183,10 @@ These fields are optional for compatibility with existing v1 canonical artifacts
## Schemas
-New completed findings must match `schemas/tools/scan-draft.schema.json`. Finalization rejects legacy field aliases, malformed optional details, and invalid semantic slugs instead of repairing them. Historical sealed reports are validated through an in-memory compatibility adapter; their saved bytes remain unchanged. Stopped-scan recovery still salvages saved evidence.
+New completed findings must match the [scan draft schema](../schemas/tools/scan-draft.schema.json). Finalization rejects legacy field aliases, malformed optional details, and invalid semantic slugs instead of repairing them. Historical sealed reports are validated through an in-memory compatibility adapter; their saved bytes remain unchanged. Stopped-scan recovery still salvages saved evidence.
-- `schemas/scan-manifest.schema.json`
-- `schemas/findings.schema.json`
-- `schemas/coverage.schema.json` for legacy scans only
+- [Scan manifest schema](../schemas/scan-manifest.schema.json)
+- [Findings schema](../schemas/findings.schema.json)
+- [Coverage schema](../schemas/coverage.schema.json) for legacy scans
V1 consumers ignore unknown properties for forward compatibility. Producers must still validate documented fields and should not emit undocumented properties casually.
-
-Representative valid contract examples live under `examples/completed-scan/`.
diff --git a/plugins/codex-security/tests/LAYER1_FOLLOWUPS.md b/plugins/codex-security/tests/LAYER1_FOLLOWUPS.md
index aa7833b74..e28bc4804 100644
--- a/plugins/codex-security/tests/LAYER1_FOLLOWUPS.md
+++ b/plugins/codex-security/tests/LAYER1_FOLLOWUPS.md
@@ -1,6 +1,6 @@
# Layer 1 Deterministic CI Coverage
-This file is the source of truth for portable deterministic, no-model Codex Security plugin CI coverage. Future pull requests that extend Layer 1 should update this checklist and link back here in their PR description.
+Maintainers use this backlog to track deterministic plugin test coverage. The [CI workflow](../../../.github/workflows/node-ci.yml) defines the active jobs, and the [CI guide](../../../docs/ci.md) explains when they run. Update this list when adding coverage or completing a deferred item.
## Covered
@@ -10,11 +10,12 @@ This file is the source of truth for portable deterministic, no-model Codex Secu
- **Prompt linting:** agent default prompts are required to be non-empty.
- **CLI and harness dry runs:** Python command entry points support `--help`; major command paths run against temporary repositories and scan bundles without a model call.
- **Static checks:** Ruff checks the plugin scripts and tests. An isolated Python interpreter imports every module in `scripts/`.
-
- **MCP dependencies and templates:** CI installs the MCP package with its frozen lockfile; its deterministic tests exercise Deep Scan prompt-template rendering.
## Deferred
+These proposals are open. Each entry describes how to verify completion.
+
- **Strict mypy hard gate:** the current scripts and tests have pre-existing strict-mypy errors. Enable the gate after reducing that baseline to zero; completion means `mypy scripts tests --strict` passes without suppressing real contract errors.
- **Full documentation reference validation:** add a checker for internal file paths, Markdown anchors, and documented command invocations. Completion means every plugin-local reference resolves and every documented command has a deterministic smoke test.
- **Expanded report and SARIF snapshots:** add larger artifact snapshots and platform-specific path portability fixtures. Completion means representative Windows, macOS, and Linux path cases are covered without platform-dependent golden churn.
diff --git a/plugins/codex-security/tests/threat-model-visualize/browser/README.md b/plugins/codex-security/tests/threat-model-visualize/browser/README.md
index 0815a4f20..739fc5f20 100644
--- a/plugins/codex-security/tests/threat-model-visualize/browser/README.md
+++ b/plugins/codex-security/tests/threat-model-visualize/browser/README.md
@@ -2,6 +2,8 @@
Run this explicit browser check from the repository root with Node 22+, Python 3.12+, and an installed Chrome or Chromium. It uses Node built-ins and Chrome's DevTools pipe; no browser package or download is required.
+The environment must allow launching the browser, listening on loopback, and DevTools automation. If managed Chrome disables remote debugging, use an environment where automation is permitted. The runner reports browser startup failures.
+
```sh
CHROME_PATH='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' \
PYTHON=python3.12 \
@@ -13,5 +15,3 @@ On Linux set `CHROME_PATH` to the installed browser executable, for example `/us
The test builds a standalone HTML document from a synthetic assessment and model, serves it on loopback, selects the alternate route and an unverified detection control using the real DOM, and clicks **Download map SVG**. It reads the actual download, parses it as XML in Chromium, and checks route highlights, route text, evidence qualification, conditions, and removal of the live zoom transform.
Temporary files, browser profile, browser process, and server are cleaned up. Optionally set `BROWSER_SMOKE_ARTIFACTS` to retain the generated HTML and downloaded SVG, including when an output assertion fails. `BROWSER_SMOKE_SKILL_DIR` can point to a disposable copy of the skill to test a baseline or mutation without editing production files.
-
-The environment must permit launching the browser and listening on loopback, and browser policy must allow DevTools automation. Managed Chrome may disable remote debugging; the test fails with startup diagnostics in that case. Do not change or bypass that policy to run this check. A separate browser-tool walkthrough is useful validation but does not establish that this standalone runner passed.
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 0b35f4de7..c5996754c 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -42,14 +42,9 @@ npm install --global @openai/codex-security
cs --version
```
-`cs` is a short alias for `codex-security`; both commands run the same CLI.
-The installation creates both commands in npm's global executable directory,
-which must be on your `PATH`. If `cs` already resolves to another tool, use
-`codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
-`npx @openai/codex-security` without a global installation.
-
-Continue with the [CLI walkthrough](#cli). To run without a global installation,
-replace `cs` in the CLI examples with `npx @openai/codex-security`.
+Continue with the [CLI walkthrough](#cli). You can use the full command
+`codex-security` if `cs` names another tool on your PATH. If installation
+fails with `EEXIST`, use `npx @openai/codex-security` in place of `cs`.
### Install the TypeScript SDK
@@ -59,24 +54,6 @@ Install the package locally in your TypeScript project:
npm install @openai/codex-security
```
-### Package and plugin versions
-
-For bug reports, run `npx @openai/codex-security info --json` in the project
-where the SDK is installed, or `codex-security info --json` for a global install.
-Include the npm version (`cliVersion` and `sdkVersion`), bundled plugin manifest
-version (`bundledPluginVersion`), and Codex runtime and SDK pins (`codexVersion`
-and `codexSdkVersion`). If you used a marketplace plugin, a plugin supplied by
-path, or a custom Codex executable, include its version separately.
-
-For example, `npm view @openai/[email protected] gitHead dist.integrity`
-shows the registry's source commit and tarball digest. Compare `gitHead` with
-the commit for tag `npm-v0.1.5`. `npm pack @openai/[email protected]` downloads
-the archive, including `package/_bundled_plugin/.codex-plugin/plugin.json`.
-
-The [release workflow](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml)
-verifies the signed attestation that binds the tarball to the tagged commit.
-For `0.1.0` and `0.1.1`, npm omits `gitHead`. Use the commit from the verified attestation.
-
## Authentication
Sign in with ChatGPT:
@@ -131,39 +108,6 @@ Bedrock scans use AWS credentials and model access. They do not require
[Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
for setup, model selection, and verification.
-## Read existing Cloud findings
-
-The Security plugin includes `$cloud-findings` for accounts where Codex Security
-Cloud is available. Install the plugin through your configured Codex marketplace,
-sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
-the intended account and workspace. Installation alone does not authenticate the
-connection. Local scans do not require Cloud, and an API key used for scanning
-does not replace the Cloud connection.
-
-In Codex desktop or the interactive Codex CLI, ask:
-
-> Use $cloud-findings to list findings for example/security-demo in my selected
-> workspace. Inspect the highest-severity finding and its report, and show its
-> recorded assignee, patch links, verification results, and latest scan status.
-> Do not change anything.
-
-After completing connection setup, the same host connection can be used by
-`codex exec`:
-
-```bash
-codex exec --ephemeral --json -s read-only 'Use $codex-security:cloud-findings to read findings and the latest scan status for example/security-demo in my selected workspace. Inspect one finding and its report. If the workspace or repository is ambiguous, explain the required selection and stop. Do not change anything.'
-```
-
-Noninteractive execution needs an existing authenticated connection; it cannot
-complete first-time sign-in. If authentication expires, the app is unavailable,
-or workspace policy denies access, complete the reported setup action before
-retrying. Those failures do not mean the repository has no findings.
-
-Assignment, issue validation, patch checks, periodic fix checks, and finding
-lifecycle status are separate records. Some finding sources do not provide all
-of them. The read workflow reports missing data and incomplete evidence pages,
-and does not describe failed or unfinished scans as clean.
-
## Run a scan from TypeScript
Scan a repository you own or have permission to assess:
@@ -198,19 +142,21 @@ permissions; newly created directories are private to you by default.
| --------------------------------- | ---------------------------------------------------------------- |
| `findings.findings` | Findings from this scan. |
| `reportPath` | Path to the Markdown report. |
-| `review` | Additional excluded paths. This is not file coverage. |
+| `review.excludedPaths` | Additional paths the scan excluded. |
| `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. |
-Review the requested paths and exclusions alongside the execution outcome.
-`reviewState.deferred` records unfinished requested work, while
-`reviewState.openQuestions` records optional follow-up separately.
+Read `result.manifest.scan.status` and `result.manifest.scan.scope` alongside
+`result.review.excludedPaths` to see the outcome, the requested scope and any
+additional exclusions. A completed scan can report zero findings within that scope.
-Review the scan status and scope 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.
+If the run retained a draft or checkpoint, its `reviewState.deferred` lists
+unfinished work and `reviewState.openQuestions` lists follow-up questions.
+See [saved scan files](docs/cli.md#understand-scan-scope-and-follow-up-work)
+for the current and legacy layouts. Reports and logs can include source code,
+vulnerability details and credentials. Review them before sharing.
Saved-history excerpts use scanned Git objects without fetching missing data.
Working-tree diff scans omit excerpts, as do historical scans whose source or
@@ -484,6 +430,10 @@ See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget
### Validate an existing finding
+`validate()` sends the finding to your configured model provider. The model's
+review tools can read the checkout, with network access and web search disabled.
+Validation uses source evidence and skips builds, tests and application execution.
+
```ts
import { writeFile } from "node:fs/promises";
@@ -498,15 +448,10 @@ console.log(result.disposition, result.report);
await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
```
-Pass finding text or a JSON-serializable object, not a file path. Standalone
-validation uses source evidence in a read-only, offline session. It does not build
-the target, execute application code, run tests or PoCs, or add a scan to history.
-The validator returns the assessment without writing report files. The example
-saves `result.report` in an existing directory. `outputDir` selects the session
-directory, not a report destination. Callers that previously read reports from it
-must save `result.report` instead.
-Callers needing runtime proof must arrange a separate reproduction step. Standard,
-Deep, and diff scan validation keep their existing workflows.
+Pass literal finding text or a JSON-serializable object. The assessment is
+returned to the caller and has no scan history entry. The example saves
+`result.report` in an existing directory. Use `outputDir` to select the
+session directory. If you need runtime evidence, arrange a separate check.
The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
`reportable` can rely on static analysis; `deferred` means there is insufficient
@@ -526,6 +471,8 @@ See [host-provided standalone validation](docs/validate-records.md).
workspace that the caller has intentionally made writable:
```ts
+import { CodexSecurity } from "@openai/codex-security";
+
const security = new CodexSecurity();
try {
const result = await security.patch({
@@ -535,7 +482,6 @@ try {
summary: "User input reaches a raw SQL query.",
locations: [{ path: "src/query.ts", startLine: 42 }],
},
- signal,
onActivity(activity) {
console.log(activity.description);
},
@@ -593,23 +539,16 @@ After [installing the CLI](#install-the-cli), sign in if needed:
cs login
```
-From your repository, optionally [draft a `SECURITY.md`](#generate-a-security-policy)
-that explains what counts as a security issue in your project:
-
-```bash
-cs policy .
-```
-
-The draft is saved outside your repository. Review the diff and notes, edit the
-draft, then copy only `SECURITY.md` to the **Policy target** shown. Skip this step
-to keep your current policy or scan without one.
-
-Then scan the repository:
+From the repository you want to review, run:
```bash
cs scan .
```
+Open the report at the path printed on completion. To inspect the latest
+completed scan for this checkout, run `cs scans show`. To provide a project
+policy for future scans, [draft and review a `SECURITY.md`](#generate-a-security-policy).
+
To narrow the scan scope or check the configuration before scanning:
```bash
@@ -683,6 +622,39 @@ on CODEOWNERS, source, and Git history. Declared owners take priority over Git
contributors. Suggestions do not assign tickets. See
[owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.
+### Read existing Cloud findings
+
+The Security plugin includes `$cloud-findings` for accounts where Codex Security
+Cloud is available. Install the plugin through your configured Codex marketplace,
+sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
+the intended account and workspace. Installation alone does not authenticate the
+connection. Local scans do not require Cloud, and an API key used for scanning
+does not replace the Cloud connection.
+
+In Codex desktop or the interactive Codex CLI, ask:
+
+> Use $cloud-findings to list findings for example/security-demo in my selected
+> workspace. Inspect the highest-severity finding and its report, and show its
+> recorded assignee, patch links, verification results, and latest scan status.
+> Do not change anything.
+
+After completing connection setup, the same host connection can be used by
+`codex exec`:
+
+```bash
+codex exec --ephemeral --json -s read-only 'Use $codex-security:cloud-findings to read findings and the latest scan status for example/security-demo in my selected workspace. Inspect one finding and its report. If the workspace or repository is ambiguous, explain the required selection and stop. Do not change anything.'
+```
+
+Noninteractive execution needs an existing authenticated connection; it cannot
+complete first-time sign-in. If authentication expires, the app is unavailable,
+or workspace policy denies access, complete the reported setup action before
+retrying. Those failures do not mean the repository has no findings.
+
+Assignment, issue validation, patch checks, periodic fix checks, and finding
+lifecycle status are separate records. Some finding sources do not provide all
+of them. The read workflow reports missing data and incomplete evidence pages,
+and does not describe failed or unfinished scans as clean.
+
### Publish findings to Cloud
`publish scan --to cloud` uploads selected findings to Codex Security Cloud.
@@ -821,6 +793,18 @@ paths. Keep state and scan artifacts private and outside the repository.
## Compatibility
+### Package and plugin versions
+
+When reporting a problem, run `codex-security info --json` with the installation
+that produced it. For a local SDK installation, run
+`npx @openai/codex-security info --json` in that project. Include `cliVersion`,
+`sdkVersion`, `bundledPluginVersion`, `codexVersion` and `codexSdkVersion`. If
+you supplied a separate plugin or Codex executable, include its version too.
+
+For package provenance, compare the registry's `gitHead` and `dist.integrity`
+with the release tag and tarball. If a package omits `gitHead`, use the commit
+in its [verified release attestation](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml).
+
### Custom plugins
New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
diff --git a/sdk/typescript/TESTING.md b/sdk/typescript/TESTING.md
index ed1cd80ca..61b30f536 100644
--- a/sdk/typescript/TESTING.md
+++ b/sdk/typescript/TESTING.md
@@ -1,25 +1,49 @@
# Testing the SDK and CLI
-Use the pnpm version in `package.json` and Bun 1.3.14, matching required CI.
-Install both the SDK and MCP app dependencies before building or testing.
-Prepare the [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
-before running a command that builds the bundled plugin.
-Run these commands from `sdk/typescript`:
+## Install dependencies
+
+Use [the repository’s pinned pnpm version](../../package.json) and [CI’s Bun version](../../.github/workflows/node-ci.yml). From the repository root, enter the SDK directory and install both packages:
```sh
+cd sdk/typescript
pnpm install --frozen-lockfile
pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile
-pnpm run check:plugin-source
+```
+
+The commands below run from `sdk/typescript` unless a different directory is named. For a test that builds or loads the bundled plugin, first [download the universal native payload](../../plugins/codex-security/native/README.md#package-inputs). The SDK’s `test`, `test:ci`, `test:mcp` and `prepack` scripts all build that bundle.
+
+## Run a focused test
+
+Run the file for the behavior you changed. This example exercises progress parsing:
+
+```sh
bun test --timeout 30000 ./tests-ts/worker-progress.test.ts
+```
+
+For an MCP change, follow the [MCP test guide](../../plugins/codex-security/mcp-app/TESTING.md). To see which suites this repository requires for a PR, see [How this repository tests pull requests](../../docs/ci.md).
+
+## Check the package
+
+Run static checks, the MCP suite and the SDK suite after installing the dependencies and native payload:
+
+```sh
+pnpm run check:plugin-source
pnpm run types
-pnpm run test:mcp
pnpm run format
+pnpm run test:mcp
pnpm run test
-pnpm run test:ci
+```
+
+To collect JUnit and coverage while running the SDK suite, use `pnpm run test:ci` in place of `pnpm run test`. To test what an npm consumer receives, pack the archive and pass its exact path to the inspection command:
+
+```sh
pnpm pack --pack-destination ../../dist
+pnpm run check:package ../../dist/openai-codex-security-X.Y.Z.tgz
pnpm run test:package
```
+Replace `X.Y.Z` with the version in the filename printed by `pnpm pack`.
+
The authored plugin lives in `plugins/codex-security`. `pnpm pack` generates
the ignored `_bundled_plugin` runtime payload from `plugins/codex-security/plugin-files.json` during
`prepack`, including the MCP runtime built from `mcp-app`; do not edit generated
@@ -29,8 +53,6 @@ not the generated `mcp/server.mjs` or compressed runtime chunks.
`pnpm run check:plugin-source` fails if any file beneath `_bundled_plugin` is
tracked by Git. Required CI runs the same check before installing dependencies.
-For CI's full archive inspection, pass the exact `.tgz` path printed by
-`pnpm pack` to `pnpm run check:package`.
These checks include native Node contracts for SDK completion, cancellation,
close cleanup, and CLI terminal sanitization. They use the installed package,
controlled model output, and the real workbench without live model credentials.
@@ -61,20 +83,7 @@ before proposing a coverage floor.
## Native artifacts in fresh development environments
-SDK tests, including Ona's **Run tests** automation, require the eight verified
-native payloads. Installing Node and Python dependencies alone does not supply
-them. Select a successful native-artifacts or node-ci run built from this
-checkout's native sources and toolchain, then use the exact artifact name from
-that run (pull request artifacts use the tested merge commit):
-
-```sh
-gh run download <run-id> --name native-universal-<commit> --dir plugins/codex-security/native/prebuilt
-```
-
-Run this command from the repository root before starting the automation.
-Refresh the artifact after changing native source or toolchain. The standalone
-plugin supports a host-only build; that does not satisfy the SDK's universal
-packaging tests. See the [native build guide](../../plugins/codex-security/native/README.md).
+Before running the full SDK tests or Ona’s **Run tests** task in a fresh checkout, [download the verified native package inputs](../../plugins/codex-security/native/README.md#package-inputs) for that checkout. Refresh them whenever the native source or build toolchain changes.
## Python test dependencies
@@ -84,7 +93,7 @@ Use Python 3.10 or later. From the repository root, install the Python test and
python -m pip install --disable-pip-version-check --no-input -r plugins/codex-security/requirements-test.txt
```
-This replaces `pip install -e 'plugins/codex-security[test]'`. Tests load the plugin scripts from source; the repository does not need an installed Python distribution.
+Tests load the plugin scripts from source; the repository does not need an installed Python distribution.
The requirements file is the single list of pinned Python test dependencies. Ruff and pytest settings remain in `plugins/codex-security/pyproject.toml`; the Ruff dependency and its `required-version` setting must agree.
## Writing tests
@@ -186,8 +195,7 @@ become uneven. From the SDK directory, pass reports for one platform to
(use `linux` or `darwin` for the other platforms). The updater sums testcase
durations for executed cases per file and uses their median across reports. A
report that skipped every case in a file leaves its timing hint unchanged. Other
-platforms retain their hints. Review and commit the generated snapshot. The initial hints use runs
-`39521539826`, `39694506447`, and `39694510011`. Keep runner versions, coverage,
+platforms retain their hints. Review and commit the generated snapshot. Keep runner versions, coverage,
timeouts, seeds, and platform-specific checks unchanged when comparing scheduling
changes; compare complete JUnit inventories and outcomes as well as wall time.
@@ -205,38 +213,9 @@ sealed artifacts. Each platform uploads its JUnit report. To replay the weekly j
Ordinary source pull requests run focused contracts for the shard runner, timing
metadata, report comparator, and Windows test-root helper in the required SDK suite.
-Manual and reusable workflow runs default to comparing the previous layout
-(three shards on Linux/macOS,
-seven on Windows) with the expanded production layout (six on Linux/macOS,
-fourteen on Windows), for 39 sharded runner jobs. Both layouts use the same serial
-Bun runner and platform timing snapshot; the comparison combines all shards for
-each OS before checking inventory and outcomes. Local full-suite runs still cover
-unsharded cross-file ordering. More jobs add setup overhead, so compare required-green
-latency and summed runner time alongside shard test timings.
-
-The comparison uses the same seed for property cases and test ordering in every
-layout. Manual runs use the workflow run number. Calls from pull request workflows
-use seed 1. Reports have unique OS/layout/shard
-names. The workflow requires every expected shard report
-before accepting comparisons, then compares complete shard groups by test
-identity, outcome, assertion count, and occurrence count, retaining legitimate
-repeated names from parameterized tests while detecting missing or extra instances. It records every
-shard's timing, including failed shards, in the job summary. It is not a required
-check or part of the release trigger.
-
-Required CI and shard diagnostics use Bun 1.3.14 without `--parallel` or
-`--isolate`. Runtime upgrades and worker-based execution need separate
-qualification of process-failure propagation and report/coverage finalization
-before promotion.
-
-Both layouts use the same property seed and coverage settings. Required CI uses
-the default property seed and collects Linux coverage; diagnostics use the seed
-above and the same Linux LCOV instrumentation. Artifacts include JUnit and
-coverage in separate OS/layout/shard paths. The automated comparison checks JUnit
-inventories, outcomes, and assertion counts; LCOV remains available for covered-line
-comparison during qualification. Compare inventories across required CI and
-diagnostics, but measure scheduling changes between diagnostic layouts.
-Both workflows install ripgrep on Linux so the inventory-path test executes.
+For a scheduling comparison, run [test-quality](../../.github/workflows/test-quality.yml) with `compare-layouts` enabled. It runs the same serial Bun test inventory under two shard layouts. Compare the aggregate JUnit identities, outcomes, occurrence counts, and assertion counts for each OS, then review Linux LCOV artifacts for coverage differences. The job summary includes failed shard timings. Compare both elapsed time to a green gate and total runner time.
+
+Use the same Bun version, seed, timeouts and coverage settings across layouts. Run the full local suite separately to exercise cross-file ordering. Qualify changes to Bun or its execution mode separately, including how test failures propagate and whether JUnit and coverage finish writing.
Keep the machine-policy test serial. Do not replace the full required suite
with `--changed`: Python files, schemas, fixtures, and workflows loaded at
@@ -245,7 +224,7 @@ runtime are not necessarily part of Bun's import graph.
## Mutation testing
Mutation tests require Node 22.18+ or 24.11+ because Stryker 10 uses Babel 8.
-CI runs this tooling on Node 24.15.0. The SDK itself still supports Node 22.13+.
+Use the Node version pinned by the [mutation job](../../.github/workflows/test-quality.yml). The SDK’s supported runtimes are listed in its [package manifest](package.json).
The commands below install Stryker from the separate, frozen `sdk/mutation`
lockfile and run it from the SDK directory.
@@ -254,7 +233,7 @@ pnpm run test:mutation
pnpm run test:mutation --mutate src/worker-progress.ts
```
-The initial Stryker trial covers progress parsing, safe error messages, and
+The Stryker configuration covers progress parsing, safe error messages, and
pure cost arithmetic. It uses the fixed default property-test seed and writes
HTML and JSON under `reports/mutation`. Review surviving mutants for missing
behavior assertions or equivalent changes. There is no score gate yet; set
diff --git a/sdk/typescript/docs/classify-severity-records.md b/sdk/typescript/docs/classify-severity-records.md
index c3257bf85..4b173ed95 100644
--- a/sdk/typescript/docs/classify-severity-records.md
+++ b/sdk/typescript/docs/classify-severity-records.md
@@ -6,28 +6,42 @@ state. It uses the same bidirectional JSON-RPC transport as [record deduplicatio
Use `--records` alone or with `--runs N`; model execution remains host-provided.
The SDK exports `classifySeverityRecords`, `classifySeverityRecordsInputSchema`,
-and their input, result, and review-request types. The protocol and input have
-version `1`. Before using the protocol, confirm that your installed CLI lists
-`--records` in `classify-severity --help`.
+and their input, result, and review-request types. The protocol and input use version `1`.
## Immutable inputs
-Send one newline-delimited JSON-RPC request with `method: "run"` and these params:
-
-```ts
-{
+Send one JSON-RPC `run` request. This Node.js example prints the complete
+request as one line of JSON. Replace the model name with one your host
+authorizes. Write that line to the CLI's stdin and keep the pipe open to
+[reply to each review](#host-execution-contract).
+
+```js
+import { createHash } from "node:crypto";
+
+const id = "canonical-one";
+const findingJson = JSON.stringify({
+ findingId: id,
+ title: "Missing tenant filter",
+ summary: "The invoice lookup omits the tenant ID.",
+});
+const inputSha256 = createHash("sha256")
+ .update(findingJson, "utf8")
+ .digest("hex");
+const params = {
version: 1,
- rubric: { revision: 4, markdown: rubricMarkdown, sha256: rubricSha256 },
model: "your-authorized-model",
effort: "high",
- records: [{ id: "canonical-one", revision: 7, findingJson, inputSha256 }]
-}
+ records: [{ id, revision: 7, findingJson, inputSha256 }],
+};
+console.log(
+ JSON.stringify({ jsonrpc: "2.0", id: "run-1", method: "run", params }),
+);
```
The `rubric` field is optional. Omit it to classify with the
[built-in severity rubric](https://github.com/openai/codex-security/blob/main/plugins/codex-security/references/default-severity-rubric.md), using the same configured
independent host reviews and usage accounting. The result echoes its built-in
-revision (currently `1`) and exact Markdown SHA-256. Supplying a custom rubric
+revision and exact Markdown SHA-256. Supplying a custom rubric
replaces the default completely and preserves the supplied revision/hash binding.
Do not reuse cached results across differing rubric hashes; preserve the default
snapshot from the review prompt alongside its returned binding. Default revisions
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 4127f1963..fbd2299bd 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -16,13 +16,6 @@ codex-security info --json
`info --json` reports package, plugin, runtime, and model details.
`scans` and `findings` default to their `list` subcommands.
-To retrieve GitHub code scanning alerts without an MCP server, use
-[`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
-findings file in local scan history, use
-[`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
-GitHub import returns upstream alerts for validation; file import saves findings
-without running security analysis.
-
## Find a workflow
- [Sign in or configure a provider](#authentication).
@@ -31,10 +24,8 @@ without running security analysis.
[save project settings](#project-files).
- [Review one system across repositories](#review-one-system-across-repositories)
or [run independent bulk scans](#bulk-scans).
-- [Import vendor findings locally](#import-vendor-findings-locally),
- [import Sonar issues selected in Codex](#import-sonarqube-cloud-issues),
- [save findings as a scan](#import-findings-as-a-saved-scan), or
- [retrieve GitHub alerts](#import-alerts-from-the-cli).
+- [Choose an import command](#import-vendor-findings-locally) to save a scan,
+ collect upstream alerts, or store vendor evidence locally or in Cloud.
- [Inspect saved scans and rerun them](#scan-history-and-reruns),
[classify severity](#classify-finding-severity), or
[suggest owners](#suggest-finding-owners).
@@ -558,8 +549,9 @@ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
Scans already validate findings against local source. Add `--validate` to run
the existing standalone validation workflow for each reported finding after
-the scan, using the same selected Cyber access program. Validation has read-only
-filesystem access with network and web search disabled. Each assessment uses a
+the scan, using the same selected Cyber access program. Validation sends each
+finding to the configured model provider. Its review tools have read-only
+filesystem access, with network access and web search disabled. Each assessment uses a
separate evidence directory; the combined report is saved as
`<scan-dir>/validation.md`, or a uniquely suffixed report
if that path already exists. Each completed assessment is saved immediately;
@@ -603,26 +595,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
fail after registration but before writing its artifacts; investigate those
failures through its history record and any available logs. When artifacts were
retained, use the saved results directory returned by `scans show` to inspect
-whichever of these files are present:
-
-| File | What to check |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
-| `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
-| `coverage.json` | `includePaths` and `excludePaths` for scope boundaries; `explicitExclusions` for recorded exclusion reasons; `surfaces` for reviewed areas; `deferred` for unfinished review work; and optional `openQuestions`. |
-
-Deferred items can identify affected `paths` or `surfaceIds`. Surface
-`receiptRefs` link to retained evidence under `artifacts/` when available.
-Deep Scan summaries retain coverage from accepted worker reviews, including
-worker-specific deferred work. Check those details as well as the final findings.
-
-These records describe what the scan recorded, not an exhaustive file-by-file
-audit. A retained source inventory, when present, lists inputs rather than
-proving that each file was reviewed. An absent path in a surface summary does not
-establish whether it was read, and the scan ID cannot reconstruct evidence that
-was never saved.
-Session logs can help explain failures and tool activity, but do not prove
-complete review either.
+the saved files:
+
+| File | What to check |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scan-manifest.json` | `scan.status` and `scan.target` identify the outcome and snapshot. `scan.scope` lists requested inclusions and exclusions. `scan.review.excludedPaths` lists additional excluded paths in current scans. |
+| `findings.json` | Reported findings, source locations and supporting evidence. |
+| `report.md` | A readable summary of the scope and findings. |
+
+When a checkpoint is retained, `checkpoint-head.json` identifies the file in
+`checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
+unfinished work and `reviewState.openQuestions` lists follow-up questions.
+Older manifests with `scan.coverageRef` point to a separate `coverage.json`
+with reviewed surfaces, explicit exclusions and deferred work. A saved source
+inventory identifies inputs. Neither that inventory nor session logs establish
+which files the scan reviewed in full.
For a local plugin scan, ask Codex to open the saved scan and explain its scope,
exclusions, deferred work, and follow-up questions. CLI history can also locate
@@ -666,12 +653,13 @@ completeness values to determine scan status or exit codes.
```bash
codex-security init
-codex-security scan . -c codex-security.yaml --dry-run --json
codex-security info -c codex-security.yaml --json
+codex-security scan . -c codex-security.yaml --dry-run --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`,
+Keep `-c` on both `info` and the scan preview to inspect the same target and
+limits. 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.
@@ -1394,9 +1382,15 @@ Supply the validation prompt again when rerunning.
## Import vendor findings locally
-Choose an input in the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
-Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
-to confirm the import and read the resulting records.
+Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
+
+| Input and goal | Command | Service contacted | Where to find the result |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
+| Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
+| Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
+| Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
+| Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` to enable `publish findings`,
`findings imported`, `import sonar`, `import semgrep`, `import snyk`, and `import github-advisories`. Only `1`
@@ -1406,9 +1400,19 @@ and the existing `import github` alert collector remain available independently.
Disabling the flag retains saved records.
For `publish findings`, `--to` is required. With `--to local`, `--repository`
-takes a checkout path. The reader detects the file format, and `--format json`
-selects the output format. A local preview writes no findings and needs no Cloud
-login, network connection, or model call.
+takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
+The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
+saving findings or calling a model. For example, preview a complete Endor
+Finding export from the matching checkout, replacing the namespace, project
+and branch in the source key.
+
+```sh
+codex-security publish findings /private/path/endor-findings.json --provider endor \
+ --to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
+```
+
+After reviewing the findings and exclusions, rerun the command without
+`--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
Local readback uses `findings imported [PATH]`. The path defaults to the current
directory. Each imported record starts as `not_assessed`. Unknown revisions and
@@ -1418,22 +1422,16 @@ source key and finding ID reports created, updated, or unchanged records.
Records omitted from the new selection stay stored. An import with exclusions
exits with status 1. Local imports can retain evidence that exceeds Cloud's per-finding limits.
-Use `publish findings FILE --provider semgrep --to local` for a
-[selected Guardian MCP capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings)
-or a [saved Semgrep Web API selection](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).
-Guardian uses its existing sign-in. Its imported IDs are separate from Web API IDs.
-To [collect a full Semgrep project and branch](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch), use
-`import semgrep PROJECT --semgrep-deployment SLUG --semgrep-ref REF [--semgrep-product sast|sca|ai_sast]`. Both saved formats support local and Cloud import.
-
-For completed scans exported in the Codex Security JSON or CSV format, use
-[scan import](#import-findings-as-a-saved-scan).
-
-For Checkmarx One CLI JSON or CxSAST XML, use `--provider checkmarx` and pass the
-verified Git URL with `--source-repository-url`. See the [Checkmarx SAST guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/checkmarx.md).
+Preview the same file and source key again for the intended destination before
+publishing. Semgrep Guardian captures support local import only. Both Web API
+formats, a selected SAST capture and a full project collection, support local
+and Cloud import. The [Semgrep input selector](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) lists the four routes.
## Import Trivy dependency findings
-Use `--provider trivy` to read a schema-v2 repository or filesystem report (JSON or gzip). Pass `--trivy-scan-root .` for a whole checkout or a checkout-relative path for a subtree. A corroborated remote repository scan can infer the root. See the [Trivy import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) for a preview command, repository matching, and how to save or publish the results.
+Use `--provider trivy` for language-package vulnerabilities in schema-v2
+repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
+to set the scan root and check manifest paths.
## Import Endor Labs findings
@@ -1441,6 +1439,46 @@ Use `--provider endor` for one Endor project and context. The
[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
SARIF compatibility, and the local preview.
+## Import SonarQube Cloud issues
+
+`import sonar --dry-run` writes a private capture and returns its path. Preview
+that capture for the intended destination before confirming. A Cloud confirmation
+saves the issues locally and publishes them. Use `--full-output` with
+`--format json` or `--format jsonl` for a structured result.
+[Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
+
+## Import GitHub findings locally or to Cloud
+
+Use `--provider github` with separate source keys for
+[code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
+[Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
+[security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
+Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
+
+### Import GHSA advisories separately
+
+Use `import github-advisories OWNER/REPO` for published repository advisories
+or add `--github-advisory-source global` and one or more `--github-advisory`
+IDs to collect global advisories. Check the installed dependency against each
+affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
+
+## Import alerts from the CLI
+
+Collect open code-scanning alerts on the default branch and save the complete
+array outside the checkout. Use a private temporary directory and run
+validation from the matching checkout. Validation sends the evidence to your
+configured model provider.
+
+```sh
+out=$(mktemp -d) &&
+ codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
+ codex-security validate "$out/alerts.json"
+```
+
+The collector reads alerts, including third-party SARIF uploads. It does not
+start a scan. For filters, ref selection and SDK validation, see the
+[code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
+
## Publish findings to Cloud
Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
@@ -1567,197 +1605,24 @@ readback.
### Import Snyk findings
-For an existing monitored Snyk project, use
-`codex-security import snyk PROJECT_ID --snyk-org ORG_ID --source-repository-url URL --format json`
-and save its output for `publish findings --provider snyk` with `--to local` or `--to cloud`. Set
-`SNYK_TOKEN` with read access. The default product is Open Source. Select
-`--snyk-product code` for Code and `--snyk-api-origin` for a regional API
-(default `https://api.snyk.io`). See the [hosted import example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md#existing-issues-from-snyk).
-
-Use `--provider snyk` for Open Source SCA vulnerabilities. Native CLI JSON, plugin
-exports, and Open Source SARIF can produce different occurrence IDs. Use a
-separate source key for each format. See the [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for
-collection and preview commands.
+Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
+monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
+covers saved files, distinct source keys for each format, and collection with
+`import snyk`.
### Import Wiz findings
-The [Wiz guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md) shows how to preview saved package vulnerabilities,
-SAST findings, repository secrets, or IaC findings. The format reference below
-describes the fields to preserve when preparing those exports.
-
-#### Select findings and a destination
-
-Acquire selected findings through an authorized Wiz connection and save the
-complete native response. The publisher reads the saved file. MCP summaries,
-Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
-the selected response against the format for its finding family. Acquisition
-against a live Wiz tenant requires separate qualification.
-
-For saved reports, use the detailed repository package vulnerability export
-shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
-metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
-
-#### Package vulnerability inputs
-
-Native package input can be a Wiz JSON vulnerability report, a vulnerability
-finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
-with one package record per line. The repository package-vulnerability CSV
-profile below is also supported. Plain and gzip-compressed files are accepted.
-A response that advertises another page is rejected. Complete the requested pages
-or save only the explicitly selected records; retain the named collection for
-SAST, repository secrets, and IaC.
-
-For native package records, include `id`, `name`, `detailedName`,
-`vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
-package, image, and repository metadata.
-
-The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
-`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
-this profile; other Wiz report types use different fields.
-For repository imports, `CloudPlatform` must identify GitHub and
-`CloudProviderURL` must identify a repository branch. The repository URL must
-match the selected Cloud repository or, for local import, one of the checkout's
-Git remotes when configured. This also applies when the parsed findings are saved and
-read again as normalized JSONL. Other resource types are excluded.
-
-CSV imports use `ID` as the occurrence identity and retain every parsed field,
-including unknown columns and quoted multiline values, in `source_data.row`.
-Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
-Vendor resolution status stays in the original evidence. The importer does not
-derive a branch or revision from a tree URL, or treat last-detected time as a
-record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
-and duplicate occurrence IDs among otherwise importable records stop the import.
-Review any excluded records in the preview before publishing.
-
-Normalized JSONL is also accepted:
-
-```json
-{
- "source_finding_id": "vendor-finding-42",
- "evidence": {
- "title": "Vulnerable example package",
- "severity": "high",
- "source_data": { "id": "vendor-finding-42" }
- }
-}
-```
-
-Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
-exports; a selected project filter does not change the vendor namespace. Confirm
-that the selected assets or builds map to this repository. The raw Wiz adapter
-retains each record in `source_data`, uses reported severity, and leaves unknown
-branch/revision empty. Repository-branch findings retain their repository-relative
-file paths; container and other workload paths remain vendor evidence rather than
-source-code locations. It does not
-fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
-Findings from external network scans are excluded from this package vulnerability
-mapping.
-
-#### SAST, repository secrets, and IaC inputs
-
-For SAST, repository secrets, and IaC, save the documented JSON API collection:
-
-| Finding family | Collection | Raw occurrence identity |
-| ------------------ | ---------------------------- | ----------------------- |
-| SAST | `data.sastFindings.nodes` | `sast:<id>` |
-| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
-| IaC | `data.iacFindings.nodes` | `iac:<id>` |
-
-The collection identifies the mapping. Bare arrays of these raw findings are
-excluded because their overlapping fields do not identify a family. An export
-may contain multiple named collections. GraphQL errors and unfinished pages stop
-the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
-relationship to source code does not make it a repository secret.
-
-Each new finding needs a verified source repository URL. Supply `repository.url`
-in the finding's repository metadata, or include the matching repository inventory
-in `data.versionControlResources.nodes`. For secrets, repository metadata is under
-`resource.typedProperties.repository`. The importer joins the inventory's
-`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
-`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
-must agree with the inventory and with the selected Cloud repository before any
-finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
-establishes case-insensitive repository matching on custom GitHub Enterprise
-hosts. Fresh imports preserve the reported branch name literally. Duplicate
-entries for one repository ID must agree on their platform and repository URL.
-For example, this synthetic selection supplies the inventory alongside its SAST
-collection:
-
-```json
-{
- "data": {
- "sastFindings": {
- "nodes": [
- {
- "id": "finding-42",
- "name": "Untrusted query construction",
- "severity": "HIGH",
- "repository": { "id": "source-repository-1" },
- "filePath": "src/query.ts",
- "startLine": 10,
- "endLine": 12
- }
- ]
- },
- "versionControlResources": {
- "nodes": [
- {
- "repository": {
- "id": "source-repository-1",
- "url": "https://github.com/example/project"
- }
- }
- ]
- }
- }
-}
-```
+<a id="select-findings-and-a-destination"></a>
+<a id="package-vulnerability-inputs"></a>
+<a id="sast-repository-secrets-and-iac-inputs"></a>
+<a id="preserved-evidence"></a>
+<a id="convert-csv-reports"></a>
-#### Preserved evidence
-
-The adapters preserve each selected raw node exactly in `source_data`. Typed
-`evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
-and family-specific evidence:
-
-| Family | Evidence retained in typed fields |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
-| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
-| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
-
-Vendor status and verdict remain separate from Codex assessment. A secret's
-introduced commit is not its scanned revision. Missing source revisions and scan
-IDs stay unknown. A logical IaC resource is retained in the original record and
-does not establish that it is deployed. Precise original timestamps remain in
-`source_data`; only an explicit record-update timestamp maps to the whole-second
-`source_updated_at` field. SAST creation time and IaC last-seen time are not update
-timestamps.
-
-#### Convert CSV reports
-
-Native SAST and secret report downloads can be CSV, including gzip-compressed
-CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
-for its actual column headers into normalized JSONL, preserving each original row
-in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
-verifying the source repository. Use the same prefixed occurrence ID shown above
-so API and report imports update the same finding; normalized IDs are accepted
-exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
-for a vendor occurrence ID. Missing IDs or severity must be corrected at the
-source rather than invented.
-
-For repository-secret reports, select `path` and `lineNumber` for source
-navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
-as the introduced commit. The standard secret metadata API does not supply a
-path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
-`rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
-repository/branch metadata. Preserve the original fields; source locations must
-be repository-relative, and an end line requires a start line. Keep credential
-values out of the metadata selection; the importer does not retrieve or test
-credentials or apply remediation instructions.
-
-Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
-integer range is rejected; export those values as strings to preserve them
-exactly. Invalid records appear in `excluded` with their source ID and reason.
+Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
+The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
+[named SAST, secret and IaC collections](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#sast-repository-secrets-and-iac-inputs),
+[retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
+[conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
### Publish completed scans
@@ -2447,155 +2312,18 @@ reinstall with the same threshold. Restore the backup if installation fails.
The installer uses host Git for the selected repository and respects
`core.hooksPath`.
-## Import SonarQube Cloud issues
-
-The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
-binding, saved issue-search pages, and replay. Unlike a saved-file
-`publish findings` preview, `import sonar --dry-run` writes a private capture
-and returns its path. Confirm with the capture from the preview for the intended
-destination. A Cloud confirmation imports the selected issues locally and
-publishes them to Cloud. Use `--full-output` with `--format json` or
-`--format jsonl` for a structured success or error envelope.
-
-## Import GitHub findings locally or to Cloud
-
-Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
-[Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
-[GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
-and preview findings. All three use `--provider github`. Keep a separate source
-key for each family. Saving locally or publishing to Cloud requires the
-[external-import opt-in](#import-vendor-findings-locally).
-
-The code-scanning and advisory CLI collectors use `gh` to authenticate for
-`GH_HOST` (default `github.com`). A GitHub
-plugin connection can select alerts but does not sign the CLI in.
-Collection retains the selected ref's instance. Branches keep separate
-evidence. An alert-wide dismissal takes precedence over the selected instance's
-open or fixed state. Missing security severity stays `unknown`. See
-[code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
-
-The SDK offers the same preview and publication boundary for Cloud:
-
-```ts
-import {
- importGitHubCodeScanningAlerts,
- normalizeGitHubCodeScanningAlerts,
- prepareNormalizedExternalPublication,
-} from "@openai/codex-security";
-
-const alerts = await importGitHubCodeScanningAlerts({
- repository: "example/project",
-});
-const prepared = await prepareNormalizedExternalPublication(
- normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
- {
- provider: "github",
- repository: "https://github.com/example/project",
- sourceKey: "github.com/example/project/code-scanning",
- },
-);
-console.log(prepared.preview);
-// After reviewing the preview:
-const receipt = await prepared.publish();
-```
-
-For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
-the original alerts to retain evidence that exceeds Cloud limits. Pass the result
-to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
-its preview, and call `import()`. Alternatively, pass the saved alert file directly
-to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
-
-### Import GHSA advisories separately
-
-See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
-to save repository advisories or selected global database records and preview
-them for the chosen destination. Advisories report affected ranges and
-available fixes. Verify installed dependencies and applicability in the
-destination repository separately.
-
-Repository lists default to published advisories. When selecting exact IDs, omit
-`--github-state`. Selecting a repository advisory by its GHSA ID can return a
-draft if you have access.
-Global collection requires one or more explicit IDs.
-Acquisition failure yields no partial selection. Access to private or
-unpublished repository advisories requires the repository advisory read
-permission and access to the record. See
-[GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
-
-In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
-pass `normalizeGitHubAdvisories(advisories, "cloud")` to
-`prepareNormalizedExternalPublication()`. For local storage, pass
-`normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
-`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
-`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
-records. Both forms require `repository: "OWNER/REPO"` as source or target context.
-Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
-
-## 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.
- githubHost: "github.com",
- 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`.
-Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
-If you omit the token, the SDK asks the GitHub CLI for credentials, including
-its supported 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
Hosts that manage their own model execution can use `codex-security validate --records`.
This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
-`validate` assesses candidates from local source evidence without building the
-target, executing application code, running tests or PoCs, or contacting services.
-It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
-validation, and `patch` still fixes and verifies findings. Both commands accept files
-or literal text and work in the current directory. Saved finding/occurrence IDs
-select their original repository for patching.
+`validate` sends the finding to your configured model provider. Its review
+tools can read the checkout, with network access and web search disabled.
+The assessment uses source evidence and skips builds, tests, PoCs and application
+execution. Both `validate` and `patch` accept files or literal text in the
+current directory. Patching by saved finding or occurrence ID selects the
+original repository.
Basic patching also works in ordinary directories and Git worktrees before their
first commit. Directory change tracking excludes `.git` and `.svn` metadata.
@@ -2637,7 +2365,7 @@ locally does not guarantee provider support. Keep the schema small and use it on
when the caller needs structured results. It checks the result's shape, not whether
the security conclusion is correct. Relative paths resolve from the current directory.
-The validator no longer writes reports. Save the assessment by redirecting stdout:
+Save the assessment by redirecting stdout:
`codex-security validate findings.json > assessment.md`. For runtime proof, run a
separate reproduction step. Missing facts are reported as proof gaps; a finding
supported by source evidence does not require runtime reproduction.
@@ -2699,7 +2427,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
An illustrative result is below. Actual decisions depend on the repository;
this example assumes a tenant filter exists but deployment routing is unavailable.
-Both candidate IDs remain in the output, including the unresolved claim.
+Before updating finding records, [check that each input ID appears exactly
+once](validate-records.md#check-the-returned-ids), including unresolved
+candidates.
```json
{
diff --git a/sdk/typescript/docs/dedupe-records.md b/sdk/typescript/docs/dedupe-records.md
index fe05c22a6..2985bfc91 100644
--- a/sdk/typescript/docs/dedupe-records.md
+++ b/sdk/typescript/docs/dedupe-records.md
@@ -6,25 +6,26 @@ Findings API. It performs no authentication, update checks, local Codex launches
candidate retrieval, or persistence. The host owns repository authorization,
model execution, sessions, credentials, cancellation of remote work, and cleanup.
-The SDK equivalent is:
+## A minimal exchange
-```typescript
-import { deduplicateRecords } from "@openai/codex-security";
+To check the connection before dispatching reviews, send an empty batch as
+one line on the CLI's stdin. Keep the pipe open.
-const result = await deduplicateRecords(input, {
- reviewRunner: {
- async run(request, { signal } = {}) {
- return await hostReview(request, signal); // Return the structured answer.
- },
- },
- signal: controller.signal,
-});
+```text
+{"jsonrpc":"2.0","id":"run-1","method":"run","params":{"version":1,"observations":[],"candidateRelationships":[]}}
```
-`DeduplicateRecordsInput`, `DeduplicateRecordsResult`,
-`DeduplicationReviewRequest`, and `DeduplicationReviewRunner` are exported types.
-The entry point validates the input structure, unique identities, and candidate
-references before any review.
+The CLI writes one line to stdout with the same run ID. With no candidates,
+this exchange makes zero model calls.
+
+```text
+{"jsonrpc":"2.0","id":"run-1","result":{"version":1,"status":"completed","groups":[],"unresolved":[]}}
+```
+
+For a populated batch, supply observations and candidate relationships as below.
+[Answer each review](#review-exchange) using its own request ID, then read the
+[terminal result](#final-response-and-persistence) using your original run ID.
+The [Python host](#runnable-python-fake-host) demonstrates the complete exchange.
## Input and identities
@@ -36,7 +37,8 @@ from -9007199254740991 through 9007199254740991 and are compared without coercio
Use strings for larger numeric identifiers. Review IDs are generated strings;
request and response ID namespaces are directional.
-The host sends:
+The following messages are expanded for reading. Serialize each object to a
+single line before writing it to the pipe. For a populated batch, the host sends:
```json
{
@@ -131,8 +133,7 @@ and beneficiaries are nonempty. Candidate-only observations never become
beneficiaries, even when selected as the final representative. An incoming
observation participating in several reviews appears in each review's metadata.
-This is additive metadata: JSON-RPC remains 2.0 and input/result versions remain 1.
-Older hosts may ignore it; hosts that require attribution must validate it
+Hosts that use attribution for accounting must validate it
and reject missing or unknown identities before executing a review. Persist the
request UUID and attribution before provisioning remote execution. The host owns
accounting and any partitioning of invocation anchors by origin scan; the CLI
@@ -203,16 +204,11 @@ For failure or an inconclusive review, send an explicit error:
A host error ends the review without another submission. Invalid final model
answers, missing final decisions, and host errors make the whole batch unresolved;
previous successful reviews in that run do not become persistence decisions.
-The existing algorithm treats a validated `DISTINCT` as a nonmatch, when
+The CLI treats a validated `DISTINCT` as a nonmatch, when
supplied finding content is insufficient to establish a shared correction. If the host considers the review
inconclusive, it must return an error rather than manufacture a `DISTINCT` answer.
No new `INCONCLUSIVE` model decision is introduced.
-The existing screening, independent pair review, contradiction-aware grouping, and
-severity-based representative selection are reused. No local review checkpoints
-are read or written in records mode. Local saved-scan execution retains its
-existing tool-submission validation and workflow checkpoints.
-
### Continuing a review
A `review.run` request with `supportsContinuation: true` can receive the result
@@ -278,6 +274,30 @@ observation as unique. Cross-run replay/idempotency and reconciliation of remote
work whose acceptance is uncertain belong to the host; a new process creates
new review IDs and does not resume earlier remote execution.
+## TypeScript integration
+
+The SDK accepts the same input and returns the result directly. In this host
+integration, provide an authorized `reviewRunner` that executes the request
+and returns the structured answer. Pass an `AbortSignal` to support cancellation.
+
+```ts
+import {
+ deduplicateRecords,
+ type DeduplicateRecordsInput,
+ type DeduplicationReviewRunner,
+} from "@openai/codex-security";
+
+export function reviewDuplicates(
+ input: DeduplicateRecordsInput,
+ reviewRunner: DeduplicationReviewRunner,
+ signal: AbortSignal,
+) {
+ return deduplicateRecords(input, { reviewRunner, signal });
+}
+```
+
+`DeduplicateRecordsResult` and `DeduplicationReviewRequest` are also exported.
+
## Cancellation and protocol failures
To cancel the active run, send a notification:
diff --git a/sdk/typescript/docs/findings-service.md b/sdk/typescript/docs/findings-service.md
index 2f9821564..ef27f7ffb 100644
--- a/sdk/typescript/docs/findings-service.md
+++ b/sdk/typescript/docs/findings-service.md
@@ -1,23 +1,33 @@
# Findings storage and deduplication
-Saved scans and findings persist in the local workbench SQLite database.
-Deduplication reads that database directly; no local HTTP service is needed.
-The CLI can also publish to and deduplicate against independently operated
-compatible endpoints through explicit `--findings-url` settings.
+Choose where the duplicate candidates and groups should live.
-For an older service deployment or helper integration, see [compatibility](#compatibility).
+- **Local workbench.** The CLI stores saved scans and findings in SQLite.
+ Use this default to search the current checkout's stored findings. New
+ embeddings and fresh reviews still need provider access.
+- **Independently operated endpoint.** To search a shared corpus, use a
+ [compatible findings endpoint](#compatible-endpoint-contract) that already
+ holds your candidates. [Publish the scan](#publish-a-scan) or import its
+ findings into the service with the matching `repositoryId` first.
## Deduplicate a scan
-Saved-scan deduplication uses local SQLite by default. No findings service or
-publication step is required:
+For the local workbench, run:
```bash
codex-security dedupe --scan SCAN_ID --json
```
-See [local embedding requirements](#local-embeddings-and-backups) for endpoint,
-credential, and vector compatibility.
+For a shared corpus, supply the base URL of your endpoint:
+
+```bash
+codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
+```
+
+Replace `SCAN_ID` with the ID of a completed scan, or use `latest` for the
+current repository. For local setup or migration, see
+[embedding credentials and backups](#local-embeddings-and-backups) or
+[moving from the bundled service](#local-service-removal).
The CLI prepares missing or stale embeddings for the local repository's stored
findings, searches them, and saves reviewed duplicate groups in the workbench
@@ -36,24 +46,15 @@ select logical findings using their current stored bodies; dedupe does not
replace newer bodies with old scan artifacts. A local database does not include
findings stored only in a separate Docker volume or remote service.
-To retain a centralized findings corpus, publish the scan first, or import its
-findings with `repositoryId`, and explicitly select the service:
-
-```bash
-codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
-```
-
-A scan or workflow selector is 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.
+A scan or workflow selector is required. `--scan` also accepts a unique ID
+prefix. The scan must have sealed artifacts and a local checkout available.
Local `latest` lookup matches the exact checkout path without Git. Matching
across worktrees or clones additionally requires a Git executable outside all
saved scan targets. If an unrelated historical target includes the available
Git installation, use `codex-security dedupe --scan SCAN_ID` with an explicit
saved scan ID instead.
By default, candidates come from its manifest's `scan.target.targetId`. Use
-`--all-repositories` to search the whole selected database or service. Explicit
-`--findings-url` retains the existing remote lookup and publication behavior.
+`--all-repositories` to search the whole selected database or service.
```typescript
import { deduplicateScan } from "@openai/codex-security";
diff --git a/sdk/typescript/docs/hosted-remediation.md b/sdk/typescript/docs/hosted-remediation.md
index 9b4d827ae..45a4e9ded 100644
--- a/sdk/typescript/docs/hosted-remediation.md
+++ b/sdk/typescript/docs/hosted-remediation.md
@@ -12,7 +12,14 @@ to its recorded base. The API does not apply a patch or infer a branch from the
finding. It checks HEAD before and after execution; the host owns checking the
candidate's bytes/digest and verifying that verification did not change them.
+In this TypeScript host integration, `executor` is your application's
+`RemediationExecutor`. It runs the request in the prepared checkout and returns
+an execution receipt. Substitute the frozen revision, finding evidence, model
+and attempt identity from your host.
+
```ts
+import { runHostedRemediation } from "@openai/codex-security";
+
const result = await runHostedRemediation(
{
version: 1,
@@ -39,6 +46,9 @@ const result = await runHostedRemediation(
);
```
+Read `result.verification?.status` and its evidence before marking a finding
+fixed. A completed request can return `still_vulnerable` or `inconclusive`.
+
Both instruction fields are optional and are distinct from finding data.
Reasoning effort is passed through unchanged so the selected model and provider
determine which values they support.
@@ -50,8 +60,7 @@ verification are separate operations.
Set `verificationMode: "static"` to review attack paths, bypasses, and legitimate
behavior from source and diffs, without installing dependencies or executing
builds, tests, reproducers, or the application. Select it for both `patch` and
-`verify` requests when both stages should be static. Omitted or `"standard"`
-retains the existing behavior.
+`verify` requests when both stages should be static. Use `"standard"` (the default) when runtime checks are appropriate.
Static mode treats validation instructions as source-review questions. Missing
runtime tooling alone is not a blocker; material proof gaps still produce
@@ -110,14 +119,12 @@ codex-security verify-fix --host
Use `--host` alone with either command. The `run` request supplies all settings,
and its `operation` must match the command: `patch` or `verify`, respectively.
-Neither command falls back to local inference. Ordinary patching and verification
-remain unchanged when `--host` is omitted.
+The host executes the model request for either command.
The SDK also exports `runHostedRemediationProtocol` for in-process hosts.
-Use the existing newline-delimited host transport: send one `run` request whose
-`params` are the input above; respond to `execution.run` with the executor
-receipt. `execution.progress` notifications use `{ requestId, event }` and are
+Use one JSON object per line. Send one `run` request whose `params` are the
+input above. Respond to `execution.run` with the executor receipt. `execution.progress` notifications use `{ requestId, event }` and are
forwarded as `remediation.progress` with `{ id: originalRunId, event }`. Send
`cancel` with `{ id: originalRunId }` to receive `execution.cancel`; then return
the final execution receipt so usage and session identity survive cancellation.
diff --git a/sdk/typescript/docs/hosted-scans.md b/sdk/typescript/docs/hosted-scans.md
index 61f279f05..9c83db51d 100644
--- a/sdk/typescript/docs/hosted-scans.md
+++ b/sdk/typescript/docs/hosted-scans.md
@@ -2,7 +2,7 @@
`codex-security scan --host` runs one scan using newline-delimited JSON-RPC on
stdin/stdout. Use the flag alone. It performs no login, update check, local
-inference, or model fallback. Ordinary local scans keep their existing behavior.
+inference, or model fallback.
For hosted patch generation and verification, use the separate
[hosted remediation API](hosted-remediation.md).
@@ -22,6 +22,9 @@ accepted output independently from inference. Findings ingestion and
deduplication consume that accepted output separately. CLI workbench state
remains scan-domain state; there is no hosted-attempt replay store.
+In this TypeScript integration, `host` is your application's executor and
+receipt store. Substitute your authorized model, checkout and frozen revision.
+
```ts
import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
@@ -86,44 +89,6 @@ host's durable run state before starting its first CLI process. Send that saved
snapshot with every subsequent attempt for the same run, including attempts in
a fresh checkout or container. A configuration change then applies to new runs.
-Set `ownerSuggestions: true` to record ownership evidence during the existing
-scan execution. The scan agent may include an optional hint on each finding:
-
-```json
-{
- "extensions": {
- "ownerSuggestion": {
- "email": "[email protected]",
- "commit": "0123456789012345678901234567890123456789",
- "reason": "Maintains the affected source."
- }
- }
-}
-```
-
-Use an observed contributor email and a full supporting commit hash from Git
-blame/history for the affected source. Omit the hint when ownership is unclear.
-Hints use the scan's existing session and budget; there is no extra ownership
-turn or model call. Security findings take priority over optional hints.
-
-After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
-CODEOWNERS declarations take precedence. Other hints must match an observed Git
-identity and supporting commit in the finding's evidence. Missing hints abstain;
-invalid hints produce per-finding owner errors. Neither invalid hints nor report
-failures invalidate sealed findings. A completed receipt includes the artifact
-when available, or `ownerSuggestionsError` if finalization fails.
-
-Hosts run the normal scan request and capture the optional owner report.
-Automatic reporting uses `suggestOwnersFromScan`; it does not use the legacy
-`ownerCodex` option or send `owner.infer` / `owner.cancel` requests.
-
-The standalone `suggestOwners` API and `suggest-owners` command can call a
-model under their own budget. Both paths use the same CODEOWNERS rules, Git
-evidence, identity checks, and report format.
-
-Report generation works after the scan reaches `maxCostUsd`. It uses the
-hints already recorded and never starts another model call to fill gaps.
-
`ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
`{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
uses the existing `ScanProgress` type; activity uses `ScanActivity`. Progress may
@@ -206,7 +171,7 @@ the same state. This includes:
- The whole `stateDirectory`, including the registered workbench database,
journals, and scan inputs; a live database file alone is not a consistent copy.
- `outputDirectory`, where the executor records its draft and the CLI later
- writes the validated manifest, findings, coverage, and report.
+ writes the validated manifest, findings and report.
- The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
`CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
by preflight and scope binding, even though they can live outside the state
@@ -275,6 +240,42 @@ resume, or finalize-only operation: calling `runHostedScan` again registers a ne
scan. A provider reporting execution completion does not substitute for a
validated, sealed scan receipt.
+## Optional owner suggestions
+
+Set `ownerSuggestions: true` to record ownership evidence during the existing
+scan execution. The scan agent may include an optional hint on each finding:
+
+```json
+{
+ "extensions": {
+ "ownerSuggestion": {
+ "email": "[email protected]",
+ "commit": "0123456789012345678901234567890123456789",
+ "reason": "Maintains the affected source."
+ }
+ }
+}
+```
+
+Use an observed contributor email and a full supporting commit hash from Git
+blame/history for the affected source. Omit the hint when ownership is unclear.
+The scan collects hints within its session and budget. Findings take priority
+over optional hints.
+
+After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
+CODEOWNERS declarations take precedence. Other hints must match an observed Git
+identity and supporting commit in the finding's evidence. Missing hints abstain;
+invalid hints produce per-finding owner errors. Neither invalid hints nor report
+failures invalidate sealed findings. A completed receipt includes the artifact
+when available, or `ownerSuggestionsError` if finalization fails.
+
+Read the owner report from the completed receipt. Finalization uses
+`suggestOwnersFromScan` and can run after the scan reaches `maxCostUsd`.
+
+The standalone `suggestOwners` API and `suggest-owners` command can call a
+model under their own budget. Both paths use the same CODEOWNERS rules, Git
+evidence, identity checks, and report format.
+
## Progress, cancellation and artifacts
The host sends `execution.progress` notifications with `{requestId, event}`.
diff --git a/sdk/typescript/docs/telemetry.md b/sdk/typescript/docs/telemetry.md
index 40311cc08..d29d9c15d 100644
--- a/sdk/typescript/docs/telemetry.md
+++ b/sdk/typescript/docs/telemetry.md
@@ -85,12 +85,20 @@ Resuming a saved scan keeps its operation ID but creates a new attempt ID.
resumed cumulative receipts. The supplied summary takes the maximum observed cost
per usage scope; separate retry scans have separate scopes.
+Pass the Codex Security state directory as the first argument to this script.
+Use `CODEX_SECURITY_STATE_DIR` if you set it, or the default
+`$CODEX_HOME/state/plugins/codex-security`. The reader looks for `telemetry/`
+inside that directory.
+
```ts
import {
readOperationTelemetry,
summarizeOperationTelemetry,
} from "@openai/codex-security";
+const stateDirectory = process.argv[2];
+if (!stateDirectory)
+ throw new Error("Pass the Codex Security state directory.");
const { events, parseFailures } = await readOperationTelemetry(stateDirectory);
const summary = summarizeOperationTelemetry(events);
console.log({ ...summary, parseFailures });
@@ -118,13 +126,13 @@ production collector's loss rate.
## Usage and completeness
-Prefer `onMeasurement` when displaying or collecting live usage:
+Use `onMeasurement` on your SDK client to see usage during a scan of your checkout:
```ts
await security.run(repository, {
onMeasurement(measurement) {
// usage and cost may be null; partial values are observed subtotals.
- display(measurement.usage, measurement.cost, measurement.coverage);
+ console.log(measurement.usage, measurement.cost, measurement.coverage);
},
});
```
diff --git a/sdk/typescript/docs/validate-records.md b/sdk/typescript/docs/validate-records.md
index 348092c8d..23f33a135 100644
--- a/sdk/typescript/docs/validate-records.md
+++ b/sdk/typescript/docs/validate-records.md
@@ -1,16 +1,15 @@
# Host-provided standalone validation (protocol v1)
-Run `codex-security validate --records` with that flag alone. It uses the
-standalone validation instructions to assess existing findings against source
-evidence. The host runs the model; the CLI does not start Codex, authenticate,
-read scan history, or save results. Existing `validate` commands are unchanged.
+Run `codex-security validate --records` with that flag alone to assess findings
+against source evidence. Your host provides the authorized checkout, runs the
+model and decides whether to update stored findings. For the CLI-managed model
+and sandbox, use [standalone validation](cli.md#validate-and-patch-findings).
-Use the same JSON-RPC transport as [records deduplication](dedupe-records.md):
-one JSON object per line, one `run` request, and `review.run` requests answered
-by the host. Keep stdin open until the final response. Cancellation, disconnects,
-and host errors terminate the invocation without retrying the review.
+## Send the findings
-The `run` request's `params` has this shape:
+Use the [records transport](dedupe-records.md#input-and-identities). Send one
+JSON-RPC `run` request with the following `params`. Give each finding a unique,
+nonempty host ID and enough source evidence to assess it.
```json
{
@@ -18,52 +17,87 @@ The `run` request's `params` has this shape:
"findings": [
{
"id": "finding-1",
- "finding": { "title": "Example candidate", "evidence": "..." }
+ "finding": {
+ "title": "Missing tenant filter",
+ "location": "src/invoices.ts:24",
+ "evidence": "The lookup accepts an invoice ID from the route."
+ }
}
],
- "context": "Optional deployment facts or reviewer feedback.",
- "knowledgeBasePath": "/validation/context",
"outputSchema": {
"type": "object",
- "properties": { "rationale": { "type": "string" } },
- "required": ["rationale"],
+ "properties": {
+ "assessments": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "rationale": { "type": "string" }
+ },
+ "required": ["id", "rationale"],
+ "additionalProperties": false
+ }
+ }
+ },
+ "required": ["assessments"],
"additionalProperties": false
}
}
```
-Provide at least one finding with a unique, nonempty host ID. The `finding`
-value preserves the caller's candidate format. Supply enough source locations
-and evidence to assess it. `context` and `knowledgeBasePath` are optional.
-The directory must already exist in the host's review environment; this mode
-does not copy files. Context and notes are evidence to check against source,
-not instructions or automatic dismissal rules.
+The `finding` value preserves the caller's format. Optional `context` supplies
+deployment facts or reviewer feedback. Optional `knowledgeBasePath` points to a
+directory already present in the host's review environment. Treat its contents
+and reviewer feedback as evidence to check against source. Optional `model`
+and `effort` override the SDK defaults.
-`outputSchema` is required. It controls the returned structured answer; it does
-not define a standard disposition or product status model. The host must verify
-finding ID coverage and any application-specific conditions before changing
-published findings. Optional `model` and `effort` override the SDK's default
-model configuration. Local configuration files and CLI model flags are not read.
+## Run the review
-The CLI emits one `review.run` request containing `requestId`, `model`, `effort`,
-`trustedInstructions`, `prompt`, and `schema`. The host supplies the authorized
-source checkout and context directory, executes the review, and returns its
-structured answer. The CLI checks that answer against `outputSchema` before
-returning `{ "status": "completed", "result": <assessment> }` as the final
-JSON-RPC `result`. Success exits with code 0; invalid input, invalid output, or
-execution failure exits with code 2. SIGINT and SIGTERM
-retain exit codes 130 and 143.
+The CLI sends one `review.run` with `requestId`, `model`, `effort`,
+`trustedInstructions`, `prompt`, and `schema`. The host authorizes source
+access, provides model credentials, and enforces a source-only review with
+builds, tests, target execution and network investigation disabled. Return the
+structured answer using the review request's JSON-RPC ID. Keep stdin open
+until the final response.
-The host owns repository authorization, credentials, model accounting,
-cancellation of remote work, and cleanup. It selects and enforces the review
-environment's isolation and permissions.
-The review instructions require source-only assessment: no builds, tests, PoCs,
-target execution, or network investigation. This mode does not configure a local
-Codex sandbox; regular `validate` retains its existing read-only sandbox. A
-protocol success only proves that the answer matched the schema; it does not
-establish assessment quality.
+The CLI checks the answer against the required `outputSchema` and returns
+`{ "status": "completed", "result": <assessment> }` in the final JSON-RPC
+`result`. A schema match checks the structure of the answer. The host decides
+which dispositions, evidence and other conditions justify a record update.
-The SDK equivalent is `validateRecords(input, { reviewRunner, signal })`, exported
-from `@openai/codex-security`. The runner's `run(request, { signal })` method returns
-the structured answer. `ValidateRecordsInput`, `ValidateRecordsOptions`, and
+## Check the returned IDs
+
+Before updating any records, check that the assessment names each input ID
+exactly once. In this JavaScript example, pass the original `params.findings`
+and the `assessments` array from the schema-checked answer.
+
+```js
+function checkFindingIds(findings, assessments) {
+ const remaining = new Set(findings.map((finding) => finding.id));
+ for (const { id } of assessments) {
+ if (!remaining.delete(id)) {
+ throw new Error(`Duplicate or unexpected finding ID: ${id}`);
+ }
+ }
+ if (remaining.size > 0) {
+ throw new Error(`Missing finding IDs: ${[...remaining].join(", ")}`);
+ }
+}
+```
+
+For the example above, the final message's
+`result.result.assessments` might contain
+`[{"id":"finding-1","rationale":"The lookup at src/invoices.ts:24 also filters on the authenticated tenant."}]`.
+A missing, repeated or unfamiliar ID must stop the update.
+
+Completion exits with code 0. Invalid input, invalid output or execution
+failure exits with code 2. SIGINT and SIGTERM use 130 and 143. Cancellation,
+disconnects and host errors terminate the invocation without retrying the review.
+The host owns remote cancellation, usage and cleanup.
+
+The SDK exports `validateRecords(input, { reviewRunner, signal })` from
+`@openai/codex-security`. Its runner's `run(request, { signal })` method
+returns the structured answer, and the SDK returns that answer after the schema
+check. `ValidateRecordsInput`, `ValidateRecordsOptions` and
`ValidationReviewRequest` are exported types.
diff --git a/sdk/typescript/scripts/release-pr.mjs b/sdk/typescript/scripts/release-pr.mjs
index 0b95bbbb9..d22526c20 100644
--- a/sdk/typescript/scripts/release-pr.mjs
+++ b/sdk/typescript/scripts/release-pr.mjs
@@ -78,13 +78,21 @@ function visibleChanges(changes) {
export function generateNoteSections(changes) {
const visible = visibleChanges(changes);
+ const highlights = visible.filter((change) => !change.breaking);
const breaking = visible.filter((change) => change.breaking);
return {
highlights: [
"## Highlights",
"",
- visible.length > 0
- ? visible.map(changeLine).join("\n")
+ highlights.length > 0
+ ? [
+ "<details>",
+ "<summary>Changes to review for highlights</summary>",
+ "",
+ ...highlights.map(changeLine),
+ "",
+ "</details>",
+ ].join("\n")
: "No release highlights have been drafted yet.",
].join("\n"),
upgrades: [
@@ -92,7 +100,7 @@ export function generateNoteSections(changes) {
"",
breaking.length > 0
? [
- "Review migration steps for these breaking changes:",
+ "<!-- Replace each candidate with the affected users and the action they need to take. -->",
"",
...breaking.map(changeLine),
].join("\n")
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 782692c17..82226cc56 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -5292,7 +5292,8 @@ export async function main(
},
})
.command("install-hook", {
- description: "Install an advisory Git pre-commit check.",
+ description:
+ "Install a local pre-commit hook that blocks on scan errors or findings at the selected severity threshold.",
hint: "Require a passing scan in CI to enforce a scan before merging.",
destructive: true,
mcp: false,
@@ -7415,7 +7416,9 @@ export async function main(
codexVersion: CODEX_EXECUTABLE_VERSION,
codexSdkVersion: CODEX_SDK_VERSION,
...scanModelConfiguration(codex),
- nextStep: "codex-security scan . --dry-run",
+ nextStep: project
+ ? "Run codex-security scan . -c FILE --dry-run, replacing FILE with the project configuration you selected."
+ : "codex-security scan . --dry-run",
configuration: {
...(project?.path === undefined ? {} : { path: project.path }),
settings: { ...resolved.options, ...deep?.settings },
diff --git a/sdk/typescript/src/default-severity-rubric.ts b/sdk/typescript/src/default-severity-rubric.ts
index f3ef62680..6975ec2ff 100644
--- a/sdk/typescript/src/default-severity-rubric.ts
+++ b/sdk/typescript/src/default-severity-rubric.ts
@@ -1,3 +1,3 @@
// Generated from the plugin references/default-severity-rubric.md. Run pnpm build.
export const defaultSeverityRubric =
- "# Severity guidance\n\nJudge the attacker's actual starting access, the security boundary crossed, and the additional unauthorized harm. Keep confidence separate from severity and identify the missing fact that could change the assessment. Missing proof alone does not establish that a broader attack is impossible; do not invent an attack path or downgrade merely because exploitation was not demonstrated.\n\n## Critical\n\nReserve Critical for consequential, strongly supported compromise meeting all three conditions:\n- Access: an unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.\n- Impact: crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.\n- Evidence: demonstrated exploitation or strong source-backed validation establishes the complete attack path.\n\nSecond-order attacks can qualify: an external attacker plants data that a trusted user or system later processes, causing consequential unauthorized access or privileged actions.\n\n## High\n\nAssign High when a realistic, evidenced path gives a lower-trust attacker a substantial unauthorized capability they did not already possess. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify; unauthenticated internet access is not required. Consequences include sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, or significant repeatable disruption of a critical or shared service. A dangerous function, production label, internal access, or the existence of a privileged credential alone is insufficient: identify the lower-trust actor, boundary crossing, and consequential new capability.\n\n## Medium\n\nAssign Medium to a credible vulnerability with concretely bounded impact, such as nonsecret operational information, narrow unauthorized changes, contained disruption of a noncritical service, or isolated development or staging systems without a consequential pivot. A fully demonstrated vulnerability can still be Medium. Base a downgrade on verified constraints, not on an assumption that missing evidence rules out broader harm.\n\n## Low\n\nAssign Low to a supported security weakness with minor additional unauthorized harm and verified limits on its scope, sensitivity, or duration, such as a small information exposure with little security value or a narrowly contained nuisance. Do not use Low as a substitute for uncertainty about a potentially serious path.\n\n## Informational\n\nAssign Informational to a hardening opportunity or observation for which the supplied evidence establishes no additional unauthorized capability or security impact. Explain why it is informational rather than treating missing proof of exploitation as proof of safety. Administrative records that do not describe a security finding may be excluded; exclusion is distinct from severity.\n";
+ "# Severity guidance\n\nJudge the attacker's actual starting access, the security boundary crossed, and the additional unauthorized harm. Keep confidence separate from severity and identify the missing fact that could change the assessment. Missing proof alone does not establish that a broader attack is impossible; do not invent an attack path or downgrade merely because exploitation was not demonstrated.\n\n## Critical\n\nReserve Critical for consequential, strongly supported compromise meeting all three conditions:\n\n- **Access.** An unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.\n- **Impact.** Crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.\n- **Evidence.** Demonstrated exploitation or strong source-backed validation establishes the complete attack path.\n\nSecond-order attacks can qualify: an external attacker plants data that a trusted user or system later processes, causing consequential unauthorized access or privileged actions.\n\n## High\n\nAssign High when the evidence establishes all three conditions:\n\n- **Access.** A lower-trust actor can reach the affected operation. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify.\n- **Impact.** Crossing the boundary grants a substantial new capability. Examples include access to sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, and significant repeatable disruption of a critical or shared service.\n- **Evidence.** Identify a realistic path from the actor's existing access to the new capability. A dangerous function, production label, internal access, or privileged credential alone leaves that path unproven.\n\n## Medium\n\nAssign Medium to a credible vulnerability with concretely bounded impact, such as nonsecret operational information, narrow unauthorized changes, contained disruption of a noncritical service, or isolated development or staging systems without a consequential pivot. A fully demonstrated vulnerability can still be Medium. Base a downgrade on verified constraints, not on an assumption that missing evidence rules out broader harm.\n\n## Low\n\nAssign Low to a supported security weakness with minor additional unauthorized harm and verified limits on its scope, sensitivity, or duration, such as a small information exposure with little security value or a narrowly contained nuisance. Do not use Low as a substitute for uncertainty about a potentially serious path.\n\n## Informational\n\nAssign Informational to a hardening opportunity or observation for which the supplied evidence establishes no additional unauthorized capability or security impact. Explain why it is informational rather than treating missing proof of exploitation as proof of safety. Administrative records that do not describe a security finding may be excluded; exclusion is distinct from severity.\n";
diff --git a/sdk/typescript/tests-ts/cli-project-config.test.ts b/sdk/typescript/tests-ts/cli-project-config.test.ts
index acb8ccbe5..bc4ff7ad0 100644
--- a/sdk/typescript/tests-ts/cli-project-config.test.ts
+++ b/sdk/typescript/tests-ts/cli-project-config.test.ts
@@ -187,6 +187,7 @@ test("info resolves a config and its sources without a target, prompt reads, or
expect(stdout.text()).not.toContain("synthetic-private-value");
expect(JSON.parse(stdout.text())).toMatchObject({
model: "gpt-5.6-terra",
+ nextStep: expect.stringContaining("scan . -c FILE --dry-run"),
configuration: {
path: input.config,
settings: {
diff --git a/sdk/typescript/tests-ts/release-pr.test.ts b/sdk/typescript/tests-ts/release-pr.test.ts
index 18b97e418..2f42c2d07 100644
--- a/sdk/typescript/tests-ts/release-pr.test.ts
+++ b/sdk/typescript/tests-ts/release-pr.test.ts
@@ -1209,7 +1209,7 @@ describe("pre-1.0 release policy", () => {
expect(plan.generated.highlights).not.toContain("extend coverage");
expect(plan.generated.highlights).toContain("update dependencies");
expect(plan.generated.highlights).toContain("explain publishing");
- expect(plan.generated.highlights).toContain("require migration");
+ expect(plan.generated.highlights).not.toContain("require migration");
expect(plan.generated.upgrades).toContain("require migration");
});