@openai/codex-security 0.1.31 → 0.2.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 (314) hide show
  1. package/README.md +295 -32
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +4 -4
  5. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  6. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +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/references/artifact-storage.md +4 -4
  16. package/_bundled_plugin/references/config-preflight.md +1 -1
  17. package/_bundled_plugin/references/core-scan.md +14 -2
  18. package/_bundled_plugin/references/final-report.md +4 -2
  19. package/_bundled_plugin/references/scan-artifacts.md +2 -2
  20. package/_bundled_plugin/references/scan-contract.md +2 -2
  21. package/_bundled_plugin/references/threat-model.md +2 -2
  22. package/_bundled_plugin/schemas/coverage.schema.json +22 -0
  23. package/_bundled_plugin/schemas/scan-manifest.schema.json +100 -85
  24. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +116 -102
  25. package/_bundled_plugin/scripts/config_preflight.py +4 -8
  26. package/_bundled_plugin/scripts/deep_scan_workbench.py +83 -217
  27. package/_bundled_plugin/scripts/filesystem_identity.py +1 -5
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +441 -166
  29. package/_bundled_plugin/scripts/finding_preview.py +42 -82
  30. package/_bundled_plugin/scripts/generate_in_scope_files.py +30 -34
  31. package/_bundled_plugin/scripts/generate_rank_input.py +58 -99
  32. package/_bundled_plugin/scripts/launch_codex_security_mcp +5 -1
  33. package/_bundled_plugin/scripts/rank_preview.py +85 -68
  34. package/_bundled_plugin/scripts/report_projection.py +37 -58
  35. package/_bundled_plugin/scripts/threat_model_projection.py +164 -0
  36. package/_bundled_plugin/scripts/windows_scan_local_files.py +11 -6
  37. package/_bundled_plugin/scripts/workbench/storage.py +11 -0
  38. package/_bundled_plugin/scripts/workbench_cli.py +11 -17
  39. package/_bundled_plugin/scripts/workbench_constants.py +6 -14
  40. package/_bundled_plugin/scripts/workbench_db.py +116 -228
  41. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -6
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -4
  43. package/_bundled_plugin/scripts/workbench_progress.py +12 -34
  44. package/_bundled_plugin/scripts/workbench_publication.py +47 -62
  45. package/_bundled_plugin/scripts/workbench_remediation.py +2 -20
  46. package/_bundled_plugin/scripts/workbench_saved_results.py +1246 -230
  47. package/_bundled_plugin/scripts/workbench_scan_start.py +4 -11
  48. package/_bundled_plugin/scripts/workbench_scan_usage.py +7 -15
  49. package/_bundled_plugin/scripts/workbench_schema.py +86 -271
  50. package/_bundled_plugin/scripts/workbench_severity.py +3 -0
  51. package/_bundled_plugin/scripts/workbench_source_excerpt.py +5 -6
  52. package/_bundled_plugin/scripts/workbench_target.py +98 -10
  53. package/_bundled_plugin/scripts/workbench_target_state.py +1 -5
  54. package/_bundled_plugin/scripts/workbench_validation.py +6 -20
  55. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +3 -3
  56. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +3 -3
  57. package/_bundled_plugin/skills/security-scan/SKILL.md +2 -2
  58. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  59. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  60. package/dist/api.d.ts +3 -5
  61. package/dist/api.d.ts.map +1 -1
  62. package/dist/api.js +201 -207
  63. package/dist/api.js.map +1 -1
  64. package/dist/artifact-export.d.ts +70 -0
  65. package/dist/artifact-export.d.ts.map +1 -0
  66. package/dist/artifact-export.js +277 -0
  67. package/dist/artifact-export.js.map +1 -0
  68. package/dist/auth.d.ts.map +1 -1
  69. package/dist/auth.js +8 -3
  70. package/dist/auth.js.map +1 -1
  71. package/dist/bulk-scan-discovery.d.ts +1 -0
  72. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  73. package/dist/bulk-scan-discovery.js +8 -9
  74. package/dist/bulk-scan-discovery.js.map +1 -1
  75. package/dist/classify-scan-severity.d.ts.map +1 -1
  76. package/dist/classify-scan-severity.js +2 -5
  77. package/dist/classify-scan-severity.js.map +1 -1
  78. package/dist/classify-severity.d.ts +2 -8
  79. package/dist/classify-severity.d.ts.map +1 -1
  80. package/dist/classify-severity.js +3 -5
  81. package/dist/classify-severity.js.map +1 -1
  82. package/dist/cli-help.d.ts +3 -0
  83. package/dist/cli-help.d.ts.map +1 -0
  84. package/dist/cli-help.js +281 -0
  85. package/dist/cli-help.js.map +1 -0
  86. package/dist/cli.d.ts +19 -22
  87. package/dist/cli.d.ts.map +1 -1
  88. package/dist/cli.js +631 -714
  89. package/dist/cli.js.map +1 -1
  90. package/dist/cloud-publish.d.ts.map +1 -1
  91. package/dist/cloud-publish.js +1 -8
  92. package/dist/cloud-publish.js.map +1 -1
  93. package/dist/codex-prompt.d.ts.map +1 -1
  94. package/dist/codex-prompt.js +1 -2
  95. package/dist/codex-prompt.js.map +1 -1
  96. package/dist/codex-sdk-environment.d.ts +2 -0
  97. package/dist/codex-sdk-environment.d.ts.map +1 -0
  98. package/dist/codex-sdk-environment.js +30 -0
  99. package/dist/codex-sdk-environment.js.map +1 -0
  100. package/dist/component-plan.d.ts.map +1 -1
  101. package/dist/component-plan.js +2 -6
  102. package/dist/component-plan.js.map +1 -1
  103. package/dist/component-scan.d.ts +1 -0
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +31 -9
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/config.d.ts.map +1 -1
  108. package/dist/config.js +32 -33
  109. package/dist/config.js.map +1 -1
  110. package/dist/contract.d.ts +2 -1
  111. package/dist/contract.d.ts.map +1 -1
  112. package/dist/contract.js +63 -122
  113. package/dist/contract.js.map +1 -1
  114. package/dist/cost-model.d.ts.map +1 -1
  115. package/dist/cost-model.js +65 -34
  116. package/dist/cost-model.js.map +1 -1
  117. package/dist/cost.d.ts.map +1 -1
  118. package/dist/cost.js +15 -31
  119. package/dist/cost.js.map +1 -1
  120. package/dist/custom-validation-prompt.js +4 -4
  121. package/dist/custom-validation-prompt.js.map +1 -1
  122. package/dist/custom-validation.d.ts.map +1 -1
  123. package/dist/custom-validation.js +17 -16
  124. package/dist/custom-validation.js.map +1 -1
  125. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  126. package/dist/deduplication/checkpointed-review.js +10 -11
  127. package/dist/deduplication/checkpointed-review.js.map +1 -1
  128. package/dist/deduplication/codex-review.d.ts +2 -0
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +3 -3
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  133. package/dist/deduplication/deduplication-reviewer.js +2 -0
  134. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  135. package/dist/deduplication/deduplication.js +40 -62
  136. package/dist/deduplication/deduplication.js.map +1 -1
  137. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  138. package/dist/deduplication/records-protocol.js +1 -4
  139. package/dist/deduplication/records-protocol.js.map +1 -1
  140. package/dist/deduplication/records.d.ts +2 -1
  141. package/dist/deduplication/records.d.ts.map +1 -1
  142. package/dist/deduplication/records.js +24 -6
  143. package/dist/deduplication/records.js.map +1 -1
  144. package/dist/deduplication/review.d.ts +7 -0
  145. package/dist/deduplication/review.d.ts.map +1 -1
  146. package/dist/deduplication/review.js.map +1 -1
  147. package/dist/deduplication/scan.js +3 -7
  148. package/dist/deduplication/scan.js.map +1 -1
  149. package/dist/deep-config.d.ts.map +1 -1
  150. package/dist/deep-config.js +3 -19
  151. package/dist/deep-config.js.map +1 -1
  152. package/dist/deep-progress.d.ts +0 -1
  153. package/dist/deep-progress.d.ts.map +1 -1
  154. package/dist/deep-progress.js +22 -40
  155. package/dist/deep-progress.js.map +1 -1
  156. package/dist/errors.d.ts +3 -2
  157. package/dist/errors.d.ts.map +1 -1
  158. package/dist/errors.js +5 -7
  159. package/dist/errors.js.map +1 -1
  160. package/dist/finding-catalogue.d.ts.map +1 -1
  161. package/dist/finding-catalogue.js +22 -22
  162. package/dist/finding-catalogue.js.map +1 -1
  163. package/dist/finding-workflow.d.ts.map +1 -1
  164. package/dist/finding-workflow.js +4 -7
  165. package/dist/finding-workflow.js.map +1 -1
  166. package/dist/findings-import.d.ts.map +1 -1
  167. package/dist/findings-import.js +7 -17
  168. package/dist/findings-import.js.map +1 -1
  169. package/dist/github.d.ts.map +1 -1
  170. package/dist/github.js +2 -3
  171. package/dist/github.js.map +1 -1
  172. package/dist/import-scan.js +2 -2
  173. package/dist/import-scan.js.map +1 -1
  174. package/dist/index.d.ts +4 -2
  175. package/dist/index.d.ts.map +1 -1
  176. package/dist/index.js +2 -1
  177. package/dist/index.js.map +1 -1
  178. package/dist/knowledge-base.js +2 -2
  179. package/dist/knowledge-base.js.map +1 -1
  180. package/dist/linear.d.ts.map +1 -1
  181. package/dist/linear.js +2 -3
  182. package/dist/linear.js.map +1 -1
  183. package/dist/models.d.ts +24 -0
  184. package/dist/models.d.ts.map +1 -1
  185. package/dist/models.js.map +1 -1
  186. package/dist/multiscan.d.ts.map +1 -1
  187. package/dist/multiscan.js +36 -31
  188. package/dist/multiscan.js.map +1 -1
  189. package/dist/owner-evidence.d.ts.map +1 -1
  190. package/dist/owner-evidence.js +2 -6
  191. package/dist/owner-evidence.js.map +1 -1
  192. package/dist/patch-tui.d.ts.map +1 -1
  193. package/dist/patch-tui.js +2 -4
  194. package/dist/patch-tui.js.map +1 -1
  195. package/dist/project-config-schema.d.ts +10 -0
  196. package/dist/project-config-schema.d.ts.map +1 -1
  197. package/dist/project-config-schema.js +1 -0
  198. package/dist/project-config-schema.js.map +1 -1
  199. package/dist/project-config.d.ts +1 -0
  200. package/dist/project-config.d.ts.map +1 -1
  201. package/dist/project-config.js +2 -0
  202. package/dist/project-config.js.map +1 -1
  203. package/dist/prompt-files.d.ts +0 -1
  204. package/dist/prompt-files.d.ts.map +1 -1
  205. package/dist/prompt-files.js +2 -4
  206. package/dist/prompt-files.js.map +1 -1
  207. package/dist/publication-events.d.ts.map +1 -1
  208. package/dist/publication-events.js +15 -29
  209. package/dist/publication-events.js.map +1 -1
  210. package/dist/publication-store.d.ts.map +1 -1
  211. package/dist/publication-store.js +9 -13
  212. package/dist/publication-store.js.map +1 -1
  213. package/dist/publication.d.ts.map +1 -1
  214. package/dist/publication.js +11 -14
  215. package/dist/publication.js.map +1 -1
  216. package/dist/publish.d.ts.map +1 -1
  217. package/dist/publish.js +31 -41
  218. package/dist/publish.js.map +1 -1
  219. package/dist/record.d.ts +2 -0
  220. package/dist/record.d.ts.map +1 -0
  221. package/dist/record.js +4 -0
  222. package/dist/record.js.map +1 -0
  223. package/dist/result.d.ts +4 -1
  224. package/dist/result.d.ts.map +1 -1
  225. package/dist/result.js +7 -0
  226. package/dist/result.js.map +1 -1
  227. package/dist/runtime.d.ts +10 -13
  228. package/dist/runtime.d.ts.map +1 -1
  229. package/dist/runtime.js +203 -131
  230. package/dist/runtime.js.map +1 -1
  231. package/dist/saved-scan.d.ts.map +1 -1
  232. package/dist/saved-scan.js +10 -20
  233. package/dist/saved-scan.js.map +1 -1
  234. package/dist/scan-activity.d.ts.map +1 -1
  235. package/dist/scan-activity.js +8 -22
  236. package/dist/scan-activity.js.map +1 -1
  237. package/dist/scan-comparison.d.ts +3 -3
  238. package/dist/scan-comparison.d.ts.map +1 -1
  239. package/dist/scan-comparison.js +38 -73
  240. package/dist/scan-comparison.js.map +1 -1
  241. package/dist/scan-dashboard.d.ts +0 -1
  242. package/dist/scan-dashboard.d.ts.map +1 -1
  243. package/dist/scan-dashboard.js +10 -19
  244. package/dist/scan-dashboard.js.map +1 -1
  245. package/dist/scan-history-renderer.d.ts.map +1 -1
  246. package/dist/scan-history-renderer.js +1 -2
  247. package/dist/scan-history-renderer.js.map +1 -1
  248. package/dist/scan-logs.d.ts.map +1 -1
  249. package/dist/scan-logs.js +2 -6
  250. package/dist/scan-logs.js.map +1 -1
  251. package/dist/scan-sessions.d.ts.map +1 -1
  252. package/dist/scan-sessions.js +1 -3
  253. package/dist/scan-sessions.js.map +1 -1
  254. package/dist/scan-settings.d.ts +5 -0
  255. package/dist/scan-settings.d.ts.map +1 -1
  256. package/dist/scan-settings.js +4 -0
  257. package/dist/scan-settings.js.map +1 -1
  258. package/dist/security-policy-cli.d.ts.map +1 -1
  259. package/dist/security-policy-cli.js +8 -6
  260. package/dist/security-policy-cli.js.map +1 -1
  261. package/dist/security-policy.d.ts +8 -4
  262. package/dist/security-policy.d.ts.map +1 -1
  263. package/dist/security-policy.js +98 -84
  264. package/dist/security-policy.js.map +1 -1
  265. package/dist/server/dashboard/app.js +5 -5
  266. package/dist/server/embeddings.d.ts.map +1 -1
  267. package/dist/server/embeddings.js +1 -0
  268. package/dist/server/embeddings.js.map +1 -1
  269. package/dist/server/routes.d.ts +3 -2
  270. package/dist/server/routes.d.ts.map +1 -1
  271. package/dist/server/routes.js +19 -7
  272. package/dist/server/routes.js.map +1 -1
  273. package/dist/server/server.d.ts.map +1 -1
  274. package/dist/server/server.js +2 -3
  275. package/dist/server/server.js.map +1 -1
  276. package/dist/server/sqlite-store.d.ts.map +1 -1
  277. package/dist/server/sqlite-store.js +4 -14
  278. package/dist/server/sqlite-store.js.map +1 -1
  279. package/dist/severity-store.js +8 -15
  280. package/dist/severity-store.js.map +1 -1
  281. package/dist/suggest-owners.d.ts +2 -3
  282. package/dist/suggest-owners.d.ts.map +1 -1
  283. package/dist/suggest-owners.js +4 -5
  284. package/dist/suggest-owners.js.map +1 -1
  285. package/dist/targets.d.ts +1 -0
  286. package/dist/targets.d.ts.map +1 -1
  287. package/dist/targets.js +24 -21
  288. package/dist/targets.js.map +1 -1
  289. package/dist/trusted-executable.d.ts +5 -0
  290. package/dist/trusted-executable.d.ts.map +1 -1
  291. package/dist/trusted-executable.js +22 -5
  292. package/dist/trusted-executable.js.map +1 -1
  293. package/dist/value.d.ts +2 -0
  294. package/dist/value.d.ts.map +1 -0
  295. package/dist/value.js +20 -0
  296. package/dist/value.js.map +1 -0
  297. package/dist/version.d.ts.map +1 -1
  298. package/dist/version.js +3 -6
  299. package/dist/version.js.map +1 -1
  300. package/dist/windows-path.d.ts.map +1 -1
  301. package/dist/windows-path.js +1 -2
  302. package/dist/windows-path.js.map +1 -1
  303. package/dist/worker-progress.d.ts +1 -0
  304. package/dist/worker-progress.d.ts.map +1 -1
  305. package/dist/worker-progress.js +13 -34
  306. package/dist/worker-progress.js.map +1 -1
  307. package/docs/dedupe-records.md +24 -0
  308. package/package.json +11 -10
  309. package/schemas/project-config.schema.json +5 -0
  310. package/_bundled_plugin/scripts/normalize_candidates.py +0 -338
  311. package/dist/server/findings-service.d.ts +0 -20
  312. package/dist/server/findings-service.d.ts.map +0 -1
  313. package/dist/server/findings-service.js +0 -31
  314. package/dist/server/findings-service.js.map +0 -1
