@openai/codex-security 0.1.5 → 0.1.6

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 (94) hide show
  1. package/README.md +79 -8
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +8 -1
  4. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/preflight/capability-profiles.toml +0 -57
  8. package/_bundled_plugin/references/config-preflight.md +1 -1
  9. package/_bundled_plugin/references/final-report.md +15 -7
  10. package/_bundled_plugin/references/scan-artifacts.md +11 -9
  11. package/_bundled_plugin/references/scan-contract.md +3 -1
  12. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +42 -0
  13. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +100 -0
  14. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +181 -0
  15. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +166 -0
  16. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +120 -0
  17. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +83 -0
  18. package/_bundled_plugin/schemas/tools/review-items.schema.json +80 -0
  19. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +572 -0
  20. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +18 -0
  21. package/_bundled_plugin/scripts/deep_scan_config.py +11 -3
  22. package/_bundled_plugin/scripts/deep_scan_workbench.py +153 -133
  23. package/_bundled_plugin/scripts/finalize_scan_contract.py +21 -0
  24. package/_bundled_plugin/scripts/generate_in_scope_files.py +134 -0
  25. package/_bundled_plugin/scripts/workbench_cli.py +33 -1
  26. package/_bundled_plugin/scripts/workbench_db.py +127 -117
  27. package/_bundled_plugin/scripts/workbench_feedback.py +2 -0
  28. package/_bundled_plugin/scripts/workbench_native_indexes.py +5 -49
  29. package/_bundled_plugin/scripts/workbench_progress.py +86 -3
  30. package/_bundled_plugin/scripts/workbench_remediation.py +19 -1
  31. package/_bundled_plugin/scripts/workbench_scan_history.py +7 -1
  32. package/_bundled_plugin/scripts/workbench_scan_start.py +11 -5
  33. package/_bundled_plugin/scripts/workbench_scan_usage.py +557 -0
  34. package/_bundled_plugin/scripts/workbench_schema.py +501 -0
  35. package/_bundled_plugin/scripts/workbench_validation.py +117 -13
  36. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -4
  37. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +34 -28
  38. package/_bundled_plugin/skills/finding-discovery/SKILL.md +1 -1
  39. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -8
  40. package/_bundled_plugin/skills/security-scan/SKILL.md +16 -9
  41. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +26 -14
  42. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +1 -1
  43. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  44. package/_bundled_plugin/skills/validation/SKILL.md +5 -5
  45. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +145 -227
  46. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +53 -68
  47. package/dist/api.d.ts +29 -7
  48. package/dist/api.d.ts.map +1 -1
  49. package/dist/api.js +323 -47
  50. package/dist/api.js.map +1 -1
  51. package/dist/auth.js +1 -1
  52. package/dist/auth.js.map +1 -1
  53. package/dist/cli.d.ts +3 -2
  54. package/dist/cli.d.ts.map +1 -1
  55. package/dist/cli.js +458 -40
  56. package/dist/cli.js.map +1 -1
  57. package/dist/config.d.ts +28 -0
  58. package/dist/config.d.ts.map +1 -1
  59. package/dist/config.js +39 -2
  60. package/dist/config.js.map +1 -1
  61. package/dist/cost.d.ts +7 -0
  62. package/dist/cost.d.ts.map +1 -1
  63. package/dist/cost.js +345 -17
  64. package/dist/cost.js.map +1 -1
  65. package/dist/index.d.ts +3 -2
  66. package/dist/index.d.ts.map +1 -1
  67. package/dist/index.js.map +1 -1
  68. package/dist/multiscan.d.ts +1 -0
  69. package/dist/multiscan.d.ts.map +1 -1
  70. package/dist/multiscan.js +3 -0
  71. package/dist/multiscan.js.map +1 -1
  72. package/dist/runtime.d.ts +16 -0
  73. package/dist/runtime.d.ts.map +1 -1
  74. package/dist/runtime.js +540 -25
  75. package/dist/runtime.js.map +1 -1
  76. package/dist/scan-activity.d.ts +13 -0
  77. package/dist/scan-activity.d.ts.map +1 -0
  78. package/dist/scan-activity.js +319 -0
  79. package/dist/scan-activity.js.map +1 -0
  80. package/dist/scan-dashboard.d.ts +47 -0
  81. package/dist/scan-dashboard.d.ts.map +1 -0
  82. package/dist/scan-dashboard.js +444 -0
  83. package/dist/scan-dashboard.js.map +1 -0
  84. package/dist/scan-history-renderer.d.ts.map +1 -1
  85. package/dist/scan-history-renderer.js +4 -1
  86. package/dist/scan-history-renderer.js.map +1 -1
  87. package/dist/version.d.ts +1 -1
  88. package/dist/version.js +1 -1
  89. package/dist/version.js.map +1 -1
  90. package/dist/worker-progress.d.ts +7 -0
  91. package/dist/worker-progress.d.ts.map +1 -1
  92. package/dist/worker-progress.js +68 -0
  93. package/dist/worker-progress.js.map +1 -1
  94. package/package.json +3 -3
