@openai/codex-security 0.7.0 → 0.8.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 (153) hide show
  1. package/README.md +10 -4
  2. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  3. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  4. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  5. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  6. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  9. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/core-scan.md +2 -2
  17. package/_bundled_plugin/references/final-report.md +16 -6
  18. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  19. package/_bundled_plugin/references/scan-contract.md +10 -12
  20. package/_bundled_plugin/references/threat-model.md +1 -1
  21. package/_bundled_plugin/schemas/scan-manifest.schema.json +36 -11
  22. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  23. package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -1
  24. package/_bundled_plugin/scripts/finalize_scan_contract.py +60 -19
  25. package/_bundled_plugin/scripts/report_projection.py +5 -2
  26. package/_bundled_plugin/scripts/review_state.py +68 -0
  27. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  28. package/_bundled_plugin/scripts/workbench/retained_coverage.py +49 -37
  29. package/_bundled_plugin/scripts/workbench/retained_records.py +7 -7
  30. package/_bundled_plugin/scripts/workbench/saved_coverage.py +15 -15
  31. package/_bundled_plugin/scripts/workbench/saved_sources.py +24 -6
  32. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  33. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +4 -4
  34. package/_bundled_plugin/scripts/workbench_db.py +5 -150
  35. package/_bundled_plugin/scripts/workbench_saved_results.py +169 -4
  36. package/_bundled_plugin/scripts/workbench_scan_history.py +12 -7
  37. package/_bundled_plugin/skills/publish-findings/SKILL.md +5 -1
  38. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  39. package/_bundled_plugin/skills/security-scan/SKILL.md +6 -6
  40. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  41. package/dist/api.d.ts.map +1 -1
  42. package/dist/api.js +19 -17
  43. package/dist/api.js.map +1 -1
  44. package/dist/cli.d.ts.map +1 -1
  45. package/dist/cli.js +28 -17
  46. package/dist/cli.js.map +1 -1
  47. package/dist/cloud-publish.d.ts.map +1 -1
  48. package/dist/cloud-publish.js +2 -23
  49. package/dist/cloud-publish.js.map +1 -1
  50. package/dist/contract.d.ts +3 -2
  51. package/dist/contract.d.ts.map +1 -1
  52. package/dist/contract.js +28 -14
  53. package/dist/contract.js.map +1 -1
  54. package/dist/custom-publish.js +2 -2
  55. package/dist/custom-publish.js.map +1 -1
  56. package/dist/custom-validation-prompt.js +5 -5
  57. package/dist/custom-validation-prompt.js.map +1 -1
  58. package/dist/custom-validation.d.ts.map +1 -1
  59. package/dist/custom-validation.js +17 -15
  60. package/dist/custom-validation.js.map +1 -1
  61. package/dist/deduplication/codex-review.d.ts.map +1 -1
  62. package/dist/deduplication/codex-review.js +2 -2
  63. package/dist/deduplication/codex-review.js.map +1 -1
  64. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  65. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  66. package/dist/deduplication/deduplication-prompts.js +3 -0
  67. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  68. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  69. package/dist/deduplication/records-protocol.js +21 -1
  70. package/dist/deduplication/records-protocol.js.map +1 -1
  71. package/dist/deduplication/scan.d.ts.map +1 -1
  72. package/dist/deduplication/scan.js +2 -2
  73. package/dist/deduplication/scan.js.map +1 -1
  74. package/dist/external-findings-local.d.ts +1 -0
  75. package/dist/external-findings-local.d.ts.map +1 -1
  76. package/dist/external-findings-local.js +6 -2
  77. package/dist/external-findings-local.js.map +1 -1
  78. package/dist/external-findings-publish.d.ts +1 -0
  79. package/dist/external-findings-publish.d.ts.map +1 -1
  80. package/dist/external-findings-publish.js +53 -25
  81. package/dist/external-findings-publish.js.map +1 -1
  82. package/dist/external-findings-read.d.ts +1 -0
  83. package/dist/external-findings-read.d.ts.map +1 -1
  84. package/dist/external-findings-read.js +10 -0
  85. package/dist/external-findings-read.js.map +1 -1
  86. package/dist/external-findings.d.ts +2 -0
  87. package/dist/external-findings.d.ts.map +1 -1
  88. package/dist/external-findings.js.map +1 -1
  89. package/dist/external-import-contract.d.ts +4 -0
  90. package/dist/external-import-contract.d.ts.map +1 -1
  91. package/dist/external-import-contract.js +34 -10
  92. package/dist/external-import-contract.js.map +1 -1
  93. package/dist/finding-workflow.d.ts +2 -0
  94. package/dist/finding-workflow.d.ts.map +1 -1
  95. package/dist/finding-workflow.js +3 -0
  96. package/dist/finding-workflow.js.map +1 -1
  97. package/dist/host-protocol.d.ts +1 -1
  98. package/dist/host-protocol.d.ts.map +1 -1
  99. package/dist/host-protocol.js +2 -2
  100. package/dist/host-protocol.js.map +1 -1
  101. package/dist/hosted-scan.d.ts.map +1 -1
  102. package/dist/hosted-scan.js +0 -1
  103. package/dist/hosted-scan.js.map +1 -1
  104. package/dist/import-scan.js +16 -16
  105. package/dist/import-scan.js.map +1 -1
  106. package/dist/index.d.ts +1 -0
  107. package/dist/index.d.ts.map +1 -1
  108. package/dist/index.js +1 -0
  109. package/dist/index.js.map +1 -1
  110. package/dist/knowledge-base.js +3 -0
  111. package/dist/knowledge-base.js.map +1 -1
  112. package/dist/mock-scan.d.ts +1 -2
  113. package/dist/mock-scan.d.ts.map +1 -1
  114. package/dist/mock-scan.js +12 -17
  115. package/dist/mock-scan.js.map +1 -1
  116. package/dist/models.d.ts +9 -1
  117. package/dist/models.d.ts.map +1 -1
  118. package/dist/models.js.map +1 -1
  119. package/dist/multiscan.d.ts.map +1 -1
  120. package/dist/multiscan.js +1 -6
  121. package/dist/multiscan.js.map +1 -1
  122. package/dist/native-json-findings.d.ts +30 -0
  123. package/dist/native-json-findings.d.ts.map +1 -0
  124. package/dist/native-json-findings.js +114 -0
  125. package/dist/native-json-findings.js.map +1 -0
  126. package/dist/opengrep-findings.d.ts +10 -0
  127. package/dist/opengrep-findings.d.ts.map +1 -0
  128. package/dist/opengrep-findings.js +198 -0
  129. package/dist/opengrep-findings.js.map +1 -0
  130. package/dist/patch-tui.d.ts.map +1 -1
  131. package/dist/patch-tui.js +2 -0
  132. package/dist/patch-tui.js.map +1 -1
  133. package/dist/publication.js +1 -2
  134. package/dist/publication.js.map +1 -1
  135. package/dist/record.d.ts +1 -0
  136. package/dist/record.d.ts.map +1 -1
  137. package/dist/record.js +10 -0
  138. package/dist/record.js.map +1 -1
  139. package/dist/result.d.ts +5 -3
  140. package/dist/result.d.ts.map +1 -1
  141. package/dist/result.js +9 -6
  142. package/dist/result.js.map +1 -1
  143. package/dist/scan-history-renderer.js +1 -1
  144. package/dist/scan-history-renderer.js.map +1 -1
  145. package/dist/security-policy.d.ts.map +1 -1
  146. package/dist/security-policy.js +16 -2
  147. package/dist/security-policy.js.map +1 -1
  148. package/dist/semgrep-findings.d.ts.map +1 -1
  149. package/dist/semgrep-findings.js +15 -82
  150. package/dist/semgrep-findings.js.map +1 -1
  151. package/docs/cli.md +16 -3
  152. package/docs/dedupe-records.md +15 -1
  153. package/package.json +3 -3
