@openai/codex-security 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +151 -36
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
- package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
- package/_bundled_plugin/references/access-advisory.md +11 -0
- package/_bundled_plugin/references/core-scan.md +30 -77
- package/_bundled_plugin/references/final-report.md +45 -189
- package/_bundled_plugin/references/scan-contract.md +2 -0
- package/_bundled_plugin/references/scan-prologue.md +1 -1
- package/_bundled_plugin/references/scan-runtime.md +1 -5
- package/_bundled_plugin/references/threat-model.md +33 -41
- package/_bundled_plugin/schemas/coverage.schema.json +12 -1
- package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
- package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
- package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
- package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
- package/_bundled_plugin/scripts/report_projection.py +44 -15
- package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
- package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
- package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
- package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
- package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
- package/_bundled_plugin/scripts/workbench_cli.py +3 -0
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
- package/_bundled_plugin/scripts/workbench_db.py +51 -22
- package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +53 -9
- package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
- package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
- package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
- package/_bundled_plugin/scripts/workbench_schema.py +1 -1
- package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
- package/_bundled_plugin/scripts/workbench_target.py +142 -17
- package/_bundled_plugin/scripts/workbench_validation.py +9 -2
- package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
- package/_bundled_plugin/shared/workbench-migrations.json +44 -0
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
- package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
- package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
- package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
- package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -30
- package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
- package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
- package/_bundled_plugin/skills/publish-findings/SKILL.md +134 -0
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +6 -0
- package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
- package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
- package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
- package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
- package/_bundled_plugin/skills/validation/SKILL.md +42 -104
- package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
- package/_bundled_plugin/skills/verify-fix/SKILL.md +8 -4
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
- package/dist/api.d.ts +8 -3
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +414 -72
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +4 -1
- package/dist/auth.js.map +1 -1
- package/dist/classify-severity-records.d.ts +5 -2
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +40 -34
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts +5 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +20 -30
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +1 -0
- package/dist/cli-help.js.map +1 -1
- package/dist/cli.d.ts +9 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +802 -149
- package/dist/cli.js.map +1 -1
- package/dist/cloud-endpoint.d.ts +6 -0
- package/dist/cloud-endpoint.d.ts.map +1 -0
- package/dist/cloud-endpoint.js +51 -0
- package/dist/cloud-endpoint.js.map +1 -0
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +7 -5
- package/dist/cloud-publish.js.map +1 -1
- package/dist/component-scan.d.ts +8 -2
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +2 -0
- package/dist/component-scan.js.map +1 -1
- package/dist/contract.d.ts +2 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +67 -33
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts +18 -0
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +107 -12
- package/dist/cost.js.map +1 -1
- package/dist/coverage-presentation.d.ts +6 -0
- package/dist/coverage-presentation.d.ts.map +1 -0
- package/dist/coverage-presentation.js +34 -0
- package/dist/coverage-presentation.js.map +1 -0
- package/dist/custom-validation-prompt.js +3 -3
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +30 -4
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
- package/dist/deduplication/checkpointed-review.js +3 -1
- package/dist/deduplication/checkpointed-review.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +7 -5
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +3 -0
- package/dist/default-severity-rubric.d.ts.map +1 -0
- package/dist/default-severity-rubric.js +67 -0
- package/dist/default-severity-rubric.js.map +1 -0
- package/dist/endor-findings.d.ts +8 -0
- package/dist/endor-findings.d.ts.map +1 -0
- package/dist/endor-findings.js +238 -0
- package/dist/endor-findings.js.map +1 -0
- package/dist/external-findings-import.d.ts +5 -0
- package/dist/external-findings-import.d.ts.map +1 -0
- package/dist/external-findings-import.js +46 -0
- package/dist/external-findings-import.js.map +1 -0
- package/dist/external-findings-local.d.ts +63 -0
- package/dist/external-findings-local.d.ts.map +1 -0
- package/dist/external-findings-local.js +344 -0
- package/dist/external-findings-local.js.map +1 -0
- package/dist/external-findings-publish.d.ts +73 -0
- package/dist/external-findings-publish.d.ts.map +1 -0
- package/dist/external-findings-publish.js +721 -0
- package/dist/external-findings-publish.js.map +1 -0
- package/dist/external-findings-read.d.ts +16 -0
- package/dist/external-findings-read.d.ts.map +1 -0
- package/dist/external-findings-read.js +97 -0
- package/dist/external-findings-read.js.map +1 -0
- package/dist/external-findings.d.ts +21 -0
- package/dist/external-findings.d.ts.map +1 -0
- package/dist/external-findings.js +2 -0
- package/dist/external-findings.js.map +1 -0
- package/dist/external-import-contract.d.ts +15 -0
- package/dist/external-import-contract.d.ts.map +1 -0
- package/dist/external-import-contract.js +262 -0
- package/dist/external-import-contract.js.map +1 -0
- package/dist/external-import-models.d.ts +362 -0
- package/dist/external-import-models.d.ts.map +1 -0
- package/dist/external-import-models.js +3 -0
- package/dist/external-import-models.js.map +1 -0
- package/dist/external-imports-feature.d.ts +6 -0
- package/dist/external-imports-feature.d.ts.map +1 -0
- package/dist/external-imports-feature.js +51 -0
- package/dist/external-imports-feature.js.map +1 -0
- package/dist/finding-workflow.d.ts +23 -6
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +23 -10
- package/dist/finding-workflow.js.map +1 -1
- package/dist/github-advisories.d.ts +386 -0
- package/dist/github-advisories.d.ts.map +1 -0
- package/dist/github-advisories.js +133 -0
- package/dist/github-advisories.js.map +1 -0
- package/dist/github-findings.d.ts +11 -0
- package/dist/github-findings.d.ts.map +1 -0
- package/dist/github-findings.js +258 -0
- package/dist/github-findings.js.map +1 -0
- package/dist/hosted-remediation-protocol.d.ts +2 -1
- package/dist/hosted-remediation-protocol.d.ts.map +1 -1
- package/dist/hosted-remediation-protocol.js +17 -11
- package/dist/hosted-remediation-protocol.js.map +1 -1
- package/dist/hosted-remediation.d.ts +4 -0
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +22 -3
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/hosted-scan.d.ts +16 -0
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +9 -2
- package/dist/hosted-scan.js.map +1 -1
- package/dist/import-scan.js +1 -1
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +16 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -1
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts +1 -0
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +17 -8
- package/dist/knowledge-base.js.map +1 -1
- package/dist/models.d.ts +1 -0
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/owner-evidence.d.ts +2 -0
- package/dist/owner-evidence.d.ts.map +1 -1
- package/dist/owner-evidence.js +2 -1
- package/dist/owner-evidence.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +2 -0
- package/dist/project-config.js.map +1 -1
- package/dist/publish.d.ts +2 -0
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +1 -1
- package/dist/publish.js.map +1 -1
- package/dist/remediation.d.ts +7 -25
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +18 -28
- package/dist/remediation.js.map +1 -1
- package/dist/result.d.ts +4 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +10 -0
- package/dist/result.js.map +1 -1
- package/dist/runtime.d.ts +1 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +10 -8
- package/dist/runtime.js.map +1 -1
- package/dist/scan-dashboard.d.ts +5 -3
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +79 -26
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +8 -2
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-owner-suggestions.d.ts +8 -0
- package/dist/scan-owner-suggestions.d.ts.map +1 -0
- package/dist/scan-owner-suggestions.js +33 -0
- package/dist/scan-owner-suggestions.js.map +1 -0
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +4 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/scan-usage-display.d.ts +8 -0
- package/dist/scan-usage-display.d.ts.map +1 -0
- package/dist/scan-usage-display.js +46 -0
- package/dist/scan-usage-display.js.map +1 -0
- package/dist/scanner-import.d.ts +20 -0
- package/dist/scanner-import.d.ts.map +1 -0
- package/dist/scanner-import.js +208 -0
- package/dist/scanner-import.js.map +1 -0
- package/dist/security-policy-diff.d.ts +2 -0
- package/dist/security-policy-diff.d.ts.map +1 -0
- package/dist/security-policy-diff.js +197 -0
- package/dist/security-policy-diff.js.map +1 -0
- package/dist/security-policy.d.ts +7 -3
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +11 -76
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts +10 -0
- package/dist/semgrep-findings.d.ts.map +1 -0
- package/dist/semgrep-findings.js +293 -0
- package/dist/semgrep-findings.js.map +1 -0
- package/dist/severity-review.d.ts +3 -0
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +19 -0
- package/dist/severity-review.js.map +1 -1
- package/dist/severity-store.js +7 -2
- package/dist/severity-store.js.map +1 -1
- package/dist/skill-authentication.d.ts +18 -0
- package/dist/skill-authentication.d.ts.map +1 -0
- package/dist/skill-authentication.js +82 -0
- package/dist/skill-authentication.js.map +1 -0
- package/dist/snyk-findings.d.ts +10 -0
- package/dist/snyk-findings.d.ts.map +1 -0
- package/dist/snyk-findings.js +350 -0
- package/dist/snyk-findings.js.map +1 -0
- package/dist/suggest-owners.d.ts +4 -1
- package/dist/suggest-owners.d.ts.map +1 -1
- package/dist/suggest-owners.js +53 -21
- package/dist/suggest-owners.js.map +1 -1
- package/dist/targets.d.ts +2 -2
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +16 -3
- package/dist/targets.js.map +1 -1
- package/dist/wiz-csv.d.ts +9 -0
- package/dist/wiz-csv.d.ts.map +1 -0
- package/dist/wiz-csv.js +116 -0
- package/dist/wiz-csv.js.map +1 -0
- package/dist/wiz-findings.d.ts +5 -0
- package/dist/wiz-findings.d.ts.map +1 -0
- package/dist/wiz-findings.js +464 -0
- package/dist/wiz-findings.js.map +1 -0
- package/docs/classify-severity-records.md +30 -13
- package/docs/cli.md +835 -47
- package/docs/findings-service.md +119 -118
- package/docs/hosted-remediation.md +43 -24
- package/docs/hosted-scans.md +38 -0
- package/package.json +11 -9
- package/schemas/external-findings.schema.json +1421 -0
- package/schemas/project-config.schema.json +4 -0
- package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
- package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
- package/_bundled_plugin/scripts/rank_preview.py +0 -129
|
@@ -1,454 +1,59 @@
|
|
|
1
|
-
# Security Hardening
|
|
1
|
+
# Detailed Security Hardening Proposals
|
|
2
2
|
|
|
3
|
-
Use this
|
|
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
|
-
##
|
|
5
|
+
## A focused proposal
|
|
6
6
|
|
|
7
|
-
|
|
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
|
|
14
|
+
## Evidence and Current Design
|
|
341
15
|
|
|
342
|
-
##
|
|
16
|
+
## Desired Invariants and Constraints
|
|
343
17
|
|
|
344
|
-
##
|
|
18
|
+
## Options and Tradeoffs
|
|
345
19
|
|
|
346
|
-
##
|
|
20
|
+
## Migration and Validation
|
|
347
21
|
|
|
348
|
-
## Open
|
|
22
|
+
## Open Decisions
|
|
349
23
|
```
|
|
350
24
|
|
|
351
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
31
|
+
## Diagrams and tables
|
|
411
32
|
|
|
412
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
37
|
+
## Multiple opportunities
|
|
424
38
|
|
|
425
|
-
|
|
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
|
-
```
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
51
|
+
## Structured output
|
|
445
52
|
|
|
446
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
451
|
-
```
|
|
57
|
+
## Implementation planning
|
|
452
58
|
|
|
453
|
-
|
|
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.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: publish-findings
|
|
3
|
+
description: Disabled by default; requires user opt-in with CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1. Import selected Snyk Open Source findings, Semgrep Code CLI/CI reports, Endor Labs findings, GitHub code-scanning alerts or GHSA advisories, or Wiz package vulnerabilities, SAST, repository secrets, and IaC findings locally or to Codex Security Cloud after previewing the destination and evidence. Prefers native JSON; also supports Snyk plugin SCA bundles, Snyk Open Source and Semgrep Code SARIF, endorctl SARIF, saved GitHub JSON/JSONL, Wiz normalized JSONL and repository package-vulnerability CSV, and gzip; does not import workload secrets or cloud configuration, run a scan, assess findings, or synchronize triage decisions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Publish external findings
|
|
7
|
+
|
|
8
|
+
Before acquiring or importing findings, check for `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` in the command environment. If it is unset or has another value, stop and ask the user to enable imports.
|
|
9
|
+
|
|
10
|
+
Use the installed `codex-security publish findings` command for preview and import. Select `--to local` for the local workbench or `--to cloud` for Cloud. The command owns source mapping, persistence, and Cloud authentication and retries. Do not implement another store or uploader or put credentials in command arguments.
|
|
11
|
+
|
|
12
|
+
## Select the evidence
|
|
13
|
+
|
|
14
|
+
Prefer the provider's supported native JSON from its authenticated CLI, plugin, or API. Keep the original records and complete the requested pagination. A JSON summary or a different product's API response is not interchangeable with the documented report. Use SARIF or CSV only when the installed provider reader supports that profile and native JSON is unavailable or the user supplies that format. Do not convert a richer JSON report to SARIF for import.
|
|
15
|
+
|
|
16
|
+
Use the same acquisition format for repeated imports. Check the provider's identity rules before switching formats: another format can create a separate record or replace a richer snapshot with less detail. Importing findings does not reconcile equivalent vulnerabilities across formats. `--format json` controls command output, not the input report format; readers detect their supported inputs.
|
|
17
|
+
|
|
18
|
+
## Import locally
|
|
19
|
+
|
|
20
|
+
Use a local repository path with `--repository`. No Cloud login is required.
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
codex-security publish findings /path/to/selected-wiz-findings.json \
|
|
24
|
+
--to local --repository /path/to/project --provider wiz \
|
|
25
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Show the repository, source namespace, normalized evidence, and exclusions. After confirmation, repeat without `--dry-run`, adding `--yes`. Keep approval when the user already approved this preview and the input and destination are unchanged.
|
|
29
|
+
|
|
30
|
+
Read the stored evidence with `codex-security findings imported /path/to/project --format json`; the repository defaults to the current directory. Report created, updated, unchanged, and excluded counts, including exclusion reasons when the command exits 1.
|
|
31
|
+
|
|
32
|
+
Local records remain unassessed source evidence, separate from `findings list` and completed scans. Repeated imports use the same repository/provider/source-key/source-ID identity; omitted records remain stored. When a source repository URL and local Git remotes are available, the URL must match a remote. Local import does not publish to Cloud or automatically investigate or patch findings.
|
|
33
|
+
|
|
34
|
+
## Endor Labs findings
|
|
35
|
+
|
|
36
|
+
For Endor Labs imports, prefer native Finding JSON from authenticated `endorctl`, scoped to one project and context. Omit `--field-mask` and fetch all pages with `--list-all`:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
|
|
40
|
+
--filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
|
|
41
|
+
--list-all --output-type json > endor-findings.json
|
|
42
|
+
codex-security publish findings endor-findings.json --to local \
|
|
43
|
+
--provider endor --repository /path/to/project \
|
|
44
|
+
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run --format json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Choose a project that corresponds to the selected local checkout or Cloud repository. To publish the same export to Cloud, use `--to cloud --repository "CLOUD_REPOSITORY_ID"`. For a different branch or scan context, change the Endor filter and keep a distinct, stable source key. The [official Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit) can help with setup and investigation; its summaries, counts and field-masked results do not replace complete Finding objects. The [CLI API](https://docs.endorlabs.com/developers-api/cli/commands/api) supplies the export. The importer reads that saved file; it does not maintain an Endor API connection or write changes back to Endor.
|
|
48
|
+
|
|
49
|
+
Native JSON retains severity, scanned commit, package and advisory data, and primary SAST/AI SAST locations. Existing self-contained endorctl SARIF is a lossy compatibility format that retains finding UUIDs and links; unavailable severity or revisions stay unknown. Both formats use the Endor UUID within the selected repository and source key as identity. Importing SARIF after native JSON updates the same record by replacing its evidence snapshot, not merging it: native detail absent from SARIF is removed from that snapshot. Use native JSON consistently for ongoing imports. Keep the original evidence and inspect exclusions. Imported records remain unassessed source evidence. For local imports, use the preview and readback procedure above; for Cloud, use the publication procedure below.
|
|
50
|
+
|
|
51
|
+
## Wiz findings
|
|
52
|
+
|
|
53
|
+
Read [Wiz import formats](references/wiz-import.md#finding-formats) before preparing input. Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API connection; a configured plugin may provide it, but do not assume an official Codex plugin is available. Prefer supported native JSON. Inspect actual records, finish the requested pagination, and save only the selected evidence with its original occurrence IDs. A supplied export is also supported. Summaries, Wiz Issues, and local CLI scan results are not automatically supported finding records.
|
|
54
|
+
|
|
55
|
+
Validate the acquisition path against actual responses from an authorized Wiz tenant; local parser checks do not establish that qualification. Direct CSV input covers repository package vulnerabilities (SCA) only, not SAST or cloud posture findings, and does not provide a complete Wiz code-to-cloud integration.
|
|
56
|
+
|
|
57
|
+
Use a stable Wiz tenant/finding namespace as `--source-key`; a project filter does not create a new identity. Confirm the selected assets or builds belong to the destination repository. Do not infer source branches or revisions from the current checkout, invent missing evidence, or import vendor credentials, unrelated records, or local assessments as original scanner evidence. Do not retrieve or test credentials or apply suggested fixes.
|
|
58
|
+
|
|
59
|
+
## Snyk Open Source
|
|
60
|
+
|
|
61
|
+
Prefer the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex) when available. Ask its `snyk-findings-export` skill for **SCA only from the repository’s Git root** and save the `snyk-findings-export/v1` bundle. It scans the current workspace through local MCP; it cannot list existing platform projects or retrieve earlier findings. Do not substitute a fresh scan for a request to read a platform backlog. Authentication, relevant Snyk access and the project's package tooling are required.
|
|
62
|
+
|
|
63
|
+
Import the bundle with `--provider snyk`, choosing `--to local --repository /path/to/project` or `--to cloud --repository https://github.com/example/project`. Use a stable repository/branch/scan-target/acquisition namespace such as `github.com/example/project/main/root/plugin-sca`. Check the bundle's scan outcomes, collection completeness and limitations alongside the preview. Only Open Source SCA vulnerability records are supported; other categories are explicit exclusions. Preserve the native MCP record and unavailable fields. MCP descriptions may be shortened and alternate dependency paths omitted; do not reconstruct missing evidence. Plugin v1 paths are target-relative without a Git-root offset, so the importer keeps them in original evidence instead of repository locations. Use a distinct source key for each scan target. Ignore status is a source policy decision, not a Codex assessment or a fix.
|
|
64
|
+
|
|
65
|
+
For CLI automation, prefer `snyk test --file=package.json --json-file-output=snyk-open-source.json` from the selected repository root. Exit 1 means vulnerabilities were found; stop on other nonzero exits instead of importing a stale file. The existing `--provider snyk` autodetects native JSON (one project or an `--all-projects` array), plugin JSON and Open Source SARIF. Native JSON preserves per-dependency-path records and remediation fields; do not use `--group-issues`. Project errors stop import. Native JSON paths also lack a Git-root offset and stay in original evidence. Only **Open Source SCA vulnerabilities** are imported: licenses, Code, Container, IaC and platform backlog ingestion are outside this adapter.
|
|
66
|
+
|
|
67
|
+
Use one format consistently per repository, branch and scan target, with a stable source key such as `github.com/example/project/main/root/native-sca`. Plugin, native JSON and SARIF have distinct identities; use separate keys when switching, without claiming cross-format deduplication or removal of older records. Existing `snyk test --sarif-file-output=snyk-open-source.sarif` reports remain a compatibility path. SARIF groups advisory occurrences and exposes one package coordinate, so prefer JSON for acquisition. Its target-relative manifest paths lack a Git-root offset and stay in original evidence with synthetic line numbers, without being projected as repository locations or package manifest paths.
|
|
68
|
+
|
|
69
|
+
Retain package versions, reported fixed versions, provenance and original evidence without claiming a fix was applied. Known repository claims must match the selected Cloud repository or, when available, a configured local Git remote. Resolve an unknown repository with the user; never infer that an export belongs to the current checkout. Follow [local imports](#import-locally) for preview, confirmation and readback or [Cloud publication](#publish-to-cloud) for upload authorization. All three Snyk formats support either destination.
|
|
70
|
+
|
|
71
|
+
## Semgrep Code
|
|
72
|
+
|
|
73
|
+
Prefer native Code/SAST CLI or CI JSON for this reader; use self-contained SARIF 2.1.0 as a compatibility path. JSON retains the original severity better than SARIF. The reader does not accept Platform API, Guardian or MCP response envelopes, or a general Supply Chain or Secrets feed. Select SAST rules or Code-only CI output; identifiable non-SAST records are excluded, but SARIF may omit the product metadata needed to distinguish Secrets.
|
|
74
|
+
|
|
75
|
+
For a user-requested new scan, use the installed Semgrep CLI from the source repository root with the selected SAST rules: `semgrep scan --config /path/to/sast-rules.yaml --json-output /path/to/semgrep.json .`. Existing CI jobs can produce the same artifact using `--json-output`; authenticated `semgrep ci --code` follows the job's policy and baseline scope. Explain that this generates fresh scan findings, and do not substitute it for a request to retrieve existing Platform findings.
|
|
76
|
+
|
|
77
|
+
For existing findings, the official [Semgrep Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex) can help select and inspect them. Importing its output needs a separate qualified response mapping and complete pagination for the selected repository/ref. The local `semgrep_findings` MCP tool and Platform REST API also use contracts distinct from CLI reports. Do not reshape a summary into a scan report or claim that a limited tool response is a complete export.
|
|
78
|
+
|
|
79
|
+
Import the native report with `--provider semgrep`, a stable organization/project/branch `--source-key`, and `--source-repository-url` identifying the actual source repository. Use `--to local --repository /path/to/project` for local storage or `--to cloud --repository URL_OR_ID` for Cloud. The source URL is checked against configured local Git remotes or the Cloud destination. Preview with `--dry-run --format json` before confirming the import.
|
|
80
|
+
|
|
81
|
+
Keep supplied fingerprints. Reimporting the same fingerprint after code moves updates the existing source record with the new range. If the fingerprint is absent or `requires login`, the fallback uses rule, literal path and range: movement creates a second retained record, and the earlier record remains stored. Do not infer a merge or deletion. Read the persisted evidence with `codex-security findings imported /path/to/project --format json` before assessment. Source rule, CWE, snippets, traces and status are vendor evidence, not Codex assessments. Do not infer a report revision from the current checkout. Resolve scan errors and review all exclusions before uploading; do not remove error metadata to force acceptance.
|
|
82
|
+
|
|
83
|
+
## GitHub alerts and advisories
|
|
84
|
+
|
|
85
|
+
Acquire code-scanning findings with `codex-security import github OWNER/REPO --format json` and save its complete JSON output for local import or Cloud publication. This existing collector completes pagination, fetches alert details, and retains the selected ref's instance. In Codex, use the official [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github) for discovery and selecting alerts, then pass that selection to the collector. Its GitHub MCP server paginates each list call separately. Do not ask the user to download JSON from a website or reconstruct an import envelope from MCP summaries; raw MCP/API responses are not accepted by `--provider github`.
|
|
86
|
+
|
|
87
|
+
The importer uses the user's GitHub CLI authentication and `GH_HOST`; plugin authentication is separate. It defaults to open alerts on the default branch. Use repeated `--github-alert NUMBER` for exact alerts or `--github-ref REF` for another ref. Save complete output without field/token filters or `--full-output`. Reading code-scanning alerts requires a token with Code scanning alerts read permission (classic: `security_events`, or `public_repo` for public repositories), along with repository access.
|
|
88
|
+
|
|
89
|
+
**GHSA import stages advisory evidence for investigation; it does not establish an installed dependency or applicability to the destination repository.** Keep advisories separate from code scanning. `codex-security import github-advisories OWNER/REPO --format json` reads published repository disclosures by default. Repeated `--github-advisory GHSA-xxxx-xxxx-xxxx` selects exact IDs; `--github-state draft|triage|closed` explicitly selects an unpublished list and cannot be combined with exact IDs. Add `--github-advisory-source global` for exact public database IDs. This does not enumerate the global database. Private advisory access needs Repository security advisories read permission and access to those records. Stop on a read failure instead of publishing an incomplete selection.
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
codex-security import github example/project --format json > /path/to/alerts.json
|
|
93
|
+
codex-security publish findings /path/to/alerts.json \
|
|
94
|
+
--to local --repository /path/to/project --provider github \
|
|
95
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
96
|
+
codex-security publish findings /path/to/alerts.json \
|
|
97
|
+
--to cloud --repository https://github.com/example/project --provider github \
|
|
98
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
99
|
+
|
|
100
|
+
codex-security import github-advisories example/project \
|
|
101
|
+
--github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
|
|
102
|
+
--format json > /path/to/advisories.json
|
|
103
|
+
codex-security publish findings /path/to/advisories.json \
|
|
104
|
+
--to cloud --repository https://github.com/example/project --provider github \
|
|
105
|
+
--source-key github.com/example/project/security-advisories --dry-run --format json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Choose the local or Cloud preview for the intended destination. GHSA input supports the same choice: use `--to local --repository /path/to/project` with the advisory file and source key. Follow [local imports](#import-locally) for confirmation and readback or [Cloud publication](#publish-to-cloud) for upload review.
|
|
109
|
+
|
|
110
|
+
Use separate stable source keys for the two families. Code-scanning identities include the ref; repository alerts and advisories must match the selected Cloud repository or, when available, a configured local Git remote. Global advisories omit source-repository provenance and are bound to the explicit local or Cloud destination for investigation. Preserve original evidence, package ranges and patches; do not infer installed packages or source locations from an advisory. Missing security severity stays `unknown`. Dismissal, resolution and withdrawal are source state, not Codex assessment. This path does not import Dependabot or secret-scanning alerts or write back to GitHub.
|
|
111
|
+
|
|
112
|
+
## Publish to Cloud
|
|
113
|
+
|
|
114
|
+
Resolve the user's destination to a connected GitHub or GitHub Enterprise repository URL or Cloud repository ID, including custom Enterprise hosts. Confirm the intended Cloud account and an authorized repository environment. Use the existing file-backed ChatGPT login; explain a missing or incompatible login rather than changing credential storage automatically.
|
|
115
|
+
|
|
116
|
+
For another Cloud deployment, read [Deployment settings](references/wiz-import.md#deployment-settings) before previewing. Keep the selected deployment and login throughout the upload.
|
|
117
|
+
|
|
118
|
+
### Preview and approve
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
codex-security publish findings /path/to/selected-wiz-findings.json \
|
|
122
|
+
--to cloud --repository https://github.com/example/project --provider wiz \
|
|
123
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Show the Cloud API endpoint, account, repository, environments, source namespace, severity counts, and exclusions. Identify the evidence file and make the complete JSON preview available for inspection without pasting a large report into the conversation. Explain that vendor evidence is not a Codex assessment.
|
|
127
|
+
|
|
128
|
+
Obtain explicit confirmation for this concrete upload, including skipped records. Then run the same command without `--dry-run`, adding `--yes`. Authorization to inspect or assess findings alone does not authorize sending them to Cloud. Keep approval when the user already approved this preview and the input and destination are unchanged.
|
|
129
|
+
|
|
130
|
+
### Upload and report
|
|
131
|
+
|
|
132
|
+
Read [Results and recovery](references/wiz-import.md#results-and-recovery), including when the process exits nonzero. After a lost response or retryable failure, repeat the command with unchanged input and destination so the publisher resumes saved requests. A lost response does not mean nothing reached Cloud. A repository reset requires fresh discovery and confirmation before a new publication.
|
|
133
|
+
|
|
134
|
+
Report verified, unacknowledged, excluded, and failed records distinctly, retaining source IDs and recovery details. Receipts and source-record readback confirm stored vendor evidence; they do not establish a Codex assessment or visibility in the shared Cloud Findings view. Include the returned `cloudUrl` as a clickable repository link when available; do not invent a UI link from the API endpoint.
|