package/README.md CHANGED
@@ -85,10 +85,10 @@ Pass scan configuration to `security.run(repository, options)` or
85
85
  | `signal` | Cancel a scan with an `AbortSignal`. |
86
86
 
87
87
  Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
88
- `onOutputArchived`, `onOutputDirReady`, `onScanStarted`, `onReconnect`,
89
- `onWorkerStatus`, `onWarning`, and `onObserverError`. Preflight does not start
90
- the runtime, authenticate, resolve Python, inspect the plugin, or run those
91
- scan-lifecycle callbacks.
88
+ `onOutputArchived`, `onOutputDirReady`, `onScanStarted`,
89
+ `onTrustedAccessStatus`, `onReconnect`, `onWorkerStatus`, `onWarning`, and
90
+ `onObserverError`. Preflight does not start the runtime, authenticate, resolve
91
+ Python, inspect the plugin, or run those scan-lifecycle callbacks.
92
92
 
93
93
  ## Authentication
94
94
 
@@ -120,6 +120,16 @@ To pass a Codex access token explicitly, use
120
120
  `login --with-access-token` and provide the token on stdin. An access token
121
121
  environment variable is not automatically used as a scan API key.
122
122
 
123
+ To use another inference provider, set its API key and select its provider:
124
+
125
+ ```bash
126
+ export OPENROUTER_API_KEY="<your-openrouter-api-key>"
127
+ npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
128
+
129
+ export FIREWORKS_API_KEY="<your-fireworks-api-key>"
130
+ npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
131
+ ```
132
+
123
133
  On Windows, set the API key in PowerShell:
124
134
 
125
135
  ```powershell
@@ -131,7 +141,11 @@ Check or remove the stored sign-in with `npx @openai/codex-security login status
131
141
  and `npx @openai/codex-security logout`. Codex Security keeps its sign-in in a
132
142
  private, stable Codex home at `$CODEX_SECURITY_STATE_DIR/codex-home`, or at
133
143
  `$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is
134
- configured. Login, status, logout, and scans use the same home. Codex manages
144
+ configured. On managed Windows devices, inherited access for `SYSTEM` and local
145
+ `Administrators` is preserved while protecting the home against future changes
146
+ to its parents. Other users and broad groups are rejected, and PowerShell
147
+ Constrained Language Mode is supported. Login,
148
+ status, logout, and scans use the same home. Codex manages
135
149
  credentials using its configured file or system-keyring backend and honors
136
150
  managed-device policies. An existing file-based Codex sign-in is imported only
137
151
  when the dedicated home does not already contain stored credentials. Logging
@@ -169,10 +183,15 @@ When an environment key is configured, ChatGPT login and
169
183
  `codex-security login status` identify the effective scan credential source
170
184
  without printing its value, including when no stored sign-in exists.
171
185
 
186
+ Some cybersecurity requests and protected findings require approval through
187
+ Trusted Access for Cyber. To apply or check your access, visit
188
+ [chatgpt.com/cyber](https://chatgpt.com/cyber).
189
+
172
190
  ## CLI
173
191
 
174
192
  ```bash
175
193
  npx @openai/codex-security scan /path/to/repository
194
+ npx @openai/codex-security scan /path/to/repository --headless
176
195
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
177
196
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
178
197
  npx @openai/codex-security scan /path/to/repository --path src --path tests
