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
feat(onboarding): add cs alias and clarify onboarding (#1415)
mldangelo-oai6ce7f47059eb
diff --git a/.github/workflows/node-release.yml b/.github/workflows/node-release.ymlindex 0005d9440..0f20fc8f3 100644--- a/.github/workflows/node-release.yml+++ b/.github/workflows/node-release.yml@@ -231,6 +231,8 @@ jobs:(cd "$consumer" && node --input-type=module --eval 'const sdk = await import("@openai/codex-security"); if (typeof sdk.CodexSecurity !== "function") process.exit(1);')"$consumer/node_modules/.bin/codex-security" --version"$consumer/node_modules/.bin/codex-security" --help+ "$consumer/node_modules/.bin/cs" --version+ "$consumer/node_modules/.bin/cs" --help- name: Upload verified packageid: uploaddiff --git a/README.md b/README.mdindex 441958068..f65c3aa6c 100644--- a/README.md+++ b/README.md@@ -21,15 +21,46 @@ fixing security vulnerabilities in your code.Requires Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, and Python 3.10+.Python 3.10 also requires `tomli`.-This example explicitly requests Daybreak Blue and requires the corresponding-access. Without Daybreak access, omit `--cyber-access-program daybreak_blue`-or use `--cyber-access-program standard`.+Install the CLI globally and sign in:```bash-npm install @openai/codex-security-npx @openai/codex-security login-npx @openai/codex-security scan /path/to/repository \- --cyber-access-program daybreak_blue+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.++From your repository directory, optionally draft security guidance before your+first scan:++```bash+cs policy .+```++The command saves a draft outside the checkout. Review the proposed diff and+notes, edit the draft as needed, then copy it to the displayed `Policy target`+so future scans use it. Generating the draft alone does not install it.+Skip this step to keep an existing policy or scan without one.++Run your 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 run without a global installation, replace `cs` in these examples with+`npx @openai/codex-security`, for example:++```bash+npx @openai/codex-security scan .```For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.@@ -45,20 +76,28 @@ Choose a scope and scan mode:```bash# Scan selected paths.-npx @openai/codex-security scan . --path src --path tests+cs scan . --path src --path tests# Scan committed changes from a base revision to HEAD.-npx @openai/codex-security scan . --diff origin/main+cs scan . --diff origin/main# Run a deep scan of the repository.-npx @openai/codex-security scan . --mode deep+cs scan . --mode deep```-Use `npx @openai/codex-security --help` to browse commands, or `scan --help`+Use `cs --help` to browse commands, or `cs scan --help`for scan options, cost limits, and patching after a scan.## TypeScript SDK+Install the package locally in your TypeScript project:++```bash+npm install @openai/codex-security+```++Then import it:+```tsimport { CodexSecurity } from "@openai/codex-security";@@ -80,8 +119,8 @@ validation, severity classification, owner suggestions, and result handling.Draft security guidance for a repository or one of its components:```bash-npx @openai/codex-security policy .-npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md+cs policy .+cs policy . --path services/api --knowledge-base architecture.md```The command saves a draft outside the checkout. Review it before installing it@@ -94,7 +133,7 @@ Scans and policy generation save threat models with their results. Export a savemodel without starting another analysis:```bash-npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md+cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md```Omit `--scan` to use the current repository's latest completed scan. The@@ -165,7 +204,7 @@ Store findings, browse them in a dashboard, and review potential duplicates.Start the local service with:```bash-npx @openai/codex-security serve+cs serve```Publish a completed scan with `publish scan --to custom`, then use `dedupe` todiff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 7b5d770c6..747edd96a 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -21,11 +21,6 @@ Before version `1.0.0`, minor releases may change the public API.## Install-```bash-npm install @openai/codex-security-npx @openai/codex-security --version-```-Supported runtimes:- Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.@@ -43,20 +38,55 @@ work on all supported runtimes.`PluginBootstrapError`, so existing catches keep working. Knowledge-basepreparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.+### Install the CLI++Install the CLI globally:++```bash+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`.++### Install the TypeScript SDK++Install the package locally in your TypeScript project:++```bash+npm install @openai/codex-security+```+## AuthenticationSign in with ChatGPT:+```bash+cs login+```++If you installed only the SDK locally, sign in from your project directory:+```bashnpx @openai/codex-security login```+In the following CLI examples, replace `cs` with `npx @openai/codex-security`+when using a local SDK installation, including the API-key login example below.+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.These keys apply to the current command without replacing your saved login.To save an API key instead, pass it on stdin:```bash-printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key+printenv OPENAI_API_KEY | cs login --with-api-key```SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,@@ -78,7 +108,7 @@ allows it. Otherwise, open an SSH tunnel from your local machine:ssh -L 1455:localhost:1455 user@remote-host```-Run `npx @openai/codex-security login` in that SSH session, then open its sign-in+Run `cs login` in that SSH session, then open its sign-inURL in your local browser. Keep SSH connected until login finishes.### Amazon Bedrock@@ -359,11 +389,36 @@ To validate GitHub code scanning alerts, first import them with## CLI+After [installing the CLI](#install-the-cli), sign in if needed:++```bash+cs login+```++From your repository directory, optionally draft security guidance before scanning:++```bash+cs policy .+```++The command saves a draft outside the checkout. Review the proposed diff and+notes, edit the draft as needed, then copy it to the displayed `Policy target`+so future scans use it. Generating the draft alone does not install it.+Skip this step to keep an existing policy or scan without one. See+[Generate a security policy](#generate-a-security-policy) for details.++Then scan the repository:+```bash-npx @openai/codex-security scan .-npx @openai/codex-security scan . --path src --path tests-npx @openai/codex-security scan . --diff origin/main --json-npx @openai/codex-security scan . --dry-run+cs scan .+```++To narrow the scan scope or check the configuration before scanning:++```bash+cs scan . --path src --path tests+cs scan . --diff origin/main --json+cs scan . --dry-run```Use `--help` to find commands and `<command> --help` for options. Scans are@@ -375,13 +430,13 @@ scans, custom validation, imports, patching, and integrations.### Generate a security policy+To draft guidance for a selected path:+```bash-npx @openai/codex-security policy .-npx @openai/codex-security policy . --path services/api+cs policy . --path services/api```-`policy` drafts `SECURITY.md` outside the checkout. Review the draft before-installing it; it guides future scans. The SDK provides `generatePolicy()`,+The SDK provides `generatePolicy()`,`preflightPolicy()`, and `previewPolicy()`. See[policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,headless use, artifacts, and review requirements.@@ -391,8 +446,8 @@ headless use, artifacts, and review requirements.Export saved findings or a threat model without starting another analysis:```bash-npx @openai/codex-security export --scan SCAN_ID --export-format sarif --output results.sarif-npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md+cs export --scan SCAN_ID --export-format sarif --output results.sarif+cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md```The SDK provides `exportArtifact()` for the same offline operations. See@@ -439,7 +494,7 @@ system, see [SDK records deduplication](docs/dedupe-records.md).### Running without Docker```bash-npx @openai/codex-security serve --port 3000+cs serve --port 3000```Open `http://127.0.0.1:3000/dashboard`. Startup and listing need no API key;diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 085800fec..caa1b61ee 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -1,8 +1,9 @@# CLI and workflows-Use `npx @openai/codex-security` without a global install. The examples below-use `codex-security`, which is available after-`npm install --global @openai/codex-security`.+The global installation provides both `codex-security` and its short alias `cs`.+They accept the same arguments and options. The examples below use+`codex-security`; you can also use `cs` or, without a global installation,+`npx @openai/codex-security`. See the [installation guide](../README.md#install).```bashcodex-security --helpdiff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex 8abea373f..13e6d33af 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -31,7 +31,8 @@"./schemas/project-config.schema.json": "./schemas/project-config.schema.json"},"bin": {- "codex-security": "./bin/codex-security.mjs"+ "codex-security": "./bin/codex-security.mjs",+ "cs": "./bin/codex-security.mjs"},"files": ["bin",diff --git a/sdk/typescript/scripts/smoke-package.mjs b/sdk/typescript/scripts/smoke-package.mjsindex b610435b7..fb4f49220 100644--- a/sdk/typescript/scripts/smoke-package.mjs+++ b/sdk/typescript/scripts/smoke-package.mjs@@ -481,18 +481,12 @@ try {".bin",process.platform === "win32" ? "codex-security.cmd" : "codex-security",);- assert.equal(- (await stat(shim)).isFile(),- true,- "npm must create the published codex-security executable shim.",- );-const launchEnvironment = {...process.env,NODE_OPTIONS: "--preserve-symlinks-main --no-experimental-detect-module",NODE_USE_ENV_PROXY: undefined,};- function runInstalledCli(argument) {+ function runInstalledCli(shim, argument) {const options = {cwd: consumer,capture: true,@@ -509,8 +503,43 @@ try {return run(shim, [argument], options);}- const version = runInstalledCli("--version");- assert.equal(version.trim(), packageManifest.version);+ for (const name of ["codex-security", "cs"]) {+ const executable = join(+ consumer,+ "node_modules",+ ".bin",+ process.platform === "win32" ? `${name}.cmd` : name,+ );+ assert.equal(+ (await stat(executable)).isFile(),+ true,+ `npm must create the published ${name} executable shim.`,+ );++ const version = runInstalledCli(executable, "--version");+ assert.equal(version.trim(), packageManifest.version);++ const help = runInstalledCli(executable, "--help");+ assert.match(help, /Usage: codex-security\b/u);+ assert.match(help, /\bpublish\b/u);+ assert.match(help, /\bdedupe\b/u);+ assert.match(help, /\bpolicy\b/u);+ }++ const scopedVersion = run(+ npm.command,+ [+ ...npm.args,+ "exec",+ "--offline",+ "--no",+ "--",+ packageManifest.name,+ "--version",+ ],+ { cwd: consumer, capture: true },+ );+ assert.equal(scopedVersion.trim(), packageManifest.version);const preload = join(consumer, "unavailable-cwd.mjs");await writeFile(@@ -547,11 +576,6 @@ try {assert.equal(failed.stdout, "");assert.equal(failed.stderr, "working directory is unavailable\n");- const help = runInstalledCli("--help");- assert.match(help, /Usage: codex-security\b/u);- assert.match(help, /\bpublish\b/u);- assert.match(help, /\bdedupe\b/u);- assert.match(help, /\bpolicy\b/u);const policyHelp = run(process.execPath, [launcher, "policy", "--help"], {cwd: consumer,capture: true,diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.tsindex 6eef178b1..b193f8ec0 100644--- a/sdk/typescript/src/cli-help.ts+++ b/sdk/typescript/src/cli-help.ts@@ -274,8 +274,28 @@ export function formatCliHelp(text: string, columns = 80): string {if (command === "") {sections.push("Get started:\n" +- " codex-security login\n" +- " codex-security scan .\n" ++ " codex-security login\n\n" ++ wrap(+ "In your repository, optionally draft SECURITY.md:",+ width,+ " ",+ " ",+ ) ++ "\n codex-security policy .\n" ++ wrap(+ "Review and edit the draft, then copy it to the displayed Policy target.",+ width,+ " ",+ " ",+ ) ++ "\n" ++ wrap(+ "Skip this step to keep an existing policy or scan without one.",+ width,+ " ",+ " ",+ ) ++ "\n\n codex-security scan .\n" +" codex-security findings",);} else if (examples) {diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 999d79d74..ca44899a0 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -3237,6 +3237,7 @@ export async function main(});const cli = Cli.create("codex-security", {+ aliases: ["cs"],description: "Find, review, and fix security issues in your code.",version: VERSION,mcp: {diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.tsindex e18fdf96f..dff1a3b74 100644--- a/sdk/typescript/tests-ts/cli-help.test.ts+++ b/sdk/typescript/tests-ts/cli-help.test.ts@@ -63,7 +63,10 @@ describe("CLI help", () => {expect(sectionFor("login")).toBeGreaterThan(sectionFor("scan"));expect(sectionFor("init")).toBe(sectionFor("login"));expect(sectionFor("completions")).toBeGreaterThan(sectionFor("scan"));- expect(text).toContain("codex-security scan .");+ expect(text).toContain("Aliases: cs");+ for (const command of ["login", "policy .", "scan .", "findings"]) {+ expect(text).toContain(` codex-security ${command}`);+ }expect(text).toContain("<command> --help");});diff --git a/sdk/typescript/tests-ts/cli-launcher.test.ts b/sdk/typescript/tests-ts/cli-launcher.test.tsindex f45ca00ba..bf269ad6c 100644--- a/sdk/typescript/tests-ts/cli-launcher.test.ts+++ b/sdk/typescript/tests-ts/cli-launcher.test.ts@@ -13,20 +13,24 @@ describe("CLI launcher", () => {const root = await temporaryDirectory("codex-security-cli-bin-");try {const launcher = join(packageRoot, "src", "cli.ts");- const bin =- process.platform === "win32" ? launcher : join(root, "codex-security");- if (process.platform !== "win32") {- await symlink(launcher, bin);- }- const { status, stdout, stderr } = await runCommand(- process.execPath,- [bin, "--version"],- { timeout: 30_000 },- );+ const bins =+ process.platform === "win32"+ ? [launcher]+ : ["codex-security", "cs"].map((name) => join(root, name));+ for (const bin of bins) {+ if (process.platform !== "win32") {+ await symlink(launcher, bin);+ }+ const { status, stdout, stderr } = await runCommand(+ process.execPath,+ [bin, "--version"],+ { timeout: 30_000 },+ );- expect(status, stderr).toBe(0);- expect(stderr).toBe("");- expect(stdout).toBe(`${VERSION}\n`);+ expect(status, stderr).toBe(0);+ expect(stderr).toBe("");+ expect(stdout).toBe(`${VERSION}\n`);+ }} finally {await rm(root, { recursive: true, force: true });}diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 30aa0f409..0981cf19a 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -205,6 +205,7 @@ describe("CLI", () => {const stderr = capture();expect(await main([], root.stream, stderr.stream, dependencies())).toBe(0);expect(root.text()).toContain("Usage: codex-security <command>");+ expect(root.text()).toContain("Aliases: cs");expect(root.text()).toContain("bulk-scan");expect(root.text()).toContain("install-hook");expect(root.text()).not.toContain("multiscan");@@ -353,6 +354,11 @@ describe("CLI", () => {0,);expect(completions.text()).toContain('export COMPLETE="bash"');+ for (const name of ["codex-security", "cs"]) {+ expect(completions.text()).toMatch(+ new RegExp(`^complete .+ ${name}$`, "mu"),+ );+ }});test("documents every public command argument and option", async () => {