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 security workflows discoverable to agents (#1698)

Michael D'Angelo40a8e7b52c96
diff --git a/README.md b/README.md
index d4a2344fd..7128b6466 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,13 @@
# Codex Security
-`@openai/codex-security` is a CLI and TypeScript SDK for finding, validating, and
-fixing security vulnerabilities in your code.
+Codex Security helps you find, investigate, and fix vulnerabilities in your code.
+Use its security workflows in Codex, or automate them with the
+`@openai/codex-security` CLI and TypeScript SDK.
+
+- **In Codex:** [choose a security workflow](docs/agent-workflows.md).
+- **In a terminal:** [install the CLI and scan your repository](#quick-start).
+- **In automation:** use the [TypeScript SDK](#typescript-sdk) or
+ [GitHub Action](#github-actions).
## Features
@@ -16,6 +22,19 @@ fixing security vulnerabilities in your code.
- Automate scans across repositories or project components, including in CI and
containers.
+## Use in Codex
+
+Open your repository in a Codex session with the Codex Security plugin enabled,
+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.
+
## Quick start
Requires Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, and Python 3.10+.
@@ -34,17 +53,6 @@ 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.
-From your repository, optionally [draft a `SECURITY.md`](#generate-securitymd)
-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.
-
Run your scan from the repository directory:
```bash
@@ -55,6 +63,17 @@ 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`.
+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.
+
To run without a global installation, replace `cs` in these examples with
`npx @openai/codex-security`, for example:
@@ -250,6 +269,7 @@ for examples.
## Documentation
- [Online documentation](https://learn.chatgpt.com/docs/security/cli)
+- [Agent workflows and recovery](docs/agent-workflows.md)
- [CLI reference](sdk/typescript/docs/cli.md)
- [Project configuration](docs/project-configuration.md)
- [Examples](examples/README.md)
diff --git a/docs/agent-workflows.md b/docs/agent-workflows.md
new file mode 100644
index 000000000..9031d0a0f
--- /dev/null
+++ b/docs/agent-workflows.md
@@ -0,0 +1,120 @@
+# Security workflows in Codex
+
+Use Codex Security to scan code, investigate a supplied finding, or make and
+verify a security fix. Choose the task that matches the evidence you already
+have; a repository scan is the default when you are looking for new findings.
+
+## Get started
+
+Open your repository in Codex. Find **Codex Security** in the desktop plugin
+browser, or enter `/plugins` in the interactive Codex CLI. Install the plugin,
+confirm it is enabled, and start a new chat. See the
+[plugin quickstart](https://learn.chatgpt.com/docs/security/plugin) for host setup
+and access requirements.
+
+Ask for the task in plain language, including the repository or paths and any
+security context:
+
+> Scan this repository with Codex Security. Focus on authorization boundaries,
+> use the existing SECURITY.md, and return the saved report and coverage limits.
+
+The [task map](#choose-a-task) below also gives explicit skill names. Local scans
+do not require the optional Cloud connection. To read existing Cloud findings,
+follow the separate [Cloud setup](../sdk/typescript/README.md#read-existing-cloud-findings).
+
+The terminal package includes the plugin used by its own scans. You can follow
+[the CLI quick start](../README.md#quick-start) without setting up an interactive
+Codex plugin session.
+
+## Choose a task
+
+| 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): repeated independent audits; excludes diff reviews. | `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). |
+| 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.
+
+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.
+
+For automation, scan exit codes distinguish these outcomes:
+
+- `0`: the scan completed without triggering a configured findings threshold.
+- `1`: findings meet the configured `--fail-on-severity` threshold.
+- `2`: execution, target-integrity, or required-output failure.
+
+Coverage gaps and investigation notes do not by themselves fail a completed
+scan. See [scan output](../sdk/typescript/docs/cli.md#scan-options-and-output)
+and [SDK results](../sdk/typescript/README.md#read-results) for the saved fields
+and failure output.
+
+## Give an agent CLI guidance
+
+The full plugin, generated CLI skills, and CLI MCP registration serve different
+purposes:
+
+| Integration | What it provides |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Codex Security plugin | The security workflow skills above, their MCP tools, and optional connected apps. |
+| `cs skills add` | Generated guidance for an agent using CLI commands. This does not install the full security plugin. |
+| `cs mcp add` | The CLI's read-only `info` tool. It does not expose scan or patch tools; this transport cannot cancel active commands. |
+
+An agent using the terminal can discover current commands and their schemas:
+
+```bash
+cs --llms
+cs scan --schema --format json
+cs scan --help
+```
+
+Use [the CLI reference](../sdk/typescript/docs/cli.md#command-discovery-and-integrations)
+for integrations and output formats.
+
+## 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. |
+
+For terminal scans, inspect an explicit ID so history commands refer to the same
+run:
+
+```bash
+cs scans show SCAN_ID
+cs scans logs SCAN_ID
+```
+
+Without an ID, `scans show` selects the latest completed scan, while `scans logs`
+selects the latest scan of any status. An interrupted Deep Scan still marked
+`running` can use `cs scans resume SCAN_ID` with its original checkout, output,
+session, and state directory. Completed, failed, and canceled scans need a new
+attempt with `cs scans rerun SCAN_ID`. A rerun uses the current checkout and may
+need the original custom prompt files supplied again. See
+[resume requirements](../sdk/typescript/docs/cli.md#resuming-an-interrupted-deep-scan)
+and [runtime troubleshooting](../sdk/typescript/docs/cli.md#troubleshooting).
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 7ee89b670..0299c96f9 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1851,8 +1851,11 @@ Use `--llms` for the command manifest, `scan --schema --format json` for its
schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
`--format toon|json|yaml|jsonl` and `--full-output`.
-`skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
-MCP exposes only read-only `info`, because the transport cannot cancel scans.
+`skills add` syncs generated CLI command guidance; it does not install the full
+Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
+only read-only `info` because the transport cannot cancel scans. For the plugin's
+scan, triage, patch, and verification workflows, see the
+[agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
For local findings storage, deduplication, and custom endpoints, see the
[findings guide](findings-service.md).