@@ -180,13 +199,15 @@ npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/th
180
199
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
181
200
  npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
182
201
  npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
202
+ npx @openai/codex-security scan /path/to/repository --verbose
183
203
  npx @openai/codex-security scan /path/to/repository --dry-run
184
204
  npx @openai/codex-security scan /path/to/repository --fail-on-severity high
185
205
  npx @openai/codex-security scan /path/to/repository --max-cost 5
206
+ npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10
186
207
  npx @openai/codex-security install-hook
187
208
  npx @openai/codex-security bulk-scan
188
209
  npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
189
- npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
210
+ npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
190
211
  npx @openai/codex-security scans list /path/to/repository
191
212
  npx @openai/codex-security scans list --scan-root /path/outside/repository/results
192
213
  npx @openai/codex-security scans show SCAN_ID
@@ -221,8 +242,40 @@ directory and any enclosing Git worktree. When SARIF is produced, it is written
221
242
  to
222
243
  `<scan-dir>/exports/results.sarif`.
223
244
 
224
- Repeat `--knowledge-base PATH` for multiple files or directories. Directories are
225
- searched recursively for Markdown, text, PDF, and Word (`.docx`) files.
245
+ Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
246
+ shares them with every repository. Directories are searched recursively for
247
+ Markdown, text, PDF, and Word (`.docx`) files.
248
+
249
+ ### Configure deep scans
250
+
251
+ For `scan --mode deep`, `--workers` limits concurrent discovery workers,
252
+ `--subagents` controls each worker's subagents, `--stop-after-no-new` stops after
253
+ that many runs find no new issues, and `--max-discovery-runs` limits total runs.
254
+ These options are also available on SDK scans:
255
+
256
+ ```ts
257
+ await security.run("/path/to/repository", {
258
+ mode: "deep",
259
+ workers: 2,
260
+ subagents: 0,
261
+ stopAfterNoNew: 3,
262
+ maxDiscoveryRuns: 10,
263
+ });
264
+ ```
265
+
266
+ Set defaults in `~/.codex/codex-security/config.toml`, or under `$CODEX_HOME`
267
+ when it is configured. Explicit CLI and SDK settings override these defaults:
268
+
269
+ ```toml
270
+ [deep_scan]
271
+ workers = 2
272
+ subagents = 0
273
+ stop_after_no_new = 3
274
+ max_discovery_runs = 10
275
+ ```
276
+
277
+ `scan --workers` controls discovery workers within one deep scan;
278
+ `bulk-scan --workers` controls how many repositories are scanned concurrently.
226
279
 
227
280
  On macOS/Linux, an existing output directory must be private to the current
228
281
  user (`chmod 700`).
@@ -255,6 +308,8 @@ defaults:
255
308
  cli_auth_credentials_store = "file"
256
309
  model = "gpt-5.6-sol"
257
310
  model_reasoning_effort = "xhigh"
311
+ model_reasoning_summary = "detailed"
312
+ show_raw_agent_reasoning = true
258
313
 
259
314
  [features]
260
315
  plugins = true
@@ -338,6 +393,8 @@ The CLI and SDK recognize the following user-configurable environment:
338
393
  | Variable | Effect |
339
394
  | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
340
395
  | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
396
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; set to `debug` for redacted diagnostics. |
397
+ | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
341
398
  | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
342
399
  | `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
343
400
  | `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
