@openai/codex-security 0.1.2 → 0.1.4

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 CHANGED
@@ -15,10 +15,11 @@ npm install @openai/codex-security
15
15
  npx @openai/codex-security --version
16
16
  ```
17
17
 
18
- The package supports macOS, Linux, and Windows and requires Node.js 22 or
19
- later. Scanning and exporting findings also require Python 3.10 or later. If
20
- you use Python 3.10, install the `tomli` package. Select another interpreter
21
- with `--python`, `pythonPath`, or `PYTHON` when needed.
18
+ The package supports macOS, Linux, and Windows and requires Node.js 22.13.0 or
19
+ later in the 22.x release line, Node.js 24.x, or Node.js 26.x. Scanning and
20
+ exporting findings also require Python 3.10 or later. If you use Python 3.10,
21
+ install the `tomli` package. Select another interpreter with `--python`,
22
+ `pythonPath`, or `PYTHON` when needed.
22
23
 
23
24
  When a newer version is available, the CLI shows the update command for your
24
25
  installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
@@ -56,6 +57,39 @@ Results can contain source excerpts, vulnerability details, and reproduction
56
57
  steps. Keep result directories and saved reports outside the repository and
57
58
  limit access to authorized reviewers.
58
59
 
60
+ ### SDK configuration and scan options
61
+
62
+ Pass runtime configuration to the `CodexSecurity` constructor:
63
+
64
+ | Option | Description |
65
+ | ---------------- | --------------------------------------------------------------------------- |
66
+ | `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |
67
+ | `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |
68
+ | `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |
69
+
70
+ Pass scan configuration to `security.run(repository, options)` or
71
+ `security.preflight(repository, options)`:
72
+
73
+ | Option | Description |
74
+ | ----------------------- | ------------------------------------------------------------------------------------- |
75
+ | `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
76
+ | `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
77
+ | `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
78
+ | `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
79
+ | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
80
+ | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
81
+ | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
82
+ | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
83
+ | `parentScanId` | Link a rerun to an existing parent scan. |
84
+ | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
85
+ | `signal` | Cancel a scan with an `AbortSignal`. |
86
+
87
+ Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
88
+ `onOutputArchived`, `onOutputDirReady`, `onScanStarted`, `onReconnect`,
89
+ `onWorkerStatus`, `onWarning`, and `onObserverError`. Preflight does not start
90
+ the runtime, authenticate, resolve Python, inspect the plugin, or run those
91
+ scan-lifecycle callbacks.
92
+
59
93
  ## Authentication
60
94
 
61
95
  For local use, sign in with ChatGPT:
@@ -78,6 +112,14 @@ pass it on stdin:
78
112
  printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
79
113
  ```
80
114
 
115
+ Environment API keys are supplied directly to the current scan and are never
116
+ saved to the Codex credential home or system keyring. Only an explicit
117
+ `login --with-api-key` stores an API key.
118
+
119
+ To pass a Codex access token explicitly, use
120
+ `login --with-access-token` and provide the token on stdin. An access token
121
+ environment variable is not automatically used as a scan API key.
122
+
81
123
  On Windows, set the API key in PowerShell:
82
124
 
83
125
  ```powershell
@@ -85,10 +127,16 @@ $env:OPENAI_API_KEY = "<your-api-key>"
85
127
  npx @openai/codex-security scan C:\code\repository
86
128
  ```
87
129
 
88
- Check or remove the stored sign-in with `npx @openai/codex-security login status` and
89
- `npx @openai/codex-security logout`. Codex Security reuses an existing file-based Codex
90
- sign-in. If Codex stores credentials in the system keyring, run
91
- `npx @openai/codex-security login` once before scanning.
130
+ Check or remove the stored sign-in with `npx @openai/codex-security login status`
131
+ and `npx @openai/codex-security logout`. Codex Security keeps its sign-in in a
132
+ private, stable Codex home at `$CODEX_SECURITY_STATE_DIR/codex-home`, or at
133
+ `$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is
134
+ configured. Login, status, logout, and scans use the same home. Codex manages
135
+ credentials using its configured file or system-keyring backend and honors
136
+ managed-device policies. An existing file-based Codex sign-in is imported only
137
+ when the dedicated home does not already contain stored credentials. Logging
138
+ out prevents later scans from automatically reimporting that ambient sign-in
139
+ until you explicitly log in again.
92
140
 
