@openai/codex-security 0.1.1 → 0.1.3

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 (40) hide show
  1. package/README.md +92 -51
  2. package/_bundled_plugin/mcp/mcp-app.html.br +0 -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/scripts/config_preflight.py +1 -1
  6. package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -1
  7. package/_bundled_plugin/scripts/finalize_scan_contract.py +289 -4
  8. package/_bundled_plugin/scripts/workbench_cli.py +5 -0
  9. package/_bundled_plugin/scripts/workbench_db.py +39 -100
  10. package/_bundled_plugin/scripts/workbench_feedback.py +96 -0
  11. package/_bundled_plugin/scripts/workbench_scan_history.py +11 -1
  12. package/_bundled_plugin/scripts/workbench_scan_start.py +76 -0
  13. package/_bundled_plugin/scripts/workbench_schema.py +8 -0
  14. package/_bundled_plugin/scripts/workbench_target.py +95 -0
  15. package/_bundled_plugin/scripts/workbench_validation.py +7 -0
  16. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  17. package/dist/api.d.ts +2 -1
  18. package/dist/api.d.ts.map +1 -1
  19. package/dist/api.js +49 -5
  20. package/dist/api.js.map +1 -1
  21. package/dist/bulk-scan-discovery.js +10 -11
  22. package/dist/bulk-scan-discovery.js.map +1 -1
  23. package/dist/cli.d.ts +4 -1
  24. package/dist/cli.d.ts.map +1 -1
  25. package/dist/cli.js +162 -45
  26. package/dist/cli.js.map +1 -1
  27. package/dist/config.d.ts.map +1 -1
  28. package/dist/config.js +4 -0
  29. package/dist/config.js.map +1 -1
  30. package/dist/multiscan.d.ts.map +1 -1
  31. package/dist/multiscan.js +3 -1
  32. package/dist/multiscan.js.map +1 -1
  33. package/dist/scan-history-renderer.d.ts.map +1 -1
  34. package/dist/scan-history-renderer.js +8 -0
  35. package/dist/scan-history-renderer.js.map +1 -1
  36. package/dist/version.d.ts +14 -0
  37. package/dist/version.d.ts.map +1 -1
  38. package/dist/version.js +102 -0
  39. package/dist/version.js.map +1 -1
  40. package/package.json +2 -1
package/README.md CHANGED
@@ -12,7 +12,7 @@ executable, and the matching Codex runtime.
12
12
 
13
13
  ```bash
14
14
  npm install @openai/codex-security
15
- npx codex-security --version
15
+ npx @openai/codex-security --version
16
16
  ```
17
17
 
18
18
  The package supports macOS, Linux, and Windows and requires Node.js 22 or
@@ -20,9 +20,13 @@ later. Scanning and exporting findings also require Python 3.10 or later. If
20
20
  you use Python 3.10, install the `tomli` package. Select another interpreter
21
21
  with `--python`, `pythonPath`, or `PYTHON` when needed.
22
22
 
23
+ When a newer version is available, the CLI shows the update command for your
24
+ installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
25
+ notice. Notices are also disabled in CI and when stderr is not a terminal.
26
+
23
27
  ## Run a scan from TypeScript
24
28
 
25
- Sign in with `npx codex-security login` or set `OPENAI_API_KEY` or
29
+ Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or
26
30
  `CODEX_API_KEY`. Then create a client and scan a repository you own or have
27
31
  permission to assess:
28
32
 
@@ -57,34 +61,34 @@ limit access to authorized reviewers.
57
61
  For local use, sign in with ChatGPT:
58
62
 
59
63
  ```bash
60
- npx codex-security login
61
- npx codex-security scan .
64
+ npx @openai/codex-security login
65
+ npx @openai/codex-security scan .
62
66
  ```
63
67
 
64
68
  On a remote or headless machine, use device authentication:
65
69
 
66
70
  ```bash
67
- npx codex-security login --device-auth
71
+ npx @openai/codex-security login --device-auth
68
72
  ```
69
73
 
70
74
  For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,
71
75
  pass it on stdin:
72
76
 
