@openai/codex-security 0.6.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 (308) hide show
  1. package/README.md +76 -39
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  4. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  6. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  9. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  11. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  12. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  13. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  23. package/_bundled_plugin/references/access-advisory.md +11 -0
  24. package/_bundled_plugin/references/core-scan.md +30 -77
  25. package/_bundled_plugin/references/final-report.md +50 -184
  26. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  27. package/_bundled_plugin/references/scan-contract.md +12 -12
  28. package/_bundled_plugin/references/scan-prologue.md +1 -1
  29. package/_bundled_plugin/references/scan-runtime.md +1 -5
  30. package/_bundled_plugin/references/threat-model.md +33 -41
  31. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  32. package/_bundled_plugin/schemas/scan-manifest.schema.json +37 -11
  33. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  34. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  35. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  36. package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
  37. package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
  38. package/_bundled_plugin/scripts/report_projection.py +49 -17
  39. package/_bundled_plugin/scripts/review_state.py +68 -0
  40. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  41. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  43. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
  44. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  45. package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
  46. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  47. package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
  48. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  49. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  50. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  51. package/_bundled_plugin/scripts/workbench_db.py +55 -171
  52. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  53. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  54. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  55. package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
  56. package/_bundled_plugin/scripts/workbench_scan_history.py +77 -7
  57. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  58. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  59. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  60. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  61. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  62. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  63. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  64. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  65. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  66. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  67. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  68. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  69. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  70. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  71. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  72. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  73. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  74. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -24
  75. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  76. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  77. package/_bundled_plugin/skills/security-scan/SKILL.md +29 -17
  78. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  79. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  80. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  81. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  82. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  83. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  84. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  85. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  86. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  87. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  88. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  89. package/dist/api.d.ts +5 -3
  90. package/dist/api.d.ts.map +1 -1
  91. package/dist/api.js +359 -53
  92. package/dist/api.js.map +1 -1
  93. package/dist/auth.d.ts.map +1 -1
  94. package/dist/auth.js +4 -1
  95. package/dist/auth.js.map +1 -1
  96. package/dist/cli.d.ts +2 -2
  97. package/dist/cli.d.ts.map +1 -1
  98. package/dist/cli.js +696 -430
  99. package/dist/cli.js.map +1 -1
  100. package/dist/cloud-publish.d.ts.map +1 -1
  101. package/dist/cloud-publish.js +2 -23
  102. package/dist/cloud-publish.js.map +1 -1
  103. package/dist/component-scan.d.ts +8 -2
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +2 -0
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/contract.d.ts +5 -2
  108. package/dist/contract.d.ts.map +1 -1
  109. package/dist/contract.js +93 -45
  110. package/dist/contract.js.map +1 -1
  111. package/dist/cost.d.ts +18 -0
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +107 -12
  114. package/dist/cost.js.map +1 -1
  115. package/dist/coverage-presentation.d.ts +6 -0
  116. package/dist/coverage-presentation.d.ts.map +1 -0
  117. package/dist/coverage-presentation.js +34 -0
  118. package/dist/coverage-presentation.js.map +1 -0
  119. package/dist/custom-publish.js +2 -2
  120. package/dist/custom-publish.js.map +1 -1
  121. package/dist/custom-validation-prompt.js +5 -5
  122. package/dist/custom-validation-prompt.js.map +1 -1
  123. package/dist/custom-validation.d.ts.map +1 -1
  124. package/dist/custom-validation.js +47 -19
  125. package/dist/custom-validation.js.map +1 -1
  126. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  127. package/dist/deduplication/checkpointed-review.js +3 -1
  128. package/dist/deduplication/checkpointed-review.js.map +1 -1
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +2 -2
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  133. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  134. package/dist/deduplication/deduplication-prompts.js +3 -0
  135. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  136. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  137. package/dist/deduplication/records-protocol.js +21 -1
  138. package/dist/deduplication/records-protocol.js.map +1 -1
  139. package/dist/deduplication/scan.d.ts.map +1 -1
  140. package/dist/deduplication/scan.js +9 -7
  141. package/dist/deduplication/scan.js.map +1 -1
  142. package/dist/endor-findings.d.ts +4 -3
  143. package/dist/endor-findings.d.ts.map +1 -1
  144. package/dist/endor-findings.js +16 -11
  145. package/dist/endor-findings.js.map +1 -1
  146. package/dist/external-findings-import.d.ts.map +1 -1
  147. package/dist/external-findings-import.js +13 -5
  148. package/dist/external-findings-import.js.map +1 -1
  149. package/dist/external-findings-local.d.ts +1 -0
  150. package/dist/external-findings-local.d.ts.map +1 -1
  151. package/dist/external-findings-local.js +14 -3
  152. package/dist/external-findings-local.js.map +1 -1
  153. package/dist/external-findings-publish.d.ts +2 -1
  154. package/dist/external-findings-publish.d.ts.map +1 -1
  155. package/dist/external-findings-publish.js +64 -28
  156. package/dist/external-findings-publish.js.map +1 -1
  157. package/dist/external-findings-read.d.ts +12 -1
  158. package/dist/external-findings-read.d.ts.map +1 -1
  159. package/dist/external-findings-read.js +25 -6
  160. package/dist/external-findings-read.js.map +1 -1
  161. package/dist/external-findings.d.ts +2 -0
  162. package/dist/external-findings.d.ts.map +1 -1
  163. package/dist/external-findings.js.map +1 -1
  164. package/dist/external-import-contract.d.ts +7 -1
  165. package/dist/external-import-contract.d.ts.map +1 -1
  166. package/dist/external-import-contract.js +63 -31
  167. package/dist/external-import-contract.js.map +1 -1
  168. package/dist/external-imports-feature.d.ts +6 -0
  169. package/dist/external-imports-feature.d.ts.map +1 -0
  170. package/dist/external-imports-feature.js +51 -0
  171. package/dist/external-imports-feature.js.map +1 -0
  172. package/dist/finding-workflow.d.ts +24 -5
  173. package/dist/finding-workflow.d.ts.map +1 -1
  174. package/dist/finding-workflow.js +24 -9
  175. package/dist/finding-workflow.js.map +1 -1
  176. package/dist/github-advisories.d.ts.map +1 -1
  177. package/dist/github-advisories.js +3 -1
  178. package/dist/github-advisories.js.map +1 -1
  179. package/dist/github-findings.d.ts +4 -3
  180. package/dist/github-findings.d.ts.map +1 -1
  181. package/dist/github-findings.js +16 -14
  182. package/dist/github-findings.js.map +1 -1
  183. package/dist/host-protocol.d.ts +1 -1
  184. package/dist/host-protocol.d.ts.map +1 -1
  185. package/dist/host-protocol.js +2 -2
  186. package/dist/host-protocol.js.map +1 -1
  187. package/dist/hosted-remediation.d.ts.map +1 -1
  188. package/dist/hosted-remediation.js +19 -2
  189. package/dist/hosted-remediation.js.map +1 -1
  190. package/dist/hosted-scan.d.ts +1 -1
  191. package/dist/hosted-scan.d.ts.map +1 -1
  192. package/dist/hosted-scan.js +0 -6
  193. package/dist/hosted-scan.js.map +1 -1
  194. package/dist/import-scan.js +17 -17
  195. package/dist/import-scan.js.map +1 -1
  196. package/dist/index.d.ts +4 -3
  197. package/dist/index.d.ts.map +1 -1
  198. package/dist/index.js +2 -1
  199. package/dist/index.js.map +1 -1
  200. package/dist/knowledge-base.d.ts +1 -0
  201. package/dist/knowledge-base.d.ts.map +1 -1
  202. package/dist/knowledge-base.js +20 -8
  203. package/dist/knowledge-base.js.map +1 -1
  204. package/dist/mock-scan.d.ts +1 -2
  205. package/dist/mock-scan.d.ts.map +1 -1
  206. package/dist/mock-scan.js +12 -17
  207. package/dist/mock-scan.js.map +1 -1
  208. package/dist/models.d.ts +10 -1
  209. package/dist/models.d.ts.map +1 -1
  210. package/dist/models.js.map +1 -1
  211. package/dist/multiscan.d.ts.map +1 -1
  212. package/dist/multiscan.js +1 -6
  213. package/dist/multiscan.js.map +1 -1
  214. package/dist/native-json-findings.d.ts +30 -0
  215. package/dist/native-json-findings.d.ts.map +1 -0
  216. package/dist/native-json-findings.js +114 -0
  217. package/dist/native-json-findings.js.map +1 -0
  218. package/dist/opengrep-findings.d.ts +10 -0
  219. package/dist/opengrep-findings.d.ts.map +1 -0
  220. package/dist/opengrep-findings.js +198 -0
  221. package/dist/opengrep-findings.js.map +1 -0
  222. package/dist/owner-evidence.d.ts +2 -0
  223. package/dist/owner-evidence.d.ts.map +1 -1
  224. package/dist/owner-evidence.js +2 -1
  225. package/dist/owner-evidence.js.map +1 -1
  226. package/dist/patch-tui.d.ts.map +1 -1
  227. package/dist/patch-tui.js +2 -0
  228. package/dist/patch-tui.js.map +1 -1
  229. package/dist/publication.js +1 -2
  230. package/dist/publication.js.map +1 -1
  231. package/dist/publish.d.ts +2 -0
  232. package/dist/publish.d.ts.map +1 -1
  233. package/dist/publish.js +1 -1
  234. package/dist/publish.js.map +1 -1
  235. package/dist/record.d.ts +1 -0
  236. package/dist/record.d.ts.map +1 -1
  237. package/dist/record.js +10 -0
  238. package/dist/record.js.map +1 -1
  239. package/dist/remediation.d.ts +1 -25
  240. package/dist/remediation.d.ts.map +1 -1
  241. package/dist/remediation.js +3 -24
  242. package/dist/remediation.js.map +1 -1
  243. package/dist/result.d.ts +5 -3
  244. package/dist/result.d.ts.map +1 -1
  245. package/dist/result.js +9 -6
  246. package/dist/result.js.map +1 -1
  247. package/dist/runtime.d.ts.map +1 -1
  248. package/dist/runtime.js +7 -7
  249. package/dist/runtime.js.map +1 -1
  250. package/dist/scan-dashboard.d.ts +5 -3
  251. package/dist/scan-dashboard.d.ts.map +1 -1
  252. package/dist/scan-dashboard.js +79 -26
  253. package/dist/scan-dashboard.js.map +1 -1
  254. package/dist/scan-history-renderer.d.ts.map +1 -1
  255. package/dist/scan-history-renderer.js +9 -3
  256. package/dist/scan-history-renderer.js.map +1 -1
  257. package/dist/scan-owner-suggestions.d.ts +1 -1
  258. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  259. package/dist/scan-owner-suggestions.js +4 -4
  260. package/dist/scan-owner-suggestions.js.map +1 -1
  261. package/dist/scan-usage-display.d.ts +8 -0
  262. package/dist/scan-usage-display.d.ts.map +1 -0
  263. package/dist/scan-usage-display.js +46 -0
  264. package/dist/scan-usage-display.js.map +1 -0
  265. package/dist/scanner-import.d.ts +1 -1
  266. package/dist/scanner-import.d.ts.map +1 -1
  267. package/dist/scanner-import.js +7 -3
  268. package/dist/scanner-import.js.map +1 -1
  269. package/dist/security-policy.d.ts.map +1 -1
  270. package/dist/security-policy.js +17 -22
  271. package/dist/security-policy.js.map +1 -1
  272. package/dist/semgrep-findings.d.ts +4 -3
  273. package/dist/semgrep-findings.d.ts.map +1 -1
  274. package/dist/semgrep-findings.js +22 -89
  275. package/dist/semgrep-findings.js.map +1 -1
  276. package/dist/skill-authentication.d.ts +18 -0
  277. package/dist/skill-authentication.d.ts.map +1 -0
  278. package/dist/skill-authentication.js +82 -0
  279. package/dist/skill-authentication.js.map +1 -0
  280. package/dist/snyk-findings.d.ts +5 -4
  281. package/dist/snyk-findings.d.ts.map +1 -1
  282. package/dist/snyk-findings.js +18 -17
  283. package/dist/snyk-findings.js.map +1 -1
  284. package/dist/suggest-owners.d.ts +4 -1
  285. package/dist/suggest-owners.d.ts.map +1 -1
  286. package/dist/suggest-owners.js +53 -21
  287. package/dist/suggest-owners.js.map +1 -1
  288. package/dist/targets.d.ts.map +1 -1
  289. package/dist/targets.js +4 -1
  290. package/dist/targets.js.map +1 -1
  291. package/dist/wiz-csv.d.ts +2 -1
  292. package/dist/wiz-csv.d.ts.map +1 -1
  293. package/dist/wiz-csv.js +3 -3
  294. package/dist/wiz-csv.js.map +1 -1
  295. package/dist/wiz-findings.d.ts +2 -1
  296. package/dist/wiz-findings.d.ts.map +1 -1
  297. package/dist/wiz-findings.js +27 -23
  298. package/dist/wiz-findings.js.map +1 -1
  299. package/docs/classify-severity-records.md +3 -4
  300. package/docs/cli.md +171 -41
  301. package/docs/dedupe-records.md +15 -1
  302. package/docs/findings-service.md +119 -118
  303. package/docs/hosted-remediation.md +19 -17
  304. package/docs/hosted-scans.md +37 -11
  305. package/package.json +9 -9
  306. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  307. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  308. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -1,454 +1,59 @@
