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(plugin): scope runtime checks to selected preflight profile (#425)

mldangelo-oai0b9593f9bc8a
diff --git a/sdk/typescript/_bundled_plugin/references/config-preflight.md b/sdk/typescript/_bundled_plugin/references/config-preflight.md
index 4acab87b5..873de40df 100644
--- a/sdk/typescript/_bundled_plugin/references/config-preflight.md
+++ b/sdk/typescript/_bundled_plugin/references/config-preflight.md
@@ -42,9 +42,9 @@ When the active session is actually managed by `codex_bridge`, provide explicit
--multi-agent-runtime-owner codex-bridge --multi-agent-runtime-version v2 --multi-agent-runtime-provenance verified-bridge --effective-config multiagent_config.max_concurrency=<count>
```
-Without `--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.
+For a profile that evaluates parent-runtime settings, passing `multiagent_config.max_concurrency` without `--multi-agent-runtime-owner codex-bridge` and `verified-bridge` provenance is an error. Explicit runtime claims still require their existing provenance and ownership checks. An unrelated backend config value does not block a profile that does not use parent-runtime settings.
-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.
+Static native V2 accepts both `[features] multi_agent_v2 = true` and `[features.multi_agent_v2] enabled = true`. When the profile evaluates parent-runtime settings or explicit runtime facts are supplied, native V2 cannot be combined with `agents.max_threads`. `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.
diff --git a/sdk/typescript/_bundled_plugin/scripts/config_preflight.py b/sdk/typescript/_bundled_plugin/scripts/config_preflight.py
index d51f8f759..ee4f1ab01 100644
--- a/sdk/typescript/_bundled_plugin/scripts/config_preflight.py
+++ b/sdk/typescript/_bundled_plugin/scripts/config_preflight.py
@@ -436,6 +436,7 @@ def resolve_multi_agent_context(
runtime_version: str | None,
runtime_session_cap: int | None,
runtime_provenance: str | None,
+ validate_multi_agent_config: bool,
) -> dict[str, Any]:
runtime_facts_supplied = any(
value is not None for value in (runtime_owner, runtime_version, runtime_session_cap)
@@ -495,7 +496,11 @@ def resolve_multi_agent_context(
effective_config=effective_config,
config_profile=config_profile,
)
- if bridge_cap_found and owner != "codex-bridge":
+ if (
+ bridge_cap_found
+ and owner != "codex-bridge"
+ and (validate_multi_agent_config or runtime_facts_supplied)
+ ):
raise ValueError(
"multiagent_config.max_concurrency does not prove bridge ownership; "
"pass --multi-agent-runtime-owner codex-bridge only when the active runtime "
@@ -514,7 +519,12 @@ def resolve_multi_agent_context(
effective_config=effective_config,
config_profile=config_profile,
)
- if owner != "codex-bridge" and feature_found and enabled and agent_threads_found:
+ if (
+ owner != "codex-bridge"
+ and ((feature_found and enabled) or (owner == "native" and version == "v2"))
+ and agent_threads_found
+ and (validate_multi_agent_config or runtime_facts_supplied)
+ ):
raise ValueError("agents.max_threads cannot be set when multi_agent_v2 is enabled")
if version == "v1":
@@ -758,6 +768,30 @@ def validate_registry(registry: dict[str, Any]) -> None:
)
+def profile_requires_multi_agent_config(
+ profile: dict[str, Any], capabilities: dict[str, dict[str, Any]]
+) -> bool:
+ def is_runtime_path(path: Any) -> bool:
+ return isinstance(path, str) and (
+ path in {"agents", "features", "features.multi_agent_v2", "multiagent_config"}
+ or path.startswith(("agents.", "multiagent_config.", "features.multi_agent_v2."))
+ )
+
+ for requirement in profile["requirements"]:
+ capability = capabilities[requirement["capability"]]
+ if (
+ capability["kind"] in {"multi_agent_capacity", "multi_agent_mode"}
+ or requirement.get("modes")
+ or is_runtime_path(capability.get("path"))
+ ):
+ return True
+ remediation = profile.get("remediation", {})
+ return bool(remediation.get("variants")) or any(
+ is_runtime_path(patch.get("path"))
+ for patch in remediation.get("patches", [])
+ )
+
+
def resolve_remediation(
profile: dict[str, Any], *, multi_agent_context: dict[str, Any]
) -> dict[str, Any]:
@@ -838,6 +872,9 @@ def evaluate(args: argparse.Namespace) -> dict[str, Any]:
runtime_version=args.multi_agent_runtime_version,
runtime_session_cap=args.multi_agent_session_cap,
runtime_provenance=args.multi_agent_runtime_provenance,
+ validate_multi_agent_config=profile_requires_multi_agent_config(
+ profile, registry["capabilities"]
+ ),
)
results = [
evaluate_requirement(
diff --git a/sdk/typescript/tests-ts/api-preflight-config.test.ts b/sdk/typescript/tests-ts/api-preflight-config.test.ts
index 0fe94b338..772a86481 100644
--- a/sdk/typescript/tests-ts/api-preflight-config.test.ts
+++ b/sdk/typescript/tests-ts/api-preflight-config.test.ts
@@ -1,5 +1,12 @@
-import { execFileSync } from "node:child_process";
-import { mkdir, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+ mkdir,
+ mkdtemp,
+ readFile,
+ realpath,
+ rm,
+ writeFile,
+} from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, test } from "bun:test";
@@ -50,7 +57,257 @@ async function temporaryDirectory(): Promise<string> {
return path;
}
+function runPreflight(
+ config: string,
+ profile: string,
+ options: readonly string[] = [],
+): { status: number | null; payload: Record<string, unknown> } {
+ const interpreter =
+ Bun.which("python3") ?? Bun.which("python") ?? Bun.which("py");
+ expect(interpreter).not.toBeNull();
+ const result = spawnSync(
+ interpreter!,
+ [
+ "-I",
+ "-B",
+ join(PLUGIN_ROOT, "scripts", "config_preflight.py"),
+ "--profile",
+ profile,
+ "--config",
+ config,
+ ...options,
+ ],
+ { encoding: "utf8" },
+ );
+ expect(result.error).toBeUndefined();
+ return {
+ status: result.status,
+ payload: JSON.parse(result.stdout) as Record<string, unknown>,
+ };
+}
+
describe("CodexSecurity preflight configuration", () => {
+ test("ignores unrelated runtime settings for profiles without parent-runtime requirements", async () => {
+ const root = await temporaryDirectory();
+ const config = join(root, "empty.toml");
+ await writeFile(config, "");
+ const settings = [
+ {
+ args: [
+ "--effective-config",
+ "features.multi_agent_v2.enabled=true",
+ "--effective-config",
+ "agents.max_threads=8",
+ ],
+ context: { owner: "native", version: "v2", agent_max_threads: 8 },
+ error: "agents.max_threads cannot be set",
+ },
+ {
+ args: ["--effective-config", "multiagent_config.max_concurrency=8"],
+ context: { owner: "unknown", version: "unknown" },
+ error: "does not prove bridge ownership",
+ },
+ ];
+
+ for (const { args, context, error } of settings) {
+ for (const profile of ["deep_security_scan", "security_diff_scan"]) {
+ const result = runPreflight(config, profile, args);
+ expect(result.status).toBe(0);
+ expect(result.payload).toMatchObject({
+ multi_agent_context: context,
+ profile,
+ status: "ready",
+ });
+ }
+
+ const required = runPreflight(config, "security_scan", args);
+ expect(required.status).toBe(2);
+ expect(required.payload["error"]).toContain(error);
+ }
+ });
+
+ test("keeps custom profile requirements and explicit runtime ownership strict", async () => {
+ const root = await temporaryDirectory();
+ const config = join(root, "empty.toml");
+ const registry = join(root, "registry.toml");
+ await writeFile(config, "");
+ await writeFile(
+ registry,
+ [
+ "version = 1",
+ "[capabilities.available]",
+ 'kind = "runtime"',
+ 'check = "available"',
+ "[capabilities.mode]",
+ 'kind = "multi_agent_mode"',
+ 'owner = "native"',
+ 'version = "v2"',
+ "[capabilities.bridge]",
+ 'kind = "config"',
+ 'path = "multiagent_config.max_concurrency"',
+ 'op = ">="',
+ "value = 1",
+ ...[
+ ["root_bridge", "multiagent_config"],
+ ["root_agents", "agents"],
+ ["root_features", "features"],
+ ["v2_feature", "features.multi_agent_v2"],
+ ].flatMap(([capability, path]) => [
+ `[capabilities.${capability}]`,
+ 'kind = "config"',
+ `path = "${path}"`,
+ 'op = "=="',
+ "value = {}",
+ ]),
+ ...[
+ ["similar_v20", "features.multi_agent_v20"],
+ ["similar_preview", "features.multi_agent_v2_preview"],
+ ].flatMap(([capability, path]) => [
+ `[capabilities.${capability}]`,
+ 'kind = "config"',
+ `path = "${path}"`,
+ 'op = "=="',
+ "value = true",
+ ]),
+ ...[
+ "available",
+ "mode",
+ "bridge",
+ "root_bridge",
+ "root_agents",
+ "root_features",
+ "v2_feature",
+ "similar_v20",
+ "similar_preview",
+ ].flatMap((profile) => [
+ `[profiles.${profile}]`,
+ `description = "${profile} capability"`,
+ `[[profiles.${profile}.requirements]]`,
+ `capability = "${profile}"`,
+ 'severity = "block"',
+ 'reason = "Required capability"',
+ ]),
+ "[profiles.root_patch]",
+ 'description = "Root runtime remediation"',
+ "[[profiles.root_patch.requirements]]",
+ 'capability = "available"',
+ 'severity = "block"',
+ 'reason = "Required capability"',
+ "[profiles.root_patch.remediation]",
+ "[[profiles.root_patch.remediation.patches]]",
+ 'path = "multiagent_config"',
+ "value = {}",
+ ].join("\n"),
+ );
+ const conflictingNative = [
+ "--registry",
+ registry,
+ "--runtime-check",
+ "available=true",
+ "--effective-config",
+ "features.multi_agent_v2.enabled=true",
+ "--effective-config",
+ "agents.max_threads=8",
+ ];
+
+ expect(runPreflight(config, "available", conflictingNative)).toMatchObject({
+ status: 0,
+ payload: { status: "ready" },
+ });
+ for (const profile of ["mode", "root_agents", "root_features"]) {
+ expect(runPreflight(config, profile, conflictingNative)).toMatchObject({
+ status: 2,
+ payload: { error: expect.stringContaining("agents.max_threads") },
+ });
+ }
+ for (const profile of [
+ "bridge",
+ "root_bridge",
+ "root_patch",
+ "v2_feature",
+ ]) {
+ expect(
+ runPreflight(config, profile, [
+ "--registry",
+ registry,
+ "--runtime-check",
+ "available=true",
+ "--effective-config",
+ "multiagent_config.max_concurrency=8",
+ ]),
+ ).toMatchObject({
+ status: 2,
+ payload: { error: expect.stringContaining("bridge ownership") },
+ });
+ }
+ for (const [profile, feature] of [
+ ["similar_v20", "features.multi_agent_v20"],
+ ["similar_preview", "features.multi_agent_v2_preview"],
+ ] as const) {
+ expect(
+ runPreflight(config, profile, [
+ "--registry",
+ registry,
+ "--effective-config",
+ `${feature}=true`,
+ "--effective-config",
+ "multiagent_config.max_concurrency=8",
+ ]),
+ ).toMatchObject({ status: 0, payload: { status: "ready" } });
+ }
+
+ for (const [version, additional] of [
+ ["v2", []],
+ ["v1", ["--effective-config", "features.multi_agent_v2.enabled=true"]],
+ ] as const) {
+ const conflictingNativeRuntime = runPreflight(
+ config,
+ "deep_security_scan",
+ [
+ "--multi-agent-runtime-owner",
+ "native",
+ "--multi-agent-runtime-version",
+ version,
+ "--multi-agent-runtime-provenance",
+ "tool-surface",
+ "--effective-config",
+ "agents.max_threads=8",
+ ...additional,
+ ],
+ );
+ expect(conflictingNativeRuntime.status).toBe(2);
+ expect(conflictingNativeRuntime.payload["error"]).toContain(
+ "agents.max_threads",
+ );
+ }
+
+ const forged = runPreflight(config, "deep_security_scan", [
+ "--multi-agent-runtime-owner",
+ "codex-bridge",
+ "--multi-agent-runtime-provenance",
+ "tool-surface",
+ ]);
+ expect(forged.status).toBe(2);
+ expect(forged.payload["error"]).toContain("verified-bridge");
+
+ const conflictingBridge = runPreflight(config, "deep_security_scan", [
+ "--multi-agent-runtime-owner",
+ "codex-bridge",
+ "--multi-agent-runtime-version",
+ "v2",
+ "--multi-agent-runtime-provenance",
+ "verified-bridge",
+ "--multi-agent-session-cap",
+ "9",
+ "--effective-config",
+ "multiagent_config.max_concurrency=8",
+ ]);
+ expect(conflictingBridge.status).toBe(2);
+ expect(conflictingBridge.payload["error"]).toContain(
+ "conflicting bridge concurrency facts",
+ );
+ });
+
test("uses a root-read filesystem profile with writable workspace and workbench state", () => {
const stateDirectory = join(tmpdir(), "codex-security-persistent-state");
const original = {