@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.
- package/README.md +10 -4
- package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
- package/_bundled_plugin/examples/completed-scan/report.md +22 -31
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
- package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
- package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
- package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
- package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
- package/_bundled_plugin/references/core-scan.md +2 -2
- package/_bundled_plugin/references/final-report.md +16 -6
- package/_bundled_plugin/references/scan-artifacts.md +5 -5
- package/_bundled_plugin/references/scan-contract.md +10 -12
- package/_bundled_plugin/references/threat-model.md +1 -1
- package/_bundled_plugin/schemas/scan-manifest.schema.json +36 -11
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
- package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +60 -19
- package/_bundled_plugin/scripts/report_projection.py +5 -2
- package/_bundled_plugin/scripts/review_state.py +68 -0
- package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +49 -37
- package/_bundled_plugin/scripts/workbench/retained_records.py +7 -7
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +15 -15
- package/_bundled_plugin/scripts/workbench/saved_sources.py +24 -6
- package/_bundled_plugin/scripts/workbench_constants.py +0 -1
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +4 -4
- package/_bundled_plugin/scripts/workbench_db.py +5 -150
- package/_bundled_plugin/scripts/workbench_saved_results.py +169 -4
- package/_bundled_plugin/scripts/workbench_scan_history.py +12 -7
- package/_bundled_plugin/skills/publish-findings/SKILL.md +5 -1
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
- package/_bundled_plugin/skills/security-scan/SKILL.md +6 -6
- package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +19 -17
- package/dist/api.js.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +28 -17
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +2 -23
- package/dist/cloud-publish.js.map +1 -1
- package/dist/contract.d.ts +3 -2
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +28 -14
- package/dist/contract.js.map +1 -1
- package/dist/custom-publish.js +2 -2
- package/dist/custom-publish.js.map +1 -1
- package/dist/custom-validation-prompt.js +5 -5
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +17 -15
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js +2 -2
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +1 -0
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +3 -0
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/records-protocol.d.ts.map +1 -1
- package/dist/deduplication/records-protocol.js +21 -1
- package/dist/deduplication/records-protocol.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +2 -2
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/external-findings-local.d.ts +1 -0
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +6 -2
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +1 -0
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +53 -25
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +1 -0
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +10 -0
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +2 -0
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +4 -0
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +34 -10
- package/dist/external-import-contract.js.map +1 -1
- package/dist/finding-workflow.d.ts +2 -0
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +3 -0
- package/dist/finding-workflow.js.map +1 -1
- package/dist/host-protocol.d.ts +1 -1
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +2 -2
- package/dist/host-protocol.js.map +1 -1
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +0 -1
- package/dist/hosted-scan.js.map +1 -1
- package/dist/import-scan.js +16 -16
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.js +3 -0
- package/dist/knowledge-base.js.map +1 -1
- package/dist/mock-scan.d.ts +1 -2
- package/dist/mock-scan.d.ts.map +1 -1
- package/dist/mock-scan.js +12 -17
- package/dist/mock-scan.js.map +1 -1
- package/dist/models.d.ts +9 -1
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +1 -6
- package/dist/multiscan.js.map +1 -1
- package/dist/native-json-findings.d.ts +30 -0
- package/dist/native-json-findings.d.ts.map +1 -0
- package/dist/native-json-findings.js +114 -0
- package/dist/native-json-findings.js.map +1 -0
- package/dist/opengrep-findings.d.ts +10 -0
- package/dist/opengrep-findings.d.ts.map +1 -0
- package/dist/opengrep-findings.js +198 -0
- package/dist/opengrep-findings.js.map +1 -0
- package/dist/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +2 -0
- package/dist/patch-tui.js.map +1 -1
- package/dist/publication.js +1 -2
- package/dist/publication.js.map +1 -1
- package/dist/record.d.ts +1 -0
- package/dist/record.d.ts.map +1 -1
- package/dist/record.js +10 -0
- package/dist/record.js.map +1 -1
- package/dist/result.d.ts +5 -3
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +9 -6
- package/dist/result.js.map +1 -1
- package/dist/scan-history-renderer.js +1 -1
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +16 -2
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +15 -82
- package/dist/semgrep-findings.js.map +1 -1
- package/docs/cli.md +16 -3
- package/docs/dedupe-records.md +15 -1
- 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
|
-
- `
|
|
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
|
|
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
|
-
##
|
|
109
|
+
## Review state
|
|
110
110
|
|
|
111
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
|
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 `
|
|
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
|
-
"
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
"
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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
|
-
"
|
|
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
|
|
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
|
-
"
|
|
746
|
-
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/
|
|
745
|
+
"reviewState": {
|
|
746
|
+
"$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/reviewState"
|
|
747
747
|
}
|
|
748
748
|
},
|
|
749
|
-
"required": ["scanId", "findings", "
|
|
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"
|
|
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
|
-
|
|
2797
|
-
|
|
2798
|
-
|
|
2799
|
-
|
|
2800
|
-
|
|
2801
|
-
scan
|
|
2802
|
-
|
|
2803
|
-
|
|
2804
|
-
|
|
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
|
-
|
|
3144
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
"
|
|
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
|
|