@openai/codex-security 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. package/package.json +74 -0
@@ -0,0 +1,901 @@
1
+ #!/usr/bin/env python3
2
+ """Evaluate Codex Security capability profiles against the current Codex setup."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import os
9
+ import re
10
+ import sys
11
+ from collections.abc import Iterator
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ try:
16
+ import tomllib
17
+ except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
18
+ import tomli as tomllib
19
+
20
+ PLUGIN_ROOT = Path(__file__).resolve().parents[1]
21
+ DEFAULT_REGISTRY = PLUGIN_ROOT / "preflight" / "capability-profiles.toml"
22
+ DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
23
+ SYSTEM_CONFIG = Path("/etc/codex/config.toml")
24
+ DEFAULT_CONFIG = DEFAULT_CODEX_HOME / "config.toml"
25
+ VALID_SEVERITIES = {"block", "warn", "suggest"}
26
+ VALID_MULTI_AGENT_OWNERS = {"native", "codex-bridge"}
27
+ VALID_MULTI_AGENT_VERSIONS = {"v1", "v2"}
28
+ VALID_MULTI_AGENT_PROVENANCE = {
29
+ "app-server",
30
+ "thread-context",
31
+ "tool-surface",
32
+ "verified-bridge",
33
+ }
34
+ NATIVE_V2_DEFAULT_SESSION_CAP = 4
35
+ CONFIG_PROFILE_NAME = re.compile(r"^[A-Za-z0-9_-]+$")
36
+ # Of the config roots evaluated here, only features is valid in legacy ConfigProfile.
37
+ LEGACY_CONFIG_PROFILE_CAPABILITY_FIELDS = {"features"}
38
+
39
+
40
+ def parse_args() -> argparse.Namespace:
41
+ parser = argparse.ArgumentParser(description=__doc__)
42
+ selector = parser.add_mutually_exclusive_group(required=True)
43
+ selector.add_argument("--profile", help="Capability profile id to evaluate.")
44
+ selector.add_argument(
45
+ "--skill", help="Top-level skill id to resolve through the registry routes."
46
+ )
47
+ parser.add_argument(
48
+ "--registry",
49
+ type=Path,
50
+ default=DEFAULT_REGISTRY,
51
+ help="Capability registry path. Defaults to the bundled registry.",
52
+ )
53
+ config_input = parser.add_mutually_exclusive_group()
54
+ config_input.add_argument(
55
+ "--config",
56
+ type=Path,
57
+ action="append",
58
+ help=(
59
+ "Codex config.toml layer, from lower to higher precedence. "
60
+ "Repeat to override automatic cwd-based discovery."
61
+ ),
62
+ )
63
+ parser.add_argument(
64
+ "--cwd",
65
+ type=Path,
66
+ default=Path.cwd(),
67
+ help="Working directory used to discover trusted project config layers.",
68
+ )
69
+ parser.add_argument(
70
+ "--codex-config-profile",
71
+ help="Selected Codex config profile name, when the session uses one.",
72
+ )
73
+ parser.add_argument(
74
+ "--multi-agent-runtime-owner",
75
+ choices=sorted(VALID_MULTI_AGENT_OWNERS),
76
+ help=(
77
+ "Verified owner of the active multi-agent runtime. Do not infer bridge "
78
+ "ownership from a backend_config value alone."
79
+ ),
80
+ )
81
+ parser.add_argument(
82
+ "--multi-agent-runtime-version",
83
+ choices=sorted(VALID_MULTI_AGENT_VERSIONS),
84
+ help="Version exposed by the active multi-agent tool surface.",
85
+ )
86
+ parser.add_argument(
87
+ "--multi-agent-session-cap",
88
+ type=positive_int,
89
+ help="Resolved V2 session cap from the active runtime; includes the root thread.",
90
+ )
91
+ parser.add_argument(
92
+ "--multi-agent-runtime-provenance",
93
+ choices=sorted(VALID_MULTI_AGENT_PROVENANCE),
94
+ help="Evidence source for explicitly supplied multi-agent runtime facts.",
95
+ )
96
+ parser.add_argument(
97
+ "--runtime-check",
98
+ action="append",
99
+ default=[],
100
+ metavar="NAME=BOOL",
101
+ help="Known runtime capability, such as delegation_available=true.",
102
+ )
103
+ parser.add_argument(
104
+ "--available-plugin-skill",
105
+ action="append",
106
+ metavar="SKILL_NAME",
107
+ help=(
108
+ "Plugin-local skill name exposed by the current runtime, such as "
109
+ "security-scan. Repeat only for skills from the capability's plugin."
110
+ ),
111
+ )
112
+ parser.add_argument(
113
+ "--effective-config",
114
+ action="append",
115
+ default=[],
116
+ metavar="PATH=JSON",
117
+ help="Known effective config value, such as agents.max_threads=8.",
118
+ )
119
+ return parser.parse_args()
120
+
121
+
122
+ def read_toml(path: Path, *, required: bool) -> dict[str, Any]:
123
+ try:
124
+ with path.open("rb") as file:
125
+ return tomllib.load(file)
126
+ except FileNotFoundError:
127
+ if required:
128
+ raise
129
+ return {}
130
+
131
+
132
+ def parse_bool(value: str) -> bool:
133
+ normalized = value.lower()
134
+ if normalized == "true":
135
+ return True
136
+ if normalized == "false":
137
+ return False
138
+ raise ValueError(f"expected true or false, got {value!r}")
139
+
140
+
141
+ def positive_int(value: str) -> int:
142
+ parsed = int(value)
143
+ if parsed < 1:
144
+ raise argparse.ArgumentTypeError("expected a positive integer")
145
+ return parsed
146
+
147
+
148
+ def parse_assignment(raw: str) -> tuple[str, str]:
149
+ key, separator, value = raw.partition("=")
150
+ if not separator or not key or not value:
151
+ raise ValueError(f"expected NAME=VALUE, got {raw!r}")
152
+ return key, value
153
+
154
+
155
+ def parse_runtime_checks(values: list[str]) -> dict[str, bool]:
156
+ checks: dict[str, bool] = {}
157
+ for raw in values:
158
+ key, value = parse_assignment(raw)
159
+ checks[key] = parse_bool(value)
160
+ return checks
161
+
162
+
163
+ def parse_available_plugin_skills(values: list[str] | None) -> set[str] | None:
164
+ if values is None:
165
+ return None
166
+ for value in values:
167
+ if ":" in value:
168
+ raise ValueError(
169
+ f"expected plugin-local skill name, got {value!r}; omit the plugin prefix"
170
+ )
171
+ return set(values)
172
+
173
+
174
+ def parse_effective_config(values: list[str]) -> dict[str, Any]:
175
+ config: dict[str, Any] = {}
176
+ for raw in values:
177
+ key, value = parse_assignment(raw)
178
+ try:
179
+ config[key] = json.loads(value)
180
+ except json.JSONDecodeError as error:
181
+ raise ValueError(f"expected JSON value for {key!r}, got {value!r}") from error
182
+ return config
183
+
184
+
185
+ def lookup_dotted(config: dict[str, Any], path: str) -> tuple[bool, Any]:
186
+ current: Any = config
187
+ for part in path.split("."):
188
+ if not isinstance(current, dict) or part not in current:
189
+ return False, None
190
+ current = current[part]
191
+ return True, current
192
+
193
+
194
+ def lookup_layered_value(
195
+ path: str, config_layers: list[tuple[Path, dict[str, Any]]]
196
+ ) -> tuple[bool, Any]:
197
+ for _config_path, config in reversed(config_layers):
198
+ found, actual = lookup_dotted(config, path)
199
+ if found:
200
+ return True, actual
201
+ return False, None
202
+
203
+
204
+ def iter_config_views(
205
+ config_layers: list[tuple[Path, dict[str, Any]]], config_profile: str | None
206
+ ) -> Iterator[tuple[str, dict[str, Any]]]:
207
+ for config_path, config in reversed(config_layers):
208
+ if config_profile is not None:
209
+ profiles = config.get("profiles")
210
+ if isinstance(profiles, dict):
211
+ profile_config = profiles.get(config_profile)
212
+ if isinstance(profile_config, dict):
213
+ supported_profile_config = {
214
+ key: value
215
+ for key, value in profile_config.items()
216
+ if key in LEGACY_CONFIG_PROFILE_CAPABILITY_FIELDS
217
+ }
218
+ if supported_profile_config:
219
+ yield (
220
+ f"{config_path} [profiles.{config_profile}]",
221
+ supported_profile_config,
222
+ )
223
+ yield str(config_path), config
224
+
225
+
226
+ def resolve_project_root(cwd: Path, config_layers: list[tuple[Path, dict[str, Any]]]) -> Path:
227
+ found, configured_markers = lookup_layered_value("project_root_markers", config_layers)
228
+ markers = configured_markers if found else [".git"]
229
+ if not isinstance(markers, list) or not all(isinstance(marker, str) for marker in markers):
230
+ raise ValueError("project_root_markers must be an array of strings")
231
+ if not markers:
232
+ return cwd
233
+ for candidate in (cwd, *cwd.parents):
234
+ if any((candidate / marker).exists() for marker in markers):
235
+ return candidate
236
+ return cwd
237
+
238
+
239
+ def project_trust_level(
240
+ config_layers: list[tuple[Path, dict[str, Any]]], project_root: Path
241
+ ) -> str | None:
242
+ for _path, config in reversed(config_layers):
243
+ projects = config.get("projects")
244
+ if not isinstance(projects, dict):
245
+ continue
246
+ project = projects.get(str(project_root))
247
+ if not isinstance(project, dict):
248
+ continue
249
+ trust_level = project.get("trust_level")
250
+ if isinstance(trust_level, str):
251
+ return trust_level
252
+ return None
253
+
254
+
255
+ def project_config_paths(project_root: Path, cwd: Path) -> list[Path]:
256
+ relative = cwd.relative_to(project_root)
257
+ directories = [project_root]
258
+ current = project_root
259
+ for part in relative.parts:
260
+ current /= part
261
+ directories.append(current)
262
+ return [directory / ".codex" / "config.toml" for directory in directories]
263
+
264
+
265
+ def discover_config_paths(
266
+ *, cwd: Path, profile_layer_path: Path | None
267
+ ) -> tuple[list[Path], dict[str, Any]]:
268
+ resolved_cwd = cwd.expanduser().resolve()
269
+ if not resolved_cwd.is_dir():
270
+ raise ValueError(f"cwd must be a directory, got {str(resolved_cwd)!r}")
271
+
272
+ base_paths = [SYSTEM_CONFIG, DEFAULT_CONFIG]
273
+ if profile_layer_path is not None:
274
+ base_paths.append(profile_layer_path)
275
+ base_layers = [(path, read_toml(path, required=False)) for path in base_paths]
276
+ project_root = resolve_project_root(resolved_cwd, base_layers)
277
+ trust_level = project_trust_level(base_layers, project_root)
278
+ paths = [*base_paths]
279
+ if trust_level == "trusted":
280
+ paths.extend(project_config_paths(project_root, resolved_cwd))
281
+ return paths, {
282
+ "cwd": str(resolved_cwd),
283
+ "project_root": str(project_root),
284
+ "project_trust_level": trust_level,
285
+ "project_layers_loaded": trust_level == "trusted",
286
+ }
287
+
288
+
289
+ def compare(actual: Any, op: str, expected: Any) -> bool:
290
+ if op == "==":
291
+ return actual == expected
292
+ if op == ">=":
293
+ return isinstance(actual, int) and not isinstance(actual, bool) and actual >= expected
294
+ raise ValueError(f"unsupported comparison operator: {op!r}")
295
+
296
+
297
+ def lookup_config_value(
298
+ path: str,
299
+ *,
300
+ config_layers: list[tuple[Path, dict[str, Any]]],
301
+ effective_config: dict[str, Any],
302
+ config_profile: str | None,
303
+ default: Any = None,
304
+ has_default: bool = False,
305
+ ) -> tuple[bool, Any, str | None]:
306
+ if path in effective_config:
307
+ return True, effective_config[path], "effective-config"
308
+ for source, config in iter_config_views(config_layers, config_profile):
309
+ found, actual = lookup_dotted(config, path)
310
+ if found:
311
+ return True, actual, source
312
+ if has_default:
313
+ return True, default, "documented-default"
314
+ return False, None, None
315
+
316
+
317
+ def resolve_active_config_profile(
318
+ *,
319
+ config_layers: list[tuple[Path, dict[str, Any]]],
320
+ override: str | None,
321
+ cli_profile_selected: bool,
322
+ ) -> tuple[str | None, str | None]:
323
+ if cli_profile_selected:
324
+ if override is None:
325
+ raise ValueError("CLI profile selection requires an explicit config profile name")
326
+ return override, None
327
+
328
+ if override is None:
329
+ found, configured = lookup_layered_value("profile", config_layers)
330
+ if not found:
331
+ return None, None
332
+ if not isinstance(configured, str):
333
+ raise ValueError("profile must be a string")
334
+ profile = configured
335
+ else:
336
+ profile = override
337
+
338
+ profile_values = [
339
+ config.get("profiles", {}).get(profile)
340
+ for _path, config in config_layers
341
+ if isinstance(config.get("profiles"), dict) and profile in config["profiles"]
342
+ ]
343
+ if not profile_values:
344
+ raise ValueError(f"config profile {profile!r} not found")
345
+ if any(not isinstance(value, dict) for value in profile_values):
346
+ raise ValueError(f"config profile {profile!r} must be a table")
347
+ return profile, profile
348
+
349
+
350
+ def config_profile_layer_path(profile: str | None) -> Path | None:
351
+ if profile is None:
352
+ return None
353
+ if not CONFIG_PROFILE_NAME.fullmatch(profile):
354
+ raise ValueError(
355
+ f"invalid config profile name {profile!r}; pass a plain name such as 'work'"
356
+ )
357
+ path = DEFAULT_CODEX_HOME / f"{profile}.config.toml"
358
+ return path if path.is_file() else None
359
+
360
+
361
+ def parse_multi_agent_v2_enabled(feature_config: Any) -> bool | None:
362
+ if isinstance(feature_config, bool):
363
+ return feature_config
364
+ if not isinstance(feature_config, dict):
365
+ raise ValueError("features.multi_agent_v2 must be a boolean or table")
366
+ if "enabled" not in feature_config:
367
+ return None
368
+ enabled = feature_config["enabled"]
369
+ if not isinstance(enabled, bool):
370
+ raise ValueError("features.multi_agent_v2.enabled must be a boolean")
371
+ return enabled
372
+
373
+
374
+ def merge_toml_value(base: Any, overlay: Any) -> Any:
375
+ if isinstance(base, dict) and isinstance(overlay, dict):
376
+ merged = dict(base)
377
+ for key, value in overlay.items():
378
+ merged[key] = merge_toml_value(merged[key], value) if key in merged else value
379
+ return merged
380
+ return overlay
381
+
382
+
383
+ def lookup_multi_agent_v2_enabled(
384
+ *,
385
+ config_layers: list[tuple[Path, dict[str, Any]]],
386
+ effective_config: dict[str, Any],
387
+ config_profile: str | None,
388
+ ) -> tuple[bool, bool | None, str | None]:
389
+ if "features.multi_agent_v2.enabled" in effective_config:
390
+ enabled = effective_config["features.multi_agent_v2.enabled"]
391
+ if not isinstance(enabled, bool):
392
+ raise ValueError("features.multi_agent_v2.enabled must be a boolean")
393
+ return True, enabled, "effective-config"
394
+
395
+ v2_configs = []
396
+ config_views = list(iter_config_views(config_layers, config_profile))
397
+ for source, config in reversed(config_views):
398
+ found, feature_config = lookup_dotted(config, "features.multi_agent_v2")
399
+ if found:
400
+ v2_configs.append((source, feature_config))
401
+
402
+ if "features.multi_agent_v2" in effective_config:
403
+ v2_configs.append(("effective-config", effective_config["features.multi_agent_v2"]))
404
+
405
+ if not v2_configs:
406
+ return False, None, None
407
+
408
+ merged_v2_config: Any = None
409
+ enabled_source: str | None = None
410
+ for index, (source, feature_config) in enumerate(v2_configs):
411
+ tables_merge = isinstance(merged_v2_config, dict) and isinstance(feature_config, dict)
412
+ if index and not tables_merge:
413
+ enabled_source = None
414
+ merged_v2_config = (
415
+ merge_toml_value(merged_v2_config, feature_config) if index else feature_config
416
+ )
417
+ if isinstance(feature_config, bool) or (
418
+ isinstance(feature_config, dict) and "enabled" in feature_config
419
+ ):
420
+ enabled_source = source
421
+
422
+ enabled = parse_multi_agent_v2_enabled(merged_v2_config)
423
+ return (
424
+ (True, enabled, enabled_source)
425
+ if enabled is not None
426
+ else (True, False, "documented-default")
427
+ )
428
+
429
+
430
+ def resolve_multi_agent_context(
431
+ *,
432
+ config_layers: list[tuple[Path, dict[str, Any]]],
433
+ effective_config: dict[str, Any],
434
+ config_profile: str | None,
435
+ runtime_owner: str | None,
436
+ runtime_version: str | None,
437
+ runtime_session_cap: int | None,
438
+ runtime_provenance: str | None,
439
+ ) -> dict[str, Any]:
440
+ runtime_facts_supplied = any(
441
+ value is not None for value in (runtime_owner, runtime_version, runtime_session_cap)
442
+ )
443
+ if runtime_facts_supplied and runtime_provenance is None:
444
+ raise ValueError(
445
+ "explicit multi-agent runtime facts require --multi-agent-runtime-provenance"
446
+ )
447
+ if runtime_provenance is not None and not runtime_facts_supplied:
448
+ raise ValueError(
449
+ "--multi-agent-runtime-provenance requires an explicit runtime owner, version, or cap"
450
+ )
451
+ if runtime_owner == "codex-bridge" and runtime_provenance != "verified-bridge":
452
+ raise ValueError(
453
+ "codex-bridge ownership requires --multi-agent-runtime-provenance verified-bridge"
454
+ )
455
+ if runtime_owner == "native" and runtime_provenance == "verified-bridge":
456
+ raise ValueError("native ownership cannot use verified-bridge provenance")
457
+
458
+ feature_found, enabled, feature_source = lookup_multi_agent_v2_enabled(
459
+ config_layers=config_layers,
460
+ effective_config=effective_config,
461
+ config_profile=config_profile,
462
+ )
463
+
464
+ if runtime_version is not None:
465
+ version = runtime_version
466
+ version_source = "runtime-fact"
467
+ elif feature_found:
468
+ version = "v2" if enabled else "v1"
469
+ version_source = feature_source
470
+ elif runtime_owner == "codex-bridge":
471
+ version = "v2"
472
+ version_source = "runtime-owner"
473
+ else:
474
+ version = "unknown"
475
+ version_source = None
476
+
477
+ if runtime_owner is not None:
478
+ owner = runtime_owner
479
+ owner_source = "runtime-fact"
480
+ elif feature_found:
481
+ owner = "native"
482
+ owner_source = feature_source
483
+ else:
484
+ owner = "unknown"
485
+ owner_source = None
486
+
487
+ if owner == "codex-bridge" and version != "v2":
488
+ raise ValueError("codex-bridge ownership requires multi-agent runtime version v2")
489
+ if runtime_session_cap is not None and version != "v2":
490
+ raise ValueError("--multi-agent-session-cap is valid only for a V2 runtime")
491
+
492
+ bridge_cap_found, bridge_cap, bridge_cap_source = lookup_config_value(
493
+ "multiagent_config.max_concurrency",
494
+ config_layers=config_layers,
495
+ effective_config=effective_config,
496
+ config_profile=config_profile,
497
+ )
498
+ if bridge_cap_found and owner != "codex-bridge":
499
+ raise ValueError(
500
+ "multiagent_config.max_concurrency does not prove bridge ownership; "
501
+ "pass --multi-agent-runtime-owner codex-bridge only when the active runtime "
502
+ "is verified as bridge-managed"
503
+ )
504
+ if bridge_cap_found and runtime_session_cap is not None and bridge_cap != runtime_session_cap:
505
+ raise ValueError(
506
+ "conflicting bridge concurrency facts: multiagent_config.max_concurrency "
507
+ f"from {bridge_cap_source} is {bridge_cap!r}, but --multi-agent-session-cap is "
508
+ f"{runtime_session_cap!r}"
509
+ )
510
+
511
+ agent_threads_found, agent_threads, agent_threads_source = lookup_config_value(
512
+ "agents.max_threads",
513
+ config_layers=config_layers,
514
+ effective_config=effective_config,
515
+ config_profile=config_profile,
516
+ )
517
+ if owner != "codex-bridge" and feature_found and enabled and agent_threads_found:
518
+ raise ValueError("agents.max_threads cannot be set when multi_agent_v2 is enabled")
519
+
520
+ if version == "v1":
521
+ mode = "v1"
522
+ elif version == "v2" and owner == "codex-bridge":
523
+ mode = "bridge-v2"
524
+ elif version == "v2" and owner == "native":
525
+ mode = "v2"
526
+ else:
527
+ mode = "unknown"
528
+ return {
529
+ "mode": mode,
530
+ "owner": owner,
531
+ "owner_source": owner_source,
532
+ "version": version,
533
+ "version_source": version_source,
534
+ "runtime_provenance": runtime_provenance,
535
+ "config_v2_enabled": feature_found and bool(enabled),
536
+ "agent_max_threads_configured": agent_threads_found,
537
+ "agent_max_threads": agent_threads if agent_threads_found else None,
538
+ "agent_max_threads_source": agent_threads_source if agent_threads_found else None,
539
+ }
540
+
541
+
542
+ def evaluate_multi_agent_capacity(
543
+ result: dict[str, Any],
544
+ capability: dict[str, Any],
545
+ *,
546
+ config_layers: list[tuple[Path, dict[str, Any]]],
547
+ effective_config: dict[str, Any],
548
+ config_profile: str | None,
549
+ multi_agent_context: dict[str, Any],
550
+ runtime_session_cap: int | None,
551
+ ) -> dict[str, Any]:
552
+ multi_agent_mode = str(multi_agent_context["mode"])
553
+ if multi_agent_mode == "unknown":
554
+ return {**result, "status": "unknown", "check": "active_multi_agent_mode"}
555
+
556
+ if multi_agent_mode == "v1":
557
+ path = "agents.max_threads"
558
+ found, actual, source = lookup_config_value(
559
+ path,
560
+ config_layers=config_layers,
561
+ effective_config=effective_config,
562
+ config_profile=config_profile,
563
+ default=capability.get("v1_default"),
564
+ has_default="v1_default" in capability,
565
+ )
566
+ worker_slots = actual
567
+ else:
568
+ if runtime_session_cap is not None:
569
+ path = "runtime.multi_agent.session_cap"
570
+ found, actual, source = True, runtime_session_cap, "runtime-fact"
571
+ elif multi_agent_context["owner"] == "codex-bridge":
572
+ path = "multiagent_config.max_concurrency"
573
+ found, actual, source = lookup_config_value(
574
+ path,
575
+ config_layers=config_layers,
576
+ effective_config=effective_config,
577
+ config_profile=config_profile,
578
+ )
579
+ elif multi_agent_context["owner"] == "native" and multi_agent_context["config_v2_enabled"]:
580
+ path = "features.multi_agent_v2.max_concurrent_threads_per_session"
581
+ found, actual, source = lookup_config_value(
582
+ path,
583
+ config_layers=config_layers,
584
+ effective_config=effective_config,
585
+ config_profile=config_profile,
586
+ default=NATIVE_V2_DEFAULT_SESSION_CAP,
587
+ has_default=True,
588
+ )
589
+ else:
590
+ path = "runtime.multi_agent.session_cap"
591
+ found, actual, source = False, None, None
592
+ worker_slots = (
593
+ actual - 1 if isinstance(actual, int) and not isinstance(actual, bool) else actual
594
+ )
595
+
596
+ if not found:
597
+ return {**result, "status": "unknown", "path": path, "multi_agent_mode": multi_agent_mode}
598
+ return {
599
+ **result,
600
+ "status": "pass"
601
+ if compare(worker_slots, capability["op"], capability["value"])
602
+ else "fail",
603
+ "path": path,
604
+ "actual": worker_slots,
605
+ "configured_value": actual,
606
+ "expected": {"op": capability["op"], "value": capability["value"]},
607
+ "source": source,
608
+ "multi_agent_mode": multi_agent_mode,
609
+ }
610
+
611
+
612
+ def resolve_profile(registry: dict[str, Any], *, profile: str | None, skill: str | None) -> str:
613
+ if profile:
614
+ return profile
615
+ routes = {route["skill"]: route["profile"] for route in registry["routes"]}
616
+ try:
617
+ return routes[str(skill)]
618
+ except KeyError as error:
619
+ raise ValueError(f"no capability profile route for skill {skill!r}") from error
620
+
621
+
622
+ def evaluate_requirement(
623
+ requirement: dict[str, Any],
624
+ *,
625
+ capabilities: dict[str, dict[str, Any]],
626
+ config_layers: list[tuple[Path, dict[str, Any]]],
627
+ effective_config: dict[str, Any],
628
+ config_profile: str | None,
629
+ runtime_checks: dict[str, bool],
630
+ available_plugin_skills: set[str] | None,
631
+ multi_agent_context: dict[str, Any],
632
+ runtime_session_cap: int | None,
633
+ ) -> dict[str, Any]:
634
+ capability_id = requirement["capability"]
635
+ capability = capabilities[capability_id]
636
+ result = {
637
+ "capability": capability_id,
638
+ "severity": requirement["severity"],
639
+ "reason": requirement["reason"],
640
+ }
641
+
642
+ if capability["kind"] == "runtime":
643
+ check = capability["check"]
644
+ if check not in runtime_checks:
645
+ return {**result, "status": "unknown", "check": check}
646
+ actual = runtime_checks[check]
647
+ return {**result, "status": "pass" if actual else "fail", "actual": actual, "check": check}
648
+
649
+ if capability["kind"] == "multi_agent_mode":
650
+ actual = {
651
+ "owner": multi_agent_context["owner"],
652
+ "version": multi_agent_context["version"],
653
+ }
654
+ expected = {
655
+ "owner": capability["owner"],
656
+ "version": capability["version"],
657
+ }
658
+ if "unknown" in actual.values():
659
+ return {
660
+ **result,
661
+ "status": "unknown",
662
+ "check": "active_multi_agent_mode",
663
+ "actual": actual,
664
+ "expected": expected,
665
+ }
666
+ return {
667
+ **result,
668
+ "status": "pass" if actual == expected else "fail",
669
+ "actual": actual,
670
+ "expected": expected,
671
+ }
672
+
673
+ if capability["kind"] == "plugin_skills":
674
+ required = capability["required"]
675
+ required_skill_ids = [f"{capability['plugin']}:{skill}" for skill in required]
676
+ if available_plugin_skills is None:
677
+ return {
678
+ **result,
679
+ "status": "unknown",
680
+ "check": "available_plugin_skills",
681
+ "required": required_skill_ids,
682
+ }
683
+ unavailable = [
684
+ f"{capability['plugin']}:{skill}"
685
+ for skill in required
686
+ if skill not in available_plugin_skills
687
+ ]
688
+ return {
689
+ **result,
690
+ "status": "fail" if unavailable else "pass",
691
+ "unavailable": unavailable,
692
+ "required": required_skill_ids,
693
+ }
694
+
695
+ if capability["kind"] == "multi_agent_capacity":
696
+ return evaluate_multi_agent_capacity(
697
+ result,
698
+ capability,
699
+ config_layers=config_layers,
700
+ effective_config=effective_config,
701
+ config_profile=config_profile,
702
+ multi_agent_context=multi_agent_context,
703
+ runtime_session_cap=runtime_session_cap,
704
+ )
705
+
706
+ if capability["kind"] == "config_absent":
707
+ path = capability["path"]
708
+ found, actual, source = lookup_config_value(
709
+ path,
710
+ config_layers=config_layers,
711
+ effective_config=effective_config,
712
+ config_profile=config_profile,
713
+ )
714
+ if not found:
715
+ return {**result, "status": "pass", "path": path, "expected": "unset"}
716
+ return {
717
+ **result,
718
+ "status": "fail",
719
+ "path": path,
720
+ "actual": actual,
721
+ "expected": "unset",
722
+ "source": source,
723
+ }
724
+
725
+ path = capability["path"]
726
+ found, actual, source = lookup_config_value(
727
+ path,
728
+ config_layers=config_layers,
729
+ effective_config=effective_config,
730
+ config_profile=config_profile,
731
+ default=capability.get("default"),
732
+ has_default="default" in capability,
733
+ )
734
+ if not found:
735
+ return {**result, "status": "unknown", "path": path}
736
+ return {
737
+ **result,
738
+ "status": "pass" if compare(actual, capability["op"], capability["value"]) else "fail",
739
+ "path": path,
740
+ "actual": actual,
741
+ "expected": {"op": capability["op"], "value": capability["value"]},
742
+ "source": source,
743
+ }
744
+
745
+
746
+ def validate_registry(registry: dict[str, Any]) -> None:
747
+ capabilities = registry["capabilities"]
748
+ profiles = registry["profiles"]
749
+ for profile_id, profile in profiles.items():
750
+ for requirement in profile["requirements"]:
751
+ if requirement["capability"] not in capabilities:
752
+ raise ValueError(
753
+ f"profile {profile_id!r} references unknown capability {requirement['capability']!r}"
754
+ )
755
+ if requirement["severity"] not in VALID_SEVERITIES:
756
+ raise ValueError(
757
+ f"profile {profile_id!r} has unsupported severity {requirement['severity']!r}"
758
+ )
759
+
760
+
761
+ def resolve_remediation(
762
+ profile: dict[str, Any], *, multi_agent_context: dict[str, Any]
763
+ ) -> dict[str, Any]:
764
+ multi_agent_mode = str(multi_agent_context["mode"])
765
+ remediation = dict(profile.get("remediation", {}))
766
+ variants = remediation.pop("variants", [])
767
+ remediation["multi_agent_mode"] = multi_agent_mode
768
+ for variant in variants:
769
+ if variant["mode"] == multi_agent_mode:
770
+ if multi_agent_mode == "v2" and multi_agent_context["owner"] != "native":
771
+ break
772
+ variant_patches = variant.get("patches", [])
773
+ if multi_agent_mode == "v2" and not multi_agent_context["agent_max_threads_configured"]:
774
+ variant_patches = [
775
+ patch
776
+ for patch in variant_patches
777
+ if not (
778
+ patch.get("kind") == "remove" and patch.get("path") == "agents.max_threads"
779
+ )
780
+ ]
781
+ remediation["patches"] = remediation.get("patches", []) + variant_patches
782
+ return remediation
783
+ if variants:
784
+ remediation["note"] = (
785
+ "Do not apply a concurrency patch until the active runtime version and config "
786
+ "ownership are known."
787
+ )
788
+ return remediation
789
+
790
+
791
+ def evaluate(args: argparse.Namespace) -> dict[str, Any]:
792
+ registry = read_toml(args.registry, required=True)
793
+ validate_registry(registry)
794
+ profile_id = resolve_profile(registry, profile=args.profile, skill=args.skill)
795
+ try:
796
+ profile = registry["profiles"][profile_id]
797
+ except KeyError as error:
798
+ raise ValueError(f"unknown capability profile: {profile_id!r}") from error
799
+
800
+ cli_profile_selected = args.codex_config_profile is not None
801
+ if args.config:
802
+ config_paths = args.config
803
+ config_discovery = None
804
+ config_resolution = "manual-layers"
805
+ project_config_paths_set: set[Path] = set()
806
+ profile_layer_path = None
807
+ else:
808
+ profile_layer_path = config_profile_layer_path(args.codex_config_profile)
809
+ config_paths, config_discovery = discover_config_paths(
810
+ cwd=args.cwd,
811
+ profile_layer_path=profile_layer_path,
812
+ )
813
+ config_resolution = "cwd-discovery"
814
+ project_config_paths_set = set(config_paths[3 if profile_layer_path else 2 :])
815
+ config_layers = []
816
+ for path in config_paths:
817
+ config = read_toml(path, required=False)
818
+ if path in project_config_paths_set:
819
+ # Codex strips project-local profile selection and definitions before
820
+ # resolving the merged config. Mirror that denylist here.
821
+ config = dict(config)
822
+ config.pop("profile", None)
823
+ config.pop("profiles", None)
824
+ config_layers.append((path, config))
825
+ config_profile, embedded_config_profile = resolve_active_config_profile(
826
+ config_layers=config_layers,
827
+ override=args.codex_config_profile,
828
+ cli_profile_selected=cli_profile_selected,
829
+ )
830
+ runtime_checks = parse_runtime_checks(args.runtime_check)
831
+ available_plugin_skills = parse_available_plugin_skills(args.available_plugin_skill)
832
+ effective_config = parse_effective_config(args.effective_config)
833
+ multi_agent_context = resolve_multi_agent_context(
834
+ config_layers=config_layers,
835
+ effective_config=effective_config,
836
+ config_profile=embedded_config_profile,
837
+ runtime_owner=args.multi_agent_runtime_owner,
838
+ runtime_version=args.multi_agent_runtime_version,
839
+ runtime_session_cap=args.multi_agent_session_cap,
840
+ runtime_provenance=args.multi_agent_runtime_provenance,
841
+ )
842
+ results = [
843
+ evaluate_requirement(
844
+ requirement,
845
+ capabilities=registry["capabilities"],
846
+ config_layers=config_layers,
847
+ effective_config=effective_config,
848
+ runtime_checks=runtime_checks,
849
+ available_plugin_skills=available_plugin_skills,
850
+ config_profile=embedded_config_profile,
851
+ multi_agent_context=multi_agent_context,
852
+ runtime_session_cap=args.multi_agent_session_cap,
853
+ )
854
+ for requirement in profile["requirements"]
855
+ if not requirement.get("modes") or multi_agent_context["mode"] in requirement["modes"]
856
+ ]
857
+ failed = [result for result in results if result["status"] == "fail"]
858
+ unknown = [result for result in results if result["status"] == "unknown"]
859
+ if any(result["severity"] == "block" for result in failed):
860
+ status = "blocked"
861
+ elif unknown:
862
+ status = "incomplete"
863
+ else:
864
+ status = "ready"
865
+ return {
866
+ "version": registry["version"],
867
+ "profile": profile_id,
868
+ "description": profile["description"],
869
+ "config_resolution": config_resolution,
870
+ "user_config_path": None if args.config else str(profile_layer_path or DEFAULT_CONFIG),
871
+ "config_paths": [str(path) for path in config_paths],
872
+ "config_discovery": config_discovery,
873
+ "config_profile": config_profile,
874
+ "config_profile_path": str(profile_layer_path) if profile_layer_path else None,
875
+ "multi_agent_mode": multi_agent_context["mode"],
876
+ "multi_agent_context": multi_agent_context,
877
+ "status": status,
878
+ "results": results,
879
+ "failed": failed,
880
+ "unknown": unknown,
881
+ "remediation": resolve_remediation(
882
+ profile,
883
+ multi_agent_context=multi_agent_context,
884
+ ),
885
+ }
886
+
887
+
888
+ def main() -> int:
889
+ try:
890
+ payload = evaluate(parse_args())
891
+ except (KeyError, OSError, TypeError, ValueError, tomllib.TOMLDecodeError) as error:
892
+ print(json.dumps({"status": "error", "error": str(error)}, indent=2, sort_keys=True))
893
+ return 2
894
+ print(json.dumps(payload, indent=2, sort_keys=True))
895
+ if payload["status"] == "blocked":
896
+ return 1
897
+ return 2 if payload["status"] == "incomplete" else 0
898
+
899
+
900
+ if __name__ == "__main__":
901
+ sys.exit(main())