@@ -8,7 +8,7 @@ A sealed terminal bundle contains these files under `<scan_dir>`:
8
8
 
9
9
  - `scan-manifest.json`: immutable terminal scan receipt after finalization
10
10
  - `findings.json`: semantic finding records retained when the scan reached its terminal outcome
11
- - `coverage.json`: structured coverage summary with detailed receipt references
11
+ - `scan.review`: additional excluded paths, stored in the manifest
12
12
 
13
13
  Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
14
14
 
@@ -37,7 +37,7 @@ Producers should use UTC ISO 8601 timestamps in the native SDK or plugin format.
37
37
  | `canceled` | The scan stopped after an explicit cancellation; retained artifacts may be partial. |
38
38
  | `interrupted` | The scan stopped before normal completion because execution was interrupted; retained artifacts may be partial. |
39
39
 
40
- Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and coverage while treating absence of findings as inconclusive.
40
+ Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and review state while treating absence of findings as inconclusive.
41
41
 
42
42
  Optional `scan.warnings` records run-level diagnostics available when the bundle is first sealed. SARIF exports include these messages alongside deferred-task reasons in `toolExecutionNotifications`; warnings do not change `executionSuccessful`, which follows `scan.status`. Missing or empty warnings add no notifications. Existing sealed bundles remain unchanged, and export or publication warnings discovered afterward remain separate operation diagnostics.