73
77
  ```bash
74
- printenv OPENAI_API_KEY | npx codex-security login --with-api-key
78
+ printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
75
79
  ```
76
80
 
77
81
  On Windows, set the API key in PowerShell:
78
82
 
79
83
  ```powershell
80
84
  $env:OPENAI_API_KEY = "<your-api-key>"
81
- npx codex-security scan C:\code\repository
85
+ npx @openai/codex-security scan C:\code\repository
82
86
  ```
83
87
 
84
- Check or remove the stored sign-in with `npx codex-security login status` and
85
- `npx codex-security logout`. Codex Security reuses an existing file-based Codex
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
86
90
  sign-in. If Codex stores credentials in the system keyring, run
87
- `npx codex-security login` once before scanning.
91
+ `npx @openai/codex-security login` once before scanning.
88
92
 
89
93
  An environment API key takes precedence over a stored sign-in by default.
90
94
  When both a stored ChatGPT sign-in and an environment API key are available, an
@@ -93,8 +97,8 @@ other noninteractive scans never prompt and retain automatic API-key
93
97
  precedence. Select the credential source explicitly with `--auth`:
94
98
 
95
99
  ```bash
96
- npx codex-security scan . --auth chatgpt
97
- npx codex-security scan . --auth api-key
100
+ npx @openai/codex-security scan . --auth chatgpt
101
+ npx @openai/codex-security scan . --auth api-key
98
102
  ```
99
103
 
100
104
  `--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
@@ -120,35 +124,40 @@ without printing its value, including when no stored sign-in exists.
120
124
  ## CLI
121
125
 
122
126
  ```bash
