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
fix(cli): make command help and discovery reflect runnable workflows (#2584)
Michael D'Angelo507e10af4feb
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.mdindex 5a8c21bd8..ac61b976f 100644--- a/docs/scanner-imports/README.md+++ b/docs/scanner-imports/README.md@@ -3,6 +3,14 @@Preview a scanner report with the CLI, then save the findings in the localworkbench or send a supported report to Codex Security Cloud.+## Choose your input++| Starting point | Command |+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Saved vendor report | `codex-security publish findings FILE --provider PROVIDER --source-key KEY --repository . --to local --dry-run` previews the evidence. Remove `--dry-run` to save it. |+| Codex Security findings export | `codex-security scan import --csv FILE` or `--json FILE` saves a completed scan in local history. Use `--format json` to select JSON output. |+| Live provider | `codex-security import --help` lists the GitHub, Semgrep, Snyk and Sonar collectors. The Sonar collector can also replay its saved capture. |+## Choose your scannerThe `--provider` value selects the reader for a saved report. To see whichdiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex e741dd7af..f6a9c299d 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -1742,7 +1742,10 @@ The provider guide describes [package JSON and CSV](https://github.com/openai/co### Publish completed scans-Preview selected completed scans before uploading:+The public `publish scan --help` menu describes Linear and custom publication+from saved scans. The CSV input below belongs to Cloud publication.+The following workflow is available to installations with Cloud publication access.+Preview selected completed scans locally before uploading them.```bashcodex-security publish scan --to cloud --dry-run --json@@ -2723,8 +2726,9 @@ retain exit codes `130` and `143` without a result.## Command discovery and integrations-Use `--llms` for the command manifest, `scan --schema --format json` for its-schema, and `completions bash|zsh|fish` for shell completions. Scan output supports+Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.++Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Scan output supports`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,`--filter-output`, `--token-limit`, and `--token-offset` options accept either`--option value` or `--option=value`.@@ -2756,6 +2760,53 @@ the client where it was registered.For local findings storage, deduplication, and custom endpoints, see the[findings guide](findings-service.md).+### Shell completions++The generated scripts register both `codex-security` and `cs`. Choose your shell+and open a new session after saving the setup.++**Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:++```bash+source <(codex-security completions bash)+```++**Zsh.** In `~/.zshrc`, load the generated script after your completion system+calls `compinit`. If you initialize completions yourself, use:++```zsh+autoload -Uz compinit+compinit+source <(codex-security completions zsh)+```++**Fish.** Add this line to `~/.config/fish/config.fish`:++```fish+codex-security completions fish | source+```++**Nushell.** Save the generated closures alongside `config.nu`:++```nu+codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)+```++In `config.nu`, source the file and dispatch the two names to their completers:++```nu+source codex-security-completions.nu+let previous_completer = $env.config.completions.external.completer?+$env.config.completions.external.enable = true+$env.config.completions.external.completer = {|spans|+ match $spans.0 {+ "codex-security" => { do $_incur_complete_codex_security $spans }+ "cs" => { do $_incur_complete_cs $spans }+ _ => { if $previous_completer != null { do $previous_completer $spans } }+ }+}+```+### Hosted Standard scan`codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.tsindex 33ccf4ebf..d09ebffb2 100644--- a/sdk/typescript/src/cli-help.ts+++ b/sdk/typescript/src/cli-help.ts@@ -4,22 +4,17 @@ type Row = { label: string; description: string };type Group = readonly [title: string, names: readonly string[]];const COMMAND_GROUPS: readonly Group[] = [- ["Scan and fix", ["scan", "policy", "validate", "patch", "verify-fix"]],+ ["Scan and remediate", ["scan", "policy", "validate", "patch", "verify-fix"]],[- "Review and share",- [- "scans",- "findings",- "classify-severity",- "dedupe",- "suggest-owners",- "export",- "import",- "publish",- ],+ "Review results",+ ["scans", "findings", "classify-severity", "dedupe", "suggest-owners"],],+ ["Import and share", ["import", "publish", "export"]],["Automate", ["bulk-scan", "scan-components", "install-hook"]],- ["Setup and support", ["login", "logout", "init", "info", "feedback"]],+ [+ "Configure and troubleshoot",+ ["login", "logout", "init", "info", "feedback"],+ ],];const SCAN_GROUPS: readonly Group[] = [@@ -50,7 +45,7 @@ const SCAN_GROUPS: readonly Group[] = [];const PUBLISH_GROUPS: readonly Group[] = [- ["Input", ["scan", "scan-dir", "csv", "finding-id", "workflow-id"]],+ ["Input", ["scan", "scan-dir", "finding-id", "workflow-id"]],["Destination", ["to", "findings-url"]],["Linear",@@ -106,9 +101,12 @@ const VALUE_LABELS: Record<string, string> = {to: "destination",};+const OUTPUT_FLAGS = ["format", "json", "filter-output", "full-output"];+const OUTPUT_GROUPS: readonly Group[] = [- ["Help and updates", ["help", "version", "update"]],- ["Output", ["format", "json", "filter-output", "full-output"]],+ ["Help and version", ["help", "version"]],+ ["Maintenance", ["update"]],+ ["Output", OUTPUT_FLAGS],];function rowName(row: Row): string {@@ -221,7 +219,10 @@ function globalRows(rows: Row[], command: string): Row[] {);});const formats = visible.find((row) => rowName(row) === "format");- if (formats && (scan || command === "scans rerun")) {+ if (+ formats &&+ (scan || command === "scans rerun" || command === "scans resume")+ ) {formats.label = formats.label.replace("|md", "");}if (formats && command !== "scan import") {@@ -270,39 +271,49 @@ export function formatCliHelp(text: string, columns = 80): string {sections.push(usage.split("\n")- .map((line) => wrap(line, width, "", " "))+ .map((line) =>+ wrap(+ line.trimStart(),+ width,+ line.startsWith(" ") ? " " : "",+ " ",+ ),+ ).join("\n"),);if (command === "") {sections.push(["Get started:",+ " codex-security scan . --dry-run"," codex-security login",- "",- wrap(- "In your repository, draft SECURITY.md (optional):",- width,- " ",- " ",- ),- " codex-security policy .",- wrap(- "Review the diff and notes. Edit the draft, then copy only SECURITY.md to the Policy target shown.",- width,- " ",- " ",- ),- wrap(- "Skip this step to keep your existing policy or scan without one.",- width,- " ",- " ",- ),- ""," codex-security scan .",- " codex-security findings",+ " codex-security scans show",].join("\n"),);+ } else if (command === "import") {+ sections.push(+ renderRows(+ "Choose your input",+ [+ {+ label: "Live provider",+ description: "Choose a collector below.",+ },+ {+ label: "Saved vendor report",+ description:+ "See codex-security publish findings --help for local storage and publication.",+ },+ {+ label: "Codex Security CSV or JSON",+ description:+ "See codex-security scan import --help to add the export to local scan history.",+ },+ ],+ width,+ ),+ );} else if (examples) {sections.push(examples);}@@ -316,7 +327,12 @@ export function formatCliHelp(text: string, columns = 80): string {: [renderRows("Commands", rows, width)]),);} else if (title === "Options:") {- const rows = parseRows(lines).map((row) => optionRow(row, command));+ const options = parseRows(lines)+ .filter((row) => command !== "publish scan" || rowName(row) !== "csv")+ .map((row) => optionRow(row, command));+ const rows = options.filter(+ (row) => !row.description.startsWith("[deprecated]"),+ );sections.push(...(command === "scan"? groupedRows(rows, SCAN_GROUPS, "Advanced", width)@@ -324,15 +340,30 @@ export function formatCliHelp(text: string, columns = 80): string {? groupedRows(rows, PUBLISH_GROUPS, "Options", width): [renderRows("Options", rows, width)]),);- } else if (title === "Global Options:") {- sections.push(- ...groupedRows(- globalRows(parseRows(lines), command),- OUTPUT_GROUPS,- "Agent options",- width,- ),+ const deprecated = options.filter((row) =>+ row.description.startsWith("[deprecated]"),);+ if (deprecated.length)+ sections.push(renderRows("Deprecated options", deprecated, width));+ } else if (title === "Global Options:") {+ const rows = globalRows(parseRows(lines), command);+ if (command === "") {+ sections.push(+ ...groupedRows(rows, OUTPUT_GROUPS, "Agent options", width),+ );+ } else {+ const outputRows = rows.filter((row) =>+ OUTPUT_FLAGS.includes(rowName(row)),+ );+ if (outputRows.length)+ sections.push(renderRows("Output", outputRows, width));+ sections.push(+ wrap(+ "See codex-security --help for shared help and agent options.",+ width,+ ),+ );+ }} else if (["Arguments:", "Integrations:", "Environment Variables:"].includes(title)) {@@ -353,6 +384,14 @@ export function formatCliHelp(text: string, columns = 80): string {);}}+ if (command === "completions") {+ sections.push(+ wrap(+ "Shell setup: https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#shell-completions",+ width,+ ),+ );+ }if (command === "") {sections.push(wrap(diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex ada871799..1dee850f2 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -2775,6 +2775,7 @@ export async function main(const findingFeedback = Cli.create("findings", {description: "Review saved findings (default: list).",}).command("false-positive", {+ usage: [{ suffix: "OCCURRENCE_ID --reason TEXT" }],description: "Mark a finding as a false positive for future scans.",examples: [{@@ -2818,6 +2819,8 @@ export async function main(});findingFeedback.command("list", {description: "List open findings for a repository across its scans.",+ examples: [{ args: { repository: "." } }],+ hint: "Use findings false-positive to record a triage decision for an occurrence.",args: z.object({repository: z.string()@@ -2881,6 +2884,8 @@ export async function main(});findingFeedback.command("imported", {description: "List imported vendor evidence for a local repository.",+ examples: [{ args: { repository: "." } }],+ hint: "Use publish findings FILE --to local to save a vendor report. See publish findings --help for its required selectors.",args: z.object({repository: z.string()@@ -2939,6 +2944,8 @@ export async function main(}).command("list", {description: "List saved scans for a repository or scan root.",+ examples: [{ args: { repository: "." } }],+ hint: "Use scans show SCAN_ID for results or scans logs SCAN_ID for activity.",args: z.object({repository: z.string()@@ -3112,6 +3119,7 @@ export async function main(}).command("resume", {description: "Resume an interrupted Deep Scan in its original session.",+ examples: [{ args: { scanId: "SCAN_ID" } }],hint: "Execution failures keep available scan results under data in failed full-output JSON, JSONL, YAML, or TOON envelopes.",args: z.object({scanId: z.string().min(1).describe("Interrupted Deep Scan identifier."),@@ -3182,6 +3190,7 @@ export async function main(.command("rerun", {description:"Start a new scan using saved settings and current checkout/context files.",+ examples: [{ args: { scanId: "SCAN_ID" } }],hint: "Execution failures keep available scan results under data in failed full-output JSON, JSONL, YAML, or TOON envelopes.",destructive: true,args: z.object({@@ -3310,6 +3319,12 @@ export async function main(}).command("match", {description: "Match findings by root cause across saved scans.",+ usage: [+ { suffix: "BEFORE AFTER [options]" },+ { suffix: "--all [options]" },+ ],+ examples: [{ options: { all: true } }],+ hint: "Use scans compare for a pair. Match all completed scans with --all; --force recomputes saved matches.",destructive: true,args: z.object({beforeId: z@@ -3355,7 +3370,11 @@ export async function main(},}).command("compare", {- description: "Match and compare findings between scans.",+ description:+ "Compare findings from two scans. Uncached matches can use the model and save matching decisions.",+ examples: [+ { args: {}, description: "Compare the latest two completed scans." },+ ],destructive: true,args: z.object({beforeId: z@@ -3408,12 +3427,25 @@ export async function main(const publication = Cli.create("publish", {description: "Publish Codex Security findings.",}).command("scan", {- description:- "Publish findings from a completed scan, or a CSV for internal publication.",- hint:- "Examples:\n" +- " codex-security publish scan --to linear --scan latest --linear-team TEAM_ID --dry-run\n" +- " codex-security publish scan --to custom --scan latest --findings-url http://localhost:3000",+ description: "Publish findings from a completed scan.",+ examples: [+ {+ options: {+ to: "linear",+ scan: ["latest"],+ linearTeam: "TEAM_ID",+ dryRun: true,+ },+ },+ {+ options: {+ to: "custom",+ scan: ["latest"],+ findingsUrl: "http://localhost:3000",+ },+ },+ ],+ hint: "Use --dry-run to preview the selected findings before publishing.",destructive: true,args: z.object({scanDir: z@@ -4032,7 +4064,31 @@ export async function main(.command("findings", {description:"Preview and import a saved scanner report locally or to Cloud.",- hint: "Choose your scanner with --provider. Reuse --source-key for later imports from the same source. See the scanner import guide for supported formats, repository setup, and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md. Gzip files are supported. Use --to local to save unassessed findings without a Cloud login. Use --full-output with --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",+ usage: [+ {+ args: { file: true },+ options: {+ to: true,+ repository: true,+ provider: true,+ sourceKey: true,+ },+ suffix: "[options]",+ },+ ],+ examples: [+ {+ args: { file: "selected-wiz.json" },+ options: {+ to: "local",+ repository: "./project",+ provider: "wiz",+ sourceKey: "tenant/vulnerability-finding",+ dryRun: true,+ },+ },+ ],+ hint: "Choose your scanner with --provider. Reuse --source-key for later imports from the same source. See the scanner import guide for supported formats, repository setup, and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md. Gzip files are supported. Use --to local to save unassessed findings without a Cloud login. Use --full-output with --format json or --format jsonl.",destructive: true,args: z.object({file: z@@ -4383,6 +4439,13 @@ export async function main(.command("check", {description:"Check saved scan history and Linear access without creating issues.",+ examples: [+ {+ args: { scanDir: "../scan-results" },+ options: { to: "linear", linearTeam: "TEAM_ID" },+ },+ ],+ hint: "Use publish scan --dry-run to preview a publication offline.",args: z.object({scanDir: z.string().describe("Completed scan directory."),}),@@ -4411,9 +4474,9 @@ export async function main(},});const imports = Cli.create("import", {- description:- "Import Sonar security issues or read hosted Semgrep, Snyk, and GitHub findings.",+ description: "Collect findings from GitHub, Semgrep, Snyk or Sonar.",}).command("github", {+ examples: [{ args: { repository: "owner/repo" } }],description: "Read GitHub code scanning alerts without changing GitHub.",hint: "Save complete --format json output for publish findings --provider github. This command reads code-scanning alerts; Dependabot and secret-scanning alerts are not supported. To save CSV or JSON findings as a local scan, use codex-security scan import --help.",destructive: false,@@ -4540,6 +4603,7 @@ export async function main(}imports.command("github-advisories", {+ examples: [{ args: { repository: "owner/repo" } }],description: "Read GitHub security advisories without changing GitHub.",hint: "Defaults to published repository advisories. Use --github-advisory-source global with explicit --github-advisory IDs to select public database entries. Advisories do not establish an installed dependency or applicability to the selected repository.",destructive: false,@@ -4607,8 +4671,24 @@ export async function main(),}).command("snyk", {+ usage: [+ {+ args: { project: true },+ options: { snykOrg: true, sourceRepositoryUrl: true },+ suffix: "[options]",+ },+ ],description:"Read Snyk Open Source or Code issues for one monitored project.",+ examples: [+ {+ args: { project: "PROJECT_ID" },+ options: {+ snykOrg: "ORG_ID",+ sourceRepositoryUrl: "https://github.com/example/project",+ },+ },+ ],hint: "Requires SNYK_TOKEN. Save the complete --format json output. Use publish findings --provider snyk with --to local or --to cloud.",destructive: false,args: z.object({@@ -4667,8 +4747,24 @@ export async function main(},}).command("semgrep", {+ usage: [+ {+ args: { project: true },+ options: { semgrepDeployment: true, semgrepRef: true },+ suffix: "[options]",+ },+ ],description:"Read a full Semgrep Platform project and ref through the Web API.",+ examples: [+ {+ args: { project: "owner/project" },+ options: {+ semgrepDeployment: "DEPLOYMENT",+ semgrepRef: "refs/heads/main",+ },+ },+ ],hint: "Requires SEMGREP_APP_TOKEN with Web API access. Import the saved --format json output with publish findings --provider semgrep and --to local or --to cloud. Selected Guardian MCP captures also support both destinations.",destructive: false,args: z.object({@@ -4732,8 +4828,16 @@ export async function main(},}).command("sonar", {+ usage: [+ { suffix: "[--sonar-project KEY] [options]" },+ { suffix: "CAPTURE [options]" },+ ],description:"Collect Sonar security findings or replay a saved capture into the local workbench.",+ examples: [+ { options: { sonarProject: "PROJECT_KEY", dryRun: true } },+ { args: { capture: "../reports/sonar.json" } },+ ],hint: "Uses the active sonar CLI login. --to cloud also publishes the locally imported selection to the connected Cloud repository. --dry-run saves a live capture for review without importing findings.",destructive: true,args: z.object({@@ -5012,6 +5116,7 @@ export async function main(},};const cli = Cli.create("codex-security", cliOptions)+ .command(scanHistory).command("policy", {description: "Draft SECURITY.md for review.",destructive: true,@@ -5180,21 +5285,27 @@ export async function main(return fail(message, 2);}},- })- .command("scan", {+ });+ function createScanCommands() {+ return Cli.create("scan", {description: "Scan a repository, selected paths, or Git changes.",- hint:- "Examples:\n" +- " codex-security scan .\n" +- " codex-security scan . --path src --path tests\n" +- " codex-security scan . --working-tree\n" +- " codex-security scan . --diff origin/main\n" +- " codex-security scan . --mode deep\n\n" +- "Import existing findings without security analysis:\n" +- " codex-security scan import --csv findings.csv\n" +- " codex-security scan import --json findings.json\n" +- "Use ./import to scan a repository named import.\n" +- "Execution failures in JSON/JSONL --full-output return ok: false and keep scan results under data.",+ usage: [+ {+ suffix:+ "[repository] [--path PATH | --diff REF | --working-tree] [options]",+ },+ { suffix: "--host" },+ { suffix: "import (--csv FILE | --json FILE) [options]" },+ ],+ examples: [+ { args: { repository: "." }, options: { dryRun: true } },+ { args: { repository: "." } },+ { args: { repository: "." }, options: { path: ["src", "tests"] } },+ { args: { repository: "." }, options: { workingTree: true } },+ { args: { repository: "." }, options: { diff: "origin/main" } },+ { args: { repository: "." }, options: { mode: "deep" } },+ ],+ hint: "Import existing findings without security analysis with scan import --help. Use ./import to scan a repository named import. Execution failures in JSON/JSONL --full-output return ok: false and keep scan results under data.",destructive: true,alias: { config: "c" },args: z.object({@@ -5228,7 +5339,7 @@ export async function main(safetyIdentifier: optionValue("--safety-identifier").optional().describe(- "Stable hashed end-user ID for this scan's model requests (1–64 characters).",+ "Stable hashed end-user ID for model requests (1–64 characters). Requires a compatible Codex runtime.",),path: z.array(optionValue("--path"))@@ -5449,10 +5560,89 @@ export async function main(? finishScan(outcome, format, incurError): finishScanCommand(outcome, format, incurError);},- })+ }).command("import", {+ usage: [{ suffix: "(--csv FILE | --json FILE) [options]" }],+ description:+ "Save CSV or JSON findings as a completed scan without security analysis.",+ destructive: true,+ options: z+ .object({+ csv: optionValue("--csv")+ .optional()+ .describe("Findings CSV in the codex-security export format."),+ json: optionValue("--json")+ .optional()+ .describe(+ "Findings JSON document or object with a findings array.",+ ),+ outputDir: optionValue("--output-dir")+ .optional()+ .describe(+ "Artifact directory (default: Codex Security state; CODEX_SECURITY_STATE_DIR).",+ ),+ archiveExisting: z+ .boolean()+ .default(false)+ .describe("Archive existing results; requires --output-dir."),+ dryRun: z+ .boolean()+ .default(false)+ .describe("Validate the input without saving a scan."),+ })+ .refine(+ (options) =>+ Number(options.csv !== undefined) ++ Number(options.json !== undefined) ===+ 1,+ { message: "Provide exactly one of --csv FILE or --json FILE." },+ )+ .refine(+ (options) =>+ !options.archiveExisting || options.outputDir !== undefined,+ { message: "--archive-existing requires --output-dir." },+ )+ .meta({ oneOf: [{ required: ["csv"] }, { required: ["json"] }] }),+ examples: [+ { options: { csv: "findings.csv" } },+ { options: { json: "findings.json" } },+ ],+ hint: "Each input row is retained, including duplicates. --json selects the input file; use --format json for JSON output.",+ output: z.record(z.string(), z.unknown()).optional(),+ async run({ options, format, error: incurError }) {+ const directory = dependencies.currentDirectory();+ const outcome = await runImport({+ sourcePath: resolveCliPath(directory, options.csv ?? options.json!),+ format: options.csv === undefined ? "json" : "csv",+ outputDir:+ options.outputDir === undefined+ ? undefined+ : resolveCliPath(directory, options.outputDir),+ archiveExisting: options.archiveExisting,+ dryRun: options.dryRun,+ });+ exitCode = outcome.exitCode;+ if (outcome.error !== undefined) {+ return incurError({+ code: "SCAN_IMPORT_FAILED",+ message: outcome.error,+ exitCode,+ });+ }+ if (!options.dryRun && useDefaultOutput(format)) {+ return;+ }+ return outcome.data;+ },+ });+ }+ cli+ .command(createScanCommands()).command("install-hook", {description:"Install a local pre-commit hook that blocks on scan errors or findings at the selected severity threshold.",+ examples: [+ { args: { repository: "." }, options: { failOnSeverity: "high" } },+ ],hint: "Require a passing scan in CI to enforce a scan before merging.",destructive: true,args: z.object({@@ -5565,10 +5755,10 @@ export async function main(}},})- .command(scanHistory).command(findingFeedback).command(publication).command("suggest-owners", {+ examples: [{ args: { findings: "findings.json" } }],description: "Suggest finding owners from CODEOWNERS and Git history.",destructive: false,args: z.object({@@ -5636,7 +5826,12 @@ export async function main(}).command("classify-severity", {description: "Assess severity for saved findings or canonical records.",- hint: "For saved findings, use --rubric for your own policy or set CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1 for the Statsig default. For host-provided reviews, use --records.",+ usage: [+ { suffix: "(--scan ID | --scan-dir DIR) [options]" },+ { suffix: "--records [--runs COUNT]" },+ ],+ examples: [{ options: { scan: "latest" } }],+ hint: `Use the built-in severity rubric or select --rubric FILE. Each uncached finding receives ${DEFAULT_REVIEW_RUNS} model reviews by default. Use --reprocess to replace saved assessments. --records accepts host-provided reviews over JSON-RPC.`,destructive: true,options: z.object({runs: reviewRunsOption.describe(@@ -5757,8 +5952,14 @@ export async function main(},}).command("dedupe", {- description: "Identify duplicate findings in a saved scan.",- hint: "Use --records alone for host-provided reviews over JSON-RPC.",+ description: "Find duplicates against the saved findings corpus.",+ usage: [+ { suffix: "--scan ID [--workflow-id ID] [options]" },+ { suffix: "--workflow-id ID [options]" },+ { suffix: "--records" },+ ],+ examples: [{ options: { scan: "latest" } }],+ hint: "Service-backed deduplication can save duplicate groups to the selected findings service. Use --records alone for host-provided reviews over JSON-RPC.",destructive: true,options: z.object({concurrency: positiveInteger@@ -5939,7 +6140,32 @@ export async function main(}).command(imports).command("scan-components", {- description: "Scan project components and combine results.",+ description:+ "Scan project components independently and combine their results.",+ usage: [+ {+ suffix:+ "[repository] (--component PATH | --components-file FILE | --auto) --output-dir DIR [options]",+ },+ ],+ examples: [+ {+ args: { repository: "." },+ options: {+ component: ["services/api"],+ outputDir: "../component-results",+ },+ },+ {+ args: { repository: "." },+ options: {+ auto: true,+ planOnly: true,+ outputDir: "../component-plan",+ },+ },+ ],+ hint: "Supply --output-dir or configure output.directory. Automatic planning can call a model even with --plan-only. A per-component --max-cost does not cover planning.",destructive: true,alias: { config: "c" },args: z.object({@@ -6259,17 +6485,22 @@ export async function main(),...runtimeOptions(() => z.string().min(1)),}),+ usage: [+ { suffix: "[options]" },+ { suffix: "repositories.csv --output-dir DIR [options]" },+ { suffix: "repositories.csv --recover --output-dir DIR [options]" },+ ],examples: [{- args: {},- options: { model: "gpt-5.6-terra", effort: "high" },+ args: { input: "repositories.csv" },+ options: { outputDir: "../campaign", workers: 4, maxAttempts: 3 },+ },+ {+ args: { input: "repositories.csv" },+ options: { recover: true, outputDir: "../campaign" },},],- hint:- "CSV example:\n" +- " codex-security bulk-scan repositories.csv " +- "--output-dir /path/outside/repositories/results " +- "--workers 4 --max-attempts 3",+ hint: "Omit the CSV to select repositories interactively. A configured output.directory can supply the results directory; --max-cost applies per repository attempt.",output: z.record(z.string(), z.unknown()).optional(),async run({ args, options }) {const controller = new AbortController();@@ -6638,6 +6869,8 @@ export async function main(},}).command("validate", {+ usage: [{ suffix: "<findings...> [options]" }, { suffix: "--records" }],+ examples: [{ args: { "findings...": "findings.json" } }],hint: "Use --records alone for host-provided reviews over JSON-RPC.",description:"Assess candidate security findings using source evidence only.",@@ -6715,6 +6948,12 @@ export async function main(},}).command("verify-fix", {+ usage: [+ { suffix: "FINDING... [options]" },+ { suffix: "--scan ID [--severity LEVEL] [options]" },+ { suffix: "(--linear-issue ID | --linear-project PROJECT) [options]" },+ { suffix: "--host" },+ ],description:"Verify existing security fixes without changing the repository.",destructive: false,@@ -6959,6 +7198,13 @@ export async function main(},}).command("patch", {+ usage: [+ { suffix: "ISSUE... [options]" },+ { suffix: "--scan ID [--severity LEVEL] [options]" },+ { suffix: "(--linear-issue ID | --linear-project PROJECT) [options]" },+ { suffix: "--resume-pr BRANCH" },+ { suffix: "--host" },+ ],description: "Patch one or more security issues.",destructive: true,args: z.object({@@ -7481,6 +7727,8 @@ export async function main(},}).command("feedback", {+ usage: [{ suffix: "[scan-id] --reason TEXT [--include-logs]" }],+ examples: [{ options: { reason: "unexpected-result" } }],description: "Send feedback to OpenAI and return a feedback ID.",destructive: true,args: z.object({@@ -7623,14 +7871,28 @@ export async function main(}const commands = Cli.toCommands.get(cli)!;+ prepareCliExamples(commands);const valueOptions = cliValueOptions(commands);- const commandIndex = argv.findIndex((value, index) => {- if (value.startsWith("-")) return false;- return index === 0 || !valueOptions.has(argv[index - 1]!);- });+ const isPositional = (value: string, index: number) =>+ !value.startsWith("-") &&+ (index === 0 || !valueOptions.has(argv[index - 1]!));+ const commandIndex = argv.findIndex(isPositional);const command = argv[commandIndex];const following = argv[commandIndex + 1];const scanImport = command === "scan" && following === "import";+ if (+ command === "scan" &&+ !scanImport &&+ argv.some(+ (value, index) => index > commandIndex && isPositional(value, index),+ )+ ) {+ // A repository such as "imports" or "./import" is a positional even when+ // shared options precede it. Bypass Incur's subcommand typo suggestions.+ const scan = commands.get(command);+ if (scan && "_group" in scan && scan.root) commands.set(command, scan.root);+ }+if ((command === "scans" || command === "findings") &&!argv.includes("--help") &&@@ -7760,6 +8022,8 @@ export async function main(continue;const next = argv[index + 1];if (next === undefined || next.startsWith("--") || next === "-h") {+ if (scanImport && option === "--json" && argv.includes("--schema"))+ continue;return `Missing value for flag: ${option}`;}index += 1;@@ -7827,6 +8091,7 @@ export async function main(errorOutput.isTTY === true &&argv.length > 0 &&argv[0] !== "completions" &&+ !process.env["COMPLETE"] &&!argv.some((argument) =>[...inspectionFlags, "--dry-run", "--update"].includes(argument),) &&@@ -7836,87 +8101,6 @@ export async function main(.catch(() => undefined): undefined;- // Incur cannot mount a command with both a handler and subcommands.- // Select the nested import route while preserving scan [repository].- if (scanImport) {- cli.command(- Cli.create("scan", {- description: "Run or import a saved scan.",- }).command("import", {- description:- "Save CSV or JSON findings as a completed scan without security analysis.",- destructive: true,- options: z- .object({- csv: optionValue("--csv")- .optional()- .describe("Findings CSV in the codex-security export format."),- json: optionValue("--json")- .optional()- .describe(- "Findings JSON document or object with a findings array.",- ),- outputDir: optionValue("--output-dir")- .optional()- .describe(- "Artifact directory (default: Codex Security state; CODEX_SECURITY_STATE_DIR).",- ),- archiveExisting: z- .boolean()- .default(false)- .describe("Archive existing results; requires --output-dir."),- dryRun: z- .boolean()- .default(false)- .describe("Validate the input without saving a scan."),- })- .refine(- (options) =>- Number(options.csv !== undefined) +- Number(options.json !== undefined) ===- 1,- { message: "Provide exactly one of --csv FILE or --json FILE." },- )- .refine(- (options) =>- !options.archiveExisting || options.outputDir !== undefined,- { message: "--archive-existing requires --output-dir." },- ),- examples: [- { options: { csv: "findings.csv" } },- { options: { json: "findings.json" } },- ],- hint: "Each input row is retained, including duplicates. --json selects the input file; use --format json for JSON output.",- output: z.record(z.string(), z.unknown()).optional(),- async run({ options, format, error: incurError }) {- const directory = dependencies.currentDirectory();- const outcome = await runImport({- sourcePath: resolveCliPath(directory, options.csv ?? options.json!),- format: options.csv === undefined ? "json" : "csv",- outputDir:- options.outputDir === undefined- ? undefined- : resolveCliPath(directory, options.outputDir),- archiveExisting: options.archiveExisting,- dryRun: options.dryRun,- });- exitCode = outcome.exitCode;- if (outcome.error !== undefined) {- return incurError({- code: "SCAN_IMPORT_FAILED",- message: outcome.error,- exitCode,- });- }- if (!options.dryRun && useDefaultOutput(format)) {- return;- }- return outcome.data;- },- }),- );- }-let notice: UpdateNotice | undefined;if (argv.includes("--schema") || argv.includes("--llms-full")) {describeCommandInputs(commands);@@ -7948,6 +8132,21 @@ export async function main()onInterruptedSignIn?.();let frameworkOutput = frameworkCapture.text();+ if (+ command !== undefined &&+ (argv.includes("--help") || argv.includes("-h")) &&+ frameworkOutput.includes("\nUsage: codex-security <command>\n")+ ) {+ // Incur returns the root menu for unresolved application help paths.+ const parent = commands.get(command);+ const group = parent && "_group" in parent ? command : undefined;+ const path = group && following ? `${group} ${following}` : command;+ errorOutput.write(+ `codex-security: Unknown command ${diagnosticValue(path)}. Use codex-security${group ? ` ${group}` : ""} --help.\n`,+ );+ return 2;+ }+if (filteredScanFailure !== undefined) {// Success-field filters do not apply to diagnostics. Reuse Incur's format// and token controls without running the saved scan a second time.@@ -8504,19 +8703,51 @@ function parseFrameworkArguments(};}+/** Incur prints example keys verbatim and treats every option as a single value.+ * Give its shared help, manifest and skill renderers the actual shell tokens.+ */+function prepareCliExamples(+ commands: NonNullable<ReturnType<typeof Cli.toCommands.get>>,+): void {+ for (const entry of commands.values()) {+ if ("_group" in entry) prepareCliExamples(entry.commands);+ const command = "_group" in entry ? entry.root : entry;+ if (!command || !("examples" in command)) continue;+ for (const example of command.examples ?? []) {+ const tokens = Object.values(example.args ?? {}).map((value) =>+ quoteCliPath(String(value)),+ );+ for (const [key, value] of Object.entries(example.options ?? {})) {+ const flag = `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;+ for (const item of Array.isArray(value) ? value : [value]) {+ tokens.push(item === false ? `${flag}=false` : flag);+ if (typeof item !== "boolean")+ tokens.push(quoteCliPath(String(item)));+ }+ }+ example.args = tokens;+ delete example.options;+ }+ }+}+function cliValueOptions(commands: NonNullable<ReturnType<typeof Cli.toCommands.get>>,+ options = new Set(FRAMEWORK_VALUE_OPTIONS),): Set<string> {- const options = new Set(FRAMEWORK_VALUE_OPTIONS);- for (const command of commands.values()) {- if ("_group" in command) {- for (const option of cliValueOptions(command.commands))- options.add(option);- } else if ("options" in command && command.options) {+ for (const entry of commands.values()) {+ if ("_group" in entry) cliValueOptions(entry.commands, options);+ const command = "_group" in entry ? entry.root : entry;+ if (command && "options" in command && command.options) {for (const [name, schema] of Object.entries(z.toJSONSchema(command.options, { io: "input" }).properties ?? {},)) {- if (typeof schema === "object" && schema.type === "boolean") continue;+ // Bare --json is the framework output shortcut, except on scan import.+ if (+ name === "json" ||+ (typeof schema === "object" && schema.type === "boolean")+ )+ continue;options.add(`--${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`,);diff --git a/sdk/typescript/tests-ts/cli-cloud-publish.test.ts b/sdk/typescript/tests-ts/cli-cloud-publish.test.tsindex f5c90912f..b70e73537 100644--- a/sdk/typescript/tests-ts/cli-cloud-publish.test.ts+++ b/sdk/typescript/tests-ts/cli-cloud-publish.test.ts@@ -74,13 +74,13 @@ async function savedScansFixture() {}describe("publish scan to Cloud", () => {- test("documents the findings CSV option", async () => {+ test("reserves CSV publication for the documented internal destination", async () => {const stdout = captureCli(main, "stdout");expect(await stdout.run(["publish", "scan", "--help"], dependencies()),).toBe(0);- expect(stdout.text()).toContain("--csv <file>");- expect(stdout.text()).toContain("Findings CSV");+ expect(stdout.text()).not.toContain("--csv");+ expect(stdout.text()).not.toContain("Findings CSV");});test("preserves native CSV read and decode failures in CLI output", async () => {diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.tsindex 6820d884f..31c16f2d5 100644--- a/sdk/typescript/tests-ts/cli-help.test.ts+++ b/sdk/typescript/tests-ts/cli-help.test.ts@@ -82,11 +82,16 @@ describe("CLI help", () => {expect(sectionFor("init")).toBe(sectionFor("login"));expect(sectionFor("completions")).toBeGreaterThan(sectionFor("scan"));expect(text).toContain("Aliases: cs");- for (const command of ["login", "policy .", "scan .", "findings"]) {+ for (const command of [+ "scan . --dry-run",+ "login",+ "scan .",+ "scans show",+ ]) {expect(text).toContain(` codex-security ${command}`);}- expect(text.indexOf("codex-security policy .")).toBeLessThan(- text.indexOf("codex-security scan ."),+ expect(text.indexOf("codex-security scan . --dry-run")).toBeLessThan(+ text.indexOf("codex-security login"),);expect(text).toContain("<command> --help");});@@ -152,6 +157,7 @@ describe("CLI help", () => {{ command: ["scan"] },{ command: ["scan", "import"] },{ command: ["scans", "rerun"] },+ { command: ["scans", "resume"] },])("advertises supported formats for $command", async ({ command }) => {const text = await help([...command, "--help"]);const format = option(text, "--format");@@ -249,12 +255,124 @@ describe("CLI help", () => {usage: "codex-security findings [command]",},{ args: ["login", "status", "--help"], usage: "codex-security login" },- { args: ["unknown", "--help"], usage: "codex-security <command>" },])("preserves help routing for $args", async ({ args, usage }) => {const text = await help(args);expect(text).toContain(`Usage: ${usage}`);});+ test.each([+ {+ args: ["sacn", "--help"],+ missing: "sacn",+ recovery: "codex-security --help",+ },+ {+ args: ["scans", "foo", "--help"],+ missing: "scans foo",+ recovery: "codex-security scans --help",+ },+ ])(+ "identifies an unresolved help path $args",+ async ({ args, missing, recovery }) => {+ const out = capture();+ const err = capture();+ expect(await main(args, out.stream, err.stream, dependencies())).toBe(2);+ expect(out.text()).toBe("");+ expect(err.text()).toContain(missing);+ expect(err.text()).toContain(recovery);+ },+ );++ test.each([+ ["imports", "--json"],+ ["--json", "./import"],+ ])(+ "inspects repository scans with shared flags in either position (%s, %s)",+ async (first, second) => {+ const args = ["scan", first, second];+ expect(await help([...args, "--help"])).toContain(+ "Usage: codex-security scan [repository]",+ );+ const schema = JSON.parse(await help([...args, "--schema"]));+ expect(schema.args.properties.repository.type).toBe("string");+ },+ );++ test("links both file import routes and keeps the vendor preview copyable", async () => {+ const menu = (await help(["import", "--help"])).replace(/\s+/gu, " ");+ expect(menu).toContain("publish findings --help");+ expect(menu).toContain("scan import --help");+ const vendor = await help(["publish", "findings", "--help"], 60);+ const preview = vendor+ .split("\n")+ .find((line) => line.startsWith(" codex-security publish findings "));+ for (const flag of [+ "--provider",+ "--source-key",+ "--repository",+ "--to",+ "--dry-run",+ ]) {+ expect(preview).toContain(flag);+ }+ });++ test("exposes the scan and its import child in both manifests", async () => {+ for (const flag of ["--llms", "--llms-full"]) {+ const manifest = JSON.parse(await help([flag, "--format", "json"]));+ const names = manifest.commands.map(({ name }: { name: string }) => name);+ expect(names.filter((name: string) => name === "scan")).toHaveLength(1);+ expect(+ names.filter((name: string) => name === "scan import"),+ ).toHaveLength(1);+ }+ });++ test("publishes runnable examples with the same flags in help and the full manifest", async () => {+ const manifest = JSON.parse(+ await help(["--llms-full", "--format", "json"]),+ ) as {+ commands: { name: string; examples?: { command: string }[] }[];+ };+ for (const [name, flags] of [+ ["scan", ["--path src --path tests"]],+ ["scan-components", ["--auto --plan-only", "--output-dir"]],+ ["publish findings", ["--source-key", "--dry-run"]],+ ] as const) {+ const example = manifest.commands+ .find((command) => command.name === name)+ ?.examples?.find(({ command }) =>+ flags.every((flag) => command.includes(flag)),+ )?.command;+ expect(example).toBeDefined();+ expect(example).not.toMatch(+ /--[a-z-]+[A-Z]|--(?:auto|plan-only|dry-run) true/u,+ );+ expect(await help([...name.split(" "), "--help"], 60)).toContain(+ ` codex-security ${example}`,+ );+ }+ });++ test("completes scan import and its file options from the command registry", async () => {+ const previousShell = process.env["COMPLETE"];+ const previousIndex = process.env["_COMPLETE_INDEX"];+ try {+ process.env["COMPLETE"] = "bash";+ process.env["_COMPLETE_INDEX"] = "2";+ expect((await help(["--", "cs", "scan", "im"])).trim()).toBe("import");+ process.env["_COMPLETE_INDEX"] = "3";+ expect((await help(["--", "cs", "scan", "import", "--cs"])).trim()).toBe(+ "--csv",+ );+ } finally {+ if (previousShell === undefined) delete process.env["COMPLETE"];+ else process.env["COMPLETE"] = previousShell;+ if (previousIndex === undefined) delete process.env["_COMPLETE_INDEX"];+ else process.env["_COMPLETE_INDEX"] = previousIndex;+ }+ });+test.each([{ command: ["mcp"] },{ command: ["mcp", "add"] },diff --git a/sdk/typescript/tests-ts/cli-scan-import.test.ts b/sdk/typescript/tests-ts/cli-scan-import.test.tsindex bca609337..1ddc2e659 100644--- a/sdk/typescript/tests-ts/cli-scan-import.test.ts+++ b/sdk/typescript/tests-ts/cli-scan-import.test.ts@@ -255,32 +255,37 @@ describe("scan import", () => {expect(help.text()).toContain("--format json");const schema = captureCli(main, "stdout");expect(- await schema.run(- ["scan", "import", "--schema", "--format", "json"],- deps,- ),+ await schema.run(["scan", "import", "--schema", "--json"], deps),).toBe(0);expect(JSON.parse(schema.text())).toMatchObject({options: {properties: { csv: { type: "string" }, json: { type: "string" } },+ oneOf: [{ required: ["csv"] }, { required: ["json"] }],},});expect(calls).toHaveLength(0);});- test("ordinary scan retains repository arguments and the --json output shortcut", async () => {- const { stdout, runCli } = createCliTest(main);+ test.each([+ ["./import", "--json"],+ ["imports", "--json"],+ ["--json", "./import"],+ ])(+ "ordinary scan retains repository arguments and the JSON output shortcut (%s, %s)",+ async (first, second) => {+ const { stdout, runCli } = createCliTest(main);- const onRun = mock();- const deps = dependencies({- onRun,- });- expect(await runCli(["scan", "./import", "--json"], deps)).toBe(0);- expect(onRun).toHaveBeenCalledTimes(1);- expect(JSON.parse(stdout.text())).toMatchObject({- manifest: { scan: { id: "scan" } },- });- });+ const onRun = mock();+ const deps = dependencies({+ onRun,+ });+ expect(await runCli(["scan", first, second], deps)).toBe(0);+ expect(onRun).toHaveBeenCalledTimes(1);+ expect(JSON.parse(stdout.text())).toMatchObject({+ manifest: { scan: { id: "scan" } },+ });+ },+ );test("preserves the global JSON shortcut before the scan command", async () => {const { deps, calls } = importDependencies();diff --git a/sdk/typescript/tests-ts/cli-skills.test.ts b/sdk/typescript/tests-ts/cli-skills.test.tsindex fb1835572..8e5faf145 100644--- a/sdk/typescript/tests-ts/cli-skills.test.ts+++ b/sdk/typescript/tests-ts/cli-skills.test.ts@@ -268,8 +268,8 @@ describe("CLI skill commands", () => {await using temp = await scopedTemporaryDirectory("codex-security-skills-");const directory = temp.path;for (const [command, skill, argument, status] of [- ["validate", "validation", "findings...", 0],- ["patch", "fix-finding", "issues...", 7],+ ["validate", "validation", "<findings...>", 0],+ ["patch", "fix-finding", "ISSUE...", 7],] as const) {const file = join(directory, `${command}.txt`);await writeFile(file, `${command} file contents\n`);@@ -382,7 +382,7 @@ describe("CLI skill commands", () => {const help = captureCli(main, "stdout");expect(await help.run([command, "--help"], dependencies())).toBe(0);expect(help.text()).toContain(- `Usage: codex-security ${command} ${command === "patch" ? `[${argument}]` : `<${argument}>`}`,+ `Usage: codex-security ${command} ${argument}`,);expect(help.text()).toContain("--effort <effort>");expect(help.text()).toContain("--model <model>");diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 8af1f4d8c..2037c3d7c 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -1025,7 +1025,12 @@ describe("CLI", () => {definitions.options?.properties ?? {},)) {const flag = `--${name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}`;- expect(help.text()).toContain(flag);+ // The CSV input belongs to the internal publication destination.+ if (command.join(" ") === "publish scan" && flag === "--csv") {+ expect(help.text()).not.toContain(flag);+ } else {+ expect(help.text()).toContain(flag);+ }expect(typeof option.description).toBe("string");expect(option.description?.trim().length).toBeGreaterThan(0);}