@@ -366,13 +423,27 @@ Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
366
423
  `CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
367
424
  internal runtime data, not supported user configuration.
368
425
 
426
+ Use `--provider openrouter` to send inference through OpenRouter. Set
427
+ `OPENROUTER_API_KEY` and specify a supported model with `--model`.
428
+
429
+ Use `--provider fireworks` to send inference through Fireworks AI. Set
430
+ `FIREWORKS_API_KEY` and specify a supported model with `--model`.
431
+
369
432
  Scan progress identifies the requested paths and reports actual ranking,
370
433
  file-review, validation, and attack-path phases as they become available.
434
+ Interactive terminals show a full-screen view; CI, redirected output, and
435
+ `--headless` use plain timestamped progress lines.
371
436
  Completion summarizes findings, severity, coverage, elapsed time, available
372
437
  token and worker counts, estimated cost, the results directory, and the next
373
438
  useful command.
374
439
  Progress and summaries use stderr; structured scan results remain on stdout.
375
440
 
441
+ Add `--verbose` or set `CODEX_SECURITY_LOG_LEVEL=debug` to print redacted
442
+ lifecycle, authentication, progress, and cost diagnostics to stderr.
443
+ `LOG_LEVEL=debug` is used only when `CODEX_SECURITY_LOG_LEVEL` is unset.
444
+ Credentials and provider identifiers remain redacted, and structured JSON
445
+ results remain on stdout.
446
+
376
447
  Each scan records its model, tokens, and estimated cost in its JSON result,
377
448
  scan history, and bulk-scan receipt. Estimates use
378
449
  [standard API token prices](https://developers.openai.com/api/docs/models/compare),
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.14",
3
+ "version": "0.1.15",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -12,7 +12,14 @@
12
12
  "PYTHON",
13
13
  "CODEX_SECURITY_KNOWLEDGE_BASE",
14
14
  "CODEX_SECURITY_SCAN_ROOT",
15
- "CODEX_SECURITY_STATE_DIR"
15
+ "CODEX_SECURITY_STATE_DIR",
16
+ "HTTP_PROXY",
17
+ "HTTPS_PROXY",
18
+ "ALL_PROXY",
19
+ "NO_PROXY",
20
+ "SSL_CERT_FILE",
21
+ "REQUESTS_CA_BUNDLE",
22
+ "NODE_EXTRA_CA_CERTS"
16
23
  ],
17
24
  "tool_timeout_sec": 86400
18
25
  }
Binary file
@@ -1,16 +1,5 @@
1
1
  version = 1
2
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
3
  [capabilities.delegated_workers]
15
4
  kind = "runtime"
16
5
  check = "delegation_available"
@@ -45,15 +34,6 @@ op = "=="
45
34
  value = true
46
35
  default = true
47
36
 
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
37
  [profiles.security_diff_scan]
58
38
  description = "Capabilities for Git-backed Codex Security diff scans."
59
39
 
@@ -98,21 +78,6 @@ reason = "Enabling goals makes long scans easier to resume and audit."
98
78
  [profiles.deep_security_scan]
99
79
  description = "Capabilities for deep repository-wide Codex Security scans."
100
80
 
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
81
  [[profiles.deep_security_scan.requirements]]
117
82
  capability = "goal_tools"
118
83
  severity = "suggest"
@@ -144,28 +109,6 @@ summary = "Recommended Codex setup for deep repository-wide scans."
144
109
  path = "features.goals"
145
110
  value = true
146
111
 
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
112
  [[routes]]
170
113
  skill = "security-diff-scan"
171
114
  profile = "security_diff_scan"
@@ -60,7 +60,7 @@ When the profile includes remediation patches, present the concrete config delta
60
60
 
61
61
  Some remediation patches have `kind = "host_setting"`. Present those as host-level setup guidance, not as edits to persistent Codex config.
62
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.
63
+ Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight does not require a particular parent delegation runtime, ownership, capacity, or depth. Discovery workers inherit the scan's model and run under the verified read-only worker sandbox.
64
64
 
65
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
66
 
@@ -16,13 +16,21 @@ Use `report.md` as the primary readable entry point. Explain report-relevant art
16
16
 
17
17
  In the final response, link the generated markdown report path as the primary readable artifact.
18
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.
19
+ Every scan mode uses the same final report pipeline. For compact Standard and Deep scans, submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`. The workbench writes the unsealed canonical draft and supplies the authoritative target, exact workbench timestamps, and derived finding identities. Other modes retain their existing canonical JSON workflow. No mode authors, repairs, or treats an existing `report.md` as input. `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 supplied in the structured canonical semantics rather than recovered from a separately authored report.
20
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.
21
+ For each surviving compact candidate, supply the evidence-supported lowercase vulnerability-family `ruleId`; `taxonomy: { category, cwe }` using the candidate's exact `cwe_ids`; verified locations; and `provenance.source`, using `"local_plugin"` only when this plugin actually discovered the finding. Preserve the canonical candidate identity and genuine worker or source provenance in the existing finding extensions. A candidate with no known CWE retains `cwe: []`; never invent a classification. Include optional `codeEvidence` only when its actual code is nonempty and every referenced evidence ID is present.
22
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.
23
+ Supply semantic coverage as `{ completeness, surfaces, explicitExclusions, deferred }`, with each surface using the actual `label` and one existing `disposition`. Mark coverage `partial` when a deferred item or `needs_follow_up` surface remains; preserve its real reason and supporting context. Each deferred item needs a meaningful reason; preserve any existing `id` or `candidateId`. The workbench derives a missing ID from its candidate identity or stable deferred-work details. Open questions may be nonempty strings or `{ question, followUpPrompt? }` objects. The workbench derives target and scope metadata, scope include and exclude paths, coverage mode and inventory strategy, finding identities and fingerprints, and surface IDs. Do not put those workbench-owned values or top-level coverage receipt references into the semantic draft.
24
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.
25
+ After a compact Standard or Deep draft is accepted, call `complete_codex_security_scan({ scanId, handoffClaimToken? })`, then read canonical results with `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`. For diff or another existing terminal/chat workflow without the completion tool, retain `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 finalization succeeds and the generated markdown report exists.
26
+
27
+ After `complete_codex_security_scan` succeeds, include its returned `usage.totalTokens`, `usage.inputTokens`, and `usage.cachedInputTokens` in the final response when `usage.coverage` is `complete` or `partial`; explicitly label a partial measurement. If coverage is `unavailable`, say that token usage could not be measured instead of reporting zero or estimating a cost. Report only measured completion metadata in a terminal/chat host. Token usage is workbench metadata, not a reason to modify sealed scan artifacts or the deterministic report.
28
+
29
+ Before compact Standard or Deep completion, require `record_codex_security_scan_draft` to succeed. Existing diff and legacy workflows continue to verify their canonical JSON before completion. Completion is finalization only: it validates and seals already-recorded canonical artifacts and generates `report.md`; it does not create missing artifacts or run skipped scan phases.
30
+
31
+ An MCP `-32602` input rejection, an `isError: true` result reporting `Input validation error`, or an explicit pre-write rejection of complete coverage containing deferred work or a follow-up surface makes no draft write. Correct only the named paths in the same draft, preserving all valid findings, fields, evidence, and deferred work; retry the same scan at most twice. Stop after the first accepted draft. Do not blindly retry an ambiguous transport or write failure.
32
+
33
+ For any other required scan phase, canonical-artifact write, or on-disk existence check that 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
34
 
