@openai/codex-security 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +44 -14
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/references/core-scan.md +1 -1
  6. package/_bundled_plugin/references/final-report.md +4 -2
  7. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  8. package/_bundled_plugin/references/scan-contract.md +18 -7
  9. package/_bundled_plugin/schemas/scan-manifest.schema.json +2 -2
  10. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +23 -0
  11. package/_bundled_plugin/scripts/deep_scan_workbench.py +88 -1
  12. package/_bundled_plugin/scripts/finalize_scan_contract.py +58 -18
  13. package/_bundled_plugin/scripts/report_projection.py +19 -8
  14. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  15. package/_bundled_plugin/scripts/workbench_db.py +149 -167
  16. package/_bundled_plugin/scripts/workbench_finding_index.py +101 -0
  17. package/_bundled_plugin/scripts/workbench_remediation.py +19 -0
  18. package/_bundled_plugin/scripts/workbench_saved_results.py +1289 -0
  19. package/_bundled_plugin/scripts/workbench_schema.py +28 -0
  20. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -4
  21. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  22. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  23. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  24. package/dist/api.d.ts +2 -0
  25. package/dist/api.d.ts.map +1 -1
  26. package/dist/api.js +54 -7
  27. package/dist/api.js.map +1 -1
  28. package/dist/cli.d.ts.map +1 -1
  29. package/dist/cli.js +13 -0
  30. package/dist/cli.js.map +1 -1
  31. package/dist/custom-validation-prompt.js +3 -3
  32. package/dist/custom-validation-prompt.js.map +1 -1
  33. package/dist/models.d.ts +1 -1
  34. package/dist/models.d.ts.map +1 -1
  35. package/dist/models.js.map +1 -1
  36. package/package.json +2 -2
package/README.md CHANGED
@@ -118,20 +118,21 @@ Pass runtime configuration to the `CodexSecurity` constructor:
118
118
  Pass scan configuration to `security.run(repository, options)` or
119
119
  `security.preflight(repository, options)`:
120
120
 
121
- | Option | Description |
122
- | ----------------------- | ------------------------------------------------------------------------------------- |
123
- | `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
124
- | `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
125
- | `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
126
- | `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
127
- | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
128
- | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
129
- | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
130
- | `maxTimeHours` | Limit deep-scan discovery to a positive number of hours, up to 96. |
131
- | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
132
- | `parentScanId` | Link a rerun to an existing parent scan. |
133
- | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
134
- | `signal` | Cancel a scan with an `AbortSignal`. |
121
+ | Option | Description |
122
+ | ----------------------- | ------------------------------------------------------------------------------------------ |
123
+ | `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
124
+ | `safetyIdentifier` | Stable hashed end-user ID for this scan's model requests; requires API-key authentication. |
125
+ | `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
126
+ | `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
127
+ | `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
128
+ | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
129
+ | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
130
+ | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
131
+ | `maxTimeHours` | Limit deep-scan discovery to a positive number of hours, up to 96. |
132
+ | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
133
+ | `parentScanId` | Link a rerun to an existing parent scan. |
134
+ | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
135
+ | `signal` | Cancel a scan with an `AbortSignal`. |
135
136
 
136
137
  Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
137
138
  `onOutputArchived`, `onOutputDirReady`, `onScanStarted`,
@@ -335,6 +336,35 @@ Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
335
336
  shares them with every repository. Directories are searched recursively for
336
337
  Markdown, text, PDF, and Word (`.docx`) files.
337
338
 
339
+ ### Attribute scans to end users
340
+
341
+ For an application that serves multiple users, pass the originating user's
342
+ stable hashed ID on each scan:
343
+
344
+ ```ts
345
+ await security.run("/path/to/repository", {
346
+ auth: "api-key",
347
+ safetyIdentifier: hashedUserId,
348
+ });
349
+ ```
350
+
351
+ ```bash
352
+ codex-security scan /path/to/repository --auth api-key --safety-identifier hashed-user-id
353
+ ```
354
+
355
+ The ID must contain 1–64 characters and cannot be blank or contain NUL.
356
+ Do not use an email address or other personal data. The ID is passed to Codex
357
+ for the scan, nested workers, retries, and follow-up work. It is not saved in
358
+ shared configuration or the scan recipe. Supply it again for a later rerun.
359
+ Concurrent SDK clients can use different IDs without changing `process.env`.
360
+
361
+ This requires a Codex runtime with native `--safety-identifier` support and a
362
+ plugin that forwards it to workers. The current bundled runtime does not yet
363
+ support this option. Use `CODEX_CLI_PATH` to select a compatible build.
364
+ The SDK does not check runtime or plugin compatibility; older versions may
365
+ omit the identifier. Omitting the option leaves ordinary scans unchanged.
366
+ Preflight checks the ID's format; authentication is checked when the scan starts.
367
+
338
368
  ### Scan project components
339
369
 
340
370
  `scan --path` runs one scan across the selected paths. Use `scan-components`