93
141
  An environment API key takes precedence over a stored sign-in by default.
94
142
  When both a stored ChatGPT sign-in and an environment API key are available, an
@@ -197,6 +245,127 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
197
245
  `--codex KEY=VALUE` for other Codex settings; existing
198
246
  `--codex 'model_reasoning_effort="high"'` overrides remain supported.
199
247
 
248
+ ### Runtime configuration and worker limits
249
+
250
+ The standalone CLI and SDK do not load an unrelated user or repository Codex
251
+ configuration. Each scan starts with a private runtime and these Codex
252
+ defaults:
253
+
254
+ ```toml
255
+ cli_auth_credentials_store = "file"
256
+ model = "gpt-5.6-sol"
257
+ model_reasoning_effort = "xhigh"
258
+
259
+ [features]
260
+ plugins = true
261
+ goals = true
262
+
263
+ [features.multi_agent_v2]
264
+ enabled = true
265
+ max_concurrent_threads_per_session = 9
266
+
267
+ [windows]
268
+ sandbox = "unelevated"
269
+ ```
270
+
271
+ Use `--model` and `--effort` for model selection. Repeat
272
+ `--codex KEY=VALUE` to deep-merge other TOML values into this isolated
273
+ configuration:
274
+
275
+ ```bash
276
+ npx @openai/codex-security scan . \
277
+ --model gpt-5.6-terra \
278
+ --effort high \
279
+ --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
280
+ ```
281
+
282
+ The session thread limit includes the parent agent: the default of `9`
283
+ provides up to eight delegated worker slots. This limit is separate from
284
+ `bulk-scan --workers`, which controls how many repositories run concurrently.
285
+ A configured limit is a maximum, not evidence that every worker started.
286
+
287
+ Quote string values as TOML, for example
288
+ `--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
289
+ `--codex 'model="..."'`, or both `--effort` and
290
+ `--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
291
+ rejected.
292
+
293
+ Plugin and marketplace loading belong to Codex Security. Overrides of
294
+ `plugins`, `marketplaces`, or `features.plugins`, including profile-specific
295
+ plugin overrides, are rejected; choose `--plugin-path` instead. Native
296
+ multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting
297
+ and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
298
+ `validate` and `patch` accept `--effort` and only the `model` and
299
+ `model_reasoning_effort` `--codex` keys; they do not accept general scan
300
+ runtime overrides.
301
+
302
+ These overrides do not change the scan's approval policy or filesystem
303
+ permissions. See [Local security model](#local-security-model).
304
+
305
+ ### Deep-scan engine configuration
306
+
307
+ When the bundled plugin runs in a normal Codex host, its repeated-discovery
308
+ engine reads `$CODEX_HOME/codex-security/config.toml`, defaulting to
309
+ `~/.codex/codex-security/config.toml`:
310
+
311
+ ```toml
312
+ [deep_scan]
313
+ workers = "auto"
314
+ subagents = 3
315
+ stop_after_no_new = 6
316
+ max_discovery_runs = 60
317
+ ```
318
+
319
+ `workers = "auto"` uses half the available parallelism, with a minimum of one
320
+ and a maximum of six discovery workers. Set `workers` to a positive integer to
321
+ choose an explicit count. `subagents` must be a nonnegative integer;
322
+ `stop_after_no_new` and `max_discovery_runs` must be positive integers. Unknown
323
+ `[deep_scan]` keys are rejected.
324
+
325
+ These settings are separate from Codex's
326
+ `features.multi_agent_v2.max_concurrent_threads_per_session` and
327
+ `bulk-scan --workers`. Importantly, standalone CLI and SDK scans create an
328
+ isolated `CODEX_HOME` and do not import the ambient deep-scan configuration
329
+ file. Consequently, `scan --mode deep` currently uses the deep engine's
330
+ defaults; there are no standalone CLI flags for these four settings. Use
331
+ `--codex` to adjust the Codex session thread limit, not to set `[deep_scan]`
332
+ values.
333
+
334
+ ### Environment variables
335
+
336
+ The CLI and SDK recognize the following user-configurable environment:
337
+
338
+ | Variable | Effect |
339
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
340
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
341
+ | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
342
+ | `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
343
+ | `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
344
+ | `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
345
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
346
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |
347
+ | `CI` | Disable interactive update notices in automated environments. |
348
+ | `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |
349
+
350
+ Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,
351
+ the managed Codex runtime, and finally `python3` or `python` from `PATH`.
352
+ `CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both
353
+ state and result paths outside the scanned repository.
354
+
355
+ The repository's Docker Compose workflow additionally recognizes
356
+ `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,
357
+ `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for
358
+ its image, runtime user, seccomp profile, input, results, and state mounts.
359
+ Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and
360
+ `CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.
361
+ These container settings are distinct from standalone CLI flags and
362
+ interactive discovery's `GH_HOST`.
363
+
364
+ Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
365
+ `CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and
366
+ `CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
367
+ internal runtime data, not supported user configuration.
368
+
200
369
  Scan progress identifies the requested paths and reports actual ranking,
201
370
  file-review, validation, and attack-path phases as they become available.
202
371
  Completion summarizes findings, severity, coverage, elapsed time, available
@@ -241,7 +410,8 @@ Results remain under `--output-dir`; rerun the same command to resume.
241
410
  `npx @openai/codex-security scans list` lists scans for the current repository. Pass a
242
411
  repository path to inspect another checkout, `--scan-root DIR` to list scans
243
412
  whose artifacts are under a particular root. `scans show SCAN_ID` includes the
244
- scan configuration, results, coverage, and artifact locations.
413
+ scan configuration, results, coverage, and artifact locations. Add
414
+ `--show-linked-findings` to include finding links from previous scans.
245
415
 
246
416
  Every scan history command accepts a full scan ID or a unique prefix of at
247
417
  least eight characters.
@@ -344,6 +514,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
344
514
  failures and rate limits remain retryable; definitive authentication and model
345
515
  authorization failures stop immediately.
346
516
 
517
+ ## Local security model
518
+
519
+ Codex Security runs with your local operating-system permissions. Scan only
520
+ repositories you trust and either own or are authorized to assess. Your
521
+ repository, Git installation, configured tools, and other scans under the
522
+ same account are not separate security principals.
523
+
524
+ Every scan uses the `codex_security_scan` filesystem profile and
525
+ `approvalPolicy: "never"`. It can read the local filesystem and write to
526
+ workspace roots and the selected scan state directory. Scans do not request
527
+ interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
528
+ through `--codex` or SDK `codexOverrides` does not replace these controls or
529
+ make them more restrictive. Independently enforced host and network
530
+ restrictions still apply.
531
+
532
+ Scan and workbench subprocesses can inherit your environment, including
533
+ unrelated API tokens and cloud credentials. Start a scan with only the
534
+ credentials it needs.
535
+
536
+ The scanner must stay within the target and output paths you authorize and
537
+ must not disclose private data beyond the operation you requested. Its results
538
+ must accurately report the scan mode, reviewed files, and exclusions. Consult
539
+ the security policy for the full threat model and private reporting process.
540
+
347
541
  ## Documentation and security
348
542
 
349
543
  - [CLI quickstart](https://developers.openai.com/codex/security/cli)
@@ -31,6 +31,8 @@ A sealed manifest records the completed timestamp and hashes for the canonical d
31
31
  Choose the target kind based on the reviewed content, not the scan invocation:
32
32
  `git_worktree` for a checked-out Git workspace, `directory_snapshot` for a non-Git directory, `git_diff` for a Git-backed change set, and `git_revision` for an exact immutable Git tree.
33
33
 
34
+ For a workbench-backed scan, use the recorded target contract instead of inferring the kind from the checkout. A clean Git checkout has `allowedKinds: ["git_revision"]`: use its recorded revision and omit `snapshotDigest`. A dirty checkout has `allowedKinds: ["git_worktree"]`: copy `requiredSnapshotDigest` exactly.
35
+
34
36
  | Kind | Required snapshot fields |
35
37
  | --- | --- |
36
38
  | `git_revision` | `revision` |
@@ -239,7 +239,7 @@ def deep_scan_path(
239
239
  resolved.relative_to(scan_dir)
240
240
  except (OSError, RuntimeError, ValueError) as exc:
241
241
  raise SystemExit(f"{label} must be an existing path inside the scan directory.") from exc
242
- if resolved != supplied.absolute():
242
+ if os.path.normcase(resolved) != os.path.normcase(supplied.absolute()):
243
243
  raise SystemExit(f"{label} must be a canonical non-symlink path.")
244
244
  if kind == "file" and not resolved.is_file():
245
245
  raise SystemExit(f"{label} must be a regular file.")
@@ -316,7 +316,7 @@ def _require_scan_directory(scan_dir: Path) -> Path:
316
316
  resolved = scan_dir.resolve(strict=True)
317
317
  except OSError as exc:
318
318
  raise ContractError("scan directory: expected an existing non-symlink directory") from exc
319
- if resolved != scan_dir:
319
+ if os.path.normcase(resolved) != os.path.normcase(scan_dir):
320
320
  raise ContractError("scan directory: expected a canonical non-symlink directory")
321
321
  return resolved
322
322
 
@@ -327,7 +327,10 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
327
327
  resolved_parent.relative_to(scan_dir)
328
328
  except (OSError, RuntimeError, ValueError) as exc:
329
329
  raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
330
- if resolved_parent != path.parent or path.is_symlink():
330
+ if (
331
+ os.path.normcase(resolved_parent) != os.path.normcase(path.parent)
332
+ or path.is_symlink()
333
+ ):
331
334
  raise ContractError(
332
335
  f"{relative_path}: expected a non-symlink path inside the scan directory"
333
336
  )
@@ -767,6 +770,267 @@ def _populate_unsealed_finding_identities(
767
770
  finding["fingerprints"] = fingerprints
768
771
 
769
772
 
773
+ def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
774
+ return (
775
+ ("informational", "low", "medium", "high", "critical").index(finding["severity"]["level"]),
776
+ ("low", "medium", "high").index(finding["confidence"]["level"]),
777
+ len(finding.get("codeEvidence") or []),
778
+ )
779
+
780
+
781
+ def _recover_unsealed_findings(
782
+ manifest: dict[str, Any],
783
+ findings: dict[str, Any],
784
+ schema_dir: Path,
785
+ scan_dir: Path,
786
+ warnings: list[str],
787
+ ) -> list[str]:
788
+ schema = _read_json(schema_dir / "findings.schema.json")
789
+ _require_safe_schema(schema, "findings.schema.json")
790
+ properties = _require_dict(schema, "properties", "findings.schema")
791
+ finding_array = _require_dict(properties, "findings", "findings.schema.properties")
792
+ finding_schema = _require_dict(finding_array, "items", "findings.schema.properties.findings")
793
+ finding_properties = _require_dict(
794
+ finding_schema, "properties", "findings.schema.properties.findings.items"
795
+ )
796
+ writeup_schema = _require_dict(
797
+ finding_properties, "writeup", "findings.schema.properties.findings.items.properties"
798
+ )
799
+ scan = _require_dict(manifest, "scan", "manifest")
800
+ scan_id = _require_str(scan, "id", "manifest.scan")
801
+ if findings.get("scanId") != scan_id:
802
+ raise ContractError("findings.scanId: must match manifest scan id")
803
+
804
+ recovered: list[dict[str, Any]] = []
805
+ discarded: list[str] = []
806
+ finding_positions: dict[str, int] = {}
807
+ writeup_paths: set[str] = set()
808
+ for index, finding in enumerate(_require_list(findings, "findings", "findings")):
809
+ context = f"findings.findings[{index}]"
810
+ try:
811
+ if not isinstance(finding, dict):
812
+ raise ContractError(f"{context}: expected an object")
813
+ identity = _require_dict(finding, "identity", context)
814
+ fields: list[tuple[dict[str, Any], str, str, str]] = [
815
+ (finding, "ruleId", context, "rule identifier"),
816
+ (identity, "anchor", f"{context}.identity", "semantic anchor"),
817
+ ]
818
+ if "instance" in identity:
819
+ fields.append((identity, "instance", f"{context}.identity", "instance"))
820
+ normalized_fields = []
821
+ for parent, field, field_context, label in fields:
822
+ value = _require_str(parent, field, field_context)
823
+ if SLUG_RE.fullmatch(value):
824
+ continue
825
+ normalized = re.sub(r"[^a-z0-9._/-]+", "-", value.lower()).strip("._/-")
826
+ if not SLUG_RE.fullmatch(normalized):
827
+ raise ContractError(
828
+ f"{field_context}.{field}: expected a stable lowercase semantic slug"
829
+ )
830
+ parent[field] = normalized
831
+ normalized_fields.append(label)
832
+
833
+ _populate_unsealed_finding_identities(
834
+ manifest,
835
+ {"scanId": scan_id, "findings": [finding]},
836
+ )
837
+ finding_id = finding["findingId"]
838
+ previous_position = finding_positions.get(finding_id)
839
+ _validate_finding(finding, context)
840
+ if "writeup" in finding:
841
+ try:
842
+ _validate_schema_node(finding["writeup"], writeup_schema, f"{context}.writeup")
843
+ report_path = finding["writeup"]["reportPath"]
844
+ previous_writeup = (
845
+ recovered[previous_position].get("writeup")
846
+ if previous_position is not None
847
+ else None
848
+ )
849
+ if report_path in writeup_paths and (
850
+ previous_writeup is None or previous_writeup["reportPath"] != report_path
851
+ ):
852
+ raise ContractError(f"{context}.writeup.reportPath: duplicate report path")
853
+ _require_scan_local_file(scan_dir, report_path, f"{context}.writeup.reportPath")
854
+ except ContractError as exc:
855
+ finding.pop("writeup")
856
+ warnings.append(f"Skipped malformed writeup for finding {index + 1}: {exc}.")
857
+ _validate_schema_node(finding, finding_schema, context)
858
+ except ContractError as exc:
859
+ warning = f"Skipped malformed finding {index + 1}: {exc}."
860
+ warnings.append(warning)
861
+ discarded.append(warning)
862
+ continue
863
+
864
+ if previous_position is not None:
865
+ previous = recovered[previous_position]
866
+ if _finding_strength(finding) <= _finding_strength(previous):
867
+ warnings.append(
868
+ f"Skipped malformed finding {index + 1}: duplicate logical finding."
869
+ )
870
+ continue
871
+ previous_writeup = previous.get("writeup")
872
+ if previous_writeup is not None:
873
+ writeup_paths.discard(previous_writeup["reportPath"])
874
+ recovered[previous_position] = finding
875
+ warnings.append(
876
+ f"Recovered finding {index + 1}: retained stronger duplicate logical finding."
877
+ )
878
+ else:
879
+ finding_positions[finding_id] = len(recovered)
880
+ recovered.append(finding)
881
+
882
+ if "writeup" in finding:
883
+ writeup_paths.add(finding["writeup"]["reportPath"])
884
+ if normalized_fields:
885
+ warnings.append(
886
+ f"Recovered finding {index + 1}: normalized {', '.join(normalized_fields)}."
887
+ )
888
+
889
+ findings["findings"] = recovered
890
+ return discarded
891
+
892
+
893
+ def _recover_unsealed_coverage(
894
+ coverage: dict[str, Any],
895
+ schema_dir: Path,
896
+ scan_dir: Path,
897
+ warnings: list[str],
898
+ discarded_findings: list[str],
899
+ ) -> None:
900
+ schema = _read_json(schema_dir / "coverage.schema.json")
901
+ _require_safe_schema(schema, "coverage.schema.json")
902
+ properties = _require_dict(schema, "properties", "coverage.schema")
903
+ completeness = coverage.get("completeness")
904
+ partial = completeness not in ("complete", "partial", "unknown")
905
+ if partial:
906
+ warnings.append("Recovered malformed coverage completeness; marked coverage as partial.")
907
+
908
+ surface_ids: set[str] = set()
909
+ for field, label in (
910
+ ("surfaces", "coverage surface"),
911
+ ("explicitExclusions", "coverage exclusion"),
912
+ ("deferred", "deferred coverage item"),
913
+ ):
914
+ array_schema = _require_dict(properties, field, "coverage.schema.properties")
915
+ item_schema = _require_dict(array_schema, "items", f"coverage.schema.properties.{field}")
916
+ items = coverage.get(field)
917
+ if not isinstance(items, list):
918
+ warnings.append(f"Skipped malformed {label} records: expected an array.")
919
+ coverage[field] = []
920
+ partial = True
921
+ continue
922
+
923
+ recovered: list[dict[str, Any]] = []
924
+ for index, item in enumerate(items):
925
+ context = f"coverage.{field}[{index}]"
926
+ try:
927
+ if not isinstance(item, dict):
928
+ raise ContractError(f"{context}: expected an object")
929
+ if field == "surfaces":
930
+ surface_id = _require_str(item, "id", context)
931
+ if surface_id in surface_ids:
932
+ raise ContractError(f"{context}.id: duplicate surface id")
933
+ disposition = item.get("disposition")
934
+ surface_recovered = False
935
+ if not isinstance(disposition, str) or disposition not in DISPOSITIONS:
936
+ warnings.append(
937
+ f"Recovered coverage surface {index + 1}: "
938
+ "the review disposition could not be verified."
939
+ )
940
+ item["disposition"] = "needs_follow_up"
941
+ surface_recovered = True
942
+
943
+ receipt_refs = item.get("receiptRefs")
944
+ if not isinstance(receipt_refs, list):
945
+ warnings.append(
946
+ f"Skipped malformed receipt references for coverage surface "
947
+ f"{index + 1}: expected an array."
948
+ )
949
+ receipt_refs = []
950
+ surface_recovered = True
951
+
952
+ recovered_receipts: list[str] = []
953
+ for ref_index, ref in enumerate(receipt_refs):
954
+ ref_context = f"{context}.receiptRefs[{ref_index}]"
955
+ try:
956
+ if not isinstance(ref, str):
957
+ raise ContractError(f"{ref_context}: expected a string")
958
+ normalized_ref = _require_safe_relative_path(ref, ref_context)
959
+ if not normalized_ref.startswith("artifacts/"):
960
+ raise ContractError(
961
+ f"{ref_context}: expected a file under artifacts/"
962
+ )
963
+ _require_scan_local_file(scan_dir, normalized_ref, ref_context)
964
+ except ContractError as exc:
965
+ warnings.append(
966
+ f"Skipped malformed coverage receipt "
967
+ f"{index + 1}.{ref_index + 1}: {exc}."
968
+ )
969
+ surface_recovered = True
970
+ continue
971
+ recovered_receipts.append(normalized_ref)
972
+
973
+ item["receiptRefs"] = recovered_receipts
974
+ if surface_recovered or item["disposition"] == "needs_follow_up":
975
+ if not surface_recovered and completeness != "partial":
976
+ warnings.append(
977
+ f"Coverage surface {index + 1} requires follow-up; "
978
+ "marked coverage as partial."
979
+ )
980
+ item["disposition"] = "needs_follow_up"
981
+ partial = True
982
+
983
+ _validate_schema_node(item, item_schema, context)
984
+ except ContractError as exc:
985
+ warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
986
+ partial = True
987
+ continue
988
+
989
+ if field == "surfaces":
990
+ surface_ids.add(surface_id)
991
+ recovered.append(item)
992
+
993
+ coverage[field] = recovered
994
+
995
+ if discarded_findings:
996
+ for surface in coverage["surfaces"]:
997
+ surface["disposition"] = "needs_follow_up"
998
+ coverage["deferred"].extend(
999
+ {"id": f"discarded-finding-{index}", "reason": warning}
1000
+ for index, warning in enumerate(discarded_findings, 1)
1001
+ )
1002
+ partial = True
1003
+
1004
+ if coverage["deferred"] and completeness != "partial":
1005
+ if not discarded_findings:
1006
+ warnings.append("Coverage has deferred review work; marked coverage as partial.")
1007
+ partial = True
1008
+ if partial:
1009
+ coverage["completeness"] = "partial"
1010
+
1011
+
1012
+ def _recover_unsealed_hardening(
1013
+ manifest: dict[str, Any],
1014
+ scan_dir: Path,
1015
+ warnings: list[str],
1016
+ ) -> None:
1017
+ scan = _require_dict(manifest, "scan", "manifest")
1018
+ if "hardening" not in scan:
1019
+ return
1020
+
1021
+ try:
1022
+ hardening = _require_dict(scan, "hardening", "manifest.scan")
1023
+ portfolio_path = _require_str(hardening, "portfolioPath", "manifest.scan.hardening")
1024
+ if portfolio_path != "hardening/hardening.md":
1025
+ raise ContractError(
1026
+ "manifest.scan.hardening.portfolioPath: expected hardening/hardening.md"
1027
+ )
1028
+ _require_hardening_portfolio_file(scan_dir, scan)
1029
+ except ContractError as exc:
1030
+ scan.pop("hardening")
1031
+ warnings.append(f"Skipped malformed hardening portfolio: {exc}.")
1032
+
1033
+
770
1034
  def _validate_derived_finding_identities(
771
1035
  manifest: dict[str, Any],
772
1036
  findings: dict[str, Any],
@@ -1792,8 +2056,21 @@ def build_sarif_projection(
1792
2056
  source_root_is_directory = False
1793
2057
  if not source_root_is_directory:
1794
2058
  raise ContractError("source root: expected an existing directory")
1795
- manifest, findings, _, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2059
+ manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
1796
2060
  sarif = build_sarif(manifest, findings, source_root)
2061
+ if coverage["completeness"] != "complete":
2062
+ run = sarif["runs"][0]
2063
+ run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2064
+ if coverage["deferred"]:
2065
+ run["invocations"] = [
2066
+ {
2067
+ "executionSuccessful": True,
2068
+ "toolExecutionNotifications": [
2069
+ {"level": "warning", "message": {"text": item["reason"]}}
2070
+ for item in coverage["deferred"]
2071
+ ],
2072
+ }
2073
+ ]
1797
2074
  _validate_sarif(sarif)
1798
2075
  return sarif
1799
2076
 
@@ -2009,6 +2286,7 @@ def _prepare_scan_finalization(
2009
2286
  *,
2010
2287
  expected_coverage_mode: str | None = None,
2011
2288
  completion_binding: dict[str, Any] | None = None,
2289
+ completion_warnings: list[str] | None = None,
2012
2290
  ) -> PreparedScanFinalization:
2013
2291
  """Read, populate, and validate a scan without writing any output files."""
2014
2292
 
@@ -2061,8 +2339,15 @@ def _prepare_scan_finalization(
2061
2339
  _validate_completion_binding(manifest, findings, coverage, completion_binding)
2062
2340
  if was_sealed:
2063
2341
  _validate_findings(manifest, findings)
2064
- if was_sealed:
2065
2342
  _validate_derived_finding_identities(manifest, findings)
2343
+ elif completion_warnings is not None:
2344
+ discarded_findings = _recover_unsealed_findings(
2345
+ manifest, findings, schema_dir, scan_dir, completion_warnings
2346
+ )
2347
+ _recover_unsealed_coverage(
2348
+ coverage, schema_dir, scan_dir, completion_warnings, discarded_findings
2349
+ )
2350
+ _recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
2066
2351
  else:
2067
2352
  _populate_unsealed_finding_identities(manifest, findings)
2068
2353
  _validate_findings(manifest, findings)
@@ -210,6 +210,10 @@ def parse_args(description: str) -> argparse.Namespace:
210
210
  update_progress.add_argument("--deep-review-pass", type=positive_int)
211
211
  update_progress.add_argument("--claim-token")
212
212
 
213
+ prepare_scan_completion = subparsers.add_parser("prepare-scan-completion")
214
+ prepare_scan_completion.add_argument("--scan-id", required=True)
215
+ prepare_scan_completion.add_argument("--claim-token")
216
+
213
217
  complete_scan = subparsers.add_parser("complete-scan")
214
218
  complete_scan.add_argument("--scan-id", required=True)
215
219
  complete_scan.add_argument("--claim-token")