OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
docs: make security workflows discoverable to agents (#1698)
Michael D'Angelo40a8e7b52c96
diff --git a/README.md b/README.mdindex 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 andcontainers.+## 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 startRequires 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.mdnew file mode 100644index 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.mdindex 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 itsschema, 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).