@@ -8,6 +8,7 @@
8
8
  "CODEX_HOME",
9
9
  "CODEX_SQLITE_HOME",
10
10
  "CODEX_API_KEY",
11
+ "CODEX_SAFETY_IDENTIFIER",
11
12
  "CODEX_BROWSER_USE_NODE_PATH",
12
13
  "CODEX_CLI_PATH",
13
14
  "CODEX_ELECTRON_RESOURCES_PATH",
@@ -9,7 +9,7 @@ Perform one complete, evidence-backed security audit of the exact supplied repos
9
9
  3. While the baseline runs, read `threat-model.md` once and obtain its independent architecture review within the available worker allowance. Verify its resource rows against their actual consumers, use the returned canonical `threatModel` as the generated model, and build source-backed investigation packets from it. Carry that object and its evidence into the final result instead of reconstructing a shorter summary. Preserve any user-supplied threat model unchanged as the authoritative security assumptions; map its real surfaces and controls without replacing it.
10
10
  4. Group related source-backed security questions into investigation packets. Each group shares its plausible attacker, protected asset, entry points, expected controls, sensitive operations, component relationships, and actual repository-relative source anchors. Keep each question concrete, preserve distinct attacker boundaries and security mechanisms, and let investigators establish the detailed dataflow.
11
11
  5. Launch focused investigator subagents with `fork_turns: "none"` as soon as useful packet groups exist. Choose their number and assignments from the amount, complexity, and independence of source-backed work, bounded by the supplied available subagent allowance; use fewer for related packets and more only when distinct surfaces justify them. Keep mapping other surfaces while they run. Send each only its focused-investigator prompt below, assigned packets, investigator perspective, repository path, authorized scope, any supplied scoped-source inventory, exact user context, supplied threat model, applicable packet-specific security guidance and its resolver command, the optional authoritative knowledge-base location, and verified search command. Do not include this reference or another worker's prompt. Supporting code may be outside a requested path, but an affected entry point, control, or operation must be in scope.
12
- 6. Reconcile source coverage before combining findings. Union only the baseline and focused investigators' `fully_reviewed_files` with files the parent fully security-audited, then intersect that set with the supplied authorized inventory or an inventory of the selected current scope. Architecture mapping alone and supporting files outside that inventory do not count toward completed audit coverage. Finish the remaining in-scope files in coherent groups, reusing available investigators within the same allowance. Inspect implementation-owning generated or compressed code as data. Do not add overlapping worker counts or claim that a search hit completed a file. Keep this one transient set; do not create a separate progress ledger or receipt format. If a user limit or unavailable source prevents completion, identify the actual remaining paths and report partial coverage. Then combine baseline and investigator findings once. Group observations only when they share the same broken security control and effective remediation; preserve every affected route, operation, sink, and supporting source location. Never merge different security failures solely because they share a CWE.
12
+ 6. Before combining or revalidating any returned baseline or investigator result, persist it through the caller's bound `record_codex_security_scan_draft` tool when available, using `complete: false` and partial coverage. Give each candidate a stable `candidateId`; put candidates awaiting parent validation in `coverage.deferred` with a meaningful reason and their original finding payload under `candidate`. Preserve returned counterevidence and unresolved questions too. Checkpoint again after each validation decision, without waiting for other workers or the final report. Put source-validated findings in `findings` with the same `provenance.candidateId`; for a rejection, retain the candidate ID, original evidence, and source-backed counterevidence on a `rejected` coverage surface. An unfinished scan must retain its saved findings and pending candidates without presenting pending work as validated. Reconcile source coverage before combining findings. Union only the baseline and focused investigators' `fully_reviewed_files` with files the parent fully security-audited, then intersect that set with the supplied authorized inventory or an inventory of the selected current scope. Architecture mapping alone and supporting files outside that inventory do not count toward completed audit coverage. Finish the remaining in-scope files in coherent groups, reusing available investigators within the same allowance. Inspect implementation-owning generated or compressed code as data. Do not add overlapping worker counts or claim that a search hit completed a file. Keep this one transient set; do not create a separate progress ledger or receipt format. If a user limit or unavailable source prevents completion, identify the actual remaining paths and report partial coverage. Then combine baseline and investigator findings once. Group observations only when they share the same broken security control and effective remediation; preserve every affected route, operation, sink, and supporting source location. Never merge different security failures solely because they share a CWE.
13
13
  7. Independently validate each unique finding against local source once. Establish its attacker, entry point, trust boundary, attacker-controlled dataflow, transformations, broken control, sensitive operation, prerequisites, effective mitigations, strongest counterevidence, and concrete impact. Record concise, source-backed `rootCause.summary`, `validation.summary`, `attackPath.dataflow.summary`, and `attackPath.reachability.summary` alongside their supporting facts; determine impact, likelihood, and severity from those established facts. State optional configuration, dependency-version, or deployment prerequisites; do not require proof of a real deployment or runtime reproduction. A public library or parser boundary is sufficient when callers control the input. Reject only with source-backed counterevidence, preserve valid baseline findings, record material unresolved proof gaps, and apply the severity rules below.