43
43
 
@@ -106,15 +106,15 @@ Examples:
106
106
 
107
107
  Use CWE taxonomy separately. Do not include file names, line numbers, scan IDs, or display numbering in `ruleId`.
108
108
 
109
- ## Coverage
109
+ ## Review state
110
110
 
111
- `coverage.json` records scan scope and completion information. Standard and diff summaries also describe reviewed surfaces and outstanding work.
111
+ New scans publish `scan-manifest.json` and `findings.json`. The manifest owns scan identity, mode, and configured scope. `scan.review` contains only `excludedPaths`, used when comparing scans. These values do not measure the percentage of files read.
112
112
 
113
113
  A Deep parent retains the configured paths and notes from accepted reviews. Worker IDs distinguish each review's surfaces and deferred items; receipt references point to the original evidence. Findings reduction does not clear pending review work. If the discovery deadline arrives before a review finishes, the host preserves valid checkpoint findings and pending work with the deadline reason. See [stopped-result recovery](#stopped-result-recovery).
114
114
 
115
- Each Deep worker writes an ordinary Standard result, including its own coverage. A reducer submits `record_codex_security_deep_reduction({ scanId, findings, scope?, threatModel? })`; its saved results and checkpoints contain the accepted findings and optional scope and threat-model context.
115
+ For file-authored drafts, put `reviewState` inside `scan` in the unsealed manifest. Finalization preserves recovery details in checkpoints and replaces the draft state with the small `scan.review` summary. For tool-authored drafts, pass `reviewState` to `record_codex_security_scan_draft`.
116
116
 
117
- For Standard and diff scans, record:
117
+ Deep reducers work on findings and do not need review state. Deep workers retain their own checkpoints. Comparison uses the later scan's execution status, configured scope, and additional exclusions before classifying an absent finding as resolved.
118
118
 
119
119
  - scan mode and inventory strategy
120
120
  - included and excluded paths
@@ -149,7 +149,7 @@ For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repe
149
149
  | `directory` | Deterministic non-Git directory inventory |
150
150
  | `custom` | Producer-defined inventory described by detailed receipts |
151
151
 
152
- Coverage lists reviewed surfaces, exclusions, and follow-up work. The manifest records execution status. Existing sealed bundles retain legacy metadata unchanged.
152
+ Review state lists reviewed surfaces, exclusions, and follow-up work. The manifest records execution status. Existing sealed bundles retain legacy metadata unchanged.
153
153
 
154
154
  Map detailed ledger closure into completed surface summaries in this order:
155
155
 
@@ -165,11 +165,11 @@ Record each explicit exclusion with a `pattern` and `reason`. Record each deferr
165
165
 
166
166
  Detailed ledgers remain under the numbered scan artifact directories.
167
167
  Receipt references must point to regular non-symlink files under `artifacts/`.
168
- `coverage.json` is the structured summary for adapters and comparison.
168
+ `scan.review` retains additional exclusions for adapters and comparison. Legacy sealed scans continue to reference their original `coverage.json`.
169
169
 
170
170
  ## Canonical Report Semantics
171
171
 
172
- The three canonical JSON files are also the only semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
172
+ The two canonical JSON files are also the only semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
173
173
 
174
174
  Record report-specific semantics without duplicating data already represented elsewhere:
175
175
 
@@ -182,8 +182,6 @@ Record report-specific semantics without duplicating data already represented el
182
182
  - finding `attackPath.reachability`: attacker, entry point, preconditions, outcome, and a concise reachability narrative.
183
183
  - finding `severity`: the assigned level plus rationale and the concrete evidence that would raise or lower it.
184
184
  - finding remediation: the existing minimal fix string plus optional tests and preventive controls.
185
- - coverage surfaces: optional `riskArea` and `notes` used by the Reviewed Surfaces table.
186
- - coverage `openQuestions`: concrete unresolved questions and optional copyable follow-up prompts.
187
185
 
188
186
  These fields are optional for compatibility with existing v1 canonical artifacts. When omitted, finalization emits explicit, deterministic fallback text derived only from the remaining canonical JSON. It never reads an existing report to recover missing semantics.
189
187
 
@@ -193,7 +191,7 @@ New completed findings must match `schemas/tools/scan-draft.schema.json`. Finali
193
191
 
194
192
  - `schemas/scan-manifest.schema.json`
195
193
  - `schemas/findings.schema.json`
196
- - `schemas/coverage.schema.json`
194
+ - `schemas/coverage.schema.json` for legacy scans only
197
195
 
198
196
  V1 consumers ignore unknown properties for forward compatibility. Producers must still validate documented fields and should not emit undocumented properties casually.
199
197
 
