@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.
- package/README.md +76 -39
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
- package/_bundled_plugin/examples/completed-scan/report.md +22 -31
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
- package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
- package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
- package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
- package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/native/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 +50 -184
- package/_bundled_plugin/references/scan-artifacts.md +5 -5
- package/_bundled_plugin/references/scan-contract.md +12 -12
- 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 +37 -11
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
- package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
- package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
- package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
- package/_bundled_plugin/scripts/report_projection.py +49 -17
- package/_bundled_plugin/scripts/review_state.py +68 -0
- package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
- package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
- package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
- package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
- package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
- package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
- package/_bundled_plugin/scripts/workbench_cli.py +3 -0
- package/_bundled_plugin/scripts/workbench_constants.py +0 -1
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
- package/_bundled_plugin/scripts/workbench_db.py +55 -171
- package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
- package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
- package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
- package/_bundled_plugin/scripts/workbench_scan_history.py +77 -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 +28 -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 +9 -28
- 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 +32 -24
- 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 +29 -17
- 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/track-findings/SKILL.md +1 -1
- 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 +4 -2
- 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 +5 -3
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +359 -53
- 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/cli.d.ts +2 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +696 -430
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +2 -23
- package/dist/cloud-publish.js.map +1 -1
- package/dist/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 +5 -2
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +93 -45
- 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-publish.js +2 -2
- package/dist/custom-publish.js.map +1 -1
- package/dist/custom-validation-prompt.js +5 -5
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +47 -19
- 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/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js +2 -2
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +1 -0
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +3 -0
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/records-protocol.d.ts.map +1 -1
- package/dist/deduplication/records-protocol.js +21 -1
- package/dist/deduplication/records-protocol.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +9 -7
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/endor-findings.d.ts +4 -3
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +16 -11
- package/dist/endor-findings.js.map +1 -1
- package/dist/external-findings-import.d.ts.map +1 -1
- package/dist/external-findings-import.js +13 -5
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +1 -0
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +14 -3
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +2 -1
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +64 -28
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +12 -1
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +25 -6
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +2 -0
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +7 -1
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +63 -31
- package/dist/external-import-contract.js.map +1 -1
- 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 +24 -5
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +24 -9
- package/dist/finding-workflow.js.map +1 -1
- package/dist/github-advisories.d.ts.map +1 -1
- package/dist/github-advisories.js +3 -1
- package/dist/github-advisories.js.map +1 -1
- package/dist/github-findings.d.ts +4 -3
- package/dist/github-findings.d.ts.map +1 -1
- package/dist/github-findings.js +16 -14
- package/dist/github-findings.js.map +1 -1
- package/dist/host-protocol.d.ts +1 -1
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +2 -2
- package/dist/host-protocol.js.map +1 -1
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +19 -2
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/hosted-scan.d.ts +1 -1
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +0 -6
- package/dist/hosted-scan.js.map +1 -1
- package/dist/import-scan.js +17 -17
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -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 +20 -8
- package/dist/knowledge-base.js.map +1 -1
- package/dist/mock-scan.d.ts +1 -2
- package/dist/mock-scan.d.ts.map +1 -1
- package/dist/mock-scan.js +12 -17
- package/dist/mock-scan.js.map +1 -1
- package/dist/models.d.ts +10 -1
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +1 -6
- package/dist/multiscan.js.map +1 -1
- package/dist/native-json-findings.d.ts +30 -0
- package/dist/native-json-findings.d.ts.map +1 -0
- package/dist/native-json-findings.js +114 -0
- package/dist/native-json-findings.js.map +1 -0
- package/dist/opengrep-findings.d.ts +10 -0
- package/dist/opengrep-findings.d.ts.map +1 -0
- package/dist/opengrep-findings.js +198 -0
- package/dist/opengrep-findings.js.map +1 -0
- package/dist/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/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +2 -0
- package/dist/patch-tui.js.map +1 -1
- package/dist/publication.js +1 -2
- package/dist/publication.js.map +1 -1
- package/dist/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/record.d.ts +1 -0
- package/dist/record.d.ts.map +1 -1
- package/dist/record.js +10 -0
- package/dist/record.js.map +1 -1
- package/dist/remediation.d.ts +1 -25
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +3 -24
- package/dist/remediation.js.map +1 -1
- package/dist/result.d.ts +5 -3
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +9 -6
- package/dist/result.js.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +7 -7
- 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 +9 -3
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-owner-suggestions.d.ts +1 -1
- package/dist/scan-owner-suggestions.d.ts.map +1 -1
- package/dist/scan-owner-suggestions.js +4 -4
- package/dist/scan-owner-suggestions.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 +1 -1
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +7 -3
- package/dist/scanner-import.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +17 -22
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts +4 -3
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +22 -89
- package/dist/semgrep-findings.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 +5 -4
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +18 -17
- package/dist/snyk-findings.js.map +1 -1
- 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.map +1 -1
- package/dist/targets.js +4 -1
- package/dist/targets.js.map +1 -1
- package/dist/wiz-csv.d.ts +2 -1
- package/dist/wiz-csv.d.ts.map +1 -1
- package/dist/wiz-csv.js +3 -3
- package/dist/wiz-csv.js.map +1 -1
- package/dist/wiz-findings.d.ts +2 -1
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +27 -23
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +3 -4
- package/docs/cli.md +171 -41
- package/docs/dedupe-records.md +15 -1
- package/docs/findings-service.md +119 -118
- package/docs/hosted-remediation.md +19 -17
- package/docs/hosted-scans.md +37 -11
- package/package.json +9 -9
- 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
package/README.md
CHANGED
|
@@ -36,10 +36,6 @@ are unavailable when reading saved activity or attaching scan logs to feedback,
|
|
|
36
36
|
scans whose original session is compressed cannot resume. Plain `.jsonl` logs
|
|
37
37
|
work on all supported runtimes.
|
|
38
38
|
|
|
39
|
-
`LocalPluginBootstrapError` identifies local plugin setup failures and extends
|
|
40
|
-
`PluginBootstrapError`, so existing catches keep working. Knowledge-base
|
|
41
|
-
preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
|
|
42
|
-
|
|
43
39
|
### Install the CLI
|
|
44
40
|
|
|
45
41
|
Install the CLI globally:
|
|
@@ -187,13 +183,17 @@ directory must be private to you (`chmod 700`).
|
|
|
187
183
|
| --------------------------------- | ---------------------------------------------------------------- |
|
|
188
184
|
| `findings.findings` | Findings from this scan. |
|
|
189
185
|
| `reportPath` | Path to the Markdown report. |
|
|
190
|
-
| `
|
|
186
|
+
| `review` | Additional excluded paths. This is not file coverage. |
|
|
191
187
|
| `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
|
|
192
188
|
| `sarifPath` | SARIF export path, or `null`. |
|
|
193
189
|
| `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
|
|
194
190
|
| `cost` | Estimated model usage cost, or `null` when unavailable. |
|
|
195
191
|
|
|
196
|
-
Review
|
|
192
|
+
Review the requested paths and exclusions alongside the execution outcome.
|
|
193
|
+
`reviewState.deferred` records unfinished requested work, while
|
|
194
|
+
`reviewState.openQuestions` records optional follow-up separately.
|
|
195
|
+
|
|
196
|
+
Review the scan status and scope alongside findings. A report with no findings does not establish
|
|
197
197
|
that the repository is secure. Reports and logs can contain source code,
|
|
198
198
|
vulnerability details, and credentials; review them before sharing.
|
|
199
199
|
|
|
@@ -243,9 +243,12 @@ files can set `scan.owner_suggestions: true`. The report uses the scan's finding
|
|
|
243
243
|
IDs and frozen revision; it does not change the sealed findings or assign users.
|
|
244
244
|
Owner failures leave the base scan completed and appear as
|
|
245
245
|
`result.ownerSuggestionsError`; successful reports set `result.ownerSuggestionsPath`.
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
246
|
+
The scan records optional owner hints within its existing session and budget.
|
|
247
|
+
Report finalization applies CODEOWNERS and validates Git evidence without another
|
|
248
|
+
model call, including when `maxCostUsd` is set. Missing hints abstain and invalid
|
|
249
|
+
hints produce per-finding errors. Working-tree and directory snapshots are
|
|
250
|
+
unsupported. Explicit owner-only analysis remains available through `suggestOwners`
|
|
251
|
+
and `suggest-owners`, sharing the same evidence validation and report code.
|
|
249
252
|
|
|
250
253
|
### Scan a diff
|
|
251
254
|
|
|
@@ -278,6 +281,7 @@ const security = new CodexSecurity({
|
|
|
278
281
|
Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
|
|
279
282
|
The bundled runtime and plugin are used by default. `pythonPath` overrides the
|
|
280
283
|
`PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
|
|
284
|
+
For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
|
|
281
285
|
|
|
282
286
|
To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
|
|
283
287
|
The toggle defaults off; an explicit `false` keeps it off. The setting reaches
|
|
@@ -286,21 +290,8 @@ isolated configuration, so a desktop toggle or personal Codex configuration does
|
|
|
286
290
|
not configure an SDK scan. See [Daybreak opt-in](docs/cli.md#daybreak-opt-in) for
|
|
287
291
|
CLI, project-file, and direct plugin configuration.
|
|
288
292
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
configuration support. Older custom plugins fail before scan execution; update
|
|
292
|
-
the plugin or omit `pluginPath` to use the bundled version. Discovery, reducer,
|
|
293
|
-
and resumed workers inherit per-scan provider, authentication, environment, and
|
|
294
|
-
executable settings, with their existing read-only permissions. Reading saved
|
|
295
|
-
reports does not require these execution capabilities.
|
|
296
|
-
|
|
297
|
-
The SDK no longer adapts the older `node ./mcp/server.mjs` MCP entrypoint; use
|
|
298
|
-
the current shell or Windows launcher for runtime-root routing.
|
|
299
|
-
|
|
300
|
-
Custom plugins must support the current workbench protocol for scan comparison
|
|
301
|
-
and archival. Update an older custom plugin or omit `pluginPath` to use the
|
|
302
|
-
bundled version. The SDK no longer adapts payloads or archives scan directories
|
|
303
|
-
on behalf of older workbench implementations.
|
|
293
|
+
Deep Scan discovery, reducer, and resumed workers inherit per-scan provider,
|
|
294
|
+
authentication, environment, and executable settings with read-only permissions.
|
|
304
295
|
|
|
305
296
|
Scans use an isolated Codex configuration. See
|
|
306
297
|
[runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)
|
|
@@ -394,6 +385,10 @@ Deep discovery retains its enforced deadline, with a default and maximum of
|
|
|
394
385
|
### Progress and cost
|
|
395
386
|
|
|
396
387
|
Use `onProgress` for scan progress and `onCost` for cost updates.
|
|
388
|
+
Use `onUsageObservation` for the last reported token measurement time
|
|
389
|
+
(`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
|
|
390
|
+
Each reading includes its own `observedAt` timestamp and the percentage used in
|
|
391
|
+
each reported window. A limit-only update can arrive before any token measurement.
|
|
397
392
|
|
|
398
393
|
Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
|
|
399
394
|
persisted worker sessions discovered by the SDK's existing session tracker,
|
|
@@ -423,19 +418,15 @@ or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
|
|
|
423
418
|
stopping the scan.
|
|
424
419
|
|
|
425
420
|
`onWorkerStatus` reports **best-effort** phase dispatch counts from model-emitted
|
|
426
|
-
text markers.
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
credentials. Deep scans additionally expose durable independent-review counts
|
|
436
|
-
through `onDeepProgress`: `completed`, `active`, and `maximum`. The maximum is a
|
|
437
|
-
configured cap, not a percentage denominator. The optional `consolidating` flag
|
|
438
|
-
reports when results are being combined or the coordinator has finished.
|
|
421
|
+
text markers. A missing dispatch status does not mean delegation was skipped.
|
|
422
|
+
For retired progress hooks, see [older progress integrations](#older-progress-integrations).
|
|
423
|
+
|
|
424
|
+
`onSessionEvent` receives saved events with thread IDs and worker numbers and can
|
|
425
|
+
contain source code or credentials. Deep scans additionally expose durable
|
|
426
|
+
independent-review counts through `onDeepProgress`: `completed`, `active`, and
|
|
427
|
+
`maximum`. The maximum is a configured cap, not a percentage denominator. The
|
|
428
|
+
optional `consolidating` flag reports when results are being combined or the
|
|
429
|
+
coordinator has finished.
|
|
439
430
|
`ScanOptions` lists all callbacks.
|
|
440
431
|
|
|
441
432
|
Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
|
|
@@ -653,6 +644,14 @@ grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-clou
|
|
|
653
644
|
for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
|
|
654
645
|
for issue creation.
|
|
655
646
|
|
|
647
|
+
External vendor imports are opt-in. Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`
|
|
648
|
+
to enable `publish findings`, `findings imported`, `import github-advisories`, and
|
|
649
|
+
the SDK's external publication, local import/readback, and advisory acquisition
|
|
650
|
+
APIs. They are disabled otherwise; CLI commands are hidden from help and schemas.
|
|
651
|
+
SDK callers can supply the flag through the existing per-call
|
|
652
|
+
`dependencies.environment`. Pure normalizers and file readers remain available.
|
|
653
|
+
This does not affect scan publishing or the existing GitHub alert collector.
|
|
654
|
+
|
|
656
655
|
The SDK also exposes `prepareExternalPublication(file, options)` for supported
|
|
657
656
|
vendor exports and `prepareNormalizedExternalPublication(findings, options)` for
|
|
658
657
|
normalized external evidence from any provider in the Cloud import contract.
|
|
@@ -668,6 +667,12 @@ options where supported, and changing formats can change record identities or
|
|
|
668
667
|
replace richer evidence with less detail. See the
|
|
669
668
|
[import guide](docs/cli.md#import-vendor-findings-locally) for format selection.
|
|
670
669
|
|
|
670
|
+
For OpenGrep, use `--provider opengrep` with native JSON or gzip and an explicit
|
|
671
|
+
`--source-repository-url`. Local and Cloud imports retain unassessed OpenGrep
|
|
672
|
+
evidence through the existing Semgrep source-provider contract. See the
|
|
673
|
+
[OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md) for preview commands,
|
|
674
|
+
coverage diagnostics, stable source identities, and local SDK assessment.
|
|
675
|
+
|
|
671
676
|
For Wiz, prefer supported native JSON acquired through an authorized MCP or API
|
|
672
677
|
connection. The [CSV compatibility reader](docs/cli.md#import-wiz-findings) covers
|
|
673
678
|
repository package vulnerabilities (SCA) only; it does not add SAST, CSPM or
|
|
@@ -730,8 +735,7 @@ cs dedupe --scan SCAN_ID --json
|
|
|
730
735
|
|
|
731
736
|
The [findings guide](docs/findings-service.md) covers local storage, embedding
|
|
732
737
|
credentials, deduplication, backups, and independently operated HTTP endpoints.
|
|
733
|
-
|
|
734
|
-
scans, findings, and duplicate groups remain in the workbench database.
|
|
738
|
+
For an older service deployment, see [migration guidance](docs/findings-service.md#local-service-removal).
|
|
735
739
|
For records stored in your own system, see
|
|
736
740
|
[SDK records deduplication](docs/dedupe-records.md).
|
|
737
741
|
|
|
@@ -761,6 +765,39 @@ Repository contents, model output, and imported artifacts do not authorize
|
|
|
761
765
|
access to other targets, disclosure of credentials, or writes outside approved
|
|
762
766
|
paths. Keep state and scan artifacts private and outside the repository.
|
|
763
767
|
|
|
768
|
+
## Compatibility
|
|
769
|
+
|
|
770
|
+
### Custom plugins
|
|
771
|
+
|
|
772
|
+
New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
|
|
773
|
+
`workerProviderSnapshot: 4`, and isolated worker configuration support. Older
|
|
774
|
+
custom plugins fail before scan execution; update the plugin or omit `pluginPath`
|
|
775
|
+
to use the bundled version. Reading saved reports does not require these
|
|
776
|
+
execution capabilities.
|
|
777
|
+
|
|
778
|
+
Use the current shell or Windows launcher for runtime-root routing. The SDK does
|
|
779
|
+
not adapt the older `node ./mcp/server.mjs` MCP entrypoint.
|
|
780
|
+
|
|
781
|
+
Custom plugins must support the current workbench protocol for scan comparison
|
|
782
|
+
and archival. The SDK does not adapt older payloads or archive scan directories
|
|
783
|
+
on behalf of older workbench implementations.
|
|
784
|
+
|
|
785
|
+
### Older progress integrations
|
|
786
|
+
|
|
787
|
+
The helper-derived `kind: "preflight"` event, `config_preflight.py` helper, and
|
|
788
|
+
custom capability registries are retired. This includes the `preflightChecks`
|
|
789
|
+
progress-tool input and workbench `--preflight-issues-json` /
|
|
790
|
+
`--preflight-issues-json-stdin` arguments. Scans use available runtime tools and
|
|
791
|
+
parent fallback without a capability registry. Saved preflight history remains
|
|
792
|
+
readable. Local `preflight()` input checks, authentication, sandbox enforcement,
|
|
793
|
+
and Deep worker configuration still apply.
|
|
794
|
+
|
|
795
|
+
### Error types
|
|
796
|
+
|
|
797
|
+
`LocalPluginBootstrapError` identifies local plugin setup failures and extends
|
|
798
|
+
`PluginBootstrapError`, so existing catches keep working. Knowledge-base
|
|
799
|
+
preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
|
|
800
|
+
|
|
764
801
|
## Documentation and security
|
|
765
802
|
|
|
766
803
|
- [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)
|
|
@@ -1,57 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"documentType": "codex-security.findings",
|
|
3
|
-
"schemaVersion": "1.0",
|
|
4
|
-
"scanId": "scan_example_001",
|
|
5
3
|
"findings": [
|
|
6
4
|
{
|
|
7
|
-
"
|
|
8
|
-
"
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
"anchor": "archive-entry-write-without-containment"
|
|
5
|
+
"attackPath": null,
|
|
6
|
+
"confidence": {
|
|
7
|
+
"level": "high",
|
|
8
|
+
"rationale": "Direct source trace reaches the filesystem write without a containment check."
|
|
12
9
|
},
|
|
10
|
+
"extensions": {},
|
|
11
|
+
"findingId": "csf_852f90d6e1177502ff113d4a",
|
|
13
12
|
"fingerprints": {
|
|
14
13
|
"algorithm": "codex-security/v1",
|
|
15
14
|
"primary": "codex-security/v1:sha256:990a4a6a2ec18440dd47eac4d7256c0ee2c02db1b43104720cab3cbe9db706ca"
|
|
16
15
|
},
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
"severity": {
|
|
20
|
-
"level": "high",
|
|
21
|
-
"score": 8.1,
|
|
22
|
-
"scoringSystem": "CVSS:3.1"
|
|
23
|
-
},
|
|
24
|
-
"confidence": {
|
|
25
|
-
"level": "high",
|
|
26
|
-
"rationale": "Direct source trace reaches the filesystem write without a containment check."
|
|
27
|
-
},
|
|
28
|
-
"taxonomy": {
|
|
29
|
-
"category": "path-traversal",
|
|
30
|
-
"cwe": [
|
|
31
|
-
"CWE-22"
|
|
32
|
-
]
|
|
16
|
+
"identity": {
|
|
17
|
+
"anchor": "archive-entry-write-without-containment"
|
|
33
18
|
},
|
|
34
19
|
"locations": [
|
|
35
20
|
{
|
|
36
|
-
"path": "src/extract.py",
|
|
37
|
-
"startLine": 41,
|
|
38
21
|
"endLine": 44,
|
|
39
|
-
"
|
|
22
|
+
"path": "src/extract.py",
|
|
23
|
+
"role": "sink",
|
|
24
|
+
"startLine": 41
|
|
40
25
|
}
|
|
41
26
|
],
|
|
42
|
-
"
|
|
43
|
-
"validation": null,
|
|
44
|
-
"attackPath": null,
|
|
45
|
-
"remediationTests": [
|
|
46
|
-
"Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
|
|
47
|
-
],
|
|
27
|
+
"occurrenceId": "occ_e79cb19591e696572a1c22be",
|
|
48
28
|
"preventiveControls": [
|
|
49
29
|
"Route all archive extraction through one helper that normalizes and validates destination paths."
|
|
50
30
|
],
|
|
51
31
|
"provenance": {
|
|
52
32
|
"source": "local_plugin"
|
|
53
33
|
},
|
|
54
|
-
"
|
|
34
|
+
"remediation": "Normalize destinations and reject entries that escape the extraction root.",
|
|
35
|
+
"remediationTests": [
|
|
36
|
+
"Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
|
|
37
|
+
],
|
|
38
|
+
"ruleId": "path-traversal.archive-extraction",
|
|
39
|
+
"severity": {
|
|
40
|
+
"level": "high",
|
|
41
|
+
"score": 8.1,
|
|
42
|
+
"scoringSystem": "CVSS:3.1"
|
|
43
|
+
},
|
|
44
|
+
"summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
|
|
45
|
+
"taxonomy": {
|
|
46
|
+
"category": "path-traversal",
|
|
47
|
+
"cwe": [
|
|
48
|
+
"CWE-22"
|
|
49
|
+
]
|
|
50
|
+
},
|
|
51
|
+
"title": "Unsafe archive extraction can escape the output directory",
|
|
52
|
+
"validation": null
|
|
55
53
|
}
|
|
56
|
-
]
|
|
54
|
+
],
|
|
55
|
+
"scanId": "scan_example_001",
|
|
56
|
+
"schemaVersion": "1.0"
|
|
57
57
|
}
|
|
@@ -9,21 +9,20 @@ The scan was configured for the include paths and exclusions listed below.
|
|
|
9
9
|
- Target ID: target\_sha256\_example
|
|
10
10
|
- Revision: deadbeef
|
|
11
11
|
- Snapshot digest: codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb
|
|
12
|
-
- Inventory strategy: repository
|
|
13
12
|
- Included paths: .
|
|
14
13
|
- Excluded paths: none
|
|
15
14
|
|
|
16
15
|
### Scan Summary
|
|
17
16
|
|
|
18
|
-
| Field
|
|
19
|
-
|
|
|
20
|
-
| Scan outcome
|
|
21
|
-
| Reportable findings | 1
|
|
22
|
-
| Severity mix
|
|
23
|
-
| Confidence mix
|
|
24
|
-
| Validation mode
|
|
17
|
+
| Field | Value |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| Scan outcome | completed |
|
|
20
|
+
| Reportable findings | 1 |
|
|
21
|
+
| Severity mix | high: 1 |
|
|
22
|
+
| Confidence mix | high: 1 |
|
|
23
|
+
| Validation mode | not recorded |
|
|
25
24
|
|
|
26
|
-
Canonical artifacts: `scan-manifest.json
|
|
25
|
+
Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.
|
|
27
26
|
|
|
28
27
|
## Threat Model
|
|
29
28
|
|
|
@@ -31,30 +30,30 @@ No explicit canonical threat-model summary was recorded.
|
|
|
31
30
|
|
|
32
31
|
## Findings
|
|
33
32
|
|
|
34
|
-
| Finding
|
|
35
|
-
|
|
|
36
|
-
| [Unsafe archive extraction can escape the output directory](#finding-1) | high
|
|
33
|
+
| Finding | Severity | Confidence | Detailed write-up |
|
|
34
|
+
| --- | --- | --- | --- |
|
|
35
|
+
| [Unsafe archive extraction can escape the output directory](#finding-1) | high | high | inline below |
|
|
37
36
|
|
|
38
37
|
### Confidence Scale
|
|
39
38
|
|
|
40
|
-
| Label
|
|
41
|
-
|
|
|
42
|
-
| high
|
|
39
|
+
| Label | Meaning |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| high | Direct evidence supports the finding with no material unresolved blocker. |
|
|
43
42
|
| medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |
|
|
44
|
-
| low
|
|
43
|
+
| low | Evidence is incomplete and the item is retained only for explicit follow-up. |
|
|
45
44
|
|
|
46
45
|
<a id="finding-1"></a>
|
|
47
46
|
|
|
48
47
|
### [1] Unsafe archive extraction can escape the output directory
|
|
49
48
|
|
|
50
|
-
| Field
|
|
51
|
-
|
|
|
52
|
-
| Severity
|
|
53
|
-
| Confidence
|
|
49
|
+
| Field | Value |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| Severity | high |
|
|
52
|
+
| Confidence | high |
|
|
54
53
|
| Confidence rationale | Direct source trace reaches the filesystem write without a containment check. |
|
|
55
|
-
| Category
|
|
56
|
-
| CWE
|
|
57
|
-
| Affected lines
|
|
54
|
+
| Category | path-traversal |
|
|
55
|
+
| CWE | CWE-22 |
|
|
56
|
+
| Affected lines | src/extract.py:41-44 |
|
|
58
57
|
|
|
59
58
|
#### Summary
|
|
60
59
|
|
|
@@ -83,15 +82,7 @@ Additional runtime or deployment evidence could raise or lower this severity.
|
|
|
83
82
|
Normalize destinations and reject entries that escape the extraction root.
|
|
84
83
|
|
|
85
84
|
Tests:
|
|
86
|
-
|
|
87
85
|
- Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root.
|
|
88
86
|
|
|
89
87
|
Preventive controls:
|
|
90
|
-
|
|
91
88
|
- Route all archive extraction through one helper that normalizes and validates destination paths.
|
|
92
|
-
|
|
93
|
-
## Reviewed Surfaces
|
|
94
|
-
|
|
95
|
-
| Surface | Risk Area | Outcome | Notes |
|
|
96
|
-
| ------------------ | ------------ | -------- | -------------------------------------------- |
|
|
97
|
-
| Archive extraction | not recorded | Reported | No additional canonical notes were recorded. |
|
|
@@ -1,43 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"documentType": "codex-security.scan-manifest",
|
|
3
|
-
"schemaVersion": "1.0",
|
|
4
3
|
"scan": {
|
|
4
|
+
"artifacts": [
|
|
5
|
+
{
|
|
6
|
+
"mediaType": "application/json",
|
|
7
|
+
"path": "findings.json",
|
|
8
|
+
"sha256": "fea40b4d1f0b92090f1c0a06f43fa03da5bdf4e7f8bdf8e8a7953ae626600d5b"
|
|
9
|
+
}
|
|
10
|
+
],
|
|
11
|
+
"completedAt": "2026-05-31T18:09:00Z",
|
|
12
|
+
"findingsRef": "findings.json",
|
|
5
13
|
"id": "scan_example_001",
|
|
14
|
+
"mode": "repository",
|
|
6
15
|
"producer": {
|
|
7
16
|
"name": "codex-security-plugin",
|
|
8
17
|
"version": "0.1.0"
|
|
9
18
|
},
|
|
10
|
-
"
|
|
11
|
-
|
|
12
|
-
"completedAt": "2026-05-31T18:09:00Z",
|
|
13
|
-
"sealedAt": "2026-05-31T18:09:00Z",
|
|
14
|
-
"target": {
|
|
15
|
-
"kind": "git_worktree",
|
|
16
|
-
"targetId": "target_sha256_example",
|
|
17
|
-
"displayName": "example/repo",
|
|
18
|
-
"remote": "https://github.com/example/repo",
|
|
19
|
-
"revision": "deadbeef",
|
|
20
|
-
"snapshotDigest": "codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb"
|
|
19
|
+
"review": {
|
|
20
|
+
"excludedPaths": []
|
|
21
21
|
},
|
|
22
22
|
"scope": {
|
|
23
|
+
"excludePaths": [],
|
|
23
24
|
"includePaths": [
|
|
24
25
|
"."
|
|
25
|
-
]
|
|
26
|
-
"excludePaths": []
|
|
26
|
+
]
|
|
27
27
|
},
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
]
|
|
42
|
-
}
|
|
28
|
+
"sealedAt": "2026-05-31T18:09:00Z",
|
|
29
|
+
"startedAt": "2026-05-31T18:00:00Z",
|
|
30
|
+
"status": "completed",
|
|
31
|
+
"target": {
|
|
32
|
+
"displayName": "example/repo",
|
|
33
|
+
"kind": "git_worktree",
|
|
34
|
+
"remote": "https://github.com/example/repo",
|
|
35
|
+
"revision": "deadbeef",
|
|
36
|
+
"snapshotDigest": "codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb",
|
|
37
|
+
"targetId": "target_sha256_example"
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
"schemaVersion": "1.0"
|
|
43
41
|
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
{
|
|
2
|
+
"documentType": "codex-security.findings",
|
|
3
|
+
"schemaVersion": "1.0",
|
|
4
|
+
"scanId": "scan_example_001",
|
|
5
|
+
"findings": [
|
|
6
|
+
{
|
|
7
|
+
"findingId": "csf_852f90d6e1177502ff113d4a",
|
|
8
|
+
"occurrenceId": "occ_e79cb19591e696572a1c22be",
|
|
9
|
+
"ruleId": "path-traversal.archive-extraction",
|
|
10
|
+
"identity": {
|
|
11
|
+
"anchor": "archive-entry-write-without-containment"
|
|
12
|
+
},
|
|
13
|
+
"fingerprints": {
|
|
14
|
+
"algorithm": "codex-security/v1",
|
|
15
|
+
"primary": "codex-security/v1:sha256:990a4a6a2ec18440dd47eac4d7256c0ee2c02db1b43104720cab3cbe9db706ca"
|
|
16
|
+
},
|
|
17
|
+
"title": "Unsafe archive extraction can escape the output directory",
|
|
18
|
+
"summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
|
|
19
|
+
"severity": {
|
|
20
|
+
"level": "high",
|
|
21
|
+
"score": 8.1,
|
|
22
|
+
"scoringSystem": "CVSS:3.1"
|
|
23
|
+
},
|
|
24
|
+
"confidence": {
|
|
25
|
+
"level": "high",
|
|
26
|
+
"rationale": "Direct source trace reaches the filesystem write without a containment check."
|
|
27
|
+
},
|
|
28
|
+
"taxonomy": {
|
|
29
|
+
"category": "path-traversal",
|
|
30
|
+
"cwe": [
|
|
31
|
+
"CWE-22"
|
|
32
|
+
]
|
|
33
|
+
},
|
|
34
|
+
"locations": [
|
|
35
|
+
{
|
|
36
|
+
"path": "src/extract.py",
|
|
37
|
+
"startLine": 41,
|
|
38
|
+
"endLine": 44,
|
|
39
|
+
"role": "sink"
|
|
40
|
+
}
|
|
41
|
+
],
|
|
42
|
+
"remediation": "Normalize destinations and reject entries that escape the extraction root.",
|
|
43
|
+
"validation": null,
|
|
44
|
+
"attackPath": null,
|
|
45
|
+
"remediationTests": [
|
|
46
|
+
"Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
|
|
47
|
+
],
|
|
48
|
+
"preventiveControls": [
|
|
49
|
+
"Route all archive extraction through one helper that normalizes and validates destination paths."
|
|
50
|
+
],
|
|
51
|
+
"provenance": {
|
|
52
|
+
"source": "local_plugin"
|
|
53
|
+
},
|
|
54
|
+
"extensions": {}
|
|
55
|
+
}
|
|
56
|
+
]
|
|
57
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Security Review: example/repo
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
The scan was configured for the include paths and exclusions listed below.
|
|
6
|
+
|
|
7
|
+
- Scan mode: repository
|
|
8
|
+
- Target kind: git\_worktree
|
|
9
|
+
- Target ID: target\_sha256\_example
|
|
10
|
+
- Revision: deadbeef
|
|
11
|
+
- Snapshot digest: codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb
|
|
12
|
+
- Inventory strategy: repository
|
|
13
|
+
- Included paths: .
|
|
14
|
+
- Excluded paths: none
|
|
15
|
+
|
|
16
|
+
### Scan Summary
|
|
17
|
+
|
|
18
|
+
| Field | Value |
|
|
19
|
+
| ------------------- | ------------ |
|
|
20
|
+
| Scan outcome | completed |
|
|
21
|
+
| Reportable findings | 1 |
|
|
22
|
+
| Severity mix | high: 1 |
|
|
23
|
+
| Confidence mix | high: 1 |
|
|
24
|
+
| Coverage | complete |
|
|
25
|
+
| Validation mode | not recorded |
|
|
26
|
+
|
|
27
|
+
Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.
|
|
28
|
+
|
|
29
|
+
## Threat Model
|
|
30
|
+
|
|
31
|
+
No explicit canonical threat-model summary was recorded.
|
|
32
|
+
|
|
33
|
+
## Findings
|
|
34
|
+
|
|
35
|
+
| Finding | Severity | Confidence | Detailed write-up |
|
|
36
|
+
| ----------------------------------------------------------------------- | -------- | ---------- | ----------------- |
|
|
37
|
+
| [Unsafe archive extraction can escape the output directory](#finding-1) | high | high | inline below |
|
|
38
|
+
|
|
39
|
+
### Confidence Scale
|
|
40
|
+
|
|
41
|
+
| Label | Meaning |
|
|
42
|
+
| ------ | ---------------------------------------------------------------------------------------- |
|
|
43
|
+
| high | Direct evidence supports the finding with no material unresolved blocker. |
|
|
44
|
+
| medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |
|
|
45
|
+
| low | Evidence is incomplete and the item is retained only for explicit follow-up. |
|
|
46
|
+
|
|
47
|
+
<a id="finding-1"></a>
|
|
48
|
+
|
|
49
|
+
### [1] Unsafe archive extraction can escape the output directory
|
|
50
|
+
|
|
51
|
+
| Field | Value |
|
|
52
|
+
| -------------------- | ----------------------------------------------------------------------------- |
|
|
53
|
+
| Severity | high |
|
|
54
|
+
| Confidence | high |
|
|
55
|
+
| Confidence rationale | Direct source trace reaches the filesystem write without a containment check. |
|
|
56
|
+
| Category | path-traversal |
|
|
57
|
+
| CWE | CWE-22 |
|
|
58
|
+
| Affected lines | src/extract.py:41-44 |
|
|
59
|
+
|
|
60
|
+
#### Summary
|
|
61
|
+
|
|
62
|
+
An attacker-controlled path reaches a filesystem write without containment validation.
|
|
63
|
+
|
|
64
|
+
#### Validation
|
|
65
|
+
|
|
66
|
+
Direct source trace reaches the filesystem write without a containment check. Validation details were not recorded separately.
|
|
67
|
+
|
|
68
|
+
#### Dataflow
|
|
69
|
+
|
|
70
|
+
The canonical finding records the affected path at src/extract.py:41-44, but no expanded source-to-sink narrative was recorded.
|
|
71
|
+
|
|
72
|
+
#### Reachability
|
|
73
|
+
|
|
74
|
+
Reachability was not recorded beyond the canonical finding summary and affected locations.
|
|
75
|
+
|
|
76
|
+
#### Severity
|
|
77
|
+
|
|
78
|
+
**High** — The scan assigned high severity; no separate canonical severity rationale was recorded.
|
|
79
|
+
|
|
80
|
+
Additional runtime or deployment evidence could raise or lower this severity.
|
|
81
|
+
|
|
82
|
+
#### Remediation
|
|
83
|
+
|
|
84
|
+
Normalize destinations and reject entries that escape the extraction root.
|
|
85
|
+
|
|
86
|
+
Tests:
|
|
87
|
+
|
|
88
|
+
- Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root.
|
|
89
|
+
|
|
90
|
+
Preventive controls:
|
|
91
|
+
|
|
92
|
+
- Route all archive extraction through one helper that normalizes and validates destination paths.
|
|
93
|
+
|
|
94
|
+
## Reviewed Surfaces
|
|
95
|
+
|
|
96
|
+
| Surface | Risk Area | Outcome | Notes |
|
|
97
|
+
| ------------------ | ------------ | -------- | -------------------------------------------- |
|
|
98
|
+
| Archive extraction | not recorded | Reported | No additional canonical notes were recorded. |
|