123
- npx codex-security scan /path/to/repository
124
- npx codex-security scan /path/to/repository --model gpt-5.6-terra
125
- npx codex-security scan /path/to/repository --path src --path tests
126
- npx codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
127
- npx codex-security scan /path/to/repository --diff origin/main --json
128
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
129
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
130
- npx codex-security scan /path/to/repository --dry-run
131
- npx codex-security scan /path/to/repository --fail-on-severity high
132
- npx codex-security scan /path/to/repository --max-cost 5
133
- npx codex-security install-hook
134
- npx codex-security bulk-scan
135
- npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
136
- npx codex-security scans list /path/to/repository
137
- npx codex-security scans list --scan-root /path/outside/repository/results
138
- npx codex-security scans show SCAN_ID
139
- npx codex-security scans rerun SCAN_ID
140
- npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
141
- npx codex-security scans match --all
142
- npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
143
- npx codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
144
- npx codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
145
- npx codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
146
- npx codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
147
- npx codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
127
+ npx @openai/codex-security scan /path/to/repository
128
+ npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
129
+ npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
130
+ npx @openai/codex-security scan /path/to/repository --path src --path tests
131
+ npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
132
+ npx @openai/codex-security scan /path/to/repository --diff origin/main --json
133
+ npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
134
+ npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
135
+ npx @openai/codex-security scan /path/to/repository --dry-run
136
+ npx @openai/codex-security scan /path/to/repository --fail-on-severity high
137
+ npx @openai/codex-security scan /path/to/repository --max-cost 5
138
+ npx @openai/codex-security install-hook
139
+ npx @openai/codex-security bulk-scan
140
+ npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
141
+ npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
142
+ npx @openai/codex-security scans list /path/to/repository
143
+ npx @openai/codex-security scans list --scan-root /path/outside/repository/results
144
+ npx @openai/codex-security scans show SCAN_ID
145
+ npx @openai/codex-security scans rerun SCAN_ID
146
+ npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
147
+ npx @openai/codex-security scans match --all
148
+ npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
149
+ npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
150
+ npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
151
+ npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
152
+ npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
153
+ npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
154
+ npx @openai/codex-security validate "Possible SQL injection" --effort high
155
+ npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
156
+ npx @openai/codex-security patch "Missing authorization check" --effort high
148
157
  ```
149
158
 
150
- Run `npx codex-security --version` for the installed CLI version or
151
- `npx codex-security info --json` for the package, bundled plugin, Codex runtime,
159
+ Run `npx @openai/codex-security --version` for the installed CLI version or
160
+ `npx @openai/codex-security info --json` for the package, bundled plugin, Codex runtime,
152
161
  default model, reasoning effort, and first-scan command. A scan with `--dry-run`
153
162
  also reports its effective model and reasoning effort, including `--codex`
154
163
  overrides, without starting Codex or contacting the network.
@@ -182,10 +191,14 @@ for a passing policy. Incomplete scans still write the available human or JSON
182
191
  result to stdout and a coverage warning to stderr, including in report-only
183
192
  mode.
184
193
 
185
- Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Use
186
- `--model gpt-5.6-terra` to switch models. Use repeatable `--codex KEY=VALUE`
187
- options for other Codex settings, such as
188
- `--codex 'model_reasoning_effort="high"'`.
194
+ Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. OpenAI is
195
+ the implied provider. Use `--model gpt-5.6-terra` to switch models and
196
+ `--effort minimal|low|medium|high|xhigh` to set reasoning effort. Repeat
197
+ `--codex KEY=VALUE` for other Codex settings; existing
198
+ `--codex 'model_reasoning_effort="high"'` overrides remain supported.
199
+
200
+ These overrides do not change the scan's approval policy or filesystem
201
+ permissions. See [Local security model](#local-security-model).
189
202
 
190
203
  Scan progress identifies the requested paths and reports actual ranking,
191
204
  file-review, validation, and attack-path phases as they become available.
@@ -203,10 +216,10 @@ Use `--max-cost USD` to stop a scan, including its delegated workers, when its
203
216
  running cost exceeds the limit. Partial results are preserved. Requests
204
217
  already in progress can finish above the limit.
205
218
 
206
- Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
219
+ Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
207
220
  for the complete CLI references.
208
221
 
209
- Sign in with `gh auth login`, then run `npx codex-security bulk-scan` to discover
222
+ Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover
210
223
  GitHub repositories pushed in the last 90 days. Archived
211
224
  repositories and forks are excluded. Search the repository list, select the
212
225
  repositories to scan, and confirm before scanning.
@@ -228,7 +241,7 @@ Results remain under `--output-dir`; rerun the same command to resume.
228
241
 
229
242
  ### Scan history and reruns
230
243
 
231
- `npx codex-security scans list` lists scans for the current repository. Pass a
244
+ `npx @openai/codex-security scans list` lists scans for the current repository. Pass a
232
245
  repository path to inspect another checkout, `--scan-root DIR` to list scans
233
246
  whose artifacts are under a particular root. `scans show SCAN_ID` includes the
234
247
  scan configuration, results, coverage, and artifact locations.
@@ -249,6 +262,10 @@ default directory, select a writable directory outside the scanned repository:
249
262
  export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
250
263
  ```
251
264
 
265
+ Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as
266
+ a false positive and explain why. Later scans dismiss a matching finding only
267
+ when the same reason still applies.
268
+
252
269
  `scans rerun SCAN_ID` repeats the original configuration against the current
253
270
  checkout so a fixed vulnerability can be checked again.
254
271
 
@@ -279,7 +296,7 @@ nonzero:
279
296
 