1
- # Security Hardening Proposal Format
1
+ # Detailed Security Hardening Proposals
2
2
 
3
- Use this format for a derived hardening analysis based on vulnerability disclosures, supplied findings, incident or assessment documents, source evidence, a completed Codex Security scan, or a mixture of these. The analysis is a design product, not part of its source evidence and not proof that any finding has been remediated.
3
+ Use this reference when the requested decision benefits from a detailed proposal or portfolio. Adapt the structure to the work; these are optional formats, not a required artifact suite.
4
4
 
5
- ## Contents
5
+ ## A focused proposal
6
6
 
7
- 1. [Artifact Set](#artifact-set)
8
- 2. [Writing Voice And Narrative](#writing-voice-and-narrative)
9
- 3. [Structured Analysis](#structured-analysis)
10
- 4. [Portfolio Format](#portfolio-format)
11
- 5. [Proposal Format](#proposal-format)
12
- 6. [Diagram Rules](#diagram-rules)
13
- 7. [Tradeoff Rules](#tradeoff-rules)
14
- 8. [Implementation Handoff](#implementation-handoff)
15
-
16
- ## Artifact Set
17
-
18
- Write the following under one analysis directory:
19
-
20
- ```text
21
- <analysis_dir>/
22
- ├── context.md
23
- ├── hardening.json
24
- ├── hardening.md
25
- ├── proposals/
26
- │ └── <opportunity-id>.md
27
- ├── diagrams/
28
- │ ├── <opportunity-id>-before.mmd
29
- │ └── <opportunity-id>-<option-id>-after.mmd
30
- └── implementation/
31
- └── <option-id>.md
32
- ```
33
-
34
- `context.md` is local working context and may contain a local source-root path.
35
- The other artifacts must be distributable and use only repository-relative source paths and analysis-relative artifact links.
36
-
37
- Create `implementation/` only after the user selects an option or explicitly asks for implementation planning.
38
-
39
- ## Writing Voice And Narrative
40
-
41
- Write for security engineers and software engineers who are technically strong but may not know this subsystem or the original scan. The documents should feel like a principal security engineer calmly walking peers through a design question: professionally warm, precise, candid about uncertainty, and open to input. Do not sound robotic, alarmist, bureaucratic, or overly familiar.
42
-
43
- Use first person as an integral part of the design-review voice:
44
-
45
- - use first-person plural throughout the substantive walkthrough to guide shared reasoning: "we can see why the current ownership boundary drifts",
46
- "if we keep the fast path", or "we would pay this memory cost only while old generations drain";
47
- - use first-person singular truthfully and sparingly to establish work the author actually performed and the recommendation being offered: "I inspected these callers", "I measured", "I could not validate the device exposure",
48
- or "I recommend Option 2 under the current constraints";
49
- - never imply that code was run, performance was measured, or behavior was observed when the basis is source review, supplied evidence, analogy, or a hypothesis. Say which basis applies in plain language.
50
-
51
- This is not a pronoun quota. Do not decorate mechanical prose with isolated
52
- "we" or "I" statements. First person should expose the reasoning, invite the reader into the design choice, and make the author's evidentiary basis clear.
53
- A proposal with only a token opening and closing in first person still fails this standard.
54
-
55
- Let professional judgment show through. Explain what is attractive about an option, what gives the author pause, which tradeoff seems proportionate, and which uncertainty prevents a firmer conclusion. Phrases such as "what gives me pause is...", "the attractive part of this option is...", "we should be honest about...", or "I would be comfortable with this if..." illustrate the tone,
56
- but are not a script. Use the language that fits the actual design and avoid repeating stock sentences across the portfolio.
57
-
58
- Build a coherent technical argument rather than filling a template. Patiently connect the relevant actor and boundary, the observed failure, the structural condition that allowed it, the desired invariants, and the available design choices. Preserve the required tables and use them generously where exact deltas, coverage mappings, or cross-option comparisons benefit from a compact view. Treat them as a second layer for scanning and reference, not a replacement for the prose that teaches the reader why the comparison matters. Introduce diagrams and source references, then explain the important edges in words.
59
-
60
- Discuss options clearly and calmly. Give each serious alternative its strongest reasonable case, its costs, its residual risks, and the conditions under which it should win. Make a recommendation without salesmanship or option theatre.
61
- Prefer language such as "I recommend Option 1 under the current constraints"
62
- and "Option 2 becomes preferable if..." over absolute declarations. When a local fix is proportionate, say so without manufacturing an architectural project.
63
-
64
- The portfolio should be concise, but the proposals should not read like terse triage notes or stitched-together bullets. Give the portfolio enough prose to explain why these opportunities form a coherent decision set. Give each proposal the fuller discussion needed to let an engineer challenge the diagnosis, compare the options, and begin implementation without reconstructing the argument. Use paragraphs for reasoning and lists for genuinely list-shaped material. Preserve the natural rhythm of the prose; terminal-friendly wrapping is welcome when it does not damage clarity, links, tables, code references, or technical language.
65
-
66
- Before accepting a proposal, make sure the narrative itself, without relying on tables, does all of the following:
67
-
68
- - connects observed evidence to the inferred structural condition and explains why that inference is reasonable;
69
- - gives every serious option its strongest case, including what it preserves,
70
- what changes, how the control works, and where risk remains;
71
- - explains the mechanism behind material security, performance, memory,
72
- reliability, operational, and migration effects;
73
- - makes the author's considered view visible, including the appealing part of each option, the principal concern, and what evidence would resolve it;
74
- - introduces each diagram and table, then explains the decision-relevant edges or comparisons that the reader should take from it;
75
- - offers a conditional recommendation and names the facts, constraints, or priorities that would make another option preferable.
76
-
77
- Reject and rewrite prose that is impersonal, mechanically mirrors the heading structure, or compresses an option into a diagram, delta table, and one short paragraph. Depth should follow the decision's complexity; do not pad a simple point to meet an artificial length target.
78
-
79
- For a complex architectural alternative, one introductory paragraph and one closing paragraph around a diagram and table will rarely be enough. Develop the option in connected prose that can stand on its own: first make its strongest case and explain the mechanics; then reason through security and residual risk; then spend real attention on the resource, reliability, and migration effects that could change the decision. Explain a credible introduction and rollback posture for that option, not only for the final recommendation. Compress genuinely neutral or simple points rather than manufacturing equal-length sections.
80
-
81
- ## Structured Analysis
82
-
83
- Write `hardening.json` as UTF-8 JSON with this shape. Additional fields are allowed when they carry meaningful semantics, but do not use `extensions` as a dumping ground for prose that belongs in the proposal.
84
-
85
- The first example is scan-backed. For ordinary documents, use the `sourceEvidence` alternative described immediately afterward.
86
-
87
- ```json
88
- {
89
- "documentType": "codex-security.hardening-analysis",
90
- "schemaVersion": "1.0",
91
- "analysisId": "hardening_20260619_example",
92
- "sourceScan": {
93
- "scanId": "scan_example_001",
94
- "manifestSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
95
- "targetRevision": "deadbeef",
96
- "snapshotDigest": "codex-security-snapshot/v1:sha256:...",
97
- "sourceDrift": "none"
98
- },
99
- "assessment": {
100
- "outcome": "opportunities_identified",
101
- "summary": "The scan supports one cross-cutting containment opportunity."
102
- },
103
- "constraints": {
104
- "profile": "balanced",
105
- "changeHorizons": ["incremental", "medium_term", "foundational"],
106
- "nonNegotiables": [],
107
- "assumptions": ["No measured latency or memory budget was supplied."]
108
- },
109
- "opportunities": [
110
- {
111
- "opportunityId": "centralize-archive-containment",
112
- "title": "Centralize archive destination containment",
113
- "summary": "Move destination derivation and containment behind one owned extraction boundary.",
114
- "diagnosis": "Several extraction paths can independently construct filesystem destinations.",
115
- "evidence": [
116
- {
117
- "claimType": "observed",
118
- "sourceKind": "finding",
119
- "findingId": "csf_852f90d6e1177502ff113d4a",
120
- "path": "src/extract.py",
121
- "claim": "An archive entry path reaches a filesystem write without containment validation."
122
- },
123
- {
124
- "claimType": "inferred",
125
- "sourceKind": "source",
126
- "path": "src/extract.py",
127
- "claim": "Destination policy is owned by callers rather than by the write boundary."
128
- }
129
- ],
130
- "desiredInvariants": [
131
- "Every extraction write uses a destination proven to remain under the caller's output root."
132
- ],
133
- "proposalPath": "proposals/centralize-archive-containment.md",
134
- "options": [
135
- {
136
- "optionId": "local-guards",
137
- "title": "Strengthen local guards",
138
- "kind": "baseline",
139
- "summary": "Patch each existing extraction path and add shared regression cases.",
140
- "diagramPaths": {
141
- "before": "diagrams/centralize-archive-containment-before.mmd",
142
- "after": "diagrams/centralize-archive-containment-local-guards-after.mmd"
143
- },
144
- "findingCoverage": [
145
- {
146
- "findingId": "csf_852f90d6e1177502ff113d4a",
147
- "effect": "addresses",
148
- "tacticalFixRequired": true,
149
- "rationale": "The local containment check is itself the tactical fix."
150
- }
151
- ],
152
- "tradeoffs": [
153
- {
154
- "dimension": "security",
155
- "direction": "improves",
156
- "confidence": "high",
157
- "basis": "source-derived",
158
- "assessment": "The observed write path rejects escaping entries, but future callers can still omit the guard.",
159
- "validationPlan": "Run the original traversal PoC and search every extraction write path."
160
- },
161
- {
162
- "dimension": "performance",
163
- "direction": "neutral",
164
- "confidence": "medium",
165
- "basis": "source-derived",
166
- "assessment": "The local lexical containment check adds no I/O or process boundary.",
167
- "validationPlan": "Benchmark representative archive extraction before and after the guard."
168
- },
169
- {
170
- "dimension": "memory",
171
- "direction": "neutral",
172
- "confidence": "medium",
173
- "basis": "source-derived",
174
- "assessment": "The guard requires only bounded temporary path values.",
175
- "validationPlan": "Compare peak RSS while extracting archives with many entries."
176
- },
177
- {
178
- "dimension": "reliability",
179
- "direction": "improves",
180
- "confidence": "medium",
181
- "basis": "source-derived",
182
- "assessment": "Escaping entries fail before a filesystem side effect.",
183
- "validationPlan": "Exercise mixed valid and invalid entries and verify deterministic failure behavior."
184
- },
185
- {
186
- "dimension": "operability",
187
- "direction": "neutral",
188
- "confidence": "low",
189
- "basis": "hypothetical",
190
- "assessment": "No new service is introduced, but rejection telemetry may be useful.",
191
- "validationPlan": "Confirm whether existing extraction errors are observable in production."
192
- },
193
- {
194
- "dimension": "migration",
195
- "direction": "neutral",
196
- "confidence": "high",
197
- "basis": "source-derived",
198
- "assessment": "The change preserves the current extraction API.",
199
- "validationPlan": "Run compatibility coverage for valid relative archive entries."
200
- }
201
- ],
202
- "residualRisks": ["Containment policy can drift between call sites."],
203
- "implementationReadiness": {
204
- "affectedComponents": ["src/extract.py"],
205
- "workPackages": [
206
- "Add containment enforcement and regression coverage."
207
- ],
208
- "acceptanceCriteria": [
209
- "The original traversal PoC cannot write outside the output root."
210
- ],
211
- "migrationNotes": [],
212
- "rollback": "Revert the focused guard and test change."
213
- }
214
- }
215
- ],
216
- "recommendedOptionId": "local-guards",
217
- "recommendation": "Use the baseline only when delivery time dominates recurrence risk."
218
- }
219
- ],
220
- "openQuestions": []
221
- }
222
- ```
223
-
224
- For disclosures, supplied findings, or another non-scan collection, replace `sourceScan` with an integrity-recorded evidence identity:
225
-
226
- ```json
227
- {
228
- "sourceEvidence": {
229
- "kind": "document_collection",
230
- "label": "Kernel vulnerability disclosure documents",
231
- "collectionSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
232
- "artifactCount": 12,
233
- "sourceDrift": "unknown"
234
- }
235
- }
236
- ```
237
-
238
- When an option maps to disclosure documents rather than canonical scan findings, use `evidenceCoverage` in place of `findingCoverage`:
239
-
240
- ```json
241
- {
242
- "evidenceCoverage": [
243
- {
244
- "evidenceId": "evidence-001",
245
- "effect": "mitigates",
246
- "tacticalFixRequired": true,
247
- "rationale": "The structural boundary narrows recurrence risk, while the affected path still needs its direct lifetime fix."
248
- }
249
- ]
250
- }
251
- ```
252
-
253
- ### Required Semantics
254
-
255
- - Record at least one of `sourceScan` or `sourceEvidence`. Both may be present for a scan supplemented by external evidence.
256
- - For analysis of an already completed scan, `sourceScan.manifestSha256` binds the analysis to the sealed input when that digest is available and verified.
257
- Do not require or invent it when hardening runs before normal scan completion. Record at least one immutable target identity, `targetRevision`
258
- or `snapshotDigest`, when the source scan provides one.
259
- - For non-scan analysis, `sourceEvidence.collectionSha256` binds the analysis to the inventoried input collection. Record its `kind`, reader-facing `label`, and positive `artifactCount`. A target revision or snapshot digest is optional because ordinary disclosures may not identify one.
260
- - `sourceDrift` is one of `none`, `present`, or `unknown`.
261
- - `assessment.outcome` is `opportunities_identified` or `local_remediation_preferred`.
262
- - `assessment.summary` is the concise reader-facing conclusion used by the scan report index. It must not claim that proposed work is implemented.
263
- - `opportunities_identified` requires at least one complete opportunity.
264
- `local_remediation_preferred` requires an empty opportunity list and a portfolio that explains why tactical fixes are proportionate.
265
- - `claimType` is `observed` or `inferred`. Proposed behavior belongs in option text, not in the evidence array.
266
- - `sourceKind` is `finding`, `disclosure`, `document`, `source`, `coverage`,
267
- `threat_model`, `poc`, or `experiment`. Use `evidenceId` for disclosure,
268
- document, PoC, or experiment evidence and `findingId` for a canonical finding.
269
- - `kind` is `baseline`, `incremental`, `structural`, `isolation`, or `foundational`.
270
- - Each option must contain at least one `findingCoverage` or `evidenceCoverage` mapping. Their `effect` is `addresses`, `mitigates`,
271
- `unaffected`, or `unknown`.
272
- - `direction` is `improves`, `regresses`, `neutral`, or `unknown`.
273
- - `confidence` is `high`, `medium`, or `low`.
274
- - `basis` is `measured`, `source-derived`, `analogous`, or `hypothetical`.
275
- - `recommendedOptionId` may be `null` when constraints do not support a clear recommendation. Otherwise it must name an option in the same opportunity.
276
- - Every opportunity and option ID must be unique within the analysis and use lowercase letters, digits, dots, underscores, or hyphens.
277
- - Every option must assess `security`, `performance`, `memory`, `reliability`,
278
- `operability`, and `migration`. Use an honest `neutral` or `unknown` entry rather than omitting an inconvenient dimension.
279
-
280
- ## Portfolio Format
281
-
282
- Write `hardening.md` with these headings in order. Use `Evidence Basis` for an ordinary or mixed collection; `Source Scan` remains acceptable for analysis derived solely from a Codex Security scan.
283
-
284
- ```markdown
285
- # Security Hardening Review: <target>
286
-
287
- ## Evidence Basis
288
-
289
- ## Constraints
290
-
291
- ## Opportunity Portfolio
292
-
293
- ## Recommendation Summary
294
-
295
- ## Next Decisions
296
- ```
297
-
298
- Under `Opportunity Portfolio`, use a compact table:
299
-
300
- | Opportunity | Evidence | Options | Recommendation | Proposal |
301
- | ----------- | -------- | ------- | -------------- | -------- |
302
-
303
- Link every proposal using its exact `proposalPath`. Make the recommendation conditional on the recorded constraints. Keep this document easy to skim; put the complete technical argument in the proposal file. Open with enough prose to orient a reader who did not participate in the scan, and use the recommendation summary to explain the reasoning in a warm design-review voice rather than merely repeating the table.
304
-
305
- The `Evidence` cell must be meaningful without opening `context.md`. Use short finding or document titles, optionally followed by their IDs, or a clear reader-facing group label linked to the proposal. Do not write a bare list such as `E021, E022, E031` or opaque canonical finding hashes. For example, prefer `Netlink length and scratch failures (E021, E031)` or link a compact label such as `6 decode-boundary findings` to the proposal that defines all six.
306
-
307
- For a `local_remediation_preferred` assessment, retain all required portfolio headings. Under `Opportunity Portfolio`, state that no structural opportunity qualified; under `Recommendation Summary`, explain the local remediation conclusion. Do not create proposal or diagram files for fictional options.
308
-
309
- ## Proposal Format
310
-
311
- Name each proposal `proposals/<opportunity-id>.md` and use these headings in order:
7
+ Explain the problem, the evidence for its structural cause, the meaningful alternatives, and the recommendation. A useful outline is:
312
8
 
313
9
  ```markdown
314
10
  # Security Hardening Proposal: <title>
315
11
 
316
- ## Decision
317
-
318
- ## Executive Recommendation
319
-
320
- ## Evidence
321
-
322
- ## Current Design And Failure Mode
323
-
324
- ## Desired Invariants
325
-
326
- ## Constraints And Non-Goals
327
-
328
- ## Before Architecture
329
-
330
- ## Options
331
-
332
- ### Option 1: <baseline, when useful>
333
-
334
- ### Option 2: <first alternative>
335
-
336
- ## Comparison
337
-
338
12
  ## Recommendation
339
13
 
340
- ## Evidence Coverage And Residual Risk
14
+ ## Evidence and Current Design
341
15
 
342
- ## Migration And Rollout
16
+ ## Desired Invariants and Constraints
343
17
 
344
- ## Validation Plan
18
+ ## Options and Tradeoffs
345
19
 
346
- ## Implementation Work Packages
20
+ ## Migration and Validation
347
21
 
348
- ## Open Questions
22
+ ## Open Decisions
349
23
  ```
350
24
 
351
- Requirements:
352
-
353
- - start reader-facing option numbering at 1, including when Option 1 is the baseline; never expose a zero-based implementation index as "Option 0";
354
- - keep structured `optionId` values semantic and independent of display order so options can be reordered without renaming machine-facing identities;
355
- - introduce every option in `Executive Recommendation` using its number and a short descriptive title before referring to the option by number alone;
356
- - make the complete option set visible before recommending a subset, and avoid numbered step lists that could be mistaken for the numbered options;
357
- - identify observed and inferred claims explicitly in `Evidence`;
358
- - define every opaque finding or evidence ID in the proposal where it is used;
359
- pair it with a concise title and a one-line statement of what it establishes,
360
- using a compact evidence map when several items contribute;
361
- - when source or artifacts were actually inspected, state that basis truthfully in first-person and explain which evidence most influenced the structural diagnosis;
362
- - cite finding IDs or evidence IDs and repository-relative source locations when source is available;
363
- - explain the structural condition, not merely the vulnerable line;
364
- - state desired invariants before proposing components;
365
- - include the before diagram and one after diagram for every option;
366
- - follow each diagram pair with a delta table using `Change`, `Before`,
367
- `After`, `Security consequence`, and `Cost`;
368
- - include a tradeoff comparison table without a fabricated composite score;
369
- - explain every option in connected prose before relying on its diagram or delta table, including the control mechanism, strongest case, material costs, residual risk, rollout, and rollback;
370
- - explain the recommendation under current assumptions, state it in first-person when a recommendation is supported, and say when another option should win;
371
- - preserve tactical fixes needed during migration;
372
- - list concrete validation, benchmark, rollout, rollback, and acceptance work.
373
-
374
- Use this shape under `Evidence` when several findings or documents contribute:
375
-
376
- | Evidence | Finding or document | What it establishes |
377
- | -------- | ------------------------------------ | ----------------------------------------------------------------------- |
378
- | `E021` | Netlink multipath scratch exhaustion | Attacker-controlled nesting can exhaust unchecked parser scratch space. |
379
-
380
- Link the finding or document title to its writeup when a distributable relative path is available. The title may be shortened for readability, but it must be specific enough that a new reader understands the reference. After defining an ID once in the proposal, later prose may use the ID alone where repetition would be awkward. In `Evidence Coverage And Residual Risk`, label every row with both the ID and short title, for example `E021 — Netlink scratch exhaustion`. Apply the same rule to canonical scan finding IDs. A complete registry in `context.md` supports auditability but does not make a bare ID self-explanatory in another document.
381
-
382
- The proposal should read as one connected discussion. In particular:
383
-
384
- - establish the component, relevant actor, trust or lifetime boundary, and evidence basis before asking the reader to choose an option;
385
- - keep evidence references locally understandable; do not make the reader shuttle to `context.md` to decode an identifier;
386
- - move naturally from observed facts to the inferred structural condition,
387
- making the change in epistemic status explicit without reducing the section to labels;
388
- - introduce each option in prose, explain what it preserves and what it asks the project to change, how the changed boundary creates the security effect,
389
- and then use diagrams or tables to sharpen the point;
390
- - return to prose after each diagram and comparison table to interpret the important edges, cost mechanisms, and remaining uncertainty;
391
- - avoid repeating the same opening, transition, and verdict formula for every option or proposal; let the actual engineering concern shape the discussion;
392
- - compare alternatives fairly, including useful rejected or deferred designs when they teach an important constraint;
393
- - state the recommendation in first-person when it is supported, explain why it fits the current constraints, and name the evidence or priority that would change the recommendation;
394
- - avoid generic endings. Leave reviewers with concrete decisions, open questions, and a comfortable path to refine or implement the design.
395
-
396
- ## Diagram Rules
397
-
398
- Use Mermaid `flowchart` source in `.mmd` files. Keep diagrams compact and security-relevant:
25
+ Keep the recommendation understandable without reading the original finding. Define evidence identifiers with a short title and explain what each cited item establishes. Cite source locations and revisions when known. Separate supplied claims, inspected evidence, inference, and design expectations.
399
26
 
400
- - reuse component names and abstraction level across before and after views;
401
- - show trust boundaries, attacker-controlled entry points, control ownership,
402
- dangerous capabilities or sinks, and failure containment;
403
- - label changed control or authority edges clearly;
404
- - avoid code-level call graphs unless the proposed change is itself a call boundary;
405
- - do not imply that a process, service, queue, or sandbox exists unless source or deployment evidence supports the before view;
406
- - keep supporting detail in prose rather than filling nodes with paragraphs.
27
+ For each serious option, describe how it works, why its changed boundary improves security, what risk remains, and the costs that matter. Give alternatives a fair comparison. When local fixes are sufficient, explain that conclusion without inventing larger designs.
407
28
 
408
- ## Tradeoff Rules
29
+ Discuss performance or resource effects through their mechanisms, such as added copies, process boundaries, retained state, or synchronization. Separate measured results from estimates. Where uncertainty could change the choice, identify a useful workload, metric, baseline, and decision criterion rather than manufacturing a score.
409
30
 
410
- Assess these dimensions for every option:
31
+ ## Diagrams and tables
411
32
 
412
- | Dimension | Questions |
413
- | ----------- | ------------------------------------------------------------------------------------ |
414
- | Security | Which attack paths disappear, narrow, or remain? What new trusted component appears? |
415
- | Performance | Does the critical path gain hops, copies, serialization, locks, or cache misses? |
416
- | Memory | Are there new processes, buffers, indexes, queues, caches, or retained objects? |
417
- | Reliability | How do failure isolation, retries, backpressure, recovery, and availability change? |
418
- | Operability | What new deployment, observability, alerting, or incident response burden appears? |
419
- | Migration | What compatibility, data, protocol, rollout, and rollback work is required? |
33
+ Use a diagram when it explains control ownership, authority flow, isolation, or state transitions more clearly than prose. Keep before-and-after views at the same abstraction level, reuse component names, and show only supported current structure. Mermaid flowcharts can be embedded in the proposal; separate `.mmd` files are useful when requested for reuse.
420
34
 
421
- For unmeasured effects, name the likely mechanism and a measurement plan. A useful plan identifies the workload, metric, baseline, candidate design, and decision threshold. Do not present analogy or intuition as benchmark data.
35
+ A comparison table can summarize material differences. An evidence-coverage table can help when several findings contribute; identify what an option addresses, mitigates, leaves unaffected, or cannot yet resolve. Neither table is required for a simple decision.
422
36
 
423
- ## Implementation Handoff
37
+ ## Multiple opportunities
424
38
 
425
- After selection, write `implementation/<option-id>.md` with:
39
+ For a large analysis, use a short portfolio that links to individual proposals and explains their relationship and relative priority. Suggested relative paths are:
426
40
 
427
- ```markdown
428
- # Implementation Plan: <option title>
429
-
430
- ## Selected Design And Constraints
431
-
432
- ## Source Revision And Drift Check
433
-
434
- ## Affected Components
435
-
436
- ## Ordered Work Packages
437
-
438
- ## Compatibility And Migration
41
+ ```text
42
+ hardening/hardening.md
43
+ hardening/proposals/<opportunity-id>.md
44
+ hardening/diagrams/<opportunity-id>-<view>.mmd
45
+ ```
439
46
 
440
- ## Tactical Protections During Migration
47
+ Resolve physical directories through `../../../references/artifact-storage.md`. Only `hardening/hardening.md` is required when attaching the analysis to a scan. If no structural change is warranted, that file can explain why local remediation is preferable; no proposal or diagram files are needed.
441
48
 
442
- ## Tests And Security Validation
49
+ Keep distributable source citations repository-relative and links relative to the analysis. Do not include author-machine paths or internal drafting notes. Preserve original evidence separately from the derived design.
443
50
 
444
- ## Performance And Resource Benchmarks
51
+ ## Structured output
445
52
 
446
- ## Rollout And Rollback
53
+ Generate structured output when requested or when an identified consumer needs it. Use that consumer's schema. The scan attachment consumes `scan.hardening.portfolioPath`, not a separate `hardening.json` document.
447
54
 
448
- ## Acceptance Criteria
55
+ For a standalone structured analysis without an existing schema, useful fields include source identity, constraints, opportunities, evidence references, options, material tradeoffs, residual risks, and recommendations. Use stable semantic IDs for cross-references. Record immutable revisions or verified digests when available; do not fabricate missing identities or require a collection digest merely to analyze supplied documents. Validate generated JSON and its references before delivery.
449
56
 
450
- ## Open Decisions
451
- ```
57
+ ## Implementation planning
452
58
 
453
- Anchor the plan to the scan manifest digest or evidence collection digest and,
454
- when available, the refreshed implementation revision. If source drift changes a relevant boundary, return to design review instead of quietly adapting the proposal while coding.
59
+ When requested, turn the selected design into work packages with affected components, compatibility constraints, tactical protections, meaningful tests, rollout or rollback needs, and acceptance criteria. Include benchmarks only where resource or performance uncertainty matters. Check the source revision before implementation and revisit the design if relevant drift changes its assumptions.