27
35
  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
36
 
@@ -34,7 +42,7 @@ Canonical report semantics live in these fields:
34
42
  - `scan-manifest.json`: optional `scan.hardening.portfolioPath` for the derived, unsealed design portfolio at `hardening/hardening.md`
35
43
  - `coverage.json`: `surfaces` including `riskArea` and `notes`, plus `openQuestions`
36
44
 
37
- For a whole-repository Deep scan, keep `coverage.inventoryStrategy` as `repository`; repeated discovery is workflow metadata, not a different inventory strategy.
45
+ For a whole-repository Deep scan, the workbench derives `coverage.inventoryStrategy: "repository"` in the stored coverage document; repeated discovery is workflow metadata, not a different inventory strategy. Do not include `inventoryStrategy` in `record_codex_security_scan_draft`.
38
46
 
39
47
  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
48
 
@@ -53,11 +61,11 @@ Set the finding category and CWE from the primary broken control. Do not add sec
53
61
 
54
62
  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
63
 
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.
64
+ For a Standard or Deep repository or scoped-path scan, read the same enriched candidates with `list_codex_security_candidates`. 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. Submit those semantics through `record_codex_security_scan_draft`. Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
57
65
 
58
66
  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
67
 
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.
68
+ Diff 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
69
 
62
70
  ## Report Structure
63
71
 
@@ -38,18 +38,18 @@ End each repository-scoped threat model with these two lines:
38
38
 
39
39
  ## Finding Discovery (Phase 2) Paths
40
40
 
41
- ### Standard Repository Or Scoped-Path Scan
41
+ ### Standard And Deep Repository Or Scoped-Path Scans
42
42
 