@@ -51,7 +51,7 @@ Generated models may include `origin: "generated"` and known `scope` (`includePa
51
51
  | `securityObjectives` | Enforceable invariants, including user-requested settings and limits |
52
52
  | `assumptions` | Prerequisites, exclusions, documentation/implementation discrepancies, and unknowns |
53
53
 
54
- Keep citations with the facts they support and label provided context. Use scenarios to direct investigation. Reconcile material scenarios with findings, source-backed dispositions, or open questions: put resolved control questions and rejections in `coverage.surfaces[].notes` with source anchors, and unresolved prerequisites in `coverage.openQuestions`. Retain established discrepancies even when no finding survives; do not create a separate speculative-finding registry.
54
+ Keep citations with the facts they support and label provided context. Use scenarios to direct investigation. Reconcile material scenarios with findings, source-backed dispositions, or open questions: put resolved control questions and rejections in `reviewState.surfaces[].notes` with source anchors, and unresolved prerequisites in `reviewState.openQuestions`. Retain established discrepancies even when no finding survives; do not create a separate speculative-finding registry.
55
55
 
56
56
  ## Standalone Model
57
57
 
@@ -134,6 +134,28 @@
134
134
  "required": ["portfolioPath"]
135
135
  },
136
136
  "coverageRef": { "const": "coverage.json" },
137
+ "mode": {
138
+ "enum": [
139
+ "repository",
140
+ "scoped_path",
141
+ "diff",
142
+ "commit",
143
+ "branch_diff",
144
+ "working_tree",
145
+ "deep_repository"
146
+ ]
147
+ },
148
+ "review": {
149
+ "type": "object",
150
+ "properties": {
151
+ "excludedPaths": { "type": "array", "items": { "type": "string" } }
152
+ },
153
+ "required": ["excludedPaths"]
154
+ },
155
+ "reviewState": {
156
+ "type": "object",
157
+ "propertyNames": { "type": "string" }
158
+ },
137
159
  "findingsRef": { "const": "findings.json" },
138
160
  "artifacts": {
139
161
  "minItems": 1,
@@ -162,7 +184,6 @@
162
184
  "sealedAt",
163
185
  "target",
164
186
  "scope",
165
- "coverageRef",
166
187
  "findingsRef",
167
188
  "artifacts"
168
189
  ],
@@ -181,17 +202,21 @@
181
202
  }
182
203
  },
183
204
  {
184
- "properties": {
185
- "artifacts": {
186
- "contains": {
187
- "type": "object",
188
- "required": ["path"],
189
- "properties": { "path": { "const": "coverage.json" } }
190
- },
191
- "minContains": 1,
192
- "maxContains": 1
205
+ "if": { "required": ["coverageRef"] },
206
+ "then": {
207
+ "properties": {
208
+ "artifacts": {
209
+ "contains": {
210
+ "type": "object",
211
+ "required": ["path"],
212
+ "properties": { "path": { "const": "coverage.json" } }
213
+ },
214
+ "minContains": 1,
215
+ "maxContains": 1
216
+ }
193
217
  }
194
- }
218
+ },
219
+ "else": { "required": ["mode", "review"] }
195
220
  }
196
221
  ]
197
222
  }
@@ -614,7 +614,7 @@
614
614
  "required": ["label", "disposition"],
615
615
  "additionalProperties": true
616
616
  },
617
- "coverage": {
617
+ "reviewState": {
618
618
  "type": "object",
619
619
  "properties": {
620
620
  "documentType": false,
@@ -722,7 +722,7 @@
722
722
  "properties": {
723
723
  "complete": {
724
724
  "type": "boolean",
725
- "description": "Set false to save progress without declaring this worker or parent audit finished. Omit or set true only for the terminal result. Put provisional candidates in coverage.deferred, not findings."
725
+ "description": "Set false to save progress without declaring this worker or parent audit finished. Omit or set true only for the terminal result. Put provisional candidates in reviewState.deferred, not findings."
726
726
  },
727
727
  "scanId": {
728
728
  "$ref": "codex-security://schemas/definitions/artifact-common.schema.json#/$defs/scanId"
@@ -742,11 +742,11 @@
742
742
  "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/finding"
743
743
  }
744
744
  },
745
- "coverage": {
746
- "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/coverage"
745
+ "reviewState": {
746
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/reviewState"
747
747
  }
748
748
  },
749
- "required": ["scanId", "findings", "coverage"],
749
+ "required": ["scanId", "findings", "reviewState"],
750
750
  "additionalProperties": false
751
751
  },
752
752
  "completedScanInput": {
@@ -1791,7 +1791,7 @@ def finish_deep_scan_locked(
1791
1791
  )
1792
1792
  canonical_artifacts = None
1793
1793
  if standard_scan_manifest:
1794
- for artifact_name in ("scan-manifest.json", "findings.json", "coverage.json"):
1794
+ for artifact_name in ("scan-manifest.json", "findings.json"):
1795
1795
  deep_scan_path(
1796
1796
  scan,
1797
1797
  str(Path(scan["scan_dir"]) / artifact_name),
@@ -27,6 +27,7 @@ from urllib.parse import quote, urlsplit
27
27
  sys.path.insert(0, str(Path(__file__).resolve().parent))
28
28
  import report_projection
29
29
  import threat_model_projection
30
+ from review_state import checkpoint_review_state, review_state, review_summary
30
31
 
31
32
  SCHEMA_VERSION = "1.0"
32
33
  PRODUCER_NAME = "codex-security-plugin"
@@ -1467,8 +1468,9 @@ def _populate_unsealed_manifest_envelope(
1467
1468
  scan["status"] = (
1468
1469
  completion_binding.get("status", "completed") if completion_binding else "completed"
1469
1470
  )
1470
- scan["coverageRef"] = "coverage.json"
1471
1471
  scan["findingsRef"] = "findings.json"
1472
+ if "coverageRef" in scan:
1473
+ scan["coverageRef"] = "coverage.json"
1472
1474
  if completion_binding is None:
1473
1475
  started_at = os.environ.get("CODEX_SECURITY_STARTED_AT")
1474
1476
  if started_at is not None:
@@ -1881,7 +1883,7 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1881
1883
  artifact_collision_keys.add(collision_key)
1882
1884
  _require_str(artifact, "sha256", context)
1883
1885
  _require_str(artifact, "mediaType", context)
1884
- for required_path in ("findings.json", "coverage.json"):
1886
+ for required_path in ("findings.json", *(["coverage.json"] if "coverageRef" in scan else [])):
1885
1887
  if required_path not in artifact_paths:
1886
1888
  raise ContractError(
1887
1889
  f"manifest.scan.artifacts: missing required artifact: {required_path}"
@@ -2305,6 +2307,9 @@ def _validate_canonical_schemas_before_projection(
2305
2307
  {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
2306
2308
  {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
2307
2309
  ]
2310
+ if "coverageRef" not in provisional_scan:
2311
+ provisional_scan["mode"] = coverage["mode"]
2312
+ provisional_scan["review"] = review_summary(coverage)
2308
2313
  validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
2309
2314
  validate_against_schema(findings, schema_dir / "findings.schema.json")
2310
2315
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
@@ -2315,6 +2320,8 @@ def _validate_contract_refs(scan: dict[str, Any]) -> None:
2315
2320
  ("coverageRef", "coverage.json"),
2316
2321
  ("findingsRef", "findings.json"),
2317
2322
  ):
2323
+ if field == "coverageRef" and field not in scan:
2324
+ continue
2318
2325
  actual = _require_str(scan, field, "manifest.scan")
2319
2326
  if actual != expected:
2320
2327
  raise ContractError(f"manifest.scan.{field}: expected {expected!r}")
@@ -2793,17 +2800,15 @@ def _read_sealed_artifacts(
2793
2800
  findings, findings_bytes = _read_scan_local_json_bytes(
2794
2801
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2795
2802
  )
2796
- coverage, coverage_bytes = _read_scan_local_json_bytes(
2797
- scan_dir, scan["coverageRef"], scan["coverageRef"]
2798
- )
2799
- _validate_existing_seal(
2800
- scan_dir,
2801
- scan,
2802
- artifact_contents={
2803
- scan["findingsRef"]: findings_bytes,
2804
- scan["coverageRef"]: coverage_bytes,
2805
- },
2806
- )
2803
+ contents = {scan["findingsRef"]: findings_bytes}
2804
+ if "coverageRef" in scan:
2805
+ coverage, coverage_bytes = _read_scan_local_json_bytes(
2806
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
2807
+ )
2808
+ contents[scan["coverageRef"]] = coverage_bytes
2809
+ else:
2810
+ coverage = review_state(scan)
2811
+ _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
2807
2812
  return findings, coverage, findings_bytes
2808
2813
 
2809
2814
 
@@ -3133,6 +3138,14 @@ def _prepare_scan_finalization(
3133
3138
  if scan.get("sealedAt") is None and scan.get("artifacts") == []:
3134
3139
  del scan["artifacts"]
3135
3140
  was_sealed = manifest_is_sealed(scan)
3141
+ if (
3142
+ not was_sealed
3143
+ and "review" not in scan
3144
+ and "reviewState" not in scan
3145
+ and draft_documents is None
3146
+ and (scan_dir / "coverage.json").exists()
3147
+ ):
3148
+ scan["coverageRef"] = "coverage.json"
3136
3149
  if not was_sealed:
3137
3150
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3138
3151
  _validate_contract_refs(scan)
@@ -3140,9 +3153,13 @@ def _prepare_scan_finalization(
3140
3153
  findings, findings_input_bytes = _read_scan_local_json_bytes(
3141
3154
  scan_dir, scan["findingsRef"], scan["findingsRef"]
3142
3155
  )
3143
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3144
- scan_dir, scan["coverageRef"], scan["coverageRef"]
3145
- )
3156
+ if "coverageRef" in scan:
3157
+ coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3158
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
3159
+ )
3160
+ else:
3161
+ coverage = review_state(scan)
3162
+ coverage_input_bytes = _json_bytes(coverage)
3146
3163
  else:
3147
3164
  findings, coverage = copy.deepcopy(draft_documents[1:])
3148
3165
  findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
@@ -3174,7 +3191,7 @@ def _prepare_scan_finalization(
3174
3191
  scan,
3175
3192
  artifact_contents={
3176
3193
  scan["findingsRef"]: findings_input_bytes,
3177
- scan["coverageRef"]: coverage_input_bytes,
3194
+ **({scan["coverageRef"]: coverage_input_bytes} if "coverageRef" in scan else {}),
3178
3195
  },
3179
3196
  )
3180
3197
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
@@ -3256,11 +3273,19 @@ def _prepare_scan_finalization(
3256
3273
  else:
3257
3274
  findings_bytes = _contract_json_bytes("findings.json", findings)
3258
3275
  coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3276
+ if "coverageRef" not in scan:
3277
+ scan["mode"] = coverage["mode"]
3278
+ scan["review"] = review_summary(coverage)
3279
+ scan.pop("reviewState", None)
3259
3280
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3260
3281
  _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3261
3282
  scan["artifacts"] = [
3262
3283
  _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
3263
- _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
3284
+ *(
3285
+ [_artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes)]
3286
+ if "coverageRef" in scan
3287
+ else []
3288
+ ),
3264
3289
  *[
3265
3290
  _artifact_record(scan_dir, ref, "application/octet-stream")
3266
3291
  for ref in _supplementary_artifact_refs(scan, coverage)
@@ -3311,7 +3336,23 @@ def _write_prepared_scan_finalization(
3311
3336
  prepared.manifest, prepared.schema_dir / "scan-manifest.schema.json"
3312
3337
  )
3313
3338
  _write_scan_local_json(scan_dir, "findings.json", prepared.findings)
3314
- _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3339
+ if "coverageRef" in scan:
3340
+ _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3341
+ elif "preservedSources" not in scan and not (scan_dir / "checkpoint-head.json").exists():
3342
+ checkpoint = {
3343
+ "scanId": scan["id"],
3344
+ "complete": scan["status"] == "completed",
3345
+ "scope": scan["scope"],
3346
+ "findings": prepared.findings["findings"],
3347
+ "reviewState": checkpoint_review_state(prepared.coverage),
3348
+ **({"threatModel": scan["threatModel"]} if "threatModel" in scan else {}),
3349
+ }
3350
+ contents = _json_bytes(checkpoint)
3351
+ name = hashlib.sha256(contents).hexdigest() + ".json"
3352
+ write_scan_local_bytes(scan_dir, "checkpoints/" + name, contents)
3353
+ _write_scan_local_json(scan_dir, "checkpoint-head.json", {"checkpoint": name})
3354
+ if not prepared.was_sealed and "coverageRef" not in scan:
3355
+ _remove_scan_local_file_if_exists(scan_dir, "coverage.json")
3315
3356
  sealed_paths = (
3316
3357
  [artifact["path"] for artifact in scan["artifacts"]] if prepared.was_sealed else []
3317
3358
  )
@@ -787,6 +787,10 @@ def build_report_markdown(
787
787
  manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
788
788
  ) -> str:
789
789
  scan = manifest["scan"]
790
+ if "review" in scan and "coverageRef" not in scan:
791
+ from review_state import review_state
792
+
793
+ coverage = review_state(scan)
790
794
  target = scan["target"]
791
795
  scope = scan["scope"]
792
796
  threat_model = scan.get("threatModel") if isinstance(scan.get("threatModel"), dict) else {}
@@ -832,7 +836,6 @@ def build_report_markdown(
832
836
  "",
833
837
  f"- Scan mode: {coverage['mode']}",
834
838
  *_target_scope_lines(target),
835
- f"- Inventory strategy: {coverage['inventoryStrategy']}",
836
839
  f"- Included paths: {', '.join(include_paths) or 'none'}",
837
840
  f"- Excluded paths: {', '.join(exclude_paths) or 'none'}",
838
841
  ]
@@ -874,7 +877,7 @@ def build_report_markdown(
874
877
  *summary_count_lines,
875
878
  f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
876
879
  "",
877
- "Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.",
880
+ "Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.",
878
881
  "",
879
882
  "## Threat Model",
880
883
  "",
@@ -0,0 +1,68 @@
1
+ """Keep review bookkeeping separate from published scan results."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import copy
7
+ from typing import Any
8
+
9
+
10
+ def uses_legacy_review(scan: dict[str, Any]) -> bool:
11
+ return "coverageRef" in scan or ("reviewState" not in scan and "review" not in scan)
12
+
13
+
14
+ def review_summary(state: dict[str, Any]) -> dict[str, Any]:
15
+ return {
16
+ "excludedPaths": [item["pattern"] for item in state.get("explicitExclusions", [])],
17
+ }
18
+
19
+
20
+ def review_state(scan: dict[str, Any]) -> dict[str, Any]:
21
+ """Read new manifest metadata using the recovery code's existing representation."""
22
+ summary = scan.get("review", {})
23
+ state = copy.deepcopy(scan.get("reviewState", {}))
24
+ mode = scan.get("mode", "repository")
25
+ state.setdefault("surfaces", [])
26
+ state.setdefault("deferred", [])
27
+ state.setdefault(
28
+ "explicitExclusions",
29
+ [
30
+ {"pattern": path, "reason": "Excluded from review"}
31
+ for path in summary.get("excludedPaths", [])
32
+ ],
33
+ )
34
+ state.update(
35
+ documentType="codex-security.coverage",
36
+ schemaVersion="1.0",
37
+ scanId=scan.get("id"),
38
+ mode=mode,
39
+ inventoryStrategy="scoped_path"
40
+ if mode == "scoped_path"
41
+ else "diff"
42
+ if mode in {"diff", "commit", "branch_diff", "working_tree"}
43
+ else "repository",
44
+ includePaths=copy.deepcopy(scan.get("scope", {}).get("includePaths", [])),
45
+ excludePaths=copy.deepcopy(scan.get("scope", {}).get("excludePaths", [])),
46
+ )
47
+ return state
48
+
49
+
50
+ def checkpoint_review_state(state: dict[str, Any]) -> dict[str, Any]:
51
+ """Retain unfinished work and candidate outcomes, without a coverage report."""
52
+ return {
53
+ "surfaces": [
54
+ {key: copy.deepcopy(value) for key, value in item.items() if key != "riskArea"}
55
+ for item in state.get("surfaces", [])
56
+ ],
57
+ "explicitExclusions": copy.deepcopy(state.get("explicitExclusions", [])),
58
+ "deferred": copy.deepcopy(state.get("deferred", [])),
59
+ **{
60
+ key: copy.deepcopy(state[key])
61
+ for key in ("resolvedDeferred", "openQuestions", "reviews")
62
+ if key in state
63
+ },
64
+ }
65
+
66
+
67
+ if __name__ == "__main__":
68
+ argparse.ArgumentParser(description=__doc__).parse_args()
@@ -41,7 +41,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
41
41
  "scanDir": str(scan_dir),
42
42
  "manifest": manifest,
43
43
  "findings": findings,
44
- "coverage": coverage,
44
+ "review": FINALIZER.review_summary(coverage),
45
45
  }
46
46
 
47
47
 
@@ -53,7 +53,6 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:
53
53
  "scanDir": str(scan_dir),
54
54
  "manifestPath": str(scan_dir / "scan-manifest.json"),
55
55
  "findingsPath": str(scan_dir / scan["findingsRef"]),
56
- "coveragePath": str(scan_dir / scan["coverageRef"]),
57
56
  "reportPath": str(scan_dir / "report.md"),
58
57
  }
59
58