14
14
  8. Assemble complete semantic `scope`, `threatModel`, `findings`, and `coverage` using the plugin's `examples/completed-scan/` and `schemas/` as shape references, never as values to copy. Use the canonical field mapping and scenario reconciliation in `threat-model.md`, preserving supplied models unchanged and retaining source-backed architecture, capability, deployment, and uncertainty facts. Give each finding a stable lowercase vulnerability-family `ruleId`, its precise `taxonomy.category` and `taxonomy.cwe` values, genuine `provenance.source`, an instance when separately reported findings would otherwise collide, a `root_control` location when identifiable, all materially affected locations, calibrated severity and rationale, confidence and rationale, verified nonempty source evidence, attacker-to-sink reachability, and practical remediation. Use actual coverage surface labels and dispositions; report reviewed surfaces, explicit exclusions, deferred work, and unresolved questions honestly, and mark coverage `complete` only when the requested source scope was actually reviewed. Preserve every genuine finding, evidence item, user-supplied assumption, and unresolved proof gap in the caller's complete semantic result.
15
15
 
@@ -22,13 +22,15 @@ For each finding, supply an evidence-supported lowercase vulnerability-family `r
22
22
 
23
23
  Supply semantic coverage as `{ completeness, surfaces, explicitExclusions, deferred }`, with each surface using the actual `label` and one existing `disposition`. Mark coverage `partial` when a deferred item or `needs_follow_up` surface remains; preserve its real reason and supporting context. Each deferred item needs a meaningful reason; preserve any existing `id` or `candidateId`. The workbench derives a missing ID from its candidate identity or stable deferred-work details. Open questions may be nonempty strings or `{ question, followUpPrompt? }` objects. The workbench derives target and scope metadata, scope include and exclude paths, coverage mode and inventory strategy, finding identities and fingerprints, and surface IDs. Do not put those workbench-owned values or top-level coverage receipt references into the semantic draft.
24
24
 
25
- After a workbench-owned Standard or workbench-backed diff draft is accepted, or the Deep coordinator returns its parent scan's canonical manifest, call `complete_codex_security_scan({ scanId, handoffClaimToken? })` and use its returned completion metadata. An SDK-owned scan returns its unsealed canonical files without calling a completion tool or finalizer; the SDK owns completion and report generation. Read full canonical results only when explicitly requested. For a terminal/chat workflow without a `scanId` or completion tool, retain `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the canonical JSON. Outside the SDK path, do not mark the scan goal complete until finalization succeeds and the generated report exists.
25
+ During a host-backed scan, checkpoint saved findings and pending candidates with `complete: false`; a checkpoint is not a completed audit. After a final workbench-owned Standard or workbench-backed diff draft is accepted with `complete: true` (or the backwards-compatible omitted flag), or the Deep coordinator returns its parent scan's canonical manifest, call `complete_codex_security_scan({ scanId, handoffClaimToken? })` and use its returned completion metadata. An SDK-owned scan returns its unsealed canonical files without calling a completion tool or finalizer; the SDK owns completion and report generation. Read full canonical results only when explicitly requested. For a terminal/chat workflow without a `scanId` or completion tool, retain `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the canonical JSON. Outside the SDK path, do not mark the scan goal complete until finalization succeeds and the generated report exists.
26
+
27
+ On a confirmed failure or explicit cancellation, the workbench preserves saved results without marking the scan successful. Report validated findings separately from pending candidates and explain the incomplete coverage. Use the retained report and exports; do not start additional model work after cancellation or replace saved results with a no-findings response.
26
28
 
27
29
  After `complete_codex_security_scan` succeeds, include its returned `usage.totalTokens`, `usage.inputTokens`, and `usage.cachedInputTokens` in the final response when `usage.coverage` is `complete` or `partial`; explicitly label a partial measurement. If coverage is `unavailable`, say that token usage could not be measured instead of reporting zero or estimating a cost. Report only measured completion metadata in a terminal/chat host. Token usage is workbench metadata, not a reason to modify sealed scan artifacts or the deterministic report.
28
30
 
29
31
  Before workbench-owned Standard or workbench-backed diff completion, require `record_codex_security_scan_draft` to succeed. Before Deep completion, require the coordinator to return the parent scan's already-authored canonical manifest; do not submit another draft or rerun worker phases. SDK-owned Standard and terminal diff workflows instead verify their canonical JSON before the appropriate owner finalizes it. Completion validates and seals existing canonical artifacts and generates `report.md`; it does not create missing artifacts or run skipped scan phases.
30
32
 
