@openai/codex-security 0.4.0 → 0.5.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.
- package/README.md +45 -9
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/references/core-scan.md +2 -0
- package/_bundled_plugin/references/final-report.md +5 -1
- package/_bundled_plugin/references/investigation-time-budget.md +11 -0
- package/_bundled_plugin/references/sarif-adapter.md +1 -0
- package/_bundled_plugin/references/scan-prologue.md +2 -6
- package/_bundled_plugin/references/scan-runtime.md +15 -0
- package/_bundled_plugin/references/threat-model.md +2 -0
- package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +5 -1
- package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +80 -43
- package/_bundled_plugin/scripts/finding_preview.py +5 -3
- package/_bundled_plugin/scripts/generate_rank_input.py +1 -0
- package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
- package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
- package/_bundled_plugin/scripts/workbench_cli.py +0 -3
- package/_bundled_plugin/scripts/workbench_constants.py +4 -0
- package/_bundled_plugin/scripts/workbench_db.py +56 -33
- package/_bundled_plugin/scripts/workbench_progress.py +0 -50
- package/_bundled_plugin/scripts/workbench_scan_history.py +3 -2
- package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
- package/_bundled_plugin/scripts/workbench_scan_usage.py +190 -30
- package/_bundled_plugin/scripts/workbench_schema.py +1 -1
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
- package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
- package/_bundled_plugin/scripts/workbench_target.py +7 -5
- package/_bundled_plugin/scripts/workbench_validation.py +37 -1
- package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
- package/_bundled_plugin/shared/workbench-migrations.json +5 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
- package/_bundled_plugin/skills/security-scan/SKILL.md +3 -1
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
- package/dist/api.d.ts +3 -2
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +54 -36
- package/dist/api.js.map +1 -1
- package/dist/artifact-export.d.ts +2 -1
- package/dist/artifact-export.d.ts.map +1 -1
- package/dist/artifact-export.js +38 -23
- package/dist/artifact-export.js.map +1 -1
- package/dist/classify-severity-records.d.ts +76 -0
- package/dist/classify-severity-records.d.ts.map +1 -0
- package/dist/classify-severity-records.js +141 -0
- package/dist/classify-severity-records.js.map +1 -0
- package/dist/classify-severity.d.ts +1 -23
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +3 -24
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +2 -0
- package/dist/cli-help.js.map +1 -1
- package/dist/cli.d.ts +4 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +136 -147
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js +1 -1
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-sdk-environment.js +1 -1
- package/dist/codex-sdk-environment.js.map +1 -1
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +10 -4
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts +5 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +65 -17
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +7 -2
- package/dist/cost-model.js.map +1 -1
- package/dist/custom-validation-prompt.js +3 -3
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +2 -2
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/records.js +1 -1
- package/dist/deduplication/records.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +10 -9
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-config.d.ts +4 -1
- package/dist/deep-config.d.ts.map +1 -1
- package/dist/deep-config.js +21 -1
- package/dist/deep-config.js.map +1 -1
- package/dist/findings-import.d.ts +1 -1
- package/dist/findings-import.d.ts.map +1 -1
- package/dist/findings-import.js +3 -3
- package/dist/findings-import.js.map +1 -1
- package/dist/git-remote.d.ts +10 -0
- package/dist/git-remote.d.ts.map +1 -0
- package/dist/git-remote.js +24 -0
- package/dist/git-remote.js.map +1 -0
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js +5 -7
- package/dist/github.js.map +1 -1
- package/dist/host-protocol.js +1 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +15 -0
- package/dist/host-records-protocol.d.ts.map +1 -0
- package/dist/host-records-protocol.js +15 -0
- package/dist/host-records-protocol.js.map +1 -0
- package/dist/hosted-scan.d.ts +1 -6
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +2 -2
- package/dist/hosted-scan.js.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +87 -7
- package/dist/knowledge-base.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +62 -28
- package/dist/multiscan.js.map +1 -1
- package/dist/patch-publication.d.ts +26 -0
- package/dist/patch-publication.d.ts.map +1 -0
- package/dist/patch-publication.js +105 -0
- package/dist/patch-publication.js.map +1 -0
- package/dist/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +4 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +16 -6
- package/dist/project-config.js.map +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +135 -19
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +39 -25
- package/dist/publish.js.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +83 -22
- package/dist/runtime.js.map +1 -1
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +7 -1
- package/dist/scan-settings.js.map +1 -1
- package/dist/scan-time-budget.d.ts +9 -0
- package/dist/scan-time-budget.d.ts.map +1 -0
- package/dist/scan-time-budget.js +16 -0
- package/dist/scan-time-budget.js.map +1 -0
- package/dist/severity-review.d.ts +29 -0
- package/dist/severity-review.d.ts.map +1 -0
- package/dist/severity-review.js +47 -0
- package/dist/severity-review.js.map +1 -0
- package/dist/validation-records.d.ts +38 -0
- package/dist/validation-records.d.ts.map +1 -0
- package/dist/validation-records.js +76 -0
- package/dist/validation-records.js.map +1 -0
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +4 -2
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts +2 -6
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +1 -43
- package/dist/worker-progress.js.map +1 -1
- package/docs/classify-severity-records.md +89 -0
- package/docs/cli.md +269 -33
- package/docs/validate-records.md +69 -0
- package/package.json +12 -10
- package/schemas/project-config.schema.json +7 -1
- package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
- package/_bundled_plugin/references/config-preflight.md +0 -93
- package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
- package/_bundled_plugin/scripts/config_preflight.py +0 -911
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@openai/codex-security",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "TypeScript SDK and CLI for Codex Security",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "OpenAI",
|
|
@@ -45,7 +45,9 @@
|
|
|
45
45
|
"docs/cli.md",
|
|
46
46
|
"docs/findings-service.md",
|
|
47
47
|
"docs/dedupe-records.md",
|
|
48
|
-
"docs/
|
|
48
|
+
"docs/classify-severity-records.md",
|
|
49
|
+
"docs/hosted-scans.md",
|
|
50
|
+
"docs/validate-records.md"
|
|
49
51
|
],
|
|
50
52
|
"publishConfig": {
|
|
51
53
|
"access": "public",
|
|
@@ -67,18 +69,19 @@
|
|
|
67
69
|
"papaparse": "5.7.0",
|
|
68
70
|
"pdfjs-dist": "6.4.299",
|
|
69
71
|
"react": "19.3.0",
|
|
72
|
+
"saxes": "6.0.0",
|
|
70
73
|
"semver": "7.8.5",
|
|
71
|
-
"smol-toml": "1.9.
|
|
74
|
+
"smol-toml": "1.9.1",
|
|
72
75
|
"string-width": "8.3.0",
|
|
73
76
|
"strip-ansi": "7.2.0",
|
|
74
77
|
"yaml": "2.9.1",
|
|
75
78
|
"yauzl": "3.4.0",
|
|
76
|
-
"zod": "4.6.
|
|
79
|
+
"zod": "4.6.6"
|
|
77
80
|
},
|
|
78
81
|
"devDependencies": {
|
|
79
82
|
"@stryker-mutator/core": "10.0.0",
|
|
80
|
-
"@types/bun": "1.4.
|
|
81
|
-
"@types/node": "26.6.
|
|
83
|
+
"@types/bun": "1.4.3",
|
|
84
|
+
"@types/node": "26.6.5",
|
|
82
85
|
"@types/papaparse": "5.5.2",
|
|
83
86
|
"@types/react": "19.3.0",
|
|
84
87
|
"@types/semver": "7.8.0",
|
|
@@ -89,11 +92,10 @@
|
|
|
89
92
|
"json-schema-to-typescript": "16.0.0",
|
|
90
93
|
"json5": "2.2.3",
|
|
91
94
|
"minimatch": "10.2.6",
|
|
92
|
-
"prettier": "3.9.
|
|
93
|
-
"saxes": "6.0.0",
|
|
95
|
+
"prettier": "3.9.10",
|
|
94
96
|
"typescript": "7.0.2"
|
|
95
97
|
},
|
|
96
|
-
"gitHead": "
|
|
98
|
+
"gitHead": "03414ad84e91a8638bde85af08c47fe957dc9323",
|
|
97
99
|
"scripts": {
|
|
98
100
|
"audit:prod": "pnpm audit --prod --audit-level high",
|
|
99
101
|
"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
@@ -104,7 +106,7 @@
|
|
|
104
106
|
"build:plugin": "node scripts/build-plugin.mjs",
|
|
105
107
|
"check:plugin-source": "node scripts/check-plugin-source.mjs",
|
|
106
108
|
"check:package": "node scripts/check-package.mjs",
|
|
107
|
-
"format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json}\" \"../../.github/scripts/*.mts\" \"../../examples/custom-validation/*.mts\" \"../../plugins/codex-security/native/*.mts\" \"../../evals/{deep-reducer,secret-discovery}/*.mts\" \"../../evals/triage-finding/{assertions,scripts,sastbench/assertions,sastbench/scripts}/*.mts\" \"../../evals/triage-finding/types.ts\" \"../../evals/tsconfig.json\" && node scripts/check-markdown.mjs",
|
|
109
|
+
"format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json}\" \"../../.github/scripts/*.mts\" \"../../examples/custom-validation/*.mts\" \"../../plugins/codex-security/native/*.mts\" \"../../evals/{deep-reducer,secret-discovery,workflow-routing}/*.mts\" \"../../evals/triage-finding/{assertions,scripts,sastbench/assertions,sastbench/scripts}/*.mts\" \"../../evals/triage-finding/types.ts\" \"../../evals/tsconfig.json\" && node scripts/check-markdown.mjs",
|
|
108
110
|
"generate:models": "node scripts/generate-models.cjs",
|
|
109
111
|
"generate:models:check": "node scripts/generate-models.cjs --check",
|
|
110
112
|
"lint": "tsc --noEmit",
|
|
@@ -21,6 +21,11 @@
|
|
|
21
21
|
"type": "string",
|
|
22
22
|
"enum": ["standard", "deep"]
|
|
23
23
|
},
|
|
24
|
+
"max_time_minutes": {
|
|
25
|
+
"description": "Investigation minutes: advisory in Standard (default: unset); enforced Deep discovery limit (default and maximum: 5760). Scans may finish early; reporting may run longer.",
|
|
26
|
+
"type": "number",
|
|
27
|
+
"exclusiveMinimum": 0
|
|
28
|
+
},
|
|
24
29
|
"cyber_access_program": {
|
|
25
30
|
"description": "Experimental Cyber access program for scan turns (OpenAI provider only). Omit to preserve Codex defaults.",
|
|
26
31
|
"type": "string",
|
|
@@ -138,7 +143,8 @@
|
|
|
138
143
|
},
|
|
139
144
|
"max_time_hours": {
|
|
140
145
|
"default": 96,
|
|
141
|
-
"
|
|
146
|
+
"deprecated": true,
|
|
147
|
+
"description": "Deprecated Deep-only alias for maxTimeMinutes / --max-time, in hours (default: 96; maximum: 96).",
|
|
142
148
|
"type": "number",
|
|
143
149
|
"exclusiveMinimum": 0,
|
|
144
150
|
"maximum": 96
|
|
@@ -1,76 +0,0 @@
|
|
|
1
|
-
version = 1
|
|
2
|
-
|
|
3
|
-
[capabilities.delegated_workers]
|
|
4
|
-
kind = "runtime"
|
|
5
|
-
check = "delegation_available"
|
|
6
|
-
|
|
7
|
-
[capabilities.goal_tools]
|
|
8
|
-
kind = "runtime"
|
|
9
|
-
check = "goal_tools_available"
|
|
10
|
-
|
|
11
|
-
[capabilities.usable_worker_slots_6]
|
|
12
|
-
kind = "multi_agent_capacity"
|
|
13
|
-
op = ">="
|
|
14
|
-
value = 6
|
|
15
|
-
v1_default = 6
|
|
16
|
-
|
|
17
|
-
[capabilities.goals_enabled]
|
|
18
|
-
kind = "config"
|
|
19
|
-
path = "features.goals"
|
|
20
|
-
op = "=="
|
|
21
|
-
value = true
|
|
22
|
-
default = true
|
|
23
|
-
|
|
24
|
-
[profiles.security_diff_scan]
|
|
25
|
-
description = "Capabilities for Git-backed Codex Security diff scans."
|
|
26
|
-
|
|
27
|
-
[[profiles.security_diff_scan.requirements]]
|
|
28
|
-
capability = "delegated_workers"
|
|
29
|
-
severity = "warn"
|
|
30
|
-
reason = "Large diff scans may use discovery workers when available; otherwise the parent reviews every changed file."
|
|
31
|
-
|
|
32
|
-
[[profiles.security_diff_scan.requirements]]
|
|
33
|
-
capability = "goal_tools"
|
|
34
|
-
severity = "suggest"
|
|
35
|
-
reason = "Goal tools help long diff scans preserve completion criteria across many steps."
|
|
36
|
-
|
|
37
|
-
[[profiles.security_diff_scan.requirements]]
|
|
38
|
-
capability = "goals_enabled"
|
|
39
|
-
severity = "suggest"
|
|
40
|
-
reason = "Enabling goals makes long diff scans easier to resume and audit."
|
|
41
|
-
|
|
42
|
-
[profiles.security_scan]
|
|
43
|
-
description = "Capabilities for repository-wide or scoped-path Codex Security scans."
|
|
44
|
-
|
|
45
|
-
[[profiles.security_scan.requirements]]
|
|
46
|
-
capability = "delegated_workers"
|
|
47
|
-
severity = "warn"
|
|
48
|
-
reason = "Standard scans use an independent baseline auditor and focused investigation workers when delegation is available."
|
|
49
|
-
|
|
50
|
-
[[profiles.security_scan.requirements]]
|
|
51
|
-
capability = "usable_worker_slots_6"
|
|
52
|
-
severity = "warn"
|
|
53
|
-
reason = "A six-thread cap provides room for an independent baseline and parallel investigators; it does not require six running workers."
|
|
54
|
-
|
|
55
|
-
[profiles.deep_security_scan]
|
|
56
|
-
description = "Capabilities for deep repository-wide Codex Security scans."
|
|
57
|
-
requirements = []
|
|
58
|
-
|
|
59
|
-
[profiles.security_diff_scan.remediation]
|
|
60
|
-
summary = "Recommended Codex config for longer diff scans."
|
|
61
|
-
|
|
62
|
-
[[profiles.security_diff_scan.remediation.patches]]
|
|
63
|
-
path = "features.goals"
|
|
64
|
-
value = true
|
|
65
|
-
|
|
66
|
-
[[routes]]
|
|
67
|
-
skill = "security-diff-scan"
|
|
68
|
-
profile = "security_diff_scan"
|
|
69
|
-
|
|
70
|
-
[[routes]]
|
|
71
|
-
skill = "security-scan"
|
|
72
|
-
profile = "security_scan"
|
|
73
|
-
|
|
74
|
-
[[routes]]
|
|
75
|
-
skill = "deep-security-scan"
|
|
76
|
-
profile = "deep_security_scan"
|
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
# Codex Security Config Preflight
|
|
2
|
-
|
|
3
|
-
Codex Security Standard and diff scan skills should run the read-only helper before substantive scan work. Deep scans have no parent capability requirements and do not run this helper.
|
|
4
|
-
|
|
5
|
-
The top-level parent reads `artifact-storage.md` once before preflight and follows its scan-ownership rules, including for terminal Diff scans.
|
|
6
|
-
|
|
7
|
-
Load `desktop-config-preflight.md` only after the host explicitly identifies itself as the Codex desktop app.
|
|
8
|
-
|
|
9
|
-
Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts. Before constructing the first helper command, inspect the current tool surface once and use that discovery result for both the runtime checks and `<verified-multi-agent-runtime-arguments>`. Do not omit active runtime facts from the first invocation and wait for an `incomplete` result before supplying them. The command is written on one line so it works in PowerShell, Command Prompt, and POSIX shells:
|
|
10
|
-
|
|
11
|
-
```text
|
|
12
|
-
<python_command> <plugin_dir>/scripts/config_preflight.py --profile <capability-profile> --cwd <scan-working-directory> --runtime-check delegation_available=<true|false> <verified-multi-agent-runtime-arguments>
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Determine the runtime-check values from the current tool surface. Delegation tools may be deferred instead of appearing in the initial active tool list. If `tool_search` is available and delegation tools are not already active, search for subagent or multi-agent tools before passing `--runtime-check delegation_available=false`. Pass `false` only after tool discovery fails to expose a usable delegation tool. The `security_diff_scan` profile additionally retains its existing `--runtime-check goal_tools_available=<true|false>`; Standard and Deep profiles do not inspect or require goal tools. Consume the discovered tool namespace as runtime evidence too: when the current tool surface exposes `multi_agent_v1`, replace `<verified-multi-agent-runtime-arguments>` with `--multi-agent-runtime-owner native --multi-agent-runtime-version v1 --multi-agent-runtime-provenance tool-surface`. Do not pass a V2 session cap for V1. For other runtimes, use the verified owner, version, capacity when required, and provenance described below. When static config fully describes the active mode and no session-selected runtime overrides it, remove the placeholder. When the runtime exposes a more accurate effective config value than the user's base config file, add `--effective-config <path>=<json-value>`.
|
|
16
|
-
|
|
17
|
-
For standard and diff scans, a passed `delegated_workers` check means the runtime supports delegated review and the explicitly invoked scan authorizes it; a worker-slot result is the configured maximum, not a promise that every worker will start. If the runtime forbids delegation, pass `delegation_available=false`, continue on the documented parent fallback, and do not describe configured slots as running workers or reduced coverage.
|
|
18
|
-
|
|
19
|
-
When `CODEX_SECURITY_CONFIG_PATH` is set, add `--config "$CODEX_SECURITY_CONFIG_PATH"` in POSIX shells or `--config "$env:CODEX_SECURITY_CONFIG_PATH"` in PowerShell. The CLI provides this sanitized, shell-readable copy of the active worker configuration because the credential-bearing `CODEX_HOME` is intentionally inaccessible to repository-influenced commands. Do not substitute an ambient Codex home in that case.
|
|
20
|
-
|
|
21
|
-
Otherwise, the helper discovers Codex config paths itself from `--cwd`, which defaults to the current working directory. It reads `/etc/codex/config.toml` on Unix-like hosts or `%ProgramData%\OpenAI\Codex\config.toml` on Windows, then `$CODEX_HOME/config.toml`, resolves `project_root_markers`, checks the matching `[projects."<absolute-project-root>"].trust_level`, and loads trusted project `.codex/config.toml` layers from the project root down to `--cwd`. It does not load project layers unless the user config marks that project root as `trusted`.
|
|
22
|
-
|
|
23
|
-
When the current Codex CLI session selected `-p/--profile <name>`, pass `--codex-config-profile <name>`. Current Codex loads `$CODEX_HOME/<name>.config.toml` above the base user config and below trusted project config, so the helper uses that layer for project-root markers, trust, and capability values before it discovers project config. A missing profile file is an empty layer, matching the CLI. Embedded `[profiles.<name>]` lookup remains only for older Codex configs that select `profile` without the CLI flag. Project-local `profile` and `profiles` values are ignored. For session-only CLI overrides or other effective config values that cannot be recovered from config paths, pass `--effective-config <path>=<json-value>`.
|
|
24
|
-
|
|
25
|
-
For targeted tests or unusual runtimes, repeated `--config <path>` arguments override automatic discovery. Pass those manual layers from lower to higher precedence.
|
|
26
|
-
|
|
27
|
-
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.
|
|
28
|
-
|
|
29
|
-
The parent should pass only the runtime facts the worker cannot establish itself, such as a selected config profile or effective runtime-only config values. If delegation is unavailable after tool discovery, run the helper directly in the parent so the preflight can report the degraded or blocked path.
|
|
30
|
-
|
|
31
|
-
Multi-agent config mode is auto-detected when static config fully describes it. Model- or session-selected runtimes must additionally supply the verified runtime facts exposed by the active session. Keep protocol, owner, cap, and provenance separate:
|
|
32
|
-
|
|
33
|
-
```text
|
|
34
|
-
--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>
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
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`.
|
|
38
|
-
|
|
39
|
-
When the active session is actually managed by `codex_bridge`, provide explicit verified ownership. A backend config value alone is not ownership evidence:
|
|
40
|
-
|
|
41
|
-
```text
|
|
42
|
-
--multi-agent-runtime-owner codex-bridge --multi-agent-runtime-version v2 --multi-agent-runtime-provenance verified-bridge --effective-config multiagent_config.max_concurrency=<count>
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
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.
|
|
46
|
-
|
|
47
|
-
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.
|
|
48
|
-
|
|
49
|
-
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.
|
|
50
|
-
|
|
51
|
-
Use the helper result as the preflight source of truth. Do not independently reinterpret profile requirements or compare raw config text for exact equality.
|
|
52
|
-
|
|
53
|
-
Interpret requirement severities this way:
|
|
54
|
-
|
|
55
|
-
- `block`: the requested workflow cannot be claimed honestly when unmet
|
|
56
|
-
- `warn`: the workflow can continue only with the documented degraded path
|
|
57
|
-
- `suggest`: the workflow can continue, but Codex should mention the improvement when it materially affects long-running scan quality or resumability
|
|
58
|
-
|
|
59
|
-
When a requirement is config-backed, compare the effective resolved value when the runtime exposes it. When the runtime does not expose an effective value, fall back to the loaded config value and documented Codex default from the profile when one is present.
|
|
60
|
-
|
|
61
|
-
When the profile includes remediation patches, present the concrete config delta. In an interactive session, ask before editing persistent user config. If the user approves, edit only the helper's `user_config_path`; never infer `~/.codex/config.toml` or another Codex home. A conflicting value from a higher-precedence project or profile layer must be resolved in the source reported by the helper rather than hidden with a lower-precedence edit. In a non-interactive session, follow the narrow automatic-remediation path below instead of waiting for an answer the runtime cannot provide. Never rewrite config beyond the helper's concrete patches.
|
|
62
|
-
|
|
63
|
-
Some remediation patches have `kind = "host_setting"`. Present those as host-level setup guidance, not as edits to persistent Codex config.
|
|
64
|
-
|
|
65
|
-
Do 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.
|
|
66
|
-
|
|
67
|
-
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.
|
|
68
|
-
|
|
69
|
-
## Durable scan handoff
|
|
70
|
-
|
|
71
|
-
After a native handoff or direct conversation start provides a `scanId`, use its authoritative scan context and run this preflight for the validated target and selected scan mode. The dedicated preflight worker described above should finish before goal setup, threat modeling, scan/discovery worker creation, or other substantive analysis.
|
|
72
|
-
|
|
73
|
-
For standard and diff scans, the app handoff starts preflight without an item count. After every structured helper result, call `update_codex_security_scan_progress` without changing phase and set `preflightChecks` to every entry from the helper's `results` array, projecting each entry to only `capability`, `reason`, `severity`, and `status`. Do not send `phaseItemsTotal`, `phaseItemsCompleted`, or `phaseProgressUnit` with `preflightChecks`: the server derives the total from the array length, counts `pass` and `fail` as completed, excludes `unknown` from completed, and derives the visible `block` or `warn` attention items. Send the full fresh results array after a clean rerun so stale issues disappear. Do not interpret item-count completion as readiness: remain in preflight for every blocked, incomplete, or error result while remediation or retry remains pending, even when every returned check was evaluated. Only after a `ready` result has published its fresh `preflightChecks` should a separate progress call advance to `threat_model`. These counts and issues belong to the current scan rather than the legacy setup-time workspace preflight, and remain visible after the scan advances. Deep Scan preflight and discovery progress remain owned by `start_codex_security_deep_scan`.
|
|
74
|
-
|
|
75
|
-
Continue only after a `ready` result. Explain material warnings and use the documented degraded path. For a blocked, incomplete, or error result, report the exact reason and preserve any durable running scan while recovery remains possible; do not review source or start workers early.
|
|
76
|
-
|
|
77
|
-
Do not set `autoResolutionMs`; in an interactive session, an explicit answer is required before persistent configuration changes or scan continuation. If native `request_user_input` is unavailable or errors, call `request_codex_security_user_input` with the same `questions` payload. This MCP fallback is interactive and must remain prohibited in non-interactive sessions. If it returns `accepted`, follow its answer. If it is unavailable or errors, ask the same choices in chat. If it returns `declined` or `cancelled`, do not infer a choice; preserve the running scan, stop, and state that an explicit answer is still required. In every interactive waiting case, stop for the user's answer before creating or adopting a scan goal. Do not call `fail_codex_security_scan` while waiting for that answer. Apply only the approved remediation after `Apply and retry`, preserve the running scan and stop after `Leave paused`, and call `cancel_codex_security_scan` after `Cancel scan`.
|
|
78
|
-
|
|
79
|
-
In a non-interactive session, never request user input. Automatically apply only the helper's concrete `value` or `remove` patches to its writable `user_config_path`, preserving unrelated settings; never apply `host_setting` patches automatically. Rerun once with the same verified runtime facts and continue only if the result is `ready`. If remediation is unavailable, needs a new session, remains blocked, or errors, report the blocker without looping, canceling, or marking the scan failed; preserve a durable scan for later continuation.
|
|
80
|
-
|
|
81
|
-
For any non-ready result, do not fail automatically. If an interactive chat fallback declines required remediation without choosing whether to cancel or leave the scan running, ask that follow-up before taking either action. If remediation is unavailable, the helper cannot run, the helper returns an error envelope, or a rerun remains blocked or incomplete, preserve a durable running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` with the exact reasons only after the documented recovery path is exhausted and the blocker is confirmed unrecoverable. When the user explicitly cancels, call `cancel_codex_security_scan`.
|
|
82
|
-
|
|
83
|
-
Present applicable remediation in the Codex thread. Ask before editing persistent user configuration in interactive sessions; use the narrow automatic-remediation path above in non-interactive sessions.
|
|
84
|
-
|
|
85
|
-
Codex CLI and other hosts use the same prompt-based preflight before substantive work. Explain the exact reasons and remediation in chat. Interactive CLI sessions ask before editing persistent config; non-interactive CLI sessions use the narrow automatic-remediation path above and continue only after a `ready` rerun.
|
|
86
|
-
|
|
87
|
-
## Daybreak Access Advisory
|
|
88
|
-
|
|
89
|
-
After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool once only if it is available in the current session. If the tool is unavailable, skip the advisory silently: do not attempt a call, probe for it, or use a replacement access tool or connector. This advisory checks the connected ChatGPT account or workspace; it does not check Amazon Bedrock model access or access to local CLI scan results. ChatGPT-authenticated desktop and CLI sessions support it. Skip it silently for Amazon Bedrock scans and known API-key-only sessions; neither requires an OpenAI account advisory. Use the selected runtime provider to identify Bedrock, not merely the presence of AWS environment variables. For Deep Security Scan, make the call immediately before `start_codex_security_deep_scan`. Reuse an existing result when continuing the same scan.
|
|
90
|
-
|
|
91
|
-
If the call fails, returns `status: "unknown"`, or returns `stale: true`, continue silently. Do not expose the unavailable check, unknown status, empty program list, or a speculative protected-output warning in progress messages or the final response. For a fresh `granted` result, report the exact status and available Daybreak programs. For a fresh `not_granted` result, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link, falling back to `https://chatgpt.com/cyber` when absent.
|
|
92
|
-
|
|
93
|
-
Continue regardless: this advisory never authorizes or gates the scan. Do not retry, poll, or repeat it between phases. If the user explicitly asks about Daybreak access, report the result or explain that it could not be verified; an unavailable or unknown result does not establish that access is denied. Recheck only when the user explicitly requests a fresh result after an account or Daybreak access change, and only when the tool is available.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
# Codex Desktop Capability Preflight
|
|
2
|
-
|
|
3
|
-
Read this reference only after the host explicitly identifies itself as the Codex desktop app. The shared helper invocation, runtime checks, remediation limits, and non-interactive fallback remain in `config-preflight.md`.
|
|
4
|
-
|
|
5
|
-
Run preflight only after the scan has authoritative target and scan context.
|
|
6
|
-
|
|
7
|
-
After an app-backed Standard or diff scan has its authoritative `scanId`, publish every structured preflight result through `update_codex_security_scan_progress` without changing phase. Set `preflightChecks` to all current results, keeping only `capability`, `reason`, `severity`, and `status`; do not send separate phase totals. The server derives completed and total checks. Stay in preflight until the helper returns `ready`, then advance in a separate progress update. Deep discovery owns its own preflight and progress.
|
|
8
|
-
|
|
9
|
-
When an interactive desktop scan needs remediation, present the exact helper-provided config changes and offer **Apply and retry (Recommended)**, **Leave paused**, and **Cancel scan**. Prefer native `request_user_input`; if it is unavailable or errors, use `request_codex_security_user_input` with the same choices, and fall back to chat only when that tool is unavailable or errors. Never set automatic resolution or infer a choice from a declined or cancelled input request. Wait without creating a goal, then apply only explicitly approved changes, leave the durable scan running, or cancel only when the user explicitly selects cancellation.
|
|
10
|
-
|
|
11
|
-
Never use desktop input tools from a headless or non-interactive session.
|