280
297
  ```bash
281
298
  SCAN_ROOT="$(mktemp -d)"
282
- npx codex-security scan . \
299
+ npx @openai/codex-security scan . \
283
300
  --diff origin/main \
284
301
  --output-dir "$SCAN_ROOT/results" \
285
302
  --json \
@@ -297,7 +314,7 @@ document. CSV uses the portable findings columns, marks findings as open, and
297
314
  does not include local workbench triage state. The exporter validates the seal
298
315
  before writing, accepts `--output -` for stdout, and can use
299
316
  `--source-root /path/to/repository` with SARIF to add source-line fingerprints.
300
- Run `npx codex-security export --help` for all export options.
317
+ Run `npx @openai/codex-security export --help` for all export options.
301
318
 
302
319
  Use `validate` to run the bundled validation skill on candidate findings and
303
320
  `patch` to run the bundled fix-finding skill on security issues. Each positional
@@ -305,9 +322,9 @@ input can be either a file, whose contents are read into the request, or literal
305
322
  text. Both commands operate on the current directory, use the scan model
306
323
  and reasoning defaults, ignore unrelated user configuration and plugins, and
307
324
  print the final response without the underlying Codex event stream. Override
308
- the model or reasoning effort with `--codex 'model="gpt-5.6-sol"'` or
309
- `--codex 'model_reasoning_effort="high"'`. Inputs are limited to 64 items and
310
- 1 MiB total.
325
+ the model with `--codex 'model="gpt-5.6-sol"'` and the reasoning effort with
326
+ `--effort high` or `--codex 'model_reasoning_effort="high"'`. Inputs are
327
+ limited to 64 items and 1 MiB total.
311
328
 
312
329
  Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
313
330
  findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
@@ -330,6 +347,30 @@ Progress remains on stderr so JSON output stays machine readable. Network
330
347
  failures and rate limits remain retryable; definitive authentication and model
331
348
  authorization failures stop immediately.
332
349
 
350
+ ## Local security model
351
+
352
+ Codex Security runs with your local operating-system permissions. Scan only
353
+ repositories you trust and either own or are authorized to assess. Your
354
+ repository, Git installation, configured tools, and other scans under the
355
+ same account are not separate security principals.
356
+
357
+ Every scan uses the `codex_security_scan` filesystem profile and
358
+ `approvalPolicy: "never"`. It can read the local filesystem and write to
359
+ workspace roots and the selected scan state directory. Scans do not request
360
+ interactive approval. Setting `approval_policy`, `sandbox_mode`, or permissions
361
+ through `--codex` or SDK `codexOverrides` does not replace these controls or
362
+ make them more restrictive. Independently enforced host and network
363
+ restrictions still apply.
364
+
365
+ Scan and workbench subprocesses can inherit your environment, including
366
+ unrelated API tokens and cloud credentials. Start a scan with only the
367
+ credentials it needs.
368
+
369
+ The scanner must stay within the target and output paths you authorize and
370
+ must not disclose private data beyond the operation you requested. Its results
371
+ must accurately report the scan mode, reviewed files, and exclusions. Consult
372
+ the security policy for the full threat model and private reporting process.
373
+
333
374
  ## Documentation and security
334
375
 
335
376
  - [CLI quickstart](https://developers.openai.com/codex/security/cli)
Binary file
@@ -19,7 +19,7 @@ except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
19
19
 
20
20
  PLUGIN_ROOT = Path(__file__).resolve().parents[1]
21
21
  DEFAULT_REGISTRY = PLUGIN_ROOT / "preflight" / "capability-profiles.toml"
22
- DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
22
+ DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
23
23
  SYSTEM_CONFIG = Path("/etc/codex/config.toml")
24
24
  DEFAULT_CONFIG = DEFAULT_CODEX_HOME / "config.toml"
25
25
  VALID_SEVERITIES = {"block", "warn", "suggest"}
@@ -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)
@@ -136,6 +136,9 @@ def parse_args(description: str) -> argparse.Namespace:
136
136
  get_scan.add_argument("--scan-id", required=True)
137
137
  get_scan.add_argument("--occurrence-id")
138
138
 
139
+ get_scan_feedback = subparsers.add_parser("get-scan-feedback")
140
+ get_scan_feedback.add_argument("--scan-id", required=True)
141
+
139
142
  list_scans = subparsers.add_parser("list-scans")
140
143
  list_scans.add_argument("--query")
141
144
  list_scans.add_argument("--target-id")
@@ -155,6 +158,8 @@ def parse_args(description: str) -> argparse.Namespace:
155
158
  register_cli_scan.add_argument("--repository", required=True)
156
159
  register_cli_scan.add_argument("--recipe-json", required=True)
157
160
  register_cli_scan.add_argument("--parent-scan-id")
161
+ register_cli_scan.add_argument("--archive-existing", action="store_true")
162
+ register_cli_scan.add_argument("--archived-scan-dir")
158
163
 
159
164
  get_scan_recipe = subparsers.add_parser("get-scan-recipe")
160
165
  get_scan_recipe.add_argument("--scan-id", required=True)