31
- An MCP `-32602` input rejection, an `isError: true` result reporting `Input validation error`, or an explicit pre-write rejection of complete coverage containing deferred work or a follow-up surface makes no draft write. Correct only the named paths in the same draft, preserving all valid findings, fields, evidence, and deferred work; retry the same scan at most twice. Stop after the first accepted draft. Do not blindly retry an ambiguous transport or write failure.
33
+ An MCP `-32602` input rejection, an `isError: true` result reporting `Input validation error`, or an explicit pre-write rejection of complete coverage containing deferred work or a follow-up surface makes no draft write. Correct only the named paths in the same draft, preserving all valid findings, fields, evidence, and deferred work; retry the same scan at most twice. Stop final submission after the first accepted complete draft; an accepted complete:false checkpoint does not end the audit. Do not blindly retry an ambiguous transport or write failure.
32
34
 
33
35
  For any other required scan phase, canonical-artifact write, or on-disk existence check that fails before completion, stop the current response and surface the exact workflow blocker. Do not call completion with missing artifacts, return a final report or no-findings result, or satisfy a structured output schema. Leave the durable scan available for a later continuation instead of canceling or failing it solely because canonical assembly is blocked.
34
36
 
@@ -40,7 +40,7 @@ End each repository-scoped threat model with these two lines:
40
40
 
41
41
  ### Compact Deep And Workbench-Backed Diff Discovery
42
42
 
43
- Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Deep scans run complete Standard scan workers, each of which submits its validated findings, coverage, threat model, and optional scope through its bound `record_codex_security_scan_draft` tool. The coordinator semantically reduces those complete results and writes the parent scan's unsealed `scan-manifest.json`, `findings.json`, and `coverage.json`. The parent does not list candidates, rerun validation or attack-path phases, or submit another draft. Workbench-backed diff scans retain the compact artifacts described below.
43
+ Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Deep scans run complete Standard scan workers, each of which saves `complete: false` checkpoints and submits its final validated findings, coverage, threat model, and optional scope through its bound `record_codex_security_scan_draft` tool. Pending candidates retain their original evidence in `coverage.deferred`. Host-owned immutable checkpoints survive retries, cancellation, and failure; a checkpoint alone is never an accepted complete worker result. The coordinator semantically reduces those complete results and writes the parent scan's unsealed `scan-manifest.json`, `findings.json`, and `coverage.json`. The parent does not list candidates, rerun validation or attack-path phases, or submit another draft. Workbench-backed diff scans retain the compact artifacts described below.
44
44
 
45
45
  - A workbench-backed diff scan records all candidates once with `record_codex_security_discovery_candidates({ scanId, candidates })` and reads the canonical candidates with `list_codex_security_candidates({ scanId, cursor?, limit? })`.
46
46
  - The writer validates candidates against assigned source paths, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values.
@@ -1,13 +1,13 @@
1
- # Completed Scan Contract
1
+ # Sealed Scan Contract
2
2
 
3
- This contract defines the canonical machine-readable documents for completed scans and their readable markdown report projection.
3
+ This contract defines the canonical machine-readable documents for scans that reached a sealed terminal outcome and their readable markdown report projection.
4
4
 
5
5
  ## Canonical Documents
6
6
 
7
- A completed semantic bundle contains these files under `<scan_dir>`:
7
+ A sealed terminal bundle contains these files under `<scan_dir>`:
8
8
 
9
- - `scan-manifest.json`: immutable completed-scan receipt after finalization
10
- - `findings.json`: semantic finding records for the completed scan
9
+ - `scan-manifest.json`: immutable terminal scan receipt after finalization
10
+ - `findings.json`: semantic finding records retained when the scan reached its terminal outcome
11
11
  - `coverage.json`: structured coverage summary with detailed receipt references
12
12
 
13
13
  Canonical UTF-8 document sizes are bounded consistently by the producer and SDK: `scan-manifest.json` is limited to 16 MiB, `findings.json` to 128 MiB, and `coverage.json` to 32 MiB. Finalization rejects oversized inputs or generated documents before sealing or changing scan outputs. Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
@@ -20,11 +20,22 @@ Deep-scan SARIF results and CSV rows preserve their existing instance-level pres
20
20
 
21
21
  This bundle records immutable scan observations. It is not a workflow-state database. Consumers must store mutable annotations, lifecycle decisions, external links, retention policy, and synchronization state separately.
22
22
 
23
- Retention is an explicit consumer decision. Producing a completed-scan bundle must not silently copy it into an archive.
23
+ Retention is an explicit consumer decision. Producing a sealed bundle must not silently copy it into an archive.
24
24
 
25
25
  ## Manifest Semantics
26
26
 
27
- A sealed manifest records the completed timestamp and hashes for the canonical documents and immutable evidence receipts included in that bundle. Readable reports and generated exports are projections and are not included in the canonical seal. Later adapters may read the sealed bundle to create projections, but must not mutate the sealed manifest or canonical documents. Store projections separately. Every sealed manifest includes exactly one artifact record for each canonical JSON document, and artifact paths must not repeat.
27
+ A sealed manifest records the terminal timestamp and hashes for the canonical documents and immutable evidence receipts included in that bundle. Readable reports and generated exports are projections and are not included in the canonical seal. Later adapters may read the sealed bundle to create projections, but must not mutate the sealed manifest or canonical documents. Store projections separately. Every sealed manifest includes exactly one artifact record for each canonical JSON document, and artifact paths must not repeat.
28
+
29
+ `scan.status` records why the bundle was sealed:
30
+
31
+ | Status | Meaning |
32
+ | --- | --- |
33
+ | `completed` | The requested scan reached normal completion. |
34
+ | `failed` | The scan stopped after an unrecoverable failure; retained artifacts may be partial. |
35
+ | `canceled` | The scan stopped after an explicit cancellation; retained artifacts may be partial. |
36
+ | `interrupted` | The scan stopped before normal completion because execution was interrupted; retained artifacts may be partial. |
37
+
38
+ Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and coverage while treating absence of findings as inconclusive.
28
39
 
29
40
  ## Target Snapshots
30
41
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://openai.com/codex-security/schemas/scan-manifest.schema.json",
4
- "title": "Codex Security completed scan manifest",
4
+ "title": "Codex Security sealed scan manifest",
5
5
  "type": "object",
6
6
  "required": [
7
7
  "documentType",
@@ -53,7 +53,7 @@
53
53
  }
54
54
  },
55
55
  "status": {
56
- "const": "completed"
56
+ "enum": ["completed", "failed", "canceled", "interrupted"]
57
57
  },
