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

fix: document CLI help and deep-scan configuration (#105)

mldangelo-oai1a9fc9bed3cb
diff --git a/README.md b/README.md
index 9f2cd1466..a8cf26b18 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
`@openai/codex-security` is a CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities in your code.
-**See the [Codex Security Documentation](http://learn.chatgpt.com/docs/security/cli)** for more details.
+**See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for more details.
> Note: for best results, we recommend that your account is verified for [Trusted Access](https://chatgpt.com/cyber).
@@ -17,7 +17,7 @@ npx @openai/codex-security scan .
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high
```
-For CI, set `OPENAI_API_KEY` instead of signing in.
+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` instead of signing in.
If both a ChatGPT sign-in and an API key are available, interactive scans ask
which credential to use. CI and other noninteractive scans keep the existing
@@ -51,4 +51,7 @@ console.log(result.reportPath);
await security.close();
```
-For installation, authentication, scan options, and CI setup, see the [official documentation](http://learn.chatgpt.com/docs/security/cli).
+For complete command help, runtime defaults, native multi-agent worker limits,
+environment variables, deep-scan configuration, and SDK options, see the
+[package README](sdk/typescript/README.md) and the
+[official CLI reference](https://learn.chatgpt.com/docs/security/cli/reference).
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 8d0690148..5bb93d8e8 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -56,6 +56,39 @@ Results can contain source excerpts, vulnerability details, and reproduction
steps. Keep result directories and saved reports outside the repository and
limit access to authorized reviewers.
+### SDK configuration and scan options
+
+Pass runtime configuration to the `CodexSecurity` constructor:
+
+| Option | Description |
+| ---------------- | --------------------------------------------------------------------------- |
+| `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |
+| `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |
+| `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |
+
+Pass scan configuration to `security.run(repository, options)` or
+`security.preflight(repository, options)`:
+
+| Option | Description |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
+| `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
+| `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
+| `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
+| `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
+| `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
+| `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
+| `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
+| `parentScanId` | Link a rerun to an existing parent scan. |
+| `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
+| `signal` | Cancel a scan with an `AbortSignal`. |
+
+Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
+`onOutputArchived`, `onOutputDirReady`, `onScanStarted`, `onReconnect`,
+`onWorkerStatus`, `onWarning`, and `onObserverError`. Preflight does not start
+the runtime, authenticate, resolve Python, inspect the plugin, or run those
+scan-lifecycle callbacks.
+
## Authentication
For local use, sign in with ChatGPT:
@@ -78,6 +111,10 @@ pass it on stdin:
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
```
+To pass a Codex access token explicitly, use
+`login --with-access-token` and provide the token on stdin. An access token
+environment variable is not automatically used as a scan API key.
+
On Windows, set the API key in PowerShell:
```powershell
@@ -197,9 +234,127 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
`--codex KEY=VALUE` for other Codex settings; existing
`--codex 'model_reasoning_effort="high"'` overrides remain supported.
+### Runtime configuration and worker limits
+
+The standalone CLI and SDK do not load an unrelated user or repository Codex
+configuration. Each scan starts with a private runtime and these Codex
+defaults:
+
+```toml
+cli_auth_credentials_store = "file"
+model = "gpt-5.6-sol"
+model_reasoning_effort = "xhigh"
+
+[features]
+plugins = true
+goals = true
+
+[features.multi_agent_v2]
+enabled = true
+max_concurrent_threads_per_session = 9
+
+[windows]
+sandbox = "unelevated"
+```
+
+Use `--model` and `--effort` for model selection. Repeat
+`--codex KEY=VALUE` to deep-merge other TOML values into this isolated
+configuration:
+
+```bash
+npx @openai/codex-security scan . \
+ --model gpt-5.6-terra \
+ --effort high \
+ --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
+```
+
+The session thread limit includes the parent agent: the default of `9`
+provides up to eight delegated worker slots. This limit is separate from
+`bulk-scan --workers`, which controls how many repositories run concurrently.
+A configured limit is a maximum, not evidence that every worker started.
+
+Quote string values as TOML, for example
+`--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
+`--codex 'model="..."'`, or both `--effort` and
+`--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
+rejected.
+
+Plugin and marketplace loading belong to Codex Security. Overrides of
+`plugins`, `marketplaces`, or `features.plugins`, including profile-specific
+plugin overrides, are rejected; choose `--plugin-path` instead. Native
+multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting
+and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
+`validate` and `patch` accept `--effort` and only the `model` and
+`model_reasoning_effort` `--codex` keys; they do not accept general scan
+runtime overrides.
+
These overrides do not change the scan's approval policy or filesystem
permissions. See [Local security model](#local-security-model).
+### Deep-scan engine configuration
+
+When the bundled plugin runs in a normal Codex host, its repeated-discovery
+engine reads `$CODEX_HOME/codex-security/config.toml`, defaulting to
+`~/.codex/codex-security/config.toml`:
+
+```toml
+[deep_scan]
+workers = "auto"
+subagents = 3
+stop_after_no_new = 6
+max_discovery_runs = 60
+```
+
+`workers = "auto"` uses half the available parallelism, with a minimum of one
+and a maximum of six discovery workers. Set `workers` to a positive integer to
+choose an explicit count. `subagents` must be a nonnegative integer;
+`stop_after_no_new` and `max_discovery_runs` must be positive integers. Unknown
+`[deep_scan]` keys are rejected.
+
+These settings are separate from Codex's
+`features.multi_agent_v2.max_concurrent_threads_per_session` and
+`bulk-scan --workers`. Importantly, standalone CLI and SDK scans create an
+isolated `CODEX_HOME` and do not import the ambient deep-scan configuration
+file. Consequently, `scan --mode deep` currently uses the deep engine's
+defaults; there are no standalone CLI flags for these four settings. Use
+`--codex` to adjust the Codex session thread limit, not to set `[deep_scan]`
+values.
+
+### Environment variables
+
+The CLI and SDK recognize the following user-configurable environment:
+
+| Variable | Effect |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
+| `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
+| `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
+| `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
+| `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
+| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
+| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |
+| `CI` | Disable interactive update notices in automated environments. |
+| `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |
+
+Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,
+the managed Codex runtime, and finally `python3` or `python` from `PATH`.
+`CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both
+state and result paths outside the scanned repository.
+
+The repository's Docker Compose workflow additionally recognizes
+`CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,
+`CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for
+its image, runtime user, seccomp profile, input, results, and state mounts.
+Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and
+`CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.
+These container settings are distinct from standalone CLI flags and
+interactive discovery's `GH_HOST`.
+
+Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
+`CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and
+`CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
+internal runtime data, not supported user configuration.
+
Scan progress identifies the requested paths and reports actual ranking,
file-review, validation, and attack-path phases as they become available.
Completion summarizes findings, severity, coverage, elapsed time, available
@@ -244,7 +399,8 @@ Results remain under `--output-dir`; rerun the same command to resume.
`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
repository path to inspect another checkout, `--scan-root DIR` to list scans
whose artifacts are under a particular root. `scans show SCAN_ID` includes the
-scan configuration, results, coverage, and artifact locations.
+scan configuration, results, coverage, and artifact locations. Add
+`--show-linked-findings` to include finding links from previous scans.
Every scan history command accepts a full scan ID or a unique prefix of at
least eight characters.
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 9a7b0c82d..3f69e4325 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -132,6 +132,12 @@ const MODEL_REASONING_EFFORTS = [
] as const satisfies readonly ModelReasoningEffort[];
const DEFAULT_SCAN_MODEL_CONFIGURATION =
scanModelConfiguration(DEFAULT_CODEX_CONFIG);
+const CODEX_OVERRIDE_DESCRIPTION =
+ 'Repeat TOML KEY=VALUE; e.g. model_reasoning_effort="high" or features.multi_agent_v2.max_concurrent_threads_per_session=4.';
+const PLUGIN_PATH_DESCRIPTION =
+ "Codex Security plugin directory or ZIP (default: bundled plugin).";
+const PYTHON_PATH_DESCRIPTION =
+ "Python interpreter (default: PYTHON or automatic discovery).";
const EXPORT_DEFAULT_OUTPUTS = {
csv: "findings.csv",
json: "findings.json",
@@ -883,32 +889,38 @@ export async function main(
auth: z
.enum(["auto", "chatgpt", "api-key"])
.default("auto")
- .describe("Select automatic, ChatGPT, or API-key authentication."),
+ .describe(
+ "Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication.",
+ ),
path: z
.array(optionValue("--path"))
.default([])
- .describe("Scan only PATH; repeat for multiple paths."),
+ .describe(
+ "Scan only PATH; repeat for multiple repository-relative paths.",
+ ),
knowledgeBase: z
.array(optionValue("--knowledge-base"))
.default([])
- .describe("Read security docs; repeat for multiple paths."),
+ .describe(
+ "Add security-context files or directories; repeat for multiple paths.",
+ ),
diff: optionValue("--diff")
.optional()
- .describe("Scan Git changes from BASE to --head."),
+ .describe("Scan committed Git changes from BASE to --head."),
workingTree: z
.boolean()
.default(false)
- .describe("Scan staged and unstaged changes."),
+ .describe("Scan staged and unstaged changes against --base."),
head: optionValue("--head")
.optional()
- .describe("Git head ref for --diff."),
+ .describe("Git head ref for --diff (default: HEAD)."),
base: optionValue("--base")
.optional()
- .describe("Git base ref for --working-tree."),
+ .describe("Git base ref for --working-tree (default: HEAD)."),
mode: z
.enum(["standard", "deep"])
.default("standard")
- .describe("Scan mode."),
+ .describe("Scan mode; deep supports repository and path targets."),
model: optionValue("--model")
.optional()
.describe(
@@ -917,23 +929,23 @@ export async function main(
effort: effortOption(),
outputDir: optionValue("--output-dir")
.optional()
- .describe("Write scan artifacts to DIR."),
+ .describe(
+ "Artifact directory outside the repository (default: Codex Security state; CODEX_SECURITY_STATE_DIR).",
+ ),
archiveExisting: z
.boolean()
.default(false)
- .describe("Archive existing results before scanning."),
+ .describe("Archive existing results; requires --output-dir."),
pluginPath: optionValue("--plugin-path")
.optional()
- .describe("Use a Codex Security plugin directory or ZIP."),
+ .describe(PLUGIN_PATH_DESCRIPTION),
python: optionValue("--python")
.optional()
- .describe("Python interpreter for the bundled plugin runtime."),
+ .describe(PYTHON_PATH_DESCRIPTION),
codex: z
.array(optionValue("--codex"))
.default([])
- .describe(
- 'Override Codex settings; e.g. model_reasoning_effort="high".',
- ),
+ .describe(CODEX_OVERRIDE_DESCRIPTION),
failOnSeverity: z
.enum(REPORTABLE_SEVERITIES)
.optional()
@@ -981,8 +993,16 @@ export async function main(
args: { repository: "." },
options: { model: "gpt-5.6-terra", effort: "high" },
},
- { args: { repository: "." }, options: { path: ["src", "tests"] } },
+ { args: { repository: "." }, options: { path: ["src"] } },
{ args: { repository: "." }, options: { diff: "origin/main" } },
+ {
+ args: { repository: "." },
+ options: {
+ codex: [
+ "features.multi_agent_v2.max_concurrent_threads_per_session=4",
+ ],
+ },
+ },
],
output: z.record(z.string(), z.unknown()).optional(),
async run({ args, error: incurError, format, options }) {
@@ -1118,16 +1138,30 @@ export async function main(
.string()
.min(1)
.optional()
- .describe("CSV repository list; omit to discover repositories."),
+ .describe(
+ "CSV repository list; omit to discover repositories interactively.",
+ ),
}),
options: z.object({
outputDir: z
.string()
.min(1, "--output-dir must not be empty.")
.optional()
- .describe("Directory for scan artifacts and resumable results."),
- workers: z.number().int().positive().default(4),
- mode: z.enum(["standard", "deep"]).default("standard"),
+ .describe(
+ "Resumable results directory; required with a repository CSV.",
+ ),
+ workers: z
+ .number()
+ .int()
+ .positive()
+ .default(4)
+ .describe(
+ "Concurrent repository scans. Per-scan Codex workers are separate.",
+ ),
+ mode: z
+ .enum(["standard", "deep"])
+ .default("standard")
+ .describe("Default scan mode for repositories without a CSV mode."),
model: optionValue("--model")
.optional()
.describe(
@@ -1140,15 +1174,28 @@ export async function main(
.positive()
.default(1)
.describe("Maximum scan attempts per repository."),
- pluginPath: z.string().min(1).optional(),
- python: z.string().min(1).optional(),
+ pluginPath: z
+ .string()
+ .min(1)
+ .optional()
+ .describe(PLUGIN_PATH_DESCRIPTION),
+ python: z.string().min(1).optional().describe(PYTHON_PATH_DESCRIPTION),
codex: z
.array(z.string().min(1))
.default([])
- .describe(
- 'Override Codex settings; e.g. model_reasoning_effort="high".',
- ),
+ .describe(CODEX_OVERRIDE_DESCRIPTION),
}),
+ examples: [
+ {
+ args: {},
+ options: { model: "gpt-5.6-terra", effort: "high" },
+ },
+ ],
+ hint:
+ "CSV example:\n" +
+ " codex-security bulk-scan repositories.csv " +
+ "--output-dir /path/outside/repositories/results " +
+ "--workers 4 --max-attempts 3",
output: z.record(z.string(), z.unknown()).optional(),
async run({ args, options }) {
const controller = new AbortController();
@@ -1268,10 +1315,12 @@ export async function main(
exportFormat: z
.enum(["csv", "json", "sarif"])
.default("sarif")
- .describe("Export format (default: sarif)."),
+ .describe("Artifact format to export from the completed scan."),
output: optionValue("--output")
.optional()
- .describe("Write the selected format to FILE or stdout with '-'."),
+ .describe(
+ "FILE or '-' for stdout (default: results.sarif, findings.json, or findings.csv).",
+ ),
sourceRoot: optionValue("--source-root")
.optional()
.describe(
@@ -1332,7 +1381,7 @@ export async function main(
.array(optionValue("--codex"))
.default([])
.describe(
- 'Set model="gpt-5.6-terra" or model_reasoning_effort="high".',
+ 'Repeat TOML model="gpt-5.6-terra" or model_reasoning_effort="high" only.',
),
}),
async run({ options }) {
@@ -1368,7 +1417,7 @@ export async function main(
.array(optionValue("--codex"))
.default([])
.describe(
- 'Set model="gpt-5.6-terra" or model_reasoning_effort="high".',
+ 'Repeat TOML model="gpt-5.6-terra" or model_reasoning_effort="high" only.',
),
}),
async run({ options }) {
@@ -1728,9 +1777,10 @@ function validateCliArguments(
);
if (
structuredOutput &&
- ["validate", "patch", "login", "logout"].includes(command)
+ ["validate", "patch", "login", "logout"].includes(command) &&
+ !argv.includes("--schema")
) {
- return `${command} does not support noninteractive JSON output; run it without --json or --format json.`;
+ return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
}
if (
command === "export" &&
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index 1baf3f9db..1da4538fd 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -186,6 +186,182 @@ describe("CLI", () => {
expect(completions.text()).toContain('export COMPLETE="bash"');
});
+ test("documents every public command argument and option", async () => {
+ const commands = [
+ ["scan"],
+ ["bulk-scan"],
+ ["export"],
+ ["validate"],
+ ["patch"],
+ ["login"],
+ ["logout"],
+ ["info"],
+ ["install-hook"],
+ ["scans", "list"],
+ ["scans", "show"],
+ ["scans", "rerun"],
+ ["scans", "match"],
+ ["scans", "compare"],
+ ["findings", "false-positive"],
+ ] as const;
+
+ for (const command of commands) {
+ const help = capture();
+ const schema = capture();
+ expect(
+ await main(
+ [...command, "--help"],
+ help.stream,
+ capture().stream,
+ dependencies(),
+ ),
+ ).toBe(0);
+ expect(help.text()).not.toMatch(/--[a-z][a-z0-9-]*[A-Z][A-Za-z0-9-]*/u);
+ expect(
+ await main(
+ [...command, "--schema", "--format", "json"],
+ schema.stream,
+ capture().stream,
+ dependencies(),
+ ),
+ ).toBe(0);
+
+ const definitions = JSON.parse(schema.text()) as {
+ args?: {
+ properties?: Record<string, { description?: string }>;
+ };
+ options?: {
+ properties?: Record<string, { description?: string }>;
+ };
+ };
+
+ for (const argument of Object.values(
+ definitions.args?.properties ?? {},
+ )) {
+ expect(typeof argument.description).toBe("string");
+ expect(argument.description?.trim().length).toBeGreaterThan(0);
+ }
+
+ for (const [name, option] of Object.entries(
+ definitions.options?.properties ?? {},
+ )) {
+ const flag = `--${name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}`;
+ expect(help.text()).toContain(flag);
+ expect(typeof option.description).toBe("string");
+ expect(option.description?.trim().length).toBeGreaterThan(0);
+ }
+ }
+ });
+
+ test("documents user-facing environment and deep-scan configuration", async () => {
+ const readme = await readFile(new URL("../README.md", import.meta.url), {
+ encoding: "utf8",
+ });
+
+ for (const setting of [
+ "OPENAI_API_KEY",
+ "CODEX_API_KEY",
+ "CODEX_SECURITY_STATE_DIR",
+ "CODEX_HOME",
+ "PYTHON",
+ "GH_HOST",
+ "GH_TOKEN",
+ "GITHUB_TOKEN",
+ "CODEX_SECURITY_GIT_HOST",
+ "CODEX_SECURITY_IMAGE",
+ "CODEX_SECURITY_USER",
+ "CODEX_SECURITY_SECCOMP",
+ "CODEX_SECURITY_CSV",
+ "CODEX_SECURITY_RESULTS",
+ "CODEX_SECURITY_STATE",
+ "CODEX_SECURITY_NO_UPDATE_NOTICE",
+ "NO_UPDATE_NOTIFIER",
+ "CODEX_SECURITY_NPM_REGISTRY",
+ "npm_config_registry",
+ "NPM_CONFIG_REGISTRY",
+ "NO_COLOR",
+ "TERM",
+ "CI",
+ "features.multi_agent_v2.max_concurrent_threads_per_session",
+ "agents.max_threads",
+ "$CODEX_HOME/codex-security/config.toml",
+ "[deep_scan]",
+ "stop_after_no_new",
+ "max_discovery_runs",
+ ]) {
+ expect(readme).toContain(setting);
+ }
+ });
+
+ test("keeps documented runtime and deep-scan defaults accurate", async () => {
+ const readme = await readFile(new URL("../README.md", import.meta.url), {
+ encoding: "utf8",
+ });
+ expect(readme).toContain(
+ `model = "${DEFAULT_SCAN_MODEL_CONFIGURATION.model}"`,
+ );
+ expect(readme).toContain(
+ `model_reasoning_effort = "${DEFAULT_SCAN_MODEL_CONFIGURATION.reasoningEffort}"`,
+ );
+
+ const features = DEFAULT_CODEX_CONFIG["features"] as JsonObject;
+ const multiAgent = features["multi_agent_v2"] as JsonObject;
+ expect(readme).toContain(
+ `max_concurrent_threads_per_session = ${String(multiAgent["max_concurrent_threads_per_session"])}`,
+ );
+
+ const python = Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ const root = await mkdtemp(join(tmpdir(), "codex-security-deep-defaults-"));
+
+ try {
+ const result = spawnSync(
+ python!,
+ [
+ fileURLToPath(
+ new URL(
+ "../_bundled_plugin/scripts/deep_scan_config.py",
+ import.meta.url,
+ ),
+ ),
+ "--available-parallelism",
+ "12",
+ ],
+ {
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ CODEX_HOME: join(root, "codex-home"),
+ PYTHONDONTWRITEBYTECODE: "1",
+ },
+ timeout: 30_000,
+ },
+ );
+
+ expect(result.error).toBeUndefined();
+ expect(result.status).toBe(0);
+ expect(result.stderr).toBe("");
+
+ const defaults = JSON.parse(result.stdout) as {
+ workers: number;
+ subagents: number;
+ stopAfterNoNew: number;
+ maxDiscoveryRuns: number;
+ };
+ expect(defaults.workers).toBe(6);
+ expect(readme).toContain('workers = "auto"');
+ expect(readme).toContain(`subagents = ${defaults.subagents}`);
+ expect(readme).toContain(
+ `stop_after_no_new = ${defaults.stopAfterNoNew}`,
+ );
+ expect(readme).toContain(
+ `max_discovery_runs = ${defaults.maxDiscoveryRuns}`,
+ );
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+ });
+
test("marks findings as false positives without starting Codex", async () => {
const reason = " Not reachable from untrusted input. ";
const expectedReason = reason.trim();
@@ -1088,34 +1264,42 @@ describe("CLI", () => {
test("rejects structured modes before starting interactive Codex commands", async () => {
for (const [command, arguments_] of [
- ["validate", ["finding", "--json"]],
- ["patch", ["issue", "--format", "json"]],
- ["login", ["--json"]],
- ["login", ["status", "--format", "jsonl"]],
- ["logout", ["--json"]],
+ ["validate", ["finding"]],
+ ["patch", ["issue"]],
+ ["login", []],
+ ["login", ["status"]],
+ ["logout", []],
] as const) {
- let invoked = false;
- const stdout = capture();
- const stderr = capture(true);
+ for (const format of [
+ ["--json"],
+ ["--format", "json"],
+ ["--format=json"],
+ ["--format", "jsonl"],
+ ["--format=jsonl"],
+ ] as const) {
+ let invoked = false;
+ const stdout = capture();
+ const stderr = capture(true);
- expect(
- await main(
- [command, ...arguments_],
- stdout.stream,
- stderr.stream,
- dependencies({
- onCodex: () => {
- invoked = true;
- return 0;
- },
- }),
- ),
- ).toBe(2);
- expect(invoked).toBe(false);
- expect(stdout.text()).toBe("");
- expect(stderr.text()).toContain(
- `${command} does not support noninteractive JSON output`,
- );
+ expect(
+ await main(
+ [command, ...arguments_, ...format],
+ stdout.stream,
+ stderr.stream,
+ dependencies({
+ onCodex: () => {
+ invoked = true;
+ return 0;
+ },
+ }),
+ ),
+ ).toBe(2);
+ expect(invoked).toBe(false);
+ expect(stdout.text()).toBe("");
+ expect(stderr.text()).toContain(
+ `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`,
+ );
+ }
}
});
@@ -1283,6 +1467,10 @@ describe("CLI", () => {
`Model reasoning effort (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.reasoningEffort}).`,
);
expect(help.text()).toContain('model_reasoning_effort="high"');
+ expect(help.text()).toContain(
+ "features.multi_agent_v2.max_concurrent_threads_per_session=4",
+ );
+ expect(help.text()).toContain("default: Codex Security state");
expect(help.text()).toContain(
"codex-security scan . --model gpt-5.6-terra",
);
@@ -1291,6 +1479,7 @@ describe("CLI", () => {
);
expect(help.text()).not.toContain("--provider");
expect(help.text()).not.toContain("openai:gpt");
+ expect(help.text()).not.toContain("codex-security scan . --path src,tests");
expect(help.text()).toContain("--format <toon|json|yaml|md|jsonl>");
});
@@ -1316,6 +1505,26 @@ describe("CLI", () => {
);
expect(help.text()).toContain("--codex <array>");
expect(help.text()).toContain('model_reasoning_effort="high"');
+ expect(help.text()).toContain(
+ "features.multi_agent_v2.max_concurrent_threads_per_session=4",
+ );
+ expect(help.text()).toContain("Concurrent repository scans.");
+ expect(help.text()).toContain(
+ "Default scan mode for repositories without a CSV mode.",
+ );
+ expect(help.text()).toContain(
+ "Codex Security plugin directory or ZIP (default: bundled plugin).",
+ );
+ expect(help.text()).toContain(
+ "Python interpreter (default: PYTHON or automatic discovery).",
+ );
+ expect(help.text()).toContain(
+ "codex-security bulk-scan repositories.csv " +
+ "--output-dir /path/outside/repositories/results " +
+ "--workers 4 --max-attempts 3",
+ );
+ expect(help.text()).not.toContain("--outputDir");
+ expect(help.text()).not.toContain("--maxAttempts");
expect(help.text()).not.toContain("--provider");
expect(stderr.text()).toBe("");
});