@@ -16,9 +16,9 @@ import os
16
16
  import re
17
17
  import secrets
18
18
  import stat
19
+ import struct
19
20
  import sys
20
21
  import time
21
- from collections.abc import Iterator
22
22
  from datetime import datetime, timezone
23
23
  from pathlib import Path, PurePosixPath
24
24
  from typing import Any, TextIO
@@ -73,6 +73,13 @@ EXPORT_PATHS = {
73
73
  "json": "exports/findings.json",
74
74
  "sarif": "exports/results.sarif",
75
75
  }
76
+ THREAT_MODEL_EXPORT_PATH = "exports/threatmodel.md"
77
+ _LEGACY_THREAT_MODEL_PATHS = (
78
+ "threatmodel.md",
79
+ "THREAT_MODEL.md",
80
+ "artifacts/01_context/threat_model.md",
81
+ "threat_model.md",
82
+ )
76
83
  WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
77
84
  r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
78
85
  re.IGNORECASE,
@@ -138,8 +145,217 @@ def _generate_report_projection(
138
145
  raise AssertionError("Report projection retry loop exhausted unexpectedly.")
139
146
 
140
147
 
141
- def _validate_report_output_paths(scan_dir: Path) -> None:
142
- _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
148
+ def _threat_model_renderer() -> Any:
149
+ script = Path(__file__).resolve().with_name("threat_model_projection.py")
150
+ spec = importlib.util.spec_from_file_location("codex_security_threat_model_projection", script)
151
+ if spec is None or spec.loader is None:
152
+ raise ContractError(f"could not load threat model projection helper: {script}")
153
+ module = importlib.util.module_from_spec(spec)
154
+ spec.loader.exec_module(module)
155
+ return module
156
+
157
+
158
+ def threat_model_provenance(manifest: dict[str, Any]) -> dict[str, Any]:
159
+ if manifest.get("documentType") == "codex-security.policy-draft":
160
+ scope = manifest.get("scope")
161
+ return {
162
+ "source": "policy",
163
+ "target": manifest.get("repository"),
164
+ "revision": manifest.get("revision"),
165
+ "scanScope": {"includePaths": [scope], "excludePaths": []} if scope else None,
166
+ "status": manifest.get("status", "completed"),
167
+ "provisional": manifest.get("status", "completed") != "completed",
168
+ }
169
+ scan = _require_dict(manifest, "scan", "manifest")
170
+ target = _require_dict(scan, "target", "manifest.scan") if "target" in scan else {}
171
+ status = scan.get("status")
172
+ if status == "completed" and not scan.get("sealedAt"):
173
+ status = "draft"
174
+ return {
175
+ "source": "scan",
176
+ "scanId": scan.get("id"),
177
+ "target": target.get("displayName"),
178
+ "revision": target.get("revision") or target.get("headRevision"),
179
+ "snapshotDigest": target.get("snapshotDigest"),
180
+ "scanScope": scan.get("scope"),
181
+ "status": status,
182
+ "provisional": scan.get("status") != "completed" or not scan.get("sealedAt"),
183
+ }
184
+
185
+
186
+ def _render_threat_model(model: dict[str, Any], provenance: dict[str, Any]) -> bytes:
187
+ try:
188
+ return _threat_model_renderer().render_threat_model(model, provenance)
189
+ except (TypeError, ValueError) as exc:
190
+ raise ContractError(f"threat model projection failed: {exc}") from exc
191
+
192
+
193
+ def _read_saved_threat_model(
194
+ scan_dir: Path, *, validate_seal: bool = True, schema_dir: Path | None = None
195
+ ) -> tuple[dict[str, Any], bytes] | None:
196
+ """Read canonical content first; old documents are a read-only compatibility path."""
197
+ scan_dir = _require_scan_directory(scan_dir)
198
+ saved_provenance: dict[str, Any] | None = None
199
+ sealed_artifact_paths: set[str] | None = None
200
+ scan_manifest_path = scan_dir / "scan-manifest.json"
201
+ filename = (
202
+ "scan-manifest.json"
203
+ if scan_manifest_path.exists() or scan_manifest_path.is_symlink()
204
+ else "policy-draft.json"
205
+ )
206
+ manifest_path = scan_dir / filename
207
+ if manifest_path.exists() or manifest_path.is_symlink():
208
+ manifest = _read_scan_local_json(scan_dir, filename, filename)
209
+ scan = (
210
+ _require_dict(manifest, "scan", "manifest")
211
+ if filename == "scan-manifest.json"
212
+ else manifest
213
+ )
214
+ if (
215
+ validate_seal
216
+ and filename == "scan-manifest.json"
217
+ and (scan.get("sealedAt") is not None or scan.get("artifacts"))
218
+ ):
219
+ if "threatModel" not in scan:
220
+ _validate_manifest(manifest)
221
+ recorded_paths = {
222
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
223
+ for artifact in scan["artifacts"]
224
+ }
225
+ if recorded_paths.isdisjoint(_LEGACY_THREAT_MODEL_PATHS):
226
+ validate_against_schema(
227
+ manifest,
228
+ (schema_dir or Path(__file__).resolve().parent.parent / "schemas")
229
+ / "scan-manifest.schema.json",
230
+ )
231
+ return None
232
+ manifest, _, _, _ = _read_sealed_scan(scan_dir, schema_dir, "threat model export")
233
+ scan = manifest["scan"]
234
+ sealed_artifact_paths = {
235
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
236
+ for artifact in scan["artifacts"]
237
+ }
238
+ provenance = threat_model_provenance(manifest)
239
+ saved_provenance = provenance
240
+ if "threatModel" in scan:
241
+ model = _require_dict(
242
+ scan,
243
+ "threatModel",
244
+ "manifest.scan" if filename == "scan-manifest.json" else "policy draft",
245
+ )
246
+ contents = _render_threat_model(model, provenance)
247
+ path = scan_dir / "threatmodel.md"
248
+ current_path = None
249
+ try:
250
+ descriptor = open_scan_local_file_descriptor(
251
+ scan_dir, "threatmodel.md", "Saved threat model"
252
+ )
253
+ with os.fdopen(descriptor, "rb") as handle:
254
+ if handle.read() == contents:
255
+ current_path = str(path)
256
+ except (ContractError, OSError):
257
+ # An unavailable projection does not invalidate the canonical model.
258
+ pass
259
+ return {
260
+ "threatModel": model,
261
+ "provenance": provenance,
262
+ "path": current_path,
263
+ }, contents
264
+ for filename in _LEGACY_THREAT_MODEL_PATHS:
265
+ if sealed_artifact_paths is not None and filename not in sealed_artifact_paths:
266
+ continue
267
+ path = scan_dir / filename
268
+ if not path.exists() and not path.is_symlink():
269
+ continue
270
+ descriptor, filename = _open_scan_local_file_with_path(
271
+ scan_dir,
272
+ filename,
273
+ "Saved threat model",
274
+ resolve_spelling=sealed_artifact_paths is None,
275
+ )
276
+ path = scan_dir / filename
277
+ with os.fdopen(descriptor, "rb") as handle:
278
+ contents = handle.read()
279
+ try:
280
+ body = contents.decode("utf-8")
281
+ except UnicodeDecodeError as exc:
282
+ raise ContractError(f"{filename}: expected UTF-8 Markdown") from exc
283
+ if body.strip():
284
+ return {
285
+ "threatModel": {"format": "markdown", "content": body},
286
+ "provenance": saved_provenance
287
+ or {"source": filename, "status": "unknown", "provisional": True},
288
+ "path": str(path),
289
+ }, contents
290
+ return None
291
+
292
+
293
+ def describe_threat_model(scan_dir: Path, schema_dir: Path | None = None) -> dict[str, Any]:
294
+ saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
295
+ if saved is None:
296
+ raise ContractError("No saved threat model is available for this result.")
297
+ return saved[0]
298
+
299
+
300
+ def build_threat_model_export(scan_dir: Path, schema_dir: Path | None = None) -> bytes:
301
+ saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
302
+ if saved is None:
303
+ raise ContractError("No saved threat model is available for this result.")
304
+ return saved[1]
305
+
306
+
307
+ def write_threat_model_projection_if_possible(
308
+ scan_dir: Path, manifest: dict[str, Any] | None = None
309
+ ) -> str | None:
310
+ """A convenience document failure must not discard saved canonical content."""
311
+ try:
312
+ saved_manifest = manifest
313
+ if saved_manifest is None and (scan_dir / "scan-manifest.json").exists():
314
+ saved_manifest = _read_scan_local_json(
315
+ scan_dir, "scan-manifest.json", "scan-manifest.json"
316
+ )
317
+ if (
318
+ saved_manifest is not None
319
+ and saved_manifest.get("documentType") != "codex-security.policy-draft"
320
+ ):
321
+ scan = _require_dict(saved_manifest, "scan", "manifest")
322
+ artifacts = (
323
+ _require_list(scan, "artifacts", "manifest.scan") if "artifacts" in scan else []
324
+ )
325
+ for index, artifact in enumerate(artifacts):
326
+ if not isinstance(artifact, dict):
327
+ continue
328
+ context = f"manifest.scan.artifacts[{index}]"
329
+ path = _require_portable_relative_path(
330
+ _require_str(artifact, "path", context), f"{context}.path"
331
+ )
332
+ if path.lower() == "threatmodel.md":
333
+ return None
334
+ if manifest is None:
335
+ saved = _read_saved_threat_model(scan_dir, validate_seal=False)
336
+ if saved is None:
337
+ return None
338
+ contents = saved[1]
339
+ else:
340
+ scan = (
341
+ manifest
342
+ if manifest.get("documentType") == "codex-security.policy-draft"
343
+ else _require_dict(manifest, "scan", "manifest")
344
+ )
345
+ model = scan.get("threatModel")
346
+ if not isinstance(model, dict):
347
+ return None
348
+ contents = _render_threat_model(model, threat_model_provenance(manifest))
349
+ write_scan_local_bytes(scan_dir, "threatmodel.md", contents, owner_read_write=True)
350
+ return None
351
+ except (ContractError, OSError) as exc:
352
+ warning = (
353
+ f"Automatic threat model save failed: {exc}. "
354
+ "Saved canonical content can be exported with `codex-security export "
355
+ "<result-dir> --artifact threat-model`."
356
+ )
357
+ print(f"codex-security: warning: {warning}", file=sys.stderr)
358
+ return warning
143
359
 
144
360
 
145
361
  def _json_bytes(payload: Any) -> bytes:
@@ -192,22 +408,6 @@ def _require_safe_json_string(value: str, context: str) -> None:
192
408
  raise ContractError(f"{context}: expected well-formed Unicode JSON strings") from exc
193
409
 
194
410
 
195
- def _sha256_text(value: str) -> str:
196
- return hashlib.sha256(value.encode("utf-8")).hexdigest()
197
-
198
-
199
- def _sha256_bytes(value: bytes) -> str:
200
- return hashlib.sha256(value).hexdigest()
201
-
202
-
203
- def _sha256_file(path: Path) -> str:
204
- digest = hashlib.sha256()
205
- with path.open("rb") as handle:
206
- for chunk in iter(lambda: handle.read(1024 * 1024), b""):
207
- digest.update(chunk)
208
- return digest.hexdigest()
209
-
210
-
211
411
  def _require_dict(payload: dict[str, Any], key: str, context: str) -> dict[str, Any]:
212
412
  value = payload.get(key)
213
413
  if not isinstance(value, dict):
@@ -294,10 +494,6 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
294
494
  raise ContractError(f"{relative_path}: expected a regular file")
295
495
 
296
496
 
297
- def _descriptor_relative_reads_available() -> bool:
298
- return os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")
299
-
300
-
301
497
  def _is_windows() -> bool:
302
498
  return os.name == "nt"
303
499
 
@@ -394,13 +590,22 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
394
590
 
395
591
 
396
592
  def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
593
+ return _open_scan_local_file_with_path(scan_dir, relative_path, context)[0]
594
+
595
+
596
+ def _open_scan_local_file_with_path(
597
+ scan_dir: Path, relative_path: str, context: str, *, resolve_spelling: bool = False
598
+ ) -> tuple[int, str]:
397
599
  scan_dir = _require_scan_directory(scan_dir)
398
600
  relative_path = _require_portable_relative_path(relative_path, context)
399
- if not _descriptor_relative_reads_available():
601
+ if not (os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")):
400
602
  if not _is_windows():
401
603
  raise ContractError("scan-local input requires descriptor-relative file operations")
402
604
  try:
403
- return _windows_scan_local_files().open_read_fd(scan_dir, relative_path, context)
605
+ backend = _windows_scan_local_files()
606
+ if resolve_spelling:
607
+ return backend.open_read_fd_with_path(scan_dir, relative_path, context)
608
+ return backend.open_read_fd(scan_dir, relative_path, context), relative_path
404
609
  except OSError as exc:
405
610
  raise ContractError(str(exc)) from exc
406
611
  root_fd: int | None = None
@@ -432,9 +637,22 @@ def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context:
432
637
  metadata = os.fstat(descriptor)
433
638
  if not stat.S_ISREG(metadata.st_mode):
434
639
  raise ContractError(f"{context}: expected a regular non-symlink file")
640
+ if resolve_spelling:
641
+ names = os.listdir(parent_fd)
642
+ if parts[-1] not in names:
643
+ for name in names:
644
+ if name.casefold() != parts[-1].casefold():
645
+ continue
646
+ try:
647
+ entry = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
648
+ except FileNotFoundError:
649
+ continue
650
+ if os.path.samestat(metadata, entry):
651
+ relative_path = PurePosixPath(relative_path).with_name(name).as_posix()
652
+ break
435
653
  result = descriptor
436
654
  descriptor = None
437
- return result
655
+ return result, relative_path
438
656
  finally:
439
657
  if descriptor is not None:
440
658
  os.close(descriptor)
@@ -478,14 +696,15 @@ def _require_hardening_portfolio_file(scan_dir: Path, scan: dict[str, Any]) -> N
478
696
  )
479
697
 
480
698
 
481
- def _read_scan_local_json_bytes(
699
+ def _read_scan_local_json_with_metadata(
482
700
  scan_dir: Path, relative_path: str, context: str
483
- ) -> tuple[dict[str, Any], bytes]:
701
+ ) -> tuple[dict[str, Any], bytes, os.stat_result]:
484
702
  descriptor = open_scan_local_file_descriptor(scan_dir, relative_path, context)
485
703
  try:
486
704
  with os.fdopen(descriptor, "rb") as handle:
487
705
  descriptor = -1
488
706
  raw = handle.read()
707
+ metadata = os.fstat(handle.fileno())
489
708
  try:
490
709
  payload = _loads_json(raw.decode("utf-8"))
491
710
  except (UnicodeDecodeError, ValueError) as exc:
@@ -496,6 +715,13 @@ def _read_scan_local_json_bytes(
496
715
  finally:
497
716
  if descriptor >= 0:
498
717
  os.close(descriptor)
718
+ return payload, raw, metadata
719
+
720
+
721
+ def _read_scan_local_json_bytes(
722
+ scan_dir: Path, relative_path: str, context: str
723
+ ) -> tuple[dict[str, Any], bytes]:
724
+ payload, raw, _ = _read_scan_local_json_with_metadata(scan_dir, relative_path, context)
499
725
  return payload, raw
500
726
 
501
727
 
@@ -525,6 +751,7 @@ def write_scan_local_bytes(
525
751
  *,
526
752
  external_name: bool = False,
527
753
  expected_root_identity: tuple[int, int] | None = None,
754
+ owner_read_write: bool = False,
528
755
  ) -> None:
529
756
  scan_dir = _require_scan_directory(scan_dir)
530
757
  if external_name:
@@ -603,6 +830,9 @@ def write_scan_local_bytes(
603
830
  temp_name = f".{path.name}.{secrets.token_hex(8)}.tmp"
604
831
  temp_fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
605
832
  with os.fdopen(temp_fd, "wb") as handle:
833
+ if owner_read_write:
834
+ # Generated Markdown must remain editable under a restrictive umask.
835
+ os.fchmod(handle.fileno(), 0o600)
606
836
  handle.write(payload)
607
837
  handle.flush()
608
838
  os.fsync(handle.fileno())
@@ -689,11 +919,7 @@ def _validate_target(target: dict[str, Any]) -> None:
689
919
  _validate_remote(remote, "scan.target.remote")
690
920
  if kind == "git_revision":
691
921
  _require_str(target, "revision", "scan.target")
692
- elif kind == "git_worktree":
693
- _require_str(target, "snapshotDigest", "scan.target")
694
- elif kind == "git_diff":
695
- _require_str(target, "snapshotDigest", "scan.target")
696
- elif kind == "directory_snapshot":
922
+ elif kind in ("git_worktree", "git_diff", "directory_snapshot"):
697
923
  _require_str(target, "snapshotDigest", "scan.target")
698
924
 
699
925
 
@@ -711,11 +937,11 @@ def _fingerprint(target_id: str, finding: dict[str, Any]) -> str:
711
937
  if not SLUG_RE.fullmatch(rule_id):
712
938
  raise ContractError("finding.ruleId: expected a stable lowercase rule slug")
713
939
  material = "\0".join((FINGERPRINT_ALGORITHM, target_id, rule_id, anchor, instance))
714
- return f"{FINGERPRINT_ALGORITHM}:sha256:{_sha256_text(material)}"
940
+ return f"{FINGERPRINT_ALGORITHM}:sha256:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"
715
941
 
716
942
 
717
943
  def _stable_id(prefix: str, *parts: str) -> str:
718
- return f"{prefix}_{_sha256_text(chr(0).join(parts))[:24]}"
944
+ return f"{prefix}_{hashlib.sha256(chr(0).join(parts).encode('utf-8')).hexdigest()[:24]}"
719
945
 
720
946
 
721
947
  def _validate_location(location: dict[str, Any], context: str) -> None:
@@ -1087,6 +1313,19 @@ def _recover_unsealed_coverage(
1087
1313
  )
1088
1314
  partial = True
1089
1315
 
1316
+ if "resolvedDeferred" in coverage:
1317
+ try:
1318
+ _validate_schema_node(
1319
+ coverage["resolvedDeferred"],
1320
+ properties["resolvedDeferred"],
1321
+ "coverage.resolvedDeferred",
1322
+ )
1323
+ _validate_resolved_deferred(coverage)
1324
+ except ContractError as exc:
1325
+ coverage.pop("resolvedDeferred")
1326
+ warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
1327
+ partial = True
1328
+
1090
1329
  if coverage["deferred"] and completeness != "partial":
1091
1330
  if not discarded_findings:
1092
1331
  warnings.append("Coverage has deferred review work; marked coverage as partial.")
@@ -1162,11 +1401,14 @@ def _populate_unsealed_manifest_envelope(
1162
1401
  scan["completedAt"] = completion_binding["completedAt"]
1163
1402
  scan["producer"] = copy.deepcopy(completion_binding["producer"])
1164
1403
 
1165
- target = scan.get("target")
1404
+ target = scan.setdefault("target", {})
1166
1405
  if isinstance(target, dict):
1406
+ allowed_kinds = completion_binding["allowedTargetKinds"]
1407
+ if len(allowed_kinds) == 1:
1408
+ target.setdefault("kind", allowed_kinds[0])
1167
1409
  _populate_unsealed_target_binding(target, completion_binding["target"])
1168
1410
 
1169
- scope = scan.get("scope")
1411
+ scope = scan.setdefault("scope", {})
1170
1412
  if isinstance(scope, dict):
1171
1413
  scope.update(copy.deepcopy(completion_binding["scope"]))
1172
1414
 
@@ -1394,6 +1636,30 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1394
1636
  raise ContractError(f"{context}.extensions: expected an object")
1395
1637
 
1396
1638
 
1639
+ def _validate_resolved_deferred(coverage: dict[str, Any]) -> None:
1640
+ if "resolvedDeferred" not in coverage:
1641
+ return
1642
+ active = {
1643
+ identity
1644
+ for row in coverage.get("deferred", [])
1645
+ if isinstance(row, dict)
1646
+ for identity in (row.get("id"), row.get("candidateId"))
1647
+ if isinstance(identity, str)
1648
+ }
1649
+ resolved: set[str] = set()
1650
+ for index, closure in enumerate(_require_list(coverage, "resolvedDeferred", "coverage")):
1651
+ context = f"coverage.resolvedDeferred[{index}]"
1652
+ if not isinstance(closure, dict):
1653
+ raise ContractError(f"{context}: expected an object")
1654
+ closure_id = _require_str(closure, "id", context)
1655
+ _require_str(closure, "reason", context)
1656
+ if closure_id in resolved:
1657
+ raise ContractError(f"{context}.id: duplicate resolved deferred id")
1658
+ if closure_id in active:
1659
+ raise ContractError(f"{context}.id: deferred work is still active")
1660
+ resolved.add(closure_id)
1661
+
1662
+
1397
1663
  def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_dir: Path) -> None:
1398
1664
  scan = _require_dict(manifest, "scan", "manifest")
1399
1665
  scan_id = _require_str(scan, "id", "manifest.scan")
@@ -1442,6 +1708,7 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1442
1708
  for field in ("explicitExclusions", "deferred"):
1443
1709
  if not isinstance(coverage.get(field, []), list):
1444
1710
  raise ContractError(f"coverage.{field}: expected an array")
1711
+ _validate_resolved_deferred(coverage)
1445
1712
  if completeness == "complete" and (has_needs_follow_up or coverage.get("deferred")):
1446
1713
  raise ContractError("coverage.completeness: complete coverage cannot have deferred work")
1447
1714
  _require_safe_json_value(coverage, "coverage.json")
@@ -1581,6 +1848,17 @@ def _validate_schema_node(
1581
1848
  root_schema: dict[str, Any] | None = None,
1582
1849
  ) -> None:
1583
1850
  root_schema = schema if root_schema is None else root_schema
1851
+ alternatives = schema.get("anyOf")
1852
+ if isinstance(alternatives, list):
1853
+ errors = []
1854
+ for alternative in alternatives:
1855
+ try:
1856
+ _validate_schema_node(value, alternative, context, root_schema)
1857
+ break
1858
+ except ContractError as exc:
1859
+ errors.append(str(exc))
1860
+ else:
1861
+ raise ContractError(f"{context}: no schema alternative matched: {'; '.join(errors)}")
1584
1862
  reference = schema.get("$ref")
1585
1863
  if reference is not None:
1586
1864
  if not isinstance(reference, str):
@@ -1726,7 +2004,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1726
2004
  continue
1727
2005
  canonical_evidence = finding.get("codeEvidence")
1728
2006
  canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
1729
- canonical_evidence_ids = {
2007
+ evidence_ids = {
1730
2008
  evidence["id"]
1731
2009
  for evidence in canonical_evidence
1732
2010
  if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
@@ -1734,7 +2012,6 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1734
2012
  legacy_evidence = finding.get("code_evidence")
1735
2013
  if isinstance(legacy_evidence, list):
1736
2014
  compatible_legacy_evidence = []
1737
- seen_evidence_ids = set(canonical_evidence_ids)
1738
2015
  for evidence in legacy_evidence:
1739
2016
  if not isinstance(evidence, dict):
1740
2017
  continue
@@ -1747,22 +2024,13 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1747
2024
  or not evidence_code.strip()
1748
2025
  ):
1749
2026
  continue
1750
- if evidence_id in seen_evidence_ids:
2027
+ if evidence_id in evidence_ids:
1751
2028
  continue
1752
- seen_evidence_ids.add(evidence_id)
2029
+ evidence_ids.add(evidence_id)
1753
2030
  compatible_legacy_evidence.append(evidence)
1754
2031
  finding["code_evidence"] = compatible_legacy_evidence
1755
2032
  elif "code_evidence" in finding:
1756
2033
  finding.pop("code_evidence")
1757
- compatible_legacy_evidence = finding.get("code_evidence")
1758
- compatible_legacy_evidence = (
1759
- compatible_legacy_evidence if isinstance(compatible_legacy_evidence, list) else []
1760
- )
1761
- evidence_ids = canonical_evidence_ids | {
1762
- evidence["id"]
1763
- for evidence in compatible_legacy_evidence
1764
- if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1765
- }
1766
2034
  for section_name, list_fields in (
1767
2035
  ("rootCause", ("evidenceRefs", "evidence_refs")),
1768
2036
  ("root_cause", ("evidenceRefs", "evidence_refs")),
@@ -1937,12 +2205,6 @@ def _sarif_finding_message(finding: dict[str, Any]) -> str:
1937
2205
  return "\n\n".join(details)
1938
2206
 
1939
2207
 
1940
- def _utf16_code_units(value: str) -> Iterator[int]:
1941
- encoded = value.encode("utf-16-le")
1942
- for index in range(0, len(encoded), 2):
1943
- yield int.from_bytes(encoded[index : index + 2], "little")
1944
-
1945
-
1946
2208
  def _github_line_hashes(
1947
2209
  handle: TextIO,
1948
2210
  requested_lines: set[int] | None = None,
@@ -1995,7 +2257,7 @@ def _github_line_hashes(
1995
2257
  update_hash(current)
1996
2258
 
1997
2259
  while chunk := handle.read(SOURCE_READ_CHUNK_SIZE):
1998
- for code_unit in _utf16_code_units(chunk):
2260
+ for (code_unit,) in struct.iter_unpack("<H", chunk.encode("utf-16-le")):
1999
2261
  process_character(code_unit)
2000
2262
  process_character(GITHUB_HASH_EOF)
2001
2263
  for _ in range(GITHUB_HASH_BLOCK_SIZE):
@@ -2294,23 +2556,6 @@ def build_sarif(
2294
2556
  }
2295
2557
 
2296
2558
 
2297
- def _validate_sarif(sarif: dict[str, Any]) -> None:
2298
- if sarif.get("version") != "2.1.0":
2299
- raise ContractError("SARIF: expected version 2.1.0")
2300
- runs = sarif.get("runs")
2301
- if not isinstance(runs, list) or len(runs) != 1:
2302
- raise ContractError("SARIF: expected exactly one run")
2303
- run = runs[0]
2304
- if not isinstance(run, dict):
2305
- raise ContractError("SARIF: expected a run object")
2306
- rule_ids = [rule["id"] for rule in run["tool"]["driver"]["rules"]]
2307
- for result in run["results"]:
2308
- if result["ruleId"] not in rule_ids:
2309
- raise ContractError("SARIF: result references an unknown rule")
2310
- if not result.get("partialFingerprints"):
2311
- raise ContractError("SARIF: result is missing partialFingerprints")
2312
-
2313
-
2314
2559
  def _artifact_record(
2315
2560
  scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
2316
2561
  ) -> dict[str, str]:
@@ -2321,7 +2566,7 @@ def _artifact_record(
2321
2566
  "mediaType": media_type,
2322
2567
  "path": relative_path,
2323
2568
  "sha256": (
2324
- _sha256_bytes(contents)
2569
+ hashlib.sha256(contents).hexdigest()
2325
2570
  if contents is not None
2326
2571
  else _sha256_scan_local_file(scan_dir, relative_path, relative_path)
2327
2572
  ),
@@ -2357,7 +2602,6 @@ def _validate_existing_seal(
2357
2602
  raise ContractError("manifest.scan.sealedAt: must match completedAt")
2358
2603
  if not isinstance(artifacts, list) or not artifacts:
2359
2604
  raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
2360
- artifact_paths: set[str] = set()
2361
2605
  artifact_collision_keys: set[str] = set()
2362
2606
  for index, artifact in enumerate(artifacts):
2363
2607
  context = f"manifest.scan.artifacts[{index}]"
@@ -2369,12 +2613,11 @@ def _validate_existing_seal(
2369
2613
  collision_key = path.lower()
2370
2614
  if collision_key in artifact_collision_keys:
2371
2615
  raise ContractError(f"{context}.path: duplicate artifact path")
2372
- artifact_paths.add(path)
2373
2616
  artifact_collision_keys.add(collision_key)
2374
2617
  expected_sha256 = _require_str(artifact, "sha256", context)
2375
2618
  contents = (artifact_contents or {}).get(path)
2376
2619
  actual_sha256 = (
2377
- _sha256_bytes(contents)
2620
+ hashlib.sha256(contents).hexdigest()
2378
2621
  if contents is not None
2379
2622
  else _sha256_scan_local_file(scan_dir, path, context)
2380
2623
  )
@@ -2444,7 +2687,6 @@ def build_sarif_projection(
2444
2687
  ],
2445
2688
  }
2446
2689
  ]
2447
- _validate_sarif(sarif)
2448
2690
  return sarif
2449
2691
 
2450
2692
 
@@ -2455,13 +2697,9 @@ def write_sarif_projection(
2455
2697
  _write_scan_local_json(scan_dir, "exports/results.sarif", sarif)
2456
2698
 
2457
2699
 
2458
- def write_sarif_output(scan_dir: Path, output: Path, sarif: dict[str, Any]) -> None:
2459
- write_export_output(scan_dir, output, "sarif", _json_bytes(sarif))
2460
-
2461
-
2462
2700
  def csv_cell(value: Any) -> Any:
2463
2701
  if isinstance(value, str) and (
2464
- value.startswith(("\t", "\r", "\n"))
2702
+ value.startswith(("'", "\t", "\r", "\n"))
2465
2703
  or value.lstrip().startswith(("=", "+", "-", "@", "=", "+", "-", "@"))
2466
2704
  ):
2467
2705
  return f"'{value}"
@@ -2489,6 +2727,25 @@ def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2489
2727
  )
2490
2728
 
2491
2729
 
2730
+ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2731
+ return (
2732
+ "occurrence_id",
2733
+ "finding_id",
2734
+ *(("candidate_id",) if deep_scan else ()),
2735
+ "title",
2736
+ "summary",
2737
+ "severity",
2738
+ "confidence",
2739
+ "status",
2740
+ "close_reason",
2741
+ "note",
2742
+ "remediation",
2743
+ "path",
2744
+ "start_line",
2745
+ "end_line",
2746
+ )
2747
+
2748
+
2492
2749
  def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
2493
2750
  output = io.StringIO(newline="")
2494
2751
  writer = csv.writer(output)
@@ -2504,24 +2761,7 @@ def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) ->
2504
2761
  for finding in findings["findings"]
2505
2762
  )
2506
2763
  )
2507
- writer.writerow(
2508
- (
2509
- "occurrence_id",
2510
- "finding_id",
2511
- *(("candidate_id",) if deep_scan else ()),
2512
- "title",
2513
- "summary",
2514
- "severity",
2515
- "confidence",
2516
- "status",
2517
- "close_reason",
2518
- "note",
2519
- "remediation",
2520
- "path",
2521
- "start_line",
2522
- "end_line",
2523
- )
2524
- )
2764
+ writer.writerow(finding_csv_columns(deep_scan))
2525
2765
  for finding in findings["findings"]:
2526
2766
  locations = finding["locations"]
2527
2767
  location = next(
@@ -2570,7 +2810,8 @@ def build_findings_export(
2570
2810
 
2571
2811
 
2572
2812
  def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
2573
- if export_format not in EXPORT_PATHS:
2813
+ output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
2814
+ if export_format not in output_paths:
2574
2815
  raise ContractError(f"unsupported export format: {export_format}")
2575
2816
  scan_dir = _require_scan_directory(scan_dir)
2576
2817
  output = Path(os.path.abspath(output))
@@ -2594,13 +2835,22 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2594
2835
  relative_output = output.relative_to(ancestor).as_posix()
2595
2836
  break
2596
2837
  else:
2597
- write_scan_local_bytes(output.parent, output.name, contents, external_name=True)
2838
+ write_scan_local_bytes(
2839
+ output.parent,
2840
+ output.name,
2841
+ contents,
2842
+ external_name=True,
2843
+ owner_read_write=export_format == "md",
2844
+ )
2598
2845
  return
2599
- if relative_output != EXPORT_PATHS[export_format]:
2846
+ if relative_output != output_paths[export_format]:
2600
2847
  raise ContractError(f"{export_format.upper()} output path cannot overwrite a scan artifact")
2601
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2602
- scan = _require_dict(manifest, "scan", "manifest")
2603
- artifacts = _require_list(scan, "artifacts", "manifest.scan")
2848
+ if (scan_dir / "scan-manifest.json").exists():
2849
+ manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2850
+ scan = _require_dict(manifest, "scan", "manifest")
2851
+ artifacts = scan.get("artifacts", [])
2852
+ else:
2853
+ artifacts = []
2604
2854
  artifact_paths = [
2605
2855
  _require_portable_relative_path(
2606
2856
  _require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
@@ -2633,7 +2883,9 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2633
2883
  raise ContractError(
2634
2884
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2635
2885
  )
2636
- write_scan_local_bytes(scan_dir, relative_output, contents)
2886
+ write_scan_local_bytes(
2887
+ scan_dir, relative_output, contents, owner_read_write=export_format == "md"
2888
+ )
2637
2889
 
2638
2890
 
2639
2891
  def _write_sarif_projection_if_possible(
@@ -2731,10 +2983,7 @@ def _prepare_scan_finalization(
2731
2983
  findings_for_validation = (
2732
2984
  _legacy_sealed_findings_for_validation(findings) if was_sealed else findings
2733
2985
  )
2734
- if was_sealed:
2735
- _validate_findings(manifest, findings_for_validation)
2736
- _validate_derived_finding_identities(manifest, findings)
2737
- elif completion_warnings is not None:
2986
+ if not was_sealed and completion_warnings is not None:
2738
2987
  discarded_findings = _recover_unsealed_findings(
2739
2988
  manifest, findings, schema_dir, scan_dir, completion_warnings
2740
2989
  )
@@ -2742,9 +2991,11 @@ def _prepare_scan_finalization(
2742
2991
  coverage, schema_dir, scan_dir, completion_warnings, discarded_findings
2743
2992
  )
2744
2993
  _recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
2745
- else:
2994
+ elif not was_sealed:
2746
2995
  _populate_unsealed_finding_identities(manifest, findings)
2747
2996
  _validate_findings(manifest, findings_for_validation)
2997
+ if was_sealed:
2998
+ _validate_derived_finding_identities(manifest, findings)
2748
2999
  _validate_coverage(manifest, coverage, scan_dir)
2749
3000
  _validate_canonical_schemas_before_projection(
2750
3001
  manifest, findings_for_validation, coverage, schema_dir
@@ -2755,38 +3006,24 @@ def _prepare_scan_finalization(
2755
3006
  _validate_sealed_coverage_receipts(scan, coverage)
2756
3007
  _validate_manifest(manifest)
2757
3008
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2758
- validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2759
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2760
3009
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2761
- _validate_report_output_paths(scan_dir)
2762
- return (
2763
- scan_dir,
2764
- schema_dir,
2765
- manifest,
2766
- findings,
2767
- coverage,
2768
- was_sealed,
2769
- report_markdown_bytes,
2770
- )
2771
-
2772
- findings_bytes = _contract_json_bytes("findings.json", findings)
2773
- coverage_bytes = _contract_json_bytes("coverage.json", coverage)
2774
- report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2775
- _validate_report_output_paths(scan_dir)
2776
- scan["artifacts"] = [
2777
- _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
2778
- _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
2779
- *[
2780
- _artifact_record(scan_dir, ref, "application/octet-stream")
2781
- for ref in _coverage_receipt_refs(coverage)
2782
- ],
2783
- ]
2784
- _validate_sealed_coverage_receipts(scan, coverage)
2785
- _validate_manifest(manifest)
2786
- validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2787
- validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2788
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2789
- _contract_json_bytes("scan-manifest.json", manifest)
3010
+ _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3011
+ else:
3012
+ findings_bytes = _contract_json_bytes("findings.json", findings)
3013
+ coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3014
+ report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3015
+ _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3016
+ scan["artifacts"] = [
3017
+ _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
3018
+ _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
3019
+ *[
3020
+ _artifact_record(scan_dir, ref, "application/octet-stream")
3021
+ for ref in _coverage_receipt_refs(coverage)
3022
+ ],
3023
+ ]
3024
+ _validate_manifest(manifest)
3025
+ validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
3026
+ _contract_json_bytes("scan-manifest.json", manifest)
2790
3027
  return (
2791
3028
  scan_dir,
2792
3029
  schema_dir,
@@ -2801,6 +3038,8 @@ def _prepare_scan_finalization(
2801
3038
  def _write_prepared_scan_finalization(
2802
3039
  prepared: PreparedScanFinalization,
2803
3040
  source_root: Path | None = None,
3041
+ *,
3042
+ projection_warnings: list[str] | None = None,
2804
3043
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
2805
3044
  """Write a previously validated scan finalization result."""
2806
3045
 
@@ -2814,19 +3053,22 @@ def _write_prepared_scan_finalization(
2814
3053
  report_markdown_bytes,
2815
3054
  ) = prepared
2816
3055
  scan = _require_dict(manifest, "scan", "manifest")
2817
- if was_sealed:
2818
- write_scan_local_bytes(scan_dir, "report.md", report_markdown_bytes)
2819
- _remove_scan_local_file_if_exists(scan_dir, "report.html")
2820
- _write_sarif_projection_if_possible(scan_dir, source_root, schema_dir)
2821
- return manifest, findings, coverage
2822
-
2823
- _write_scan_local_json(scan_dir, "findings.json", findings)
2824
- _write_scan_local_json(scan_dir, "coverage.json", coverage)
3056
+ if not was_sealed:
3057
+ _write_scan_local_json(scan_dir, "findings.json", findings)
3058
+ _write_scan_local_json(scan_dir, "coverage.json", coverage)
2825
3059
  write_scan_local_bytes(scan_dir, "report.md", report_markdown_bytes)
2826
3060
  _remove_scan_local_file_if_exists(scan_dir, "report.html")
2827
- _write_scan_local_json(scan_dir, "scan-manifest.json", manifest)
2828
- _validate_existing_seal(scan_dir, scan)
3061
+ if not was_sealed:
3062
+ _write_scan_local_json(scan_dir, "scan-manifest.json", manifest)
3063
+ _validate_existing_seal(scan_dir, scan)
2829
3064
  _write_sarif_projection_if_possible(scan_dir, source_root, schema_dir)
3065
+ warning = write_threat_model_projection_if_possible(scan_dir, manifest)
3066
+ if (
3067
+ warning is not None
3068
+ and projection_warnings is not None
3069
+ and warning not in projection_warnings
3070
+ ):
3071
+ projection_warnings.append(warning)
2830
3072
  return manifest, findings, coverage
2831
3073
 
2832
3074
 
@@ -2837,6 +3079,7 @@ def finalize_scan(
2837
3079
  *,
2838
3080
  expected_coverage_mode: str | None = None,
2839
3081
  completion_binding: dict[str, Any] | None = None,
3082
+ projection_warnings: list[str] | None = None,
2840
3083
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
2841
3084
  prepared = _prepare_scan_finalization(
2842
3085
  scan_dir,
@@ -2844,7 +3087,9 @@ def finalize_scan(
2844
3087
  expected_coverage_mode=expected_coverage_mode,
2845
3088
  completion_binding=completion_binding,
2846
3089
  )
2847
- return _write_prepared_scan_finalization(prepared, source_root)
3090
+ return _write_prepared_scan_finalization(
3091
+ prepared, source_root, projection_warnings=projection_warnings
3092
+ )
2848
3093
 
2849
3094
 
2850
3095
  def main() -> int:
@@ -2854,30 +3099,60 @@ def main() -> int:
2854
3099
  parser.add_argument("--source-root", type=Path)
2855
3100
  parser.add_argument("--sarif-only", action="store_true")
2856
3101
  parser.add_argument("--sarif-output", type=Path)
2857
- parser.add_argument("--export-format", choices=sorted(EXPORT_PATHS))
3102
+ parser.add_argument(
3103
+ "--export-artifact", choices=("findings", "threat-model"), default="findings"
3104
+ )
3105
+ parser.add_argument("--export-format", choices=[*sorted(EXPORT_PATHS), "md"])
2858
3106
  parser.add_argument("--export-output", type=Path)
3107
+ parser.add_argument("--export-metadata", action="store_true")
3108
+ parser.add_argument("--describe-threat-model", action="store_true")
3109
+ parser.add_argument("--write-threat-model", action="store_true")
2859
3110
  args = parser.parse_args()
2860
3111
  try:
3112
+ if args.describe_threat_model:
3113
+ sys.stdout.buffer.write(
3114
+ _json_bytes(describe_threat_model(args.scan_dir, args.schema_dir))
3115
+ )
3116
+ return 0
3117
+ if args.write_threat_model:
3118
+ write_threat_model_projection_if_possible(args.scan_dir)
3119
+ return 0
3120
+ if args.export_artifact == "threat-model" and args.export_format is None:
3121
+ args.export_format = "md"
3122
+ if args.export_metadata and (
3123
+ args.export_artifact != "threat-model" or args.export_output is None
3124
+ ):
3125
+ parser.error("--export-metadata requires a threat-model export with --export-output")
2861
3126
  if args.sarif_only and args.export_format is not None:
2862
3127
  parser.error("--sarif-only cannot be combined with --export-format")
2863
3128
  if args.export_output is not None and args.export_format is None:
2864
3129
  parser.error("--export-output requires --export-format")
2865
3130
  if args.sarif_output is not None and not args.sarif_only:
2866
3131
  parser.error("--sarif-output requires --sarif-only")
3132
+ if args.sarif_only:
3133
+ args.export_format, args.export_output = "sarif", args.sarif_output
2867
3134
  if args.export_format is not None:
2868
- contents = build_findings_export(
2869
- args.scan_dir, args.export_format, args.source_root, args.schema_dir
2870
- )
3135
+ if args.export_artifact == "threat-model":
3136
+ if args.export_format != "md":
3137
+ parser.error("threat-model exports require --export-format md")
3138
+ if args.source_root is not None:
3139
+ parser.error("source-root is only supported for SARIF exports")
3140
+ saved = _read_saved_threat_model(args.scan_dir, schema_dir=args.schema_dir)
3141
+ if saved is None:
3142
+ raise ContractError("No saved threat model is available for this result.")
3143
+ description, contents = saved
3144
+ else:
3145
+ contents = build_findings_export(
3146
+ args.scan_dir, args.export_format, args.source_root, args.schema_dir
3147
+ )
2871
3148
  if args.export_output is None:
2872
3149
  sys.stdout.buffer.write(contents)
2873
3150
  else:
2874
3151
  write_export_output(args.scan_dir, args.export_output, args.export_format, contents)
2875
- elif args.sarif_only:
2876
- sarif = build_sarif_projection(args.scan_dir, args.source_root, args.schema_dir)
2877
- if args.sarif_output is None:
2878
- sys.stdout.buffer.write(_json_bytes(sarif))
2879
- else:
2880
- write_sarif_output(args.scan_dir, args.sarif_output, sarif)
3152
+ if args.export_metadata:
3153
+ sys.stdout.buffer.write(
3154
+ _json_bytes({**description, "path": str(args.export_output.absolute())})
3155
+ )
2881
3156
  else:
2882
3157
  finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
2883
3158
  except ContractError as exc: