Skip to content

docs: simplify user guides and correct setup instructions #1857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mldangelo-oai merged 2 commits into from
Oct 22, 2026
Merged

docs: simplify user guides and correct setup instructions #1857

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9141e8a
docs: simplify user guides and correct setup instructions
mldangelo-oai Oct 22, 2026
36087d7
Merge main and preserve current import documentation
mldangelo-oai Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 2 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,16 +67,8 @@ 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. To define or update it,
optionally [draft a policy](#generate-securitymd):

```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. You can scan
without generating a policy.
Scans use your existing `SECURITY.md` guidance. You can optionally
[draft or update a policy](#generate-securitymd) before scanning.

To run without a global installation, replace `cs` in these examples with
`npx @openai/codex-security`, for example:
Expand Down
9 changes: 5 additions & 4 deletions docker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,15 +118,16 @@ also requires `latest` to reference that digest. `bootstrap` and
not start a findings service or implement another workflow engine. It passes
commands, output, and exit codes through the existing scanner entrypoint.

Run these commands from the repository root. After the selected scanner release
is available, prepare private directories and choose the host user's UID/GID so
the runner can write its bind mounts:
Run these commands from the repository root after
[verifying an image](#image-metadata-and-verification). Keep the verified
`reference` in the same shell. Prepare private directories and choose the host
user's UID/GID so the runner can write its bind mounts:

```bash
mkdir -p results state
chmod 700 results state
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest
export CODEX_SECURITY_IMAGE="$reference"
docker compose -f compose.runner.yaml pull
docker compose -f compose.runner.yaml run --rm codex-security login --device-auth
```
Expand Down
7 changes: 5 additions & 2 deletions docs/bedrock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,11 @@ Codex dependency; a successful inference alone does not verify all model metadat

Bedrock defaults `model_reasoning_summary` to `none` because some models reject
`reasoning.summary`. This setting reaches Deep Scan discovery and reducer workers,
including resumes. Reasoning effort is unchanged; an explicit summary override
still takes precedence. See [provider configuration](../sdk/typescript/README.md#amazon-bedrock).
including resumes. To request summaries from a model that supports them, add
`--codex 'model_reasoning_summary="auto"'` to the scan command. This explicit
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.

## Daybreak Blue and Red

Expand Down
42 changes: 23 additions & 19 deletions docs/project-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,25 +78,28 @@ node sdk/typescript/bin/codex-security.mjs scan . -c docs/examples/codex-securit

## Settings

| Field | Meaning | Default |
| ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------- |
| `auth` | Credential source: `auto`, `chatgpt`, or `api-key`; never a credential value | `auto` |
| `scan.mode` | `standard` or `deep` | `standard` |
| `scan.max_time_minutes` | Advisory Standard investigation allowance; enforced Deep discovery limit, in minutes | Unset in Standard; 5760 in Deep |
| `scan.cyber_access_program` | Experimental OpenAI program: `standard`, `daybreak_blue`, or `daybreak_red` | Unset; preserve Codex defaults |
| `scan.scope` | Exactly one of `paths: [src]`, `diff: {base: HEAD}`, or `working_tree: {}` | Whole repository |
| `scan.knowledge_base` | Context files or directories | Empty list |
| `scan.instructions_file` | Additional scan instructions | Unset |
| `scan.validation_file` | Custom validation instructions; incompatible with active deep mode | Built-in validation |
| `scan.deep` | Deep discovery settings shown below | Existing deep defaults |
| `codex` | Native Codex settings and profiles | Existing isolated configuration |
| `limits.max_cost_usd_per_scan` | Estimated USD limit for one scan attempt | No limit |
| `policy.fail_on_severity` | Exit threshold: `critical`, `high`, `medium`, or `low` | Report-only |
| `output.directory` | Artifact directory outside the scanned Git worktree | Existing private artifact location |

The file configures scan settings. Patching, PR creation, publication, post-scan
actions, and machine-specific plugin or Python selection remain explicit CLI/SDK
inputs.
| Field | Meaning | Default |
| ------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------- |
| `auth` | Credential source: `auto`, `chatgpt`, or `api-key`; never a credential value | `auto` |
| `scan.mode` | `standard` or `deep` | `standard` |
| `scan.max_time_minutes` | Advisory Standard investigation allowance; enforced Deep discovery limit, in minutes | Unset in Standard; 5760 in Deep |
| `scan.cyber_access_program` | Experimental OpenAI program: `standard`, `daybreak_blue`, or `daybreak_red` | Unset; preserve Codex defaults |
| `scan.scope` | Exactly one of `paths: [src]`, `diff: {base: HEAD}`, or `working_tree: {}` | Whole repository |
| `scan.knowledge_base` | Context files or directories | Empty list |
| `scan.instructions_file` | Additional scan instructions | Unset |
| `scan.validation_file` | Custom validation instructions; incompatible with active deep mode | Built-in validation |
| `scan.owner_suggestions` | Generate an owner-suggestions report after a committed Git scan | `false` |
| `scan.deep` | Deep discovery settings shown below | Existing deep defaults |
| `codex` | Native Codex settings and profiles | Existing isolated configuration |
| `limits.max_cost_usd_per_scan` | Estimated USD limit for one scan attempt | No limit |
| `policy.fail_on_severity` | Exit threshold: `critical`, `high`, `medium`, or `low` | Report-only |
| `output.directory` | Artifact directory outside the scanned Git worktree | Existing private artifact location |

See [owner suggestions](../sdk/typescript/README.md#scan-options-and-output) for
supported scan types, cost-limit behavior, and the saved report.

Patching, PR creation, publication, post-scan prompt files, and machine-specific
plugin or Python selection remain explicit CLI/SDK inputs.

## SDK and CLI contract

Expand All @@ -116,6 +119,7 @@ The resolver maps file keys to the existing SDK options:
| `scan.knowledge_base` | `knowledgeBasePaths` | `--knowledge-base` |
| `scan.instructions_file` | `scanPromptFile` | `--scan-prompt-file` |
| `scan.validation_file` | `validationPromptFile` | `--validation-prompt-file` |
| `scan.owner_suggestions` | `ownerSuggestions` | `--owner-suggestions` |
| `scan.deep.workers` | `workers` | `--workers` |
| `scan.deep.subagents_per_worker` | `subagents` | `--subagents` |
| `scan.deep.stop_after_no_new` | `stopAfterNoNew` | `--stop-after-no-new` |
Expand Down
50 changes: 17 additions & 33 deletions github-action/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,12 +120,12 @@ sandbox requirements apply on both supported GitHub Cloud hosts.
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:

| `provider` | Step environment |
| --- | --- |
| `openai` (default) | `OPENAI_API_KEY`, or `CODEX_API_KEY` as a fallback |
| `amazon-bedrock` | AWS credentials and region; see the OIDC example below |
| `openrouter` | `OPENROUTER_API_KEY` |
| `fireworks` | `FIREWORKS_API_KEY` |
| `provider` | Step environment |
| ------------------ | ------------------------------------------------------ |
| `openai` (default) | `OPENAI_API_KEY`, or `CODEX_API_KEY` as a fallback |
| `amazon-bedrock` | AWS credentials and region; see the OIDC example below |
| `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
Expand Down Expand Up @@ -360,11 +360,11 @@ findings policy. Completion does not certify that every vulnerability was found.

The Action follows the CLI outcome consistently:

| CLI exit | Action result |
| --- | --- |
| `0` | `scan-status: completed`, `policy-status: passed`; the step succeeds. |
| `1` | `scan-status: completed`, `policy-status: failed`; the step fails on findings. |
| `2` or an interrupted process | `scan-status: failed`, `policy-status: not-evaluated`; the step fails. |
| CLI exit | Action result |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `0` | `scan-status: completed`, `policy-status: passed`; the step succeeds. |
| `1` | `scan-status: completed`, `policy-status: failed`; the step fails on findings. |
| `2` or an interrupted process | `scan-status: failed`, `policy-status: not-evaluated`; the step fails. |

Usable reports retained after an execution failure remain available, but are not
eligible for SARIF upload. Invalid or missing required reports, a changed
Expand Down Expand Up @@ -487,28 +487,12 @@ 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.

Releases use the product version from `sdk/typescript/package.json`. Before npm
publication, the release workflow exercises the Action's compatibility suite
against the packed CLI candidate. After publication and provenance verification,
the Action release workflow starts from that exact CLI source commit, updates
the runtime pin and integrity lock, and fetches the locked runtime through
Socket Firewall with an empty cache before running the CLI. The lock keeps
public npm URLs for Action consumers. The workflow rebuilds the bundles and
runs the Action checks in a job with read-only repository permissions.
A fresh publisher takes only the tested runtime lock, rebuilds
from the same source, and verifies the bundle hashes without executing the CLI.
It creates a distribution commit and an immutable `action-vX.Y.Z` tag with the
same version as `npm-vX.Y.Z`. The companion Action release includes the manifest
and SBOM before publication, lists the full distribution commit SHA, and links
to the npm release's canonical changelog. It is never marked Latest.

The Action distribution commit differs from the CLI source commit because the
registry integrity lock is finalized after publication. Release metadata records
both commits, both tags, and the verified CLI integrity. A failed Action stage
can be rerun without republishing npm or changing its immutable release assets.
Recovery verifies existing Action assets and can finish a partial draft release.
Existing version tags are never moved.
See [the release process](../RELEASING.md) for the orchestration and recovery flow.
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.

<!-- prettier-ignore-start -->

Expand Down
Loading
Loading