58
58
  "startedAt": {
59
59
  "type": "string",
@@ -574,6 +574,25 @@
574
574
  "provenance": {
575
575
  "type": "object",
576
576
  "properties": {
577
+ "sourceFindingIds": {
578
+ "type": "array",
579
+ "items": { "$ref": "#/$defs/text" },
580
+ "uniqueItems": true,
581
+ "description": "Host-provided source finding references represented by this Deep reduction. Preserve every assigned reference exactly once."
582
+ },
583
+ "sourceFindings": {
584
+ "type": "array",
585
+ "items": {
586
+ "type": "object",
587
+ "properties": {
588
+ "id": { "$ref": "#/$defs/text" },
589
+ "finding": { "type": "object", "additionalProperties": true }
590
+ },
591
+ "required": ["id", "finding"],
592
+ "additionalProperties": false
593
+ },
594
+ "description": "Original source payloads retained by the host for lossless semantic merges."
595
+ },
577
596
  "source": {
578
597
  "$ref": "#/$defs/text",
579
598
  "description": "The actual finding producer. Use local_plugin only for a finding discovered by this plugin."
@@ -805,6 +824,10 @@
805
824
  "scanDraftInput": {
806
825
  "type": "object",
807
826
  "properties": {
827
+ "complete": {
828
+ "type": "boolean",
829
+ "description": "Set false to save progress without declaring this worker or parent audit finished. Omit or set true only for the terminal result. Put provisional candidates in coverage.deferred, not findings."
830
+ },
808
831
  "scanId": {
809
832
  "$ref": "#/$defs/scanId"
810
833
  },
@@ -3,6 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
+ import hashlib
6
7
  import json
7
8
  import os
8
9
  import shutil
@@ -39,6 +40,8 @@ DEEP_SCAN_TERMINAL_REASONS = ("saturated", "capped")
39
40
  DEEP_SCAN_WORKFLOW_VERSION = "deep-security-scan/v1"
40
41
  DEEP_SCAN_COORDINATOR_LEASE_SECONDS = 30
41
42
  DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS = 120
43
+ DEEP_SCAN_MAX_ERROR_LENGTH = 2400
44
+ DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR = "\nOriginal Deep Scan failure:\n"
42
45
 
43
46
 
44
47
  def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) -> None:
@@ -120,6 +123,11 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
120
123
  )
121
124
  fail_deep_scan.add_argument("--coordinator-generation", type=positive_int)
122
125
 
126
+ publication_failure = subparsers.add_parser("record-deep-scan-publication-failure")
127
+ publication_failure.add_argument("--scan-id", required=True)
128
+ publication_failure.add_argument("--message", required=True)
129
+ publication_failure.add_argument("--coordinator-generation", type=positive_int)
130
+
123
131
 
124
132
  def non_negative_int(value: str) -> int:
125
133
  parsed = int(value)
@@ -143,6 +151,7 @@ class DeepScanDependencies:
143
151
  safe_segment: Callable[[str], str]
144
152
  compact_timestamp: Callable[[], str]
145
153
  scan_completion_lock: Callable[[str], Any]
154
+ preserve_stopped_results: Callable[[sqlite3.Connection, str], None]
146
155
 
147
156
 
148
157
  _dependencies: DeepScanDependencies | None = None
@@ -163,6 +172,34 @@ def now() -> str:
163
172
  return dependencies().now()
164
173
 
165
174
 
175
+ def _bounded_error_text(message: str, maximum: int) -> str:
176
+ if len(message) <= maximum:
177
+ return message
178
+ digest = hashlib.sha256(message.encode()).hexdigest()
179
+ suffix = f"\n...[truncated; sha256:{digest}]"
180
+ if len(suffix) >= maximum:
181
+ return message[:maximum]
182
+ return f"{message[: maximum - len(suffix)]}{suffix}"
183
+
184
+
185
+ def deep_scan_error(run: sqlite3.Row) -> str | None:
186
+ original = run["error_message"]
187
+ publication = run["publication_error_message"]
188
+ if not isinstance(publication, str):
189
+ return original if isinstance(original, str) else None
190
+ if not isinstance(original, str):
191
+ return publication
192
+ available = DEEP_SCAN_MAX_ERROR_LENGTH - len(DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR)
193
+ publication_budget = min(len(publication), available // 2)
194
+ original_budget = min(len(original), available - publication_budget)
195
+ publication_budget = min(len(publication), available - original_budget)
196
+ return (
197
+ _bounded_error_text(publication, publication_budget)
198
+ + DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR
199
+ + _bounded_error_text(original, original_budget)
200
+ )
201
+
202
+
166
203
  def _parse_timestamp(value: str) -> datetime:
167
204
  if isinstance(value, str) and value.endswith(("Z", "z")):
168
205
  value = value[:-1] + "+00:00"
@@ -439,7 +476,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
439
476
  "canonicalArtifacts": canonical_artifacts,
440
477
  "manifestPath": run["manifest_path"],
441
478
  "terminalReason": run["terminal_reason"],
442
- "error": run["error_message"],
479
+ "error": deep_scan_error(run),
443
480
  "createdAt": run["created_at"],
444
481
  "updatedAt": run["updated_at"],
445
482
  "completedAt": run["completed_at"],
@@ -2022,9 +2059,59 @@ def fail_deep_scan_locked(
2022
2059
  raise
2023
2060
  if promotion is not None:
2024
2061
  finish_staged_file(promotion)
2062
+ dependencies().preserve_stopped_results(connection, scan_id)
2063
+ return deep_scan_result(connection, scan_id)
2064
+
2065
+
2066
+ def record_deep_scan_publication_failure(
2067
+ connection: sqlite3.Connection, args: argparse.Namespace
2068
+ ) -> dict[str, Any]:
2069
+ scan_id = require_uuid(args.scan_id, "scan-id")
2070
+ message = optional_text(args.message, maximum=2400)
2071
+ if message is None:
2072
+ raise SystemExit("message is required.")
2073
+ with scan_completion_lock(scan_id):
2074
+ connection.execute("BEGIN IMMEDIATE")
2075
+ try:
2076
+ run = require_deep_scan_run(connection, scan_id)
2077
+ require_current_coordinator(run, args)
2078
+ scan = require_scan(connection, scan_id)
2079
+ if (
2080
+ run["status"] not in {"failed", "canceled", "interrupted"}
2081
+ or scan["status"] != "failed"
2082
+ ):
2083
+ raise SystemExit(
2084
+ "Saved result publication failures can only update a stopped Deep Scan."
2085
+ )
2086
+ if scan["seal_manifest_digest"] is not None:
2087
+ connection.commit()
2088
+ return deep_scan_result(connection, scan_id)
2089
+ if run["publication_error_message"] != message:
2090
+ timestamp = now()
2091
+ connection.execute(
2092
+ """
2093
+ UPDATE deep_scan_runs
2094
+ SET publication_error_message = ?, updated_at = ?
2095
+ WHERE scan_id = ?
2096
+ """,
2097
+ (message, timestamp, scan_id),
2098
+ )
2099
+ connection.commit()
2100
+ except BaseException:
2101
+ connection.rollback()
2102
+ raise
2025
2103
  return deep_scan_result(connection, scan_id)
2026
2104
 
2027
2105
 
2106
+ def clear_deep_scan_publication_failure(connection: sqlite3.Connection, scan_id: str) -> None:
2107
+ with connection:
2108
+ connection.execute(
2109
+ "UPDATE deep_scan_runs SET publication_error_message = NULL, updated_at = ? "
2110
+ "WHERE scan_id = ? AND publication_error_message IS NOT NULL",
2111
+ (now(), scan_id),
2112
+ )
2113
+
2114
+
2028
2115
  def fail_from_parent_scan(
2029
2116
  connection: sqlite3.Connection,
2030
2117
  scan_id: str,
@@ -857,6 +857,20 @@ def _recover_unsealed_findings(
857
857
 
858
858
  if previous_position is not None:
859
859
  previous = recovered[previous_position]
860
+ strongest, earlier = (
861
+ (previous, finding)
862
+ if _finding_strength(finding) <= _finding_strength(previous)
863
+ else (finding, previous)
864
+ )
865
+ if strongest != earlier:
866
+ original = copy.deepcopy(earlier)
867
+ older = original["provenance"].pop("previousFindings", [])
868
+ if not isinstance(strongest["provenance"].get("previousFindings"), list):
869
+ strongest["provenance"]["previousFindings"] = []
870
+ history = strongest["provenance"]["previousFindings"]
871
+ for record in [*(older if isinstance(older, list) else []), original]:
872
+ if record not in history:
873
+ history.append(record)
860
874
  if _finding_strength(finding) <= _finding_strength(previous):
861
875
  warnings.append(
862
876
  f"Skipped malformed finding {index + 1}: duplicate logical finding."
@@ -1060,7 +1074,9 @@ def _populate_unsealed_manifest_envelope(
1060
1074
 
1061
1075
  manifest["documentType"] = "codex-security.scan-manifest"
1062
1076
  manifest["schemaVersion"] = SCHEMA_VERSION
1063
- scan["status"] = "completed"
1077
+ scan["status"] = (
1078
+ completion_binding.get("status", "completed") if completion_binding else "completed"
1079
+ )
1064
1080
  scan["coverageRef"] = "coverage.json"
1065
1081
  scan["findingsRef"] = "findings.json"
1066
1082
  if completion_binding is None:
@@ -1188,6 +1204,8 @@ def _validate_completion_binding(
1188
1204
  scan = _require_dict(manifest, "scan", "manifest")
1189
1205
  if scan.get("id") != completion_binding["scanId"]:
1190
1206
  raise ContractError("manifest.scan.id: must match the workbench scan")
1207
+ if scan.get("status") != completion_binding.get("status", "completed"):
1208
+ raise ContractError("manifest.scan.status: must match the workbench outcome")
1191
1209
  if scan.get("startedAt") != completion_binding["startedAt"]:
1192
1210
  raise ContractError("manifest.scan.startedAt: must match the workbench scan")
1193
1211
  if scan.get("completedAt") != completion_binding["completedAt"]:
@@ -1370,8 +1388,8 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1370
1388
  scan = _require_dict(manifest, "scan", "manifest")
1371
1389
  for key in ("id", "startedAt", "completedAt", "sealedAt"):
1372
1390
  _require_str(scan, key, "manifest.scan")
1373
- if scan.get("status") != "completed":
1374
- raise ContractError("manifest.scan.status: expected completed")
1391
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
1392
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome")
1375
1393
  producer = _require_dict(scan, "producer", "manifest.scan")
1376
1394
  _require_str(producer, "name", "manifest.scan.producer")
1377
1395
  _require_str(producer, "version", "manifest.scan.producer")
@@ -2175,7 +2193,7 @@ def _artifact_record(
2175
2193
  ) -> dict[str, str]:
2176
2194
  relative_path = _require_portable_relative_path(relative_path, "artifact path")
2177
2195
  if contents is not None:
2178
- _require_scan_local_file(scan_dir, relative_path, relative_path)
2196
+ _validate_scan_local_output_path(scan_dir, scan_dir / relative_path, relative_path)
2179
2197
  return {
2180
2198
  "mediaType": media_type,
2181
2199
  "path": relative_path,
@@ -2292,12 +2310,18 @@ def build_sarif_projection(
2292
2310
  sarif = build_sarif(manifest, findings, source_root)
2293
2311
  run = sarif["runs"][0]
2294
2312
  completeness = coverage["completeness"]
2295
- run["invocations"] = [{"executionSuccessful": completeness == "complete"}]
2296
- if completeness != "complete":
2313
+ scan_status = manifest["scan"]["status"]
2314
+ execution_successful = scan_status == "completed" and completeness == "complete"
2315
+ run["invocations"] = [{"executionSuccessful": execution_successful}]
2316
+ if not execution_successful:
2297
2317
  run["properties"]["codexSecurityCoverageCompleteness"] = completeness
2298
- reasons = [item["reason"] for item in coverage["deferred"]] or [
2299
- f"Scan coverage is {completeness}; results may be incomplete."
2300
- ]
2318
+ reasons = [item["reason"] for item in coverage["deferred"]]
2319
+ if not reasons:
2320
+ reasons = [
2321
+ f"Scan status is {scan_status}; results may be incomplete."
2322
+ if scan_status != "completed"
2323
+ else f"Scan coverage is {completeness}; results may be incomplete."
2324
+ ]
2301
2325
  run["invocations"][0]["toolExecutionNotifications"] = [
2302
2326
  {"level": "warning", "message": {"text": reason}} for reason in reasons
2303
2327
  ]
@@ -2326,6 +2350,13 @@ def csv_cell(value: Any) -> Any:
2326
2350
 
2327
2351
 
2328
2352
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2353
+ provenance = finding.get("provenance")
2354
+ if (
2355
+ isinstance(provenance, dict)
2356
+ and isinstance(value := provenance.get("candidateId"), str)
2357
+ and value.strip()
2358
+ ):
2359
+ return value
2329
2360
  extensions = finding.get("extensions")
2330
2361
  if not isinstance(extensions, dict):
2331
2362
  return None
@@ -2517,23 +2548,32 @@ def _prepare_scan_finalization(
2517
2548
  expected_coverage_mode: str | None = None,
2518
2549
  completion_binding: dict[str, Any] | None = None,
2519
2550
  completion_warnings: list[str] | None = None,
2551
+ draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
2520
2552
  ) -> PreparedScanFinalization:
2521
2553
  """Read, populate, and validate a scan without writing any output files."""
2522
2554
 
2523
2555
  scan_dir = _require_scan_directory(scan_dir)
2524
2556
  schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2525
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2557
+ manifest = (
2558
+ copy.deepcopy(draft_documents[0])
2559
+ if draft_documents is not None
2560
+ else _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2561
+ )
2526
2562
  scan = _require_dict(manifest, "scan", "manifest")
2527
2563
  was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
2528
2564
  if not was_sealed:
2529
2565
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
2530
2566
  _validate_contract_refs(scan)
2531
- findings, findings_input_bytes = _read_scan_local_json_bytes(
2532
- scan_dir, scan["findingsRef"], scan["findingsRef"]
2533
- )
2534
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2535
- scan_dir, scan["coverageRef"], scan["coverageRef"]
2536
- )
2567
+ if draft_documents is None:
2568
+ findings, findings_input_bytes = _read_scan_local_json_bytes(
2569
+ scan_dir, scan["findingsRef"], scan["findingsRef"]
2570
+ )
2571
+ coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2572
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
2573
+ )
2574
+ else:
2575
+ findings, coverage = copy.deepcopy(draft_documents[1:])
2576
+ findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
2537
2577
  if not was_sealed:
2538
2578
  _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
2539
2579
  _normalize_unsealed_deep_repository_inventory_strategy(
@@ -2544,8 +2584,8 @@ def _prepare_scan_finalization(
2544
2584
 
2545
2585
  if manifest.get("schemaVersion") != SCHEMA_VERSION:
2546
2586
  raise ContractError(f"manifest.schemaVersion: expected {SCHEMA_VERSION}")
2547
- if scan.get("status") != "completed":
2548
- raise ContractError("manifest.scan.status: expected completed before sealing")
2587
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
2588
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome before sealing")
2549
2589
  if (
2550
2590
  expected_coverage_mode is not None
2551
2591
  and completion_binding is not None
@@ -865,6 +865,7 @@ def build_report_markdown(
865
865
  "",
866
866
  "| Field | Value |",
867
867
  "| --- | --- |",
868
+ f"| Scan outcome | {scan.get('status', 'completed')} |",
868
869
  *summary_count_lines,
869
870
  f"| Coverage | {coverage['completeness']} |",
870
871
  f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
@@ -973,20 +974,30 @@ def build_report_markdown(
973
974
  for item in deferred
974
975
  )
975
976
  )
977
+ stopped = manifest.get("scan", {}).get("status") in {
978
+ "failed",
979
+ "canceled",
980
+ "interrupted",
981
+ }
976
982
  lines.extend(
977
983
  [
978
984
  "### No findings",
979
985
  "",
980
986
  (
981
- "No source review completed before the configured time limit. "
982
- "No vulnerability conclusion can be drawn."
983
- if no_source_review
987
+ "No findings were retained before the scan stopped. "
988
+ "The scan did not complete. No vulnerability conclusion can be drawn."
989
+ if stopped
984
990
  else (
985
- "No findings were validated before the scan reached its cost limit. "
986
- "Review the deferred candidates in Open Questions And Follow Up."
987
- if budget_exhausted
988
- else "No reportable findings survived the canonical discovery, validation, "
989
- "and reportability gates."
991
+ "No source review completed before the configured time limit. "
992
+ "No vulnerability conclusion can be drawn."
993
+ if no_source_review
994
+ else (
995
+ "No findings were validated before the scan reached its cost limit. "
996
+ "Review the deferred candidates in Open Questions And Follow Up."
997
+ if budget_exhausted
998
+ else "No reportable findings survived the canonical discovery, validation, "
999
+ "and reportability gates."
1000
+ )
990
1001
  )
991
1002
  ),
992
1003
  ]
@@ -241,6 +241,19 @@ def parse_args(description: str) -> argparse.Namespace:
241
241
  fail_scan.add_argument("--claim-token")
242
242
  fail_scan.add_argument("--cost-json")
243
243
 
244
+ preserve_scan = subparsers.add_parser("preserve-scan-results")
245
+ preserve_scan.add_argument("--scan-id", required=True)
246
+ preserve_scan.add_argument("--thread-id")
247
+ preserve_scan.add_argument("--claim-token")
248
+ preserve_scan.add_argument("--coordinator-generation", type=positive_int)
249
+
250
+ write_scan_draft = subparsers.add_parser("write-scan-draft")
251
+ write_scan_draft.add_argument("--scan-id", required=True)
252
+ write_scan_draft.add_argument("--draft-path", required=True)
253
+ write_scan_draft.add_argument("--checkpoint-path")
254
+ write_scan_draft.add_argument("--expected-draft-digest")
255
+ write_scan_draft.add_argument("--claim-token")
256
+
244
257
  mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
245
258
  mark_handoff_delivered.add_argument("--scan-id", required=True)
246
259
  mark_handoff_delivered.add_argument("--claim-token", required=True)