43
- - Deterministic in-scope file list: `<discovery_dir>/in_scope_files.txt`
44
- - Compact combined candidate ledger: `<discovery_dir>/candidate_ledger.jsonl`
45
- - The combiner reads one or more temporary raw candidate sources, validates them against the in-scope file list, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values. This is the sole durable standard candidate artifact.
43
+ - Prepare deterministic review items with `prepare_codex_security_review_items({ scanId, handoffClaimToken? })`; read their repository-relative source paths with paginated `list_codex_security_review_items`. A bound Deep worker uses `list_codex_security_review_items({ cursor?, limit? })`.
44
+ - Record the complete compact candidate set once with `record_codex_security_discovery_candidates`; read it with paginated `list_codex_security_candidates`. A Standard parent supplies `scanId`; a bound Deep worker omits it.
45
+ - The writer validates candidates against the assigned review items, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values. This is the sole durable candidate set for a Standard scan, an independent Deep discovery worker, or a canonical semantically merged Deep result.
46
46
  - After normalization, compact validation adds exactly one `validation` object to every row with `disposition` (`reportable`, `suppressed`, `not_applicable`, or `deferred`), `method`, `confidence` (`high`, `medium`, or `low`), `confidence_rationale`, concise `rubric` and `evidence`, `counterevidence_or_proof_gap`, `remaining_uncertainty`, and optional `artifact_paths`. Add `source`, `control`, `sink`, or `preconditions` only when they clarify or differ from the discovery fields.
47
47
  - Compact attack-path analysis adds exactly one `attack_path` object to each validation row marked `reportable` or `deferred`, with `decision` (`reportable`, `ignore`, or `deferred`), `dataflow`, `reachability`, `counterevidence`, `impact` and `likelihood` (`high`, `medium`, `low`, `ignore`, or `unknown`), `severity` (`critical`, `high`, `medium`, `low`, `ignore`, or `unknown`), `severity_rationale`, `change_conditions`, and `proof_gap` when deferred. A `reportable` decision requires severity `critical`, `high`, `medium`, or `low`; `ignore` requires severity `ignore`; `deferred` uses a provisional reportable severity or `unknown`.
48
- - Preserve all discovery fields and row order during enrichment, rewrite atomically, and do not pass the enriched ledger back to `normalize_candidates.py`.
48
+ - Record all validations through `record_codex_security_candidate_validations` and all eligible attack-path decisions through `record_codex_security_candidate_attack_paths`. The tools atomically preserve all discovery fields and candidate order.
49
49
  - Optional compact validation evidence: `<discovery_dir>/validation_artifacts/<candidate_id>/`
50
50
  - Create this directory only for actual PoCs, crafted inputs, or logs and reference those paths from the row's `validation` object. Do not create placeholder per-candidate directories or narrative reports.
51
51
 
52
- The legacy ranking, raw/deduped candidate, per-finding receipt, and phase-report paths below are for diff/deep or resumed legacy workflows. A compact standard scan uses the enriched ledger instead.
52
+ The legacy ranking, raw/deduped candidate, per-finding receipt, and phase-report paths below are for diff or resumed legacy workflows. Compact Standard and Deep scans use the same enriched ledger instead.
53
53
 
54
54
  ### Coverage Planning
55
55
 
@@ -82,7 +82,7 @@ The legacy ranking, raw/deduped candidate, per-finding receipt, and phase-report
82
82
 
83
83
  ## Validation (Phase 3) Paths
84
84
 
85
- Compact standard scans use the nested `validation` record and optional compact evidence path above. Other scan modes use these paths:
85
+ Compact Standard and Deep scans use the nested `validation` record and optional compact evidence path above. Other workflows use these paths:
86
86
 
87
87
  - Scan-level validation summary: `<findings_dir>/validation_summary.md` if applicable
88
88
  - Per-finding validation report: `<findings_dir>/<candidate_id>/validation_report.md`
@@ -90,13 +90,15 @@ Compact standard scans use the nested `validation` record and optional compact e
90
90
 
91
91
  ## Attack-Path Analysis (Phase 4) Paths
92
92
 
93
- Compact standard scans use the nested `attack_path` record above. Other scan modes use these paths:
93
+ Compact Standard and Deep scans use the nested `attack_path` record above. Other workflows use these paths:
94
94
 
95
95
  - Scan-level attack-path analysis report: `<findings_dir>/attack_path_analysis_report.md` if applicable
96
96
  - Per-finding attack-path analysis report: `<findings_dir>/<candidate_id>/attack_path_analysis_report.md`
97
97
 
98
98
  ## Final Report Paths
99
99
 
100
+ - Compact Standard and Deep draft: `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`
101
+ - Compact Standard and Deep completed results: `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`
100
102
  - Final scan report: `<scan_dir>/report.md`
101
103
  - Detailed vulnerability write-up: `<scan_dir>/findings/<slug>/<slug>.md`
102
104
  - Per-finding PoC and supporting files: `<scan_dir>/findings/<slug>/poc/...`
@@ -112,5 +114,5 @@ Compact standard scans use the nested `attack_path` record above. Other scan mod
112
114
 
113
115
  - Put scan phase outputs and supporting evidence under the numbered artifact subdirectories above.
114
116
  - Keep fix-finding outputs outside the numbered scan phases because fix-finding can run standalone or against an existing scan.
115
- - Do not author the final `report.md` directly. Put complete scan-level report semantics in the canonical JSON files. Detailed per-finding prose in `findings/<slug>/<slug>.md` and derived design guidance under `hardening/` are optional for a standard scan. Finalization deterministically writes the unsealed `report.md` projection and links any recorded write-ups and hardening portfolio. Do not add these derived documents to the sealed artifact list.
117
+ - Do not author the final `report.md` directly. Put complete scan-level report semantics in the canonical JSON files. Detailed per-finding prose in `findings/<slug>/<slug>.md` and derived design guidance under `hardening/` are optional for every scan mode. Finalization deterministically writes the unsealed `report.md` projection and links any recorded write-ups and hardening portfolio. Do not add these derived documents to the sealed artifact list.
116
118
  - Keep the full scan bundle together under `scan_dir`.
@@ -31,7 +31,9 @@ A sealed manifest records the completed timestamp and hashes for the canonical d
31
31
  Choose the target kind based on the reviewed content, not the scan invocation:
32
32
  `git_worktree` for a checked-out Git workspace, `directory_snapshot` for a non-Git directory, `git_diff` for a Git-backed change set, and `git_revision` for an exact immutable Git tree.
33
33
 
34
- For a workbench-backed scan, use the recorded target contract instead of inferring the kind from the checkout. A clean Git checkout has `allowedKinds: ["git_revision"]`: use its recorded revision and omit `snapshotDigest`. A dirty checkout has `allowedKinds: ["git_worktree"]`: copy `requiredSnapshotDigest` exactly.
34
+ For a workbench-backed scan, use the recorded target contract instead of inferring the kind from the checkout.
35
+ A clean Git checkout has `allowedKinds: ["git_revision"]`: use its recorded revision and omit `snapshotDigest`.
36
+ A dirty checkout has `allowedKinds: ["git_worktree"]`: copy `requiredSnapshotDigest` exactly.
35
37
 
36
38
  | Kind | Required snapshot fields |
37
39
  | --- | --- |
@@ -0,0 +1,42 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "codex-security://schemas/definitions/artifact-common.schema.json",
4
+ "$defs": {
5
+ "nonEmptyText": {
6
+ "type": "string",
7
+ "minLength": 1,
8
+ "pattern": "\\S"
9
+ },
10
+ "scanId": {
11
+ "type": "string",
12
+ "format": "uuid"
13
+ },
14
+ "repositoryPath": {
15
+ "type": "string",
16
+ "minLength": 1,
17
+ "maxLength": 4096,
18
+ "pattern": "^(?:\\./)?(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.\\.?(/|$))(?!.*//)(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
19
+ },
20
+ "candidateId": {
21
+ "type": "string",
22
+ "minLength": 1,
23
+ "maxLength": 512,
24
+ "pattern": "^(?!\\.{1,2}$)(?!.*[\\u0000-\\u001f\\u007f])(?=.*\\S)[^/\\\\]+$"
25
+ },
26
+ "page": {
27
+ "type": "object",
28
+ "properties": {
29
+ "cursor": {
30
+ "type": "string",
31
+ "pattern": "^(?:0|[1-9][0-9]*)$"
32
+ },
33
+ "limit": {
34
+ "type": "integer",
35
+ "minimum": 1,
36
+ "maximum": 1000
37
+ }
38
+ },
39
+ "additionalProperties": false
40
+ }
41
+ }
42
+ }
@@ -0,0 +1,100 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "codex-security://schemas/definitions/discovery-candidate.schema.json",
4
+ "$defs": {
5
+ "nonEmptyText": {
6
+ "type": "string",
7
+ "pattern": "\\S"
8
+ },
9
+ "cweId": {
10
+ "type": "string",
11
+ "pattern": "^\\s*[Cc][Ww][Ee]-0*[1-9][0-9]*\\s*$"
12
+ },
13
+ "locationRole": {
14
+ "enum": [
15
+ "entrypoint",
16
+ "entrypoint/wrapper",
17
+ "source",
18
+ "root_control",
19
+ "sink",
20
+ "concrete_implementation",
21
+ "evidence"
22
+ ]
23
+ },
24
+ "rawDiscoveryLocation": {
25
+ "type": "object",
26
+ "properties": {
27
+ "path": { "$ref": "#/$defs/nonEmptyText" },
28
+ "start_line": { "type": "integer", "minimum": 1 },
29
+ "end_line": { "type": "integer", "minimum": 1 },
30
+ "role": { "$ref": "#/$defs/locationRole" }
31
+ },
32
+ "required": ["path", "start_line", "role"],
33
+ "additionalProperties": false
34
+ },
35
+ "normalizedDiscoveryLocation": {
36
+ "type": "object",
37
+ "properties": {
38
+ "path": { "$ref": "#/$defs/nonEmptyText" },
39
+ "start_line": { "type": "integer", "minimum": 1 },
40
+ "end_line": { "type": "integer", "minimum": 1 },
41
+ "role": { "$ref": "#/$defs/locationRole" }
42
+ },
43
+ "required": ["path", "start_line", "end_line", "role"],
44
+ "additionalProperties": false
45
+ },
46
+ "rawDiscoveryCandidate": {
47
+ "type": "object",
48
+ "properties": {
49
+ "cwe_ids": {
50
+ "type": "array",
51
+ "items": { "$ref": "#/$defs/cweId" }
52
+ },
53
+ "locations": {
54
+ "type": "array",
55
+ "minItems": 1,
56
+ "items": { "$ref": "#/$defs/rawDiscoveryLocation" }
57
+ },
58
+ "summary": { "$ref": "#/$defs/nonEmptyText" },
59
+ "evidence": { "$ref": "#/$defs/nonEmptyText" },
60
+ "context": { "$ref": "#/$defs/nonEmptyText" },
61
+ "instance": { "$ref": "#/$defs/nonEmptyText" }
62
+ },
63
+ "required": ["cwe_ids", "locations", "summary", "evidence"],
64
+ "additionalProperties": false
65
+ },
66
+ "discoveryCandidate": {
67
+ "type": "object",
68
+ "properties": {
69
+ "candidate_id": {
70
+ "type": "string",
71
+ "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
72
+ },
73
+ "cwe_ids": {
74
+ "type": "array",
75
+ "items": {
76
+ "type": "string",
77
+ "pattern": "^CWE-[1-9][0-9]*$"
78
+ }
79
+ },
80
+ "locations": {
81
+ "type": "array",
82
+ "minItems": 1,
83
+ "items": { "$ref": "#/$defs/normalizedDiscoveryLocation" }
84
+ },
85
+ "summary": { "$ref": "#/$defs/nonEmptyText" },
86
+ "evidence": { "$ref": "#/$defs/nonEmptyText" },
87
+ "context": { "$ref": "#/$defs/nonEmptyText" },
88
+ "instance": { "$ref": "#/$defs/nonEmptyText" }
89
+ },
90
+ "required": [
91
+ "candidate_id",
92
+ "cwe_ids",
93
+ "locations",
94
+ "summary",
95
+ "evidence"
96
+ ],
97
+ "additionalProperties": true
98
+ }
99
+ }
100
+ }