@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,43 @@
1
+ {
2
+ "documentType": "codex-security.scan-manifest",
3
+ "schemaVersion": "1.0",
4
+ "scan": {
5
+ "id": "scan_example_001",
6
+ "producer": {
7
+ "name": "codex-security-plugin",
8
+ "version": "0.1.0"
9
+ },
10
+ "status": "completed",
11
+ "startedAt": "2026-05-31T18:00:00Z",
12
+ "completedAt": "2026-05-31T18:09:00Z",
13
+ "sealedAt": "2026-05-31T18:09:00Z",
14
+ "target": {
15
+ "kind": "git_worktree",
16
+ "targetId": "target_sha256_example",
17
+ "displayName": "example/repo",
18
+ "remote": "https://github.com/example/repo",
19
+ "revision": "deadbeef",
20
+ "snapshotDigest": "codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb"
21
+ },
22
+ "scope": {
23
+ "includePaths": [
24
+ "src/"
25
+ ],
26
+ "excludePaths": []
27
+ },
28
+ "coverageRef": "coverage.json",
29
+ "findingsRef": "findings.json",
30
+ "artifacts": [
31
+ {
32
+ "path": "findings.json",
33
+ "sha256": "db5ce8533c1b6cd9131f9e12e8bb705f63474caa2a3f7dd21207666b3a8da777",
34
+ "mediaType": "application/json"
35
+ },
36
+ {
37
+ "path": "coverage.json",
38
+ "sha256": "ca91e7a3a89a477796b912232bb3473dead1d342f8b6b37b073bda168819aaa6",
39
+ "mediaType": "application/json"
40
+ }
41
+ ]
42
+ }
43
+ }
@@ -0,0 +1,24 @@
1
+ import { Buffer } from "node:buffer";
2
+ import { readFile, readdir } from "node:fs/promises";
3
+ import { dirname } from "node:path";
4
+ import { createRequire } from "node:module";
5
+ import { fileURLToPath } from "node:url";
6
+ import { brotliDecompressSync } from "node:zlib";
7
+
8
+ const runtimeChunkNames = (await readdir(new URL("./", import.meta.url)))
9
+ .filter((name) => name.startsWith("server.mjs.br.part-"))
10
+ .sort();
11
+ if (!runtimeChunkNames.length) {
12
+ throw new Error("Missing compressed Codex Security MCP workspace runtime chunks.");
13
+ }
14
+ const compressedRuntime = Buffer.concat(
15
+ await Promise.all(runtimeChunkNames.map((name) => readFile(new URL(`./${name}`, import.meta.url))))
16
+ );
17
+ const runtimeSource = brotliDecompressSync(compressedRuntime).toString("utf8");
18
+ const require = createRequire(import.meta.url);
19
+ const Module = require("node:module");
20
+ const loaderPath = fileURLToPath(import.meta.url);
21
+ const runtimeModule = new Module(loaderPath);
22
+ runtimeModule.filename = loaderPath;
23
+ runtimeModule.paths = Module._nodeModulePaths(dirname(loaderPath));
24
+ runtimeModule._compile(runtimeSource, loaderPath);
@@ -0,0 +1,179 @@
1
+ version = 1
2
+
3
+ [capabilities.deep_scan_phase_skills]
4
+ kind = "plugin_skills"
5
+ plugin = "codex-security"
6
+ required = [
7
+ "attack-path-analysis",
8
+ "finding-discovery",
9
+ "security-scan",
10
+ "threat-model",
11
+ "validation",
12
+ ]
13
+
14
+ [capabilities.delegated_workers]
15
+ kind = "runtime"
16
+ check = "delegation_available"
17
+
18
+ [capabilities.goal_tools]
19
+ kind = "runtime"
20
+ check = "goal_tools_available"
21
+
22
+ [capabilities.usable_worker_slots_6]
23
+ kind = "multi_agent_capacity"
24
+ op = ">="
25
+ value = 6
26
+ v1_default = 6
27
+
28
+ [capabilities.usable_worker_slots_8]
29
+ kind = "multi_agent_capacity"
30
+ op = ">="
31
+ value = 8
32
+ v1_default = 6
33
+
34
+ [capabilities.agent_depth_2]
35
+ kind = "config"
36
+ path = "agents.max_depth"
37
+ op = ">="
38
+ value = 2
39
+ default = 1
40
+
41
+ [capabilities.goals_enabled]
42
+ kind = "config"
43
+ path = "features.goals"
44
+ op = "=="
45
+ value = true
46
+ default = true
47
+
48
+ [capabilities.native_multi_agent_v2]
49
+ kind = "multi_agent_mode"
50
+ owner = "native"
51
+ version = "v2"
52
+
53
+ [capabilities.sdk_v2_child_config_compatible]
54
+ kind = "config_absent"
55
+ path = "agents.max_threads"
56
+
57
+ [profiles.security_diff_scan]
58
+ description = "Capabilities for Git-backed Codex Security diff scans."
59
+
60
+ [[profiles.security_diff_scan.requirements]]
61
+ capability = "delegated_workers"
62
+ severity = "warn"
63
+ reason = "Large exhaustive diff scans use delegated workers when available; without them, the scan may need a narrower or parent-agent-only path."
64
+
65
+ [[profiles.security_diff_scan.requirements]]
66
+ capability = "goal_tools"
67
+ severity = "suggest"
68
+ reason = "Goal tools help long diff scans preserve completion criteria across many steps."
69
+
70
+ [[profiles.security_diff_scan.requirements]]
71
+ capability = "goals_enabled"
72
+ severity = "suggest"
73
+ reason = "Enabling goals makes long diff scans easier to resume and audit."
74
+
75
+ [profiles.security_scan]
76
+ description = "Capabilities for repository-wide or scoped-path Codex Security scans."
77
+
78
+ [[profiles.security_scan.requirements]]
79
+ capability = "delegated_workers"
80
+ severity = "warn"
81
+ reason = "Exhaustive repository-wide and scoped-path scans use delegated workers for ranking, file review, validation, and attack-path work when available."
82
+
83
+ [[profiles.security_scan.requirements]]
84
+ capability = "usable_worker_slots_6"
85
+ severity = "warn"
86
+ reason = "The default six-thread cap is the minimum practical concurrency for exhaustive scans that dispatch multiple owned work items."
87
+
88
+ [[profiles.security_scan.requirements]]
89
+ capability = "goal_tools"
90
+ severity = "suggest"
91
+ reason = "Goal tools help long scans preserve completion criteria across interruptions and compaction."
92
+
93
+ [[profiles.security_scan.requirements]]
94
+ capability = "goals_enabled"
95
+ severity = "suggest"
96
+ reason = "Enabling goals makes long scans easier to resume and audit."
97
+
98
+ [profiles.deep_security_scan]
99
+ description = "Capabilities for deep repository-wide Codex Security scans."
100
+
101
+ [[profiles.deep_security_scan.requirements]]
102
+ capability = "deep_scan_phase_skills"
103
+ severity = "block"
104
+ reason = "Deep scan depends on Codex Security phase skills loaded in the current runtime."
105
+
106
+ [[profiles.deep_security_scan.requirements]]
107
+ capability = "native_multi_agent_v2"
108
+ severity = "block"
109
+ reason = "Deep scan launches SDK discovery workers with native Subagents v2; legacy V1 and bridge-owned parent configurations are incompatible with that worker runtime."
110
+
111
+ [[profiles.deep_security_scan.requirements]]
112
+ capability = "sdk_v2_child_config_compatible"
113
+ severity = "block"
114
+ reason = "Deep scan child sessions inherit Codex configuration while enabling Subagents v2, so the legacy agents.max_threads setting must be removed before those sessions can start."
115
+
116
+ [[profiles.deep_security_scan.requirements]]
117
+ capability = "goal_tools"
118
+ severity = "suggest"
119
+ reason = "Goal tools help long deep scans preserve completion criteria across many rounds."
120
+
121
+ [[profiles.deep_security_scan.requirements]]
122
+ capability = "goals_enabled"
123
+ severity = "suggest"
124
+ reason = "Enabling goals makes long deep scans easier to resume and audit."
125
+
126
+ [profiles.security_diff_scan.remediation]
127
+ summary = "Recommended Codex config for longer diff scans."
128
+
129
+ [[profiles.security_diff_scan.remediation.patches]]
130
+ path = "features.goals"
131
+ value = true
132
+
133
+ [profiles.security_scan.remediation]
134
+ summary = "Recommended Codex config for repository-wide or scoped-path scans."
135
+
136
+ [[profiles.security_scan.remediation.patches]]
137
+ path = "features.goals"
138
+ value = true
139
+
140
+ [profiles.deep_security_scan.remediation]
141
+ summary = "Recommended Codex setup for deep repository-wide scans."
142
+
143
+ [[profiles.deep_security_scan.remediation.patches]]
144
+ path = "features.goals"
145
+ value = true
146
+
147
+ [[profiles.deep_security_scan.remediation.variants]]
148
+ mode = "v1"
149
+
150
+ [[profiles.deep_security_scan.remediation.variants.patches]]
151
+ kind = "remove"
152
+ path = "agents.max_threads"
153
+
154
+ [[profiles.deep_security_scan.remediation.variants.patches]]
155
+ path = "features.multi_agent_v2.enabled"
156
+ value = true
157
+
158
+ [[profiles.deep_security_scan.remediation.variants.patches]]
159
+ path = "features.multi_agent_v2.max_concurrent_threads_per_session"
160
+ value = 4
161
+
162
+ [[profiles.deep_security_scan.remediation.variants]]
163
+ mode = "v2"
164
+
165
+ [[profiles.deep_security_scan.remediation.variants.patches]]
166
+ kind = "remove"
167
+ path = "agents.max_threads"
168
+
169
+ [[routes]]
170
+ skill = "security-diff-scan"
171
+ profile = "security_diff_scan"
172
+
173
+ [[routes]]
174
+ skill = "security-scan"
175
+ profile = "security_scan"
176
+
177
+ [[routes]]
178
+ skill = "deep-security-scan"
179
+ profile = "deep_security_scan"
@@ -0,0 +1,115 @@
1
+ # Codex Security Config Preflight
2
+
3
+ Codex Security top-level scan skills should run the read-only helper before substantive scan work:
4
+
5
+ Resolve `<python_command>` to the configured Python interpreter (`$PYTHON` when one is provided), 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:
6
+
7
+ ```text
8
+ <python_command> <plugin_dir>/scripts/config_preflight.py --profile <capability-profile> --cwd <scan-working-directory> --runtime-check delegation_available=<true|false> --runtime-check goal_tools_available=<true|false> <verified-multi-agent-runtime-arguments> --available-plugin-skill <skill-name>
9
+ ```
10
+
11
+ 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. 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>`.
12
+
13
+ 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.
14
+
15
+ When `CODEX_SECURITY_CONFIG_PATH` is set, add `--config "$CODEX_SECURITY_CONFIG_PATH"` to the helper command. 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.
16
+
17
+ Otherwise, the helper discovers Codex config paths itself from `--cwd`, which defaults to the current working directory. It reads `/etc/codex/config.toml`, 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`.
18
+
19
+ 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>`.
20
+
21
+ For targeted tests or unusual runtimes, repeated `--config <path>` arguments override automatic discovery. Pass those manual layers from lower to higher precedence.
22
+
23
+ Repeat `--available-plugin-skill <skill-name>` only for skills from the capability's plugin when the selected profile checks skill dependencies. For the `deep_security_scan` profile, expose only the plugin-local names of available `codex-security` skills, such as `security-scan`; do not pass unrelated session skills. Use the current session's Available skills surface, not files found on disk. The helper reports unavailable skills as a runtime problem and a missing runtime plugin skill list as `incomplete`.
24
+
25
+ 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.
26
+
27
+ 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.
28
+
29
+ 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:
30
+
31
+ ```text
32
+ --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>
33
+ ```
34
+
35
+ The V2 session cap includes the root thread. For profiles that evaluate current-session worker capacity, the helper subtracts that root thread when evaluating usable worker slots. For native V2 selected by static config, the documented Codex default session cap is four when no explicit cap is configured. Do not apply that static default to model- or session-selected V2 when a profile needs the active capacity: pass the observed runtime cap, or the result remains `incomplete`.
36
+
37
+ When the active session is actually managed by `codex_bridge`, provide explicit verified ownership. A backend config value alone is not ownership evidence:
38
+
39
+ ```text
40
+ --multi-agent-runtime-owner codex-bridge --multi-agent-runtime-version v2 --multi-agent-runtime-provenance verified-bridge --effective-config multiagent_config.max_concurrency=<count>
41
+ ```
42
+
43
+ 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.
44
+
45
+ Static native V2 accepts both `[features] multi_agent_v2 = true` and `[features.multi_agent_v2] enabled = true`. Native V2 cannot be combined with `agents.max_threads`; the helper rejects that invalid config. `agents.max_depth` applies to V1 only and is not required for V2. A runtime version and cap without verified ownership cannot produce `ready`. When runtime version, ownership, or capacity remains unknown, the helper returns `incomplete` where the selected profile needs that fact and omits unsafe concurrency patches.
46
+
47
+ 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.
48
+
49
+ Use the helper result as the preflight source of truth. Do not independently reinterpret profile requirements or compare raw config text for exact equality.
50
+
51
+ Interpret requirement severities this way:
52
+
53
+ - `block`: the requested workflow cannot be claimed honestly when unmet
54
+ - `warn`: the workflow can continue only with the documented degraded path
55
+ - `suggest`: the workflow can continue, but Codex should mention the improvement when it materially affects long-running scan quality or resumability
56
+
57
+ 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.
58
+
59
+ 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.
60
+
61
+ Some remediation patches have `kind = "host_setting"`. Present those as host-level setup guidance, not as edits to persistent Codex config.
62
+
63
+ Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight requires native V2 but does not derive outer worker concurrency from the parent session cap or require parent delegation depth. When migrating a legacy V1 configuration for Deep Security Scan, remediation removes `agents.max_threads`, sets `features.multi_agent_v2.enabled = true`, and sets `features.multi_agent_v2.max_concurrent_threads_per_session = 4`. The coordinator overrides each child session's cap from the per-user deep-scan configuration. Codex rejects the legacy V1 thread setting and explicit V2 mode together.
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 runtime capability is `unknown`, establish it from the current tool surface and rerun the helper with an explicit `--runtime-check`. Do not treat an `incomplete` result or unknown value as evidence that the capability is available.
68
+
69
+ ## MCP App onboarding handoff
70
+
71
+ The onboarding workspace opens before capability preflight and does not display or enforce configuration capability results. If `open_codex_security_workspace` returns a workspace with `setup.submitted=false`, that is the app setup wait state. Do not run this helper, do not call `set_codex_security_capability_preflight`, do not create or adopt a scan goal, and do not reclassify the scan as terminal/chat fallback merely because no `scanId` exists yet. Stop and wait for the user to review setup and press Start scan.
72
+
73
+ After the user submits setup and the app-generated handoff provides a `scanId`, load the authoritative scan context with `get_codex_security_scan_context`, then run this preflight for the validated target and selected scan mode. The dedicated preflight worker described above is allowed and should finish before goal setup, threat modeling, scan/discovery worker creation, or other substantive analysis.
74
+
75
+ 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`.
76
+
77
+ Continue after a `ready` result. Explain warn or suggest issues when they materially affect scan quality, capacity, or resumability, and use the documented degraded path. If the result is `blocked` or `incomplete`, follow the remediation handling below. If the helper cannot run or returns its top-level `status: "error"` envelope, report the exact blocker and retry the documented recovery path when possible. Do not call `fail_codex_security_scan` merely because the helper is temporarily unavailable or errors; leave the durable scan running and hand off for a later retry while recovery may still be possible.
78
+
79
+ When blocked or incomplete preflight includes actionable remediation, first classify the current session before choosing a remediation control. Treat `codex exec`, headless runs, automation runs, and any host that cannot actually pause for a human reply as non-interactive even if `request_user_input` or `request_codex_security_user_input` is named in this document or appears callable. In a non-interactive session, never call either user-input tool and never fall back to a chat question; go directly to the automatic-remediation path below. Only after the session is confirmed interactive, present the exact reasons and config delta in the Codex thread and optimistically call the native `request_user_input` tool so the paused scan is visibly waiting for the user's decision instead of asking only in plain chat prose:
80
+
81
+ ```text
82
+ request_user_input(
83
+ questions=[
84
+ {
85
+ "header": "Preflight?",
86
+ "id": "apply_preflight_remediation",
87
+ "question": "Apply the recommended remediation and retry the preflight?",
88
+ "options": [
89
+ {
90
+ "label": "Apply and retry (Recommended)",
91
+ "description": "Apply the approved remediation, then rerun the capability preflight."
92
+ },
93
+ {
94
+ "label": "Leave paused",
95
+ "description": "Keep the scan running for a later retry without changing configuration."
96
+ },
97
+ {
98
+ "label": "Cancel scan",
99
+ "description": "Cancel this scan without applying the remediation."
100
+ }
101
+ ]
102
+ }
103
+ ]
104
+ )
105
+ ```
106
+
107
+ 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 `fail_codex_security_scan` with a concise cancellation reason after `Cancel scan`.
108
+
109
+ In a non-interactive Codex session, do not leave the run waiting for an answer it cannot receive. After showing the exact blocker and config delta, automatically apply only the helper's concrete Codex config patches with ordinary `value` or `remove` operations to the active writable user config, preserving unrelated settings. Never automatically apply `host_setting` remediation or invent a patch. Rerun the same preflight once with the same verified runtime facts and any newly observable effective config. Continue only after that rerun returns `ready`; do not create or adopt scan goals or start substantive scan work earlier. If the new config needs a fresh session before the active runtime can use it, the rerun remains blocked or incomplete, remediation is unavailable, or the helper errors, do not loop, call `fail_codex_security_scan`, or cancel automatically. Preserve an app-generated durable scan and hand it off for a later retry; in CLI or another host without a durable scan, report the exact remaining blocker and end without claiming that a scan is paused.
110
+
111
+ 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, or when the user explicitly cancels.
112
+
113
+ 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. Do not pass capability preflight to `open_codex_security_workspace`, depend on the setup UI to display it, or require `set_codex_security_capability_preflight` before the user can start a scan.
114
+
115
+ Codex CLI and hosts without MCP Apps use the same prompt-based preflight before substantive work. This fallback applies only when the host cannot use the setup app at all; once an app workspace has opened, remain on the app handoff path until the user submits setup or cancels it. 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.
@@ -0,0 +1,205 @@
1
+ # Final Report and Codex Review Directives
2
+
3
+ Use this guidance when authoring canonical report semantics and returning the generated Codex Security report and review directives.
4
+
5
+ ## Final Outputs
6
+
7
+ The final readable output is a deterministic projection of `scan-manifest.json`, `findings.json`, and `coverage.json`:
8
+
9
+ - primary readable markdown report at the final scan report path from `scan-artifacts.md`
10
+ - optional detailed vulnerability write-ups under `findings/<slug>/`, linked from the primary report through `finding.writeup.reportPath`
11
+ - optional structural hardening guidance under `hardening/`, linked from the primary report through `scan.hardening.portfolioPath`
12
+
13
+ When writing `findings.json` alongside this readable output, populate the optional structured details in `finding-detail-fields.md` from the same validated evidence. Do not parse the rendered report back into finding data.
14
+
15
+ Use `report.md` as the primary readable entry point. Explain report-relevant artifact paths in the report itself, especially in `Scope`, `Reviewed Surfaces`, and `Open Questions And Follow Up`.
16
+
17
+ In the final response, link the generated markdown report path as the primary readable artifact.
18
+
19
+ Every scan mode uses the same final report pipeline. The model authors canonical JSON only; it must not author, repair, or treat an existing `report.md` as input. For an app-backed running scan, author `scan-manifest.json` as an unsealed draft and omit `scan.sealedAt` and `scan.artifacts`; finalization owns the exact workbench timestamps, seal, artifact digests, and derived finding identities. `complete-scan` invokes finalization, which validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates and validates `report.md` as an unsealed downstream projection. Missing report prose must be added to the structured canonical fields rather than recovered from a separately authored report.
20
+
21
+ When `complete_codex_security_scan` is available, use it to complete the scan. In Codex CLI or another terminal/chat host without that tool, run `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the completed canonical JSON. Do not mark the scan goal complete until this command succeeds and the generated markdown report exists.
22
+
23
+ Before completion, verify on disk that the workflow-owned `scan-manifest.json`, `findings.json`, and `coverage.json` exist and contain the completed canonical JSON. Completion is finalization only: it validates and seals already-authored canonical artifacts and generates `report.md`; it does not create missing artifacts or run skipped scan phases.
24
+
25
+ If any required scan phase, canonical-artifact write, or on-disk existence check fails before completion, stop the current response and surface the exact workflow blocker. Do not call completion with missing artifacts, return a final report or no-findings result, satisfy a structured output schema, or emit benchmark JSON. Leave the durable scan available for a later continuation instead of canceling or failing it solely because canonical assembly is blocked.
26
+
27
+ If `complete_codex_security_scan` or the terminal/chat finalizer fails, stop the current response and surface the exact MCP or finalizer error. Do not retry completion in the same response, return a final report or no-findings result, satisfy a structured output schema, or emit benchmark JSON. Leave the durable scan available for a later continuation instead of canceling or failing it solely because completion failed.
28
+
29
+ Canonical report semantics live in these fields:
30
+
31
+ - `scan-manifest.json`: `scan.scope` and `scan.threatModel`
32
+ - `findings.json`: each finding's `summary`, `codeEvidence`, `rootCause`, `validation`, `attackPath.dataflow`, `attackPath.reachability`, `severity.rationale`, `severity.changeConditions`, `remediation`, `remediationTests`, and `preventiveControls`
33
+ - `findings.json`: optional `writeup.reportPath` for a derived, unsealed detailed vulnerability report written under `findings/<slug>/<slug>.md`
34
+ - `scan-manifest.json`: optional `scan.hardening.portfolioPath` for the derived, unsealed design portfolio at `hardening/hardening.md`
35
+ - `coverage.json`: `surfaces` including `riskArea` and `notes`, plus `openQuestions`
36
+
37
+ For a whole-repository Deep scan, keep `coverage.inventoryStrategy` as `repository`; repeated discovery is workflow metadata, not a different inventory strategy.
38
+
39
+ Older v1 producers may omit the new optional fields. Finalization uses explicit JSON-derived fallback text in that case; it never reads a pre-existing report to fill gaps.
40
+
41
+ When `scan.hardening.portfolioPath` is present, include a short `## Structural Hardening` section linking the portfolio. Keep individual proposal links and the full option analysis in `hardening/hardening.md` rather than copying them into the primary scan report. The portfolio is design guidance, not evidence that any finding has been remediated.
42
+
43
+ When there are no reportable findings, include a short `No findings` section that explains why nothing survived discovery or the later reportability gates. For repository-wide and scoped-path scans with a coverage ledger, still include `Reviewed Surfaces` so checked, rejected, not-applicable, and follow-up-needed surfaces remain auditable.
44
+
45
+ When there are reportable findings, render them as readable markdown findings rather than raw JSON or a dumped schema object.
46
+ Order findings from highest severity to lowest severity: `critical`, then `high`, then `medium`, then `low`.
47
+
48
+ Use a separate finding entry for each independently attackable source/control/sink instance. Do not combine sibling routes, templates, query builders, parser operations, auth/object-access endpoints, or shared-helper callers into one representative finding solely for readability; if grouping helps, add a short grouped summary after the individual finding entries.
49
+
50
+ If validation or attack-path analysis provides a broad family row with multiple independently triggerable sink, parser, helper, API-mode, or protected-action lines, split it into child final findings before writing the report. Multiple affected lines inside one finding are appropriate for one inseparable proof tuple, such as a wrapper plus its shared sink, but not as a substitute for separate findings when sibling operations can be triggered independently.
51
+
52
+ Set the finding category and CWE from the primary broken control. Do not add secondary support-impact CWEs, such as data exposure or missing authentication, to an injection/RCE/path/file/parser finding merely because they make exploitation worse; mention those impacts in prose or emit a separate finding if that secondary control is independently vulnerable.
53
+
54
+ Examples that should normally become separate final findings include SQL API modes such as `execute`, `executemany`, and `executescript`; deserializer variants such as `pickle.load`, `pickle.loads`, `yaml.load`, and `yaml.load_all`; distinct path/file helper calls; SSRF modes with different destination controls; and missing-auth protected actions such as create, delete, reset, admin, and job-trigger endpoints.
55
+
56
+ For a standard repository or scoped-path scan, assemble the canonical JSON from the enriched `<discovery_dir>/candidate_ledger.jsonl`. Map each nested `validation` record into the finding's validation fields, map its confidence and rationale into top-level `confidence.level` and `confidence.rationale`, and map each nested `attack_path` record into dataflow, reachability, severity, and change conditions.
57
+
58
+ Apply row outcomes in this order: validation disposition `reportable` plus attack-path decision `reportable` becomes a finding with its distinct instance and all relevant entrypoint, root-control, sink, and supporting locations; otherwise, a `deferred` result from either phase becomes `needs_follow_up` coverage and a `coverage.deferred` entry using the recorded uncertainty or proof gap; otherwise, validation disposition `not_applicable` becomes `not_applicable` coverage; otherwise, validation disposition `suppressed` or attack-path decision `ignore` becomes `rejected` coverage. A missing required phase record leaves the candidate unresolved and prevents complete coverage. Do not require phase receipts, per-candidate narratives, or another reconciliation pass.
59
+
60
+ Diff, deep, and resumed legacy scans may still provide per-candidate ledgers, validation closure tables, and repository coverage ledgers. When those artifacts exist, retain their traceability: start from reportable/surviving rows, preserve exact affected locations, and map suppressed, not-applicable, or deferred rows to public-facing coverage outcomes. Do not silently drop a seeded row because a same-family neighbor survived.
61
+
62
+ ## Report Structure
63
+
64
+ Use this report structure:
65
+
66
+ `# Security Review: <repo_or_target_name>`
67
+
68
+ `## Scope`
69
+
70
+ Populate `scan.scope` with in-scope context, artifacts reviewed, runtime or test status, validation mode, and explicit limitations. Include/exclude paths and coverage fields supply the remaining projected scope content. If the threat model was generated during Phase 1 rather than provided by the user, say that in canonical scope context. Do not call generated threat-model material an external input.
71
+
72
+ After the scope bullets, include a compact `### Scan Summary` table when the scan has findings or repository-wide coverage. Use columns `Field` and `Value`. Include the count of reportable findings, severity mix, confidence mix, coverage, and validation mode when those values are known. Keep artifact paths below this table.
73
+
74
+ `## Threat Model`
75
+
76
+ Populate `scan.threatModel` from the completed threat-model analysis. The detailed `<context_dir>/threat_model.md` may remain supporting evidence, but finalization reads only the canonical threat-model object when projecting this section.
77
+
78
+ `## Findings`
79
+
80
+ Start this section with the findings summary table.
81
+
82
+ For Deep Security Scan outputs, group the summary table by `extensions.candidateId` and use columns `Findings`, `Reports`, `Severity`, `Confidence`, and `Detailed write-up`. `deep_repository` scans always use this presentation. Scoped-path deep outputs use it when the reportable child findings carry the deep-scan identifiers described below; ordinary scoped standard scans keep the standard table. Emit one table row per reportable canonical DSS finding. `Findings` contains the vulnerability title without duplicated trailing report or provenance annotations. `Reports` lists every child finding's unique `extensions.reportId`, with each id linking to that child's detailed summary section. For compatibility with older deep-scan artifacts, fall back to `extensions.ledgerRowId`; when a ledger row produced multiple reports, use each child's unique trailing title annotation or instance identity rather than displaying duplicate labels. `Detailed write-up` lists the corresponding `writeup.reportPath` link for every child report. Preserve every child report as its own detailed section below the grouped table. When child reports have different severity or confidence levels, list every distinct level in the grouped row. In the scan summary, distinguish the number of reportable DSS findings from the number of child report instances. For every other scan mode, preserve the standard columns `Finding`, `Severity`, `Confidence`, and `Detailed write-up`, with the finding title linking to the detailed summary section.
83
+
84
+ After the summary table, include a compact `### Confidence Scale` table with columns `Label` and `Meaning`:
85
+
86
+ - `high`: direct source, configuration, or runtime evidence supports the finding, with no material unresolved reachability or exploitability blocker.
87
+ - `medium`: source evidence supports a plausible issue, but runtime behavior, deployment configuration, role reachability, type constraints, or exploit reliability still need proof.
88
+ - `low`: weak or incomplete evidence; include only when the user explicitly wants follow-up candidates in the final report.
89
+
90
+ When a finding records `writeup.reportPath`, link the detailed report from the findings summary and do not duplicate the complete finding inline. The linked write-up is a derived, unsealed readable output; the canonical finding remains the source of truth for adapters and regeneration. Findings without a write-up continue to use the inline format below for compatibility.
91
+
92
+ Render each inline finding as:
93
+
94
+ `### [<number>] <title>`
95
+
96
+ For each finding include a compact two-column metadata table immediately below the heading. Use columns `Field` and `Value`. Include these rows:
97
+
98
+ - `Severity`: `critical|high|medium|low`
99
+ - `Confidence`: `high|medium|low` or a short calibrated confidence label
100
+ - `Confidence rationale`: one sentence explaining why the confidence label is calibrated that way, grounded in the validation method, direct evidence, and missing proof if any
101
+ - `Category`: concrete vulnerability class
102
+ - `CWE`: id and name list, or `none`
103
+ - `Affected lines`: path:line-range list
104
+
105
+ Use a concrete category such as `Authorization bypass / IDOR`, `Path traversal`, `SQL injection`, `XXE`, `Open redirect`, or `Hardcoded credentials`. Do not use generic placeholders such as `security scan finding`.
106
+
107
+ For standard scan modes, the summary table should link each finding title to its detailed finding section with an intra-document markdown anchor. For the Deep Security Scan grouped presentation, the report id in the `Reports` column owns that link instead. Keep the displayed vulnerability title and report id aligned with the corresponding detailed heading. Use the explicit finding anchor emitted by the deterministic projection.
108
+ The summary table and the detailed finding sections must use the same descending severity order: all `critical` findings first, then `high`, then `medium`, then `low`. Renumber findings after sorting so the table order, detailed headings, and anchors match.
109
+
110
+ Affected lines must include the root broken control or dangerous sink line when that line is identifiable, not only the public wrapper, route, or caller that makes it reachable. For wrapper-to-shared-helper findings, list both the reachable wrapper/entrypoint and the underlying parser, deserializer, path/archive helper, expression evaluator, or auth/authz control line. If a seeded file, class, package, or hunk shares the surviving proof tuple, keep that seed anchor in affected lines instead of replacing it with a broader sibling-only location. If the bug is caused by unsafe transformation or selection before the sink, include the split, parse, canonicalization, normalization, comparison, regex, object-selection, or object-binding line where the control fails. For parser, XML, deserialization, and object-construction findings, include the concrete codec, converter, deserializer, parser feature setup, resolver, class filter, or container handler line when that line performs recursive parsing, type resolution, object conversion, class filtering, or fail-open hardening. For central file-format object models, include low-level helper lines such as `to*Array`, `toList`, `getObject`, numeric conversion, iterator, size-based allocation, unchecked cast, or collection-to-array loops when those helpers are the broken malformed-input control. For recursive placeholder/template findings, include the helper/parser setup line that enables recursive expansion or expression evaluation, not only the later resolver or render call. For resource-serving findings, include the allowlist, path-matcher, URL decoding, canonicalization, or resource-selection line that decides whether the attacker-selected resource is allowed. For stateful authentication protocol findings, include the principal/credential/token/issuer installation, rebind/reauthentication, or validated-vs-consumed object-selection line that creates the auth bypass. For SSO/SAML/federation findings, include the response/assertion selection, signed-object lookup, cloned/returned assertion, subject, audience, recipient, destination, ACS URL, or issuer-binding line that determines which identity object is trusted. For polymorphic or request-selected handler, operation, converter, filter, validator, or strategy families, include the concrete subclass/implementation line that transforms, validates, canonicalizes, selects, or reinterprets attacker input before a shared sink/control, including specialized helper methods and branch predicates inside the concrete class when they perform or enable the unsafe transform. If a special-case branch such as append, wildcard, fallback, copy/move `from`, default-value, or type-resolution handling bypasses or narrows validation, include that branch-local root-control line even when a shared helper is also affected. If the finding text says a shared flaw affects "all", "every", or "any" concrete operation, codec, converter, handler, validator, filter, or resolver, the affected lines must include the concrete implementations identified during discovery or validation; do not rely on "and related classes" prose for independently reachable root-control lines. If equivalent resolver/filter controls are duplicated across core, server, client, remoting, plugin, or import packages, include the runtime/exported implementation that enforces the broken control. For repeated vulnerable templates, routes, query builders, parser operations, or auth/object-access endpoints, keep each independently vulnerable file and line as its own affected instance; do not hide sibling instances as extra context on one representative finding when they can be attacked independently. The Codex review directive should point at the tightest root-cause line unless the wrapper or concrete implementation line is the actual broken control.
111
+
112
+ Then render these subsections under each finding:
113
+
114
+ - `#### Summary`
115
+ - Explain why the issue matters, what the vulnerable path is, and why the current controls are insufficient.
116
+ - Wrap code identifiers, RPC names, functions, types, fields, parameters, configuration keys, and literal values in single backticks.
117
+ - `#### Root Cause`
118
+ - State the violated security invariant and explain exactly how the implementation breaks it.
119
+ - Walk the vulnerable call stack from the code that accepts or decodes user-controlled input through each meaningful call or transformation to the missing control, dangerous operation, and security-relevant consumer. Do not begin at the sink when an earlier input boundary is known.
120
+ - Give every displayed `codeEvidence` item a role and an explanation that names the carried value and the next callee or state transition. Order `rootCause.evidenceRefs` from input to outcome, with any `expected_control` comparison after the vulnerable stack.
121
+ - Show the smallest complete snippets needed for that walkthrough. Omit incidental helpers, but do not skip a call boundary whose behavior is necessary to understand how attacker input reaches the broken invariant.
122
+ - Do not emit generic prose that only repeats an affected `path:line` already present in the metadata table.
123
+ - `#### Validation`
124
+ - Include method, checklist items, evidence, and remaining uncertainty.
125
+ - Pair each important validation claim with actual source in `validation.evidenceRefs`; a list of file names and line numbers is not sufficient evidence for the readable finding.
126
+ - `#### Dataflow`
127
+ - Show the technical source-to-sink path inside the code, such as request parameter -> controller -> service/helper -> dangerous sink -> response or side effect.
128
+ - `#### Reachability`
129
+ - Explain who can realistically trigger the dataflow, from what boundary, under what preconditions, and what attacker outcome follows. Fold any attack-path facts into this prose or compact bullets instead of emitting a separate `Attack Path Facts` section.
130
+ - Use `attackPath.evidenceRefs` for the few code transitions that establish attacker input, the missing control, and the resulting sink or state change. Keep this shorter than Validation.
131
+ - `#### Severity`
132
+ - State the final severity and then explain the rationale.
133
+ - Treat likelihood and impact as inputs to the final severity, not as separate report labels.
134
+ - The rationale should fold in reachability: attacker role, exposed entry point, exploit steps, required feature flags/config, runtime/deployment assumptions, and any counterevidence or blockers.
135
+ - The rationale should explain the concrete security consequence using repository evidence: data exposed, integrity boundary broken, credential/control-plane effect, code execution path, or why impact is narrower.
136
+ - Include one concise sentence explaining what specific additional evidence would raise or lower the severity.
137
+ - Avoid circular phrasing such as `this is high because it is high severity`, `maps to high`, or `high-severity issue`.
138
+ - `#### Remediation`
139
+ - Give concrete minimal fixes, tests, and preventive controls.
140
+
141
+ For repository-wide and scoped-path scans with a coverage ledger, include a concise `## Reviewed Surfaces` section after the findings. This section summarizes what was inspected, what came out of each reviewed surface, and seeded/root-control rows that were suppressed, not applicable, or deferred so an auditor can see why they did not become findings. Use a table with `Surface`, `Risk Area`, `Outcome`, and `Notes`.
142
+
143
+ Recommended outcomes:
144
+
145
+ - `Reported`: became a final finding.
146
+ - `No issue found`: reviewed and no credible issue survived.
147
+ - `Rejected`: plausible-looking candidate was ruled out with specific counterevidence.
148
+ - `Not applicable`: the risk class does not apply to that surface.
149
+ - `Needs follow-up`: plausible but not fully closed because of a concrete blocker or proof gap.
150
+
151
+ Write the same content, or a slightly more detailed version, to `<coverage_dir>/reviewed_surfaces.md`.
152
+
153
+ For broad scans where the completed coverage is useful for triage but too large for high-precision review, include a concise `## Open Questions And Follow Up` section near the end of the report. Use concrete, copyable prompt ideas that narrow the next review to individual commits from the current scan. Do not include this section for precise scans where the requested scope was already sufficient.
154
+
155
+ Follow-up prompts should be tailored to the actual scan results:
156
+
157
+ - use exact commit SHAs, PR numbers, short titles, file paths, or component names from the report
158
+ - focus each prompt on the specific boundary that made the commit worth follow-up, such as auth, plugin/MCP exposure, artifact downloads, signed URLs, or gateway routing
159
+ - avoid generic placeholders
160
+
161
+ Each finding should make it easy for an application security engineer or software engineer to answer:
162
+
163
+ - what changed or what path is vulnerable
164
+ - what attacker-controlled input or trust boundary matters
165
+ - what direct evidence supports the claim
166
+ - what counterevidence or uncertainty remains
167
+ - why the severity landed where it did
168
+ - what the smallest safe fix is
169
+
170
+ Include the final markdown report path in the response so the user can find the readable report easily.
171
+
172
+ After a completed scan:
173
+
174
+ - If the scan found reportable issues, ask whether the user wants to export the findings as JSON, SARIF, or CSV, generate patches, or track selected findings. Name the highest-priority finding.
175
+ - Offer tracking only when `$track-findings` can use an available destination, such as Linear, Jira, or GitHub Issues. Name the destination in the question.
176
+ - If the report names a specific follow-up, ask whether the user wants to investigate it.
177
+ - If the scan found nothing and has no specific follow-up, do not add a generic question.
178
+ - Wait for the user's answer before exporting findings, generating patches, tracking findings, or starting another scan.
179
+
180
+ ## Codex Review Directives
181
+
182
+ For Codex app rendering, emit one `::code-comment{...}` directive per surviving finding in the final response. The markdown report and review directives should agree on title, file, line range, and core explanation.
183
+
184
+ Map the final report severity to Codex directive priority only when emitting the directive:
185
+
186
+ - `critical` -> `P0`, `priority=0`
187
+ - `high` -> `P1`, `priority=1`
188
+ - `medium` -> `P2`, `priority=2`
189
+ - `low` -> `P3`, `priority=3`
190
+
191
+ For each reportable finding, emit a Codex review directive in this form:
192
+
193
+ `::code-comment{title="[P1] Example title" body="One-paragraph review explanation." file="/absolute/path/to/file" start=10 end=12 priority=1 confidence=0.55}`
194
+
195
+ Directive requirements:
196
+
197
+ - `title`, `body`, and `file` are required
198
+ - `title` should include the mapped Codex directive priority, formatted like `[P1] Example title`
199
+ - `file` should be an absolute path
200
+ - `start` and `end` should be tight 1-based line numbers
201
+ - `priority` should match the mapped Codex directive priority
202
+ - `confidence` should be numeric when available
203
+ - emit one directive per finding and none when there are no findings
204
+ - inline Markdown code spans are allowed and encouraged for short identifiers, flags, function names, and config keys, such as `git -c`, `--config`, and `diff.external`
205
+ - do not put double quote characters inside quoted attribute values, including escaped quotes like `\"`; rewrite quoted command examples without quotes or leave them only in the markdown report