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: keep optional preflight capability checks advisory (#394)
mldangelo-oai2f785900d2ce
diff --git a/sdk/typescript/_bundled_plugin/references/config-preflight.md b/sdk/typescript/_bundled_plugin/references/config-preflight.mdindex 8d1a0a04c..4acab87b5 100644--- a/sdk/typescript/_bundled_plugin/references/config-preflight.md+++ b/sdk/typescript/_bundled_plugin/references/config-preflight.md@@ -22,7 +22,7 @@ When the current Codex CLI session selected `-p/--profile <name>`, pass `--codexFor targeted tests or unusual runtimes, repeated `--config <path>` arguments override automatic discovery. Pass those manual layers from lower to higher precedence.-Repeat `--available-plugin-skill <skill-name>` only for skills from the capability's plugin when the selected profile checks skill dependencies. For the `deep_security_scan` profile, expose only the plugin-local names of available `codex-security` skills, such as `security-scan`; do not pass unrelated session skills. Use the current session's Available skills surface, not files found on disk. The helper reports unavailable skills as a runtime problem and a missing runtime plugin skill list as `incomplete`.+Repeat `--available-plugin-skill <skill-name>` only for skills from the capability's plugin when the selected profile checks skill dependencies. For the `deep_security_scan` profile, expose only the plugin-local names of available `codex-security` skills, such as `security-scan`; do not pass unrelated session skills. Use the current session's Available skills surface, not files found on disk. The helper reports unavailable skills as a runtime problem and a missing runtime plugin skill list as `incomplete` only when the selected capability is blocking.In Codex CLI, run the helper directly in the parent even when delegation is available. This keeps the exact command, exit code, and JSON result in the CLI event stream and avoids attributing an unobservable child result to the active runtime. In other hosts with delegation, run preflight in one dedicated worker before substantive scan work. Dispatch means a successful worker-spawn tool call that returns a concrete worker or thread id. Do not claim that a worker is running, or call a generic wait with no receiver, unless that spawn succeeded. Wait for the specific returned id and accept a result only from that worker. If spawning fails or returns no id, run the helper directly in the parent and report the spawn failure; never invent or reconstruct a helper result. The worker should return only a compact summary: the executed command and exit code, overall status, unmet or unknown capabilities, the returned `user_config_path`, and applicable remediation. Include the source path for any conflicting setting. Do not return the helper's raw JSON unless the parent needs it to resolve an ambiguity. This keeps preflight inspection out of the primary scan context.@@ -34,7 +34,7 @@ Multi-agent config mode is auto-detected when static config fully describes it.--multi-agent-runtime-owner native --multi-agent-runtime-version v2 --multi-agent-session-cap <count> --multi-agent-runtime-provenance <app-server|thread-context|tool-surface>```-The V2 session cap includes the root thread. For profiles that evaluate current-session worker capacity, the helper subtracts that root thread when evaluating usable worker slots. For native V2 selected by static config, the documented Codex default session cap is four when no explicit cap is configured. Do not apply that static default to model- or session-selected V2 when a profile needs the active capacity: pass the observed runtime cap, or the result remains `incomplete`.+The V2 session cap includes the root thread. For profiles that evaluate current-session worker capacity, the helper subtracts that root thread when evaluating usable worker slots. For native V2 selected by static config, the documented Codex default session cap is four when no explicit cap is configured. Do not apply that static default to model- or session-selected V2 when a profile needs the active capacity: pass the observed runtime cap, or a blocking capacity requirement remains `incomplete`.When the active session is actually managed by `codex_bridge`, provide explicit verified ownership. A backend config value alone is not ownership evidence:@@ -44,7 +44,7 @@ When the active session is actually managed by `codex_bridge`, provide explicitWithout `--multi-agent-runtime-owner codex-bridge` and `verified-bridge` provenance, passing `multiagent_config.max_concurrency` is an error. This prevents an assumed config value from reclassifying a native App session as bridge-owned.-Static native V2 accepts both `[features] multi_agent_v2 = true` and `[features.multi_agent_v2] enabled = true`. Native V2 cannot be combined with `agents.max_threads`; the helper rejects that invalid config. `agents.max_depth` applies to V1 only and is not required for V2. A runtime version and cap without verified ownership cannot produce `ready`. When runtime version, ownership, or capacity remains unknown, the helper returns `incomplete` where the selected profile needs that fact and omits unsafe concurrency patches.+Static native V2 accepts both `[features] multi_agent_v2 = true` and `[features.multi_agent_v2] enabled = true`. Native V2 cannot be combined with `agents.max_threads`; the helper rejects that invalid config. `agents.max_depth` applies to V1 only and is not required for V2. A runtime version and cap without verified ownership cannot satisfy a blocking requirement. When runtime version, ownership, or capacity remains unknown, the helper returns `incomplete` only when a blocking requirement needs that fact and omits unsafe concurrency patches.The helper reads the routed capability profile from `../preflight/capability-profiles.toml`, discovers the applicable Codex config paths from `--cwd`, applies documented defaults where the registry provides them, and prints one JSON result.@@ -66,7 +66,7 @@ Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's wDo not warn merely because a user's value differs from the profile's suggested patch. Warn or block only when the evaluated capability requirement is unmet.-If a runtime capability is `unknown`, establish it from the current tool surface and rerun the helper with an explicit `--runtime-check`. Do not treat an `incomplete` result or unknown value as evidence that the capability is available.+If a blocking runtime capability is `unknown`, establish it from the current tool surface and rerun the helper with an explicit `--runtime-check`. An unknown `warn` or `suggest` capability does not block a `ready` scan; continue on the documented degraded path without claiming that capability is available.## Durable scan handoffdiff --git a/sdk/typescript/_bundled_plugin/scripts/config_preflight.py b/sdk/typescript/_bundled_plugin/scripts/config_preflight.pyindex 2cba25ed5..d51f8f759 100644--- a/sdk/typescript/_bundled_plugin/scripts/config_preflight.py+++ b/sdk/typescript/_bundled_plugin/scripts/config_preflight.py@@ -858,7 +858,7 @@ def evaluate(args: argparse.Namespace) -> dict[str, Any]:unknown = [result for result in results if result["status"] == "unknown"]if any(result["severity"] == "block" for result in failed):status = "blocked"- elif unknown:+ elif any(result["severity"] == "block" for result in unknown):status = "incomplete"else:status = "ready"diff --git a/sdk/typescript/tests-ts/runtime.test.ts b/sdk/typescript/tests-ts/runtime.test.tsindex 4cb3f3455..cd58449d5 100644--- a/sdk/typescript/tests-ts/runtime.test.ts+++ b/sdk/typescript/tests-ts/runtime.test.ts@@ -3558,6 +3558,101 @@ describe("runtime directories and plugin Python boundary", () => {).toMatchObject({ actual: 8, source: configPath });});+ test("continues when optional preflight capabilities are unknown", async () => {+ const root = await temporaryDirectory();+ const config = join(root, "config.toml");+ await writeFile(config, "");+ const python = Bun.which("python3") ?? Bun.which("python");+ expect(python).not.toBeNull();++ for (const profile of [+ "security_diff_scan",+ "security_scan",+ "deep_security_scan",+ ]) {+ const result = spawnSync(+ python!,+ [+ "-I",+ "-B",+ join(PLUGIN_ROOT, "scripts", "config_preflight.py"),+ "--profile",+ profile,+ "--config",+ config,+ "--cwd",+ root,+ ],+ { encoding: "utf8", env: process.env },+ );++ expect(result.status, result.stderr).toBe(0);+ const payload = JSON.parse(result.stdout) as {+ status: string;+ unknown: { capability: string; severity: string }[];+ };+ expect(payload.status).toBe("ready");+ expect(payload.unknown.length).toBeGreaterThan(0);+ expect(+ payload.unknown.every(({ severity }) => severity !== "block"),+ ).toBe(true);+ }+ });++ test("keeps required preflight capabilities blocking", async () => {+ const root = await temporaryDirectory();+ const config = join(root, "config.toml");+ const registry = join(root, "capabilities.toml");+ await writeFile(config, "");+ await writeFile(+ registry,+ [+ "version = 1",+ "[capabilities.required]",+ 'kind = "runtime"',+ 'check = "required_available"',+ "[profiles.required]",+ 'description = "Required runtime capability"',+ "[[profiles.required.requirements]]",+ 'capability = "required"',+ 'severity = "block"',+ 'reason = "Required runtime capability"',+ ].join("\n"),+ );+ const python = Bun.which("python3") ?? Bun.which("python");+ expect(python).not.toBeNull();++ for (const [value, status, exitCode] of [+ [undefined, "incomplete", 2],+ ["false", "blocked", 1],+ ["true", "ready", 0],+ ] as const) {+ const result = spawnSync(+ python!,+ [+ "-I",+ "-B",+ join(PLUGIN_ROOT, "scripts", "config_preflight.py"),+ "--registry",+ registry,+ "--profile",+ "required",+ "--config",+ config,+ "--cwd",+ root,+ ...(value === undefined+ ? []+ : ["--runtime-check", `required_available=${value}`]),+ ],+ { encoding: "utf8", env: process.env },+ );++ expect(result.status, result.stderr).toBe(exitCode);+ expect(JSON.parse(result.stdout)).toMatchObject({ status });+ }+ });+test("runs workbench commands without output limits, credentials, or generated bytecode", async () => {const root = await temporaryDirectory();const pluginRoot = join(root, "plugin");diff --git a/sdk/typescript/tests-ts/worker-progress.test.ts b/sdk/typescript/tests-ts/worker-progress.test.tsindex 1bb82c79d..36b95b86b 100644--- a/sdk/typescript/tests-ts/worker-progress.test.ts+++ b/sdk/typescript/tests-ts/worker-progress.test.ts@@ -64,7 +64,7 @@ describe("worker progress events", () => {"python3 /plugin/scripts/config_preflight.py --profile security_scan",JSON.stringify({profile: "security_scan",- status: status === "unknown" ? "incomplete" : "ready",+ status: "ready",results: [{ capability: "delegated_workers", status },{