@openai/codex-security 0.1.25 → 0.1.26

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 (81) hide show
  1. package/README.md +222 -8
  2. package/_bundled_plugin/.app.json +0 -5
  3. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  4. package/_bundled_plugin/.mcp.json +1 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/references/config-preflight.md +2 -2
  8. package/_bundled_plugin/references/final-report.md +5 -3
  9. package/_bundled_plugin/references/scan-artifacts.md +5 -1
  10. package/_bundled_plugin/references/scan-contract.md +7 -3
  11. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +27 -1
  12. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  13. package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -5
  14. package/_bundled_plugin/scripts/report_projection.py +1 -1
  15. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  16. package/_bundled_plugin/scripts/workbench_db.py +11 -2
  17. package/_bundled_plugin/scripts/workbench_saved_results.py +41 -22
  18. package/_bundled_plugin/scripts/workbench_scan_usage.py +7 -6
  19. package/_bundled_plugin/scripts/workbench_schema.py +31 -0
  20. package/_bundled_plugin/scripts/workbench_severity.py +119 -0
  21. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -3
  22. package/_bundled_plugin/skills/verify-fix/SKILL.md +5 -1
  23. package/dist/api.d.ts.map +1 -1
  24. package/dist/api.js +4 -5
  25. package/dist/api.js.map +1 -1
  26. package/dist/classify-scan-severity.d.ts +16 -0
  27. package/dist/classify-scan-severity.d.ts.map +1 -0
  28. package/dist/classify-scan-severity.js +96 -0
  29. package/dist/classify-scan-severity.js.map +1 -0
  30. package/dist/classify-severity.d.ts +38 -0
  31. package/dist/classify-severity.d.ts.map +1 -0
  32. package/dist/classify-severity.js +185 -0
  33. package/dist/classify-severity.js.map +1 -0
  34. package/dist/cli.d.ts +5 -2
  35. package/dist/cli.d.ts.map +1 -1
  36. package/dist/cli.js +323 -89
  37. package/dist/cli.js.map +1 -1
  38. package/dist/cost.js +20 -6
  39. package/dist/cost.js.map +1 -1
  40. package/dist/deduplication/deduplication-reviewer.js +1 -1
  41. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  42. package/dist/finding-catalogue.d.ts +11 -0
  43. package/dist/finding-catalogue.d.ts.map +1 -0
  44. package/dist/finding-catalogue.js +150 -0
  45. package/dist/finding-catalogue.js.map +1 -0
  46. package/dist/index.d.ts +6 -0
  47. package/dist/index.d.ts.map +1 -1
  48. package/dist/index.js +3 -0
  49. package/dist/index.js.map +1 -1
  50. package/dist/patch-tui.js +1 -1
  51. package/dist/patch-tui.js.map +1 -1
  52. package/dist/publication-store.d.ts.map +1 -1
  53. package/dist/publication-store.js +9 -4
  54. package/dist/publication-store.js.map +1 -1
  55. package/dist/publication.d.ts +9 -0
  56. package/dist/publication.d.ts.map +1 -1
  57. package/dist/publication.js +45 -5
  58. package/dist/publication.js.map +1 -1
  59. package/dist/publish.d.ts +4 -2
  60. package/dist/publish.d.ts.map +1 -1
  61. package/dist/publish.js +2 -2
  62. package/dist/publish.js.map +1 -1
  63. package/dist/scan-comparison.d.ts +42 -37
  64. package/dist/scan-comparison.d.ts.map +1 -1
  65. package/dist/scan-comparison.js +535 -161
  66. package/dist/scan-comparison.js.map +1 -1
  67. package/dist/scan-history-renderer.d.ts.map +1 -1
  68. package/dist/scan-history-renderer.js +5 -0
  69. package/dist/scan-history-renderer.js.map +1 -1
  70. package/dist/severity-store.d.ts +2 -0
  71. package/dist/severity-store.d.ts.map +1 -0
  72. package/dist/severity-store.js +111 -0
  73. package/dist/severity-store.js.map +1 -0
  74. package/dist/thread-source.d.ts +1 -0
  75. package/dist/thread-source.d.ts.map +1 -1
  76. package/dist/thread-source.js +1 -0
  77. package/dist/thread-source.js.map +1 -1
  78. package/dist/version.d.ts +1 -1
  79. package/dist/version.js +1 -1
  80. package/dist/version.js.map +1 -1
  81. package/package.json +4 -4
package/README.md CHANGED
@@ -40,7 +40,7 @@ try {
40
40
 
41
41
  `result.findings` contains this scan's findings; `repositoryFindings` also
42
42
  includes earlier open findings when available. Matching earlier findings can
43
- make one extra model call, even with a cost limit.
43
+ make extra model calls; see [Progress and cost](#progress-and-cost).
44
44
 
45
45
  Keep results outside the repository and restrict access: reports can contain
46
46
  source code, vulnerability details, and reproduction steps.
@@ -69,6 +69,10 @@ Pass literal text or a JSON-serializable object as `finding`, not a file path.
69
69
  Validation uses the client's settings and credentials without changing
70
70
  repository files or adding a scan to history.
71
71
 
72
+ To disable Codex usage analytics and built-in metrics, create the client with
73
+ `new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.
74
+ This setting also applies to scans run by the same client.
75
+
72
76
  Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
73
77
  or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
74
78
  `reportable` may rely on static analysis; `deferred` means insufficient evidence.
@@ -515,8 +519,29 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
515
519
  stay enabled: `agents.max_threads` and
516
520
  `features.multi_agent_v2.enabled=false` are rejected.
517
521
 
518
- `validate` and `patch` accept `--effort` and the `model` and
519
- `model_reasoning_effort` keys in `--codex`, but no other runtime overrides.
522
+ `validate`, `patch`, and `verify-fix` accept `--effort` and the `model`,
523
+ `model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
524
+ other runtime overrides.
525
+
526
+ Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and
527
+ built-in metrics for a command:
528
+
529
+ ```bash
530
+ npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'
531
+ npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'
532
+ npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'
533
+ ```
534
+
535
+ The same setting works for `scan` and `bulk-scan`. An explicit setting is
536
+ preserved when `scan --patch` starts remediation and when
537
+ `patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
538
+ is also accepted; omitting the setting preserves the command's existing
539
+ configuration and Codex defaults. Validation continues to ignore user
540
+ configuration, while patching and verification retain their existing ambient
541
+ configuration and project-trust behavior.
542
+
543
+ This setting does not control explicitly configured OpenTelemetry log or trace
544
+ exporters, authentication, integrations, or CLI update checks.
520
545
 
521
546
  See [Local security model](#local-security-model) for approval and filesystem
522
547
  restrictions.
@@ -568,6 +593,10 @@ discovery has finished, the scan returns a sealed partial report without more
568
593
  model calls and lists unvalidated candidates as follow-up work. Bulk scans
569
594
  apply the limit per repository attempt.
570
595
 
596
+ With `--max-cost`, automatic finding-history matching makes at most one extra
597
+ model call. If it needs more context, the completed scan is kept and a warning
598
+ directs you to run `scans match --all` explicitly.
599
+
571
600
  For a single scan in the interactive dashboard, reaching 80% of the limit
572
601
  offers a higher **total** USD limit. Enter a larger amount to approve it, or
573
602
  press Enter with an empty input or Escape to keep the current limit. The scan
@@ -826,6 +855,139 @@ Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
826
855
  publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
827
856
  the same destination options for a read-only check.
828
857
 
858
+ ### Classify finding severity
859
+
860
+ Classify findings after a scan or dedupe without repeating discovery or changing
861
+ the original severity, evidence, or sealed scan artifacts:
862
+
863
+ ```bash
864
+ codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json
865
+ codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
866
+ codex-security classify-severity --scan-dir /path/to/completed-scan --json
867
+ ```
868
+
869
+ `--scan` accepts a saved scan ID, unique prefix, or `latest` for the current
870
+ repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external
871
+ completed scan without requiring local history. Supply exactly one selector.
872
+ Omitting `--rubric` inherits each finding's existing severity without a model call.
873
+
874
+ `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
875
+ to provide supporting architecture, deployment, or business context. Both accept
876
+ the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
877
+ Rubric classification uses the full supplied report and context in a separate
878
+ read-only Codex turn per finding, without source inspection, tools, or new
879
+ validation. `--model` and `--effort` select the classification model and reasoning
880
+ effort; otherwise Codex's configured model and the helper's medium effort apply.
881
+
882
+ The result contains one assessment per selected finding:
883
+
884
+ - `decision`: `assessed` or `excluded`; policy exclusions do not become Low.
885
+ - `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.
886
+ - `rubricLabel`: the policy's original label, such as `URGENT`, normalized to
887
+ `critical`; null for inherited severity or exclusions.
888
+ - `rationale`, separate `confidence`, and `reviewTrigger` describing a missing
889
+ fact that would change the classification. Inherited severity has no new
890
+ classification-confidence judgment.
891
+ - `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the
892
+ report. Top-level metadata includes `assessedAt`, `rubricSha256`, and
893
+ `knowledgeBaseSha256` for the supplied policy and context snapshots.
894
+
895
+ Scan classification saves each successful finding immediately in the local
896
+ workbench SQLite database. Rerunning skips assessments with matching finding
897
+ evidence, rubric, and knowledge-base hashes, including exclusions, and returns
898
+ both reused and newly generated assessments. Changed inputs are classified again.
899
+ Use `--reprocess` to rerun every selected finding regardless of its saved
900
+ assessment; each row is replaced only after its new assessment succeeds. A failed
901
+ or canceled run keeps completed checkpoints, so a normal retry resumes missing
902
+ work. Changing only the model or effort requires `--reprocess`.
903
+
904
+ SQLite is authoritative. A successful run also exports the complete selected
905
+ result to `severity-classification.json` alongside the sealed artifacts. The file
906
+ is replaced atomically and is not read for reuse or publication. The scan's
907
+ original findings and severity are unchanged. The database stores the requested
908
+ selection and policy/context hashes; publication rejects an incomplete selection
909
+ or assessments whose inputs no longer match. Rubric documents are read at
910
+ classification time, not again at publication time.
911
+
912
+ ```bash
913
+ codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess
914
+ ```
915
+
916
+ Use repeatable `--finding-id ID` to classify a selected set, such as the
917
+ `uniqueFindingIds` returned by dedupe. With a saved classification, Linear
918
+ publication defaults to that selection, omits excluded records, and uses assessed
919
+ severity for issue priority and title. The description retains original scan
920
+ severity and adds classification reasoning. Without a saved classification,
921
+ publication retains its existing severity mapping and selection behavior.
922
+ Publication rejects assessments whose IDs or evidence hashes no longer match.
923
+
924
+ ```bash
925
+ codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
926
+ --finding-id FINDING_ID --json
927
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
928
+ --dry-run --json
929
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
930
+ --skip-existing --json
931
+ ```
932
+
933
+ `publish scan --to linear` also accepts repeatable `--finding-id ID` to select a
934
+ subset directly. If a classification exists, every explicitly selected finding
935
+ must have an assessment. Classification does not change existing Linear tickets;
936
+ `--skip-existing` preserves recorded tickets and any human priority edits. It
937
+ retains the existing limitations around unrecorded or concurrent publications.
938
+
939
+ The SDK exposes the same operations:
940
+
941
+ ```ts
942
+ import {
943
+ classifySeverity,
944
+ classifyScanSeverity,
945
+ classifyScanDirectorySeverity,
946
+ publishScan,
947
+ } from "@openai/codex-security";
948
+
949
+ // Supplied reports from any source: returns an assessment without writing files.
950
+ const classification = await classifySeverity(findings, {
951
+ rubricPath: "/path/to/policy.md",
952
+ knowledgeBasePaths: ["/path/to/context.md"],
953
+ });
954
+
955
+ // Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.
956
+ await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
957
+ await classifyScanDirectorySeverity(scanDirectory, {
958
+ rubricPath: "/path/to/policy.md",
959
+ findingIds: dedupeResult.uniqueFindingIds,
960
+ });
961
+
962
+ await publishScan(scanDirectory, {
963
+ destination: "linear",
964
+ teamId: "TEAM_ID",
965
+ skipExisting: true,
966
+ });
967
+
968
+ // Alternatively supply a classification directly, without a saved assessment.
969
+ await publishScan(scanDirectory, {
970
+ destination: "linear",
971
+ teamId: "TEAM_ID",
972
+ classification,
973
+ findingIds: classification.assessments.map(({ findingId }) => findingId),
974
+ dryRun: true,
975
+ });
976
+ ```
977
+
978
+ `classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus
979
+ their available evidence and metadata. Original `severity` and `occurrenceId`
980
+ may be absent for imported reports; reports without severity require a rubric.
981
+ `classifySeverity` remains an in-memory operation without database persistence.
982
+ The scan wrappers use the local state database (also for external scan
983
+ directories), accept `reprocess: true`, and accept `findingIds: []` as an
984
+ intentionally empty selection. Rows outside the selected set are retained.
985
+ Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.
986
+ JSON exports from versions without database checkpoints must be reclassified
987
+ once before they can be reused.
988
+ Pass `signal` to cancel any classification operation. Keep human overrides in the
989
+ calling workflow or issue tracker; assessments remain separate recommendations.
990
+
829
991
  ### Scan history and reruns
830
992
 
831
993
  Commands default to the current repository. Select scans by full ID or a
@@ -849,6 +1011,44 @@ or unknown. Missing findings aren't resolved if the later scan is incomplete
849
1011
  or excludes their original scope. With one ID, `scans compare` compares it
850
1012
  to the latest completed scan.
851
1013
 
1014
+ Use `scans match --all --force` to rebuild comparisons chronologically while
1015
+ retaining stable finding identities. Ctrl-C keeps comparisons already saved.
1016
+ Only high-confidence duplicates are grouped; uncertain and independently
1017
+ related findings stay separate. Matching preserves triage and sealed artifacts.
1018
+
1019
+ Codex is called only when a new decision is needed, using existing authentication.
1020
+ Scans without sealed artifacts are skipped, but their confirmed links can still
1021
+ be reused. Older custom plugins save confirmed and uncertain matches; use the
1022
+ bundled plugin for related links and large comparisons.
1023
+
1024
+ SDK callers can compare findings without saving a workbench comparison:
1025
+
1026
+ ```ts
1027
+ import { readFile } from "node:fs/promises";
1028
+ import {
1029
+ matchScanFindings,
1030
+ type FindingsDocument,
1031
+ } from "@openai/codex-security";
1032
+
1033
+ const before = JSON.parse(
1034
+ await readFile("/path/to/earlier-scan/findings.json", "utf8"),
1035
+ ) as FindingsDocument;
1036
+ const after = JSON.parse(
1037
+ await readFile("/path/to/later-scan/findings.json", "utf8"),
1038
+ ) as FindingsDocument;
1039
+
1040
+ const comparison = await matchScanFindings(
1041
+ { before: before.findings, after: after.findings },
1042
+ { workingDirectory: "/path/to/repository" },
1043
+ );
1044
+ console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
1045
+ ```
1046
+
1047
+ Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values
1048
+ from your store. Results identify the original `occurrenceId` values. Options
1049
+ include model, reasoning effort, `AbortSignal`, and an optional `onProgress`
1050
+ callback whose errors do not interrupt matching.
1051
+
852
1052
  History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
853
1053
  `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
854
1054
  workbench maintain the database and its journal files as the current user.
@@ -928,8 +1128,8 @@ assessment skill once on the completed patch. The assessment is advisory and
928
1128
  does not change the patch or its merge state. Human-readable commands print the
929
1129
  report after the patch results; saved-finding JSON output returns it as
930
1130
  `patchRisk.report` in the same result object. When combined with `--create-pr`,
931
- the draft pull request body includes only the concise Markdown summary from the
932
- assessment; the validated JSON remains in the command result.
1131
+ the draft pull request or merge request body includes only the concise Markdown
1132
+ summary from the assessment; the validated JSON remains in the command result.
933
1133
 
934
1134
  ```bash
935
1135
  npx @openai/codex-security validate "Possible SQL injection" --effort high
@@ -951,11 +1151,25 @@ to select findings and add patch instructions. Results include a `patches`
951
1151
  entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
952
1152
  Verified and already-fixed findings no longer fail `--fail-on-severity`.
953
1153
 
954
- `--create-pr` commits generated patch files and opens a draft PR with `gh`.
955
- Supplied-issue pull requests require a clean working tree before patching so
1154
+ `--create-pr` commits generated patch files and opens a draft GitHub pull request
1155
+ with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
1156
+ the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is
1157
+ selected from the `origin` push URL, including SSH URLs and subgroup projects.
1158
+ For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate
1159
+ with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`
1160
+ aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain
1161
+ the GitHub workflow.
1162
+
1163
+ ```bash
1164
+ GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr
1165
+ ```
1166
+
1167
+ Both providers use the existing `pullRequest: { branch, url }` JSON result.
1168
+ Supplied-issue requests require a clean working tree before patching so
956
1169
  existing work is never included. If publication fails, run the printed
957
1170
  `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
958
1171
  commit without rerunning Codex, but refuses to publish if the branch changed.
1172
+ Use the same GitLab host setting when resuming a self-hosted merge request.
959
1173
 
960
1174
  To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
961
1175
  `--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
@@ -1360,7 +1574,7 @@ use another workflow ID for a fresh review rather than changing that saved resul
1360
1574
  2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1361
1575
  effort. The review covers every anchor-neighbor pair; nominations between
1362
1576
  neighbors are rejected.
1363
- 3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
1577
+ 3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
1364
1578
  reasoning effort. Only accepted pairs contribute to duplicate groups.
1365
1579
  4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
1366
1580
  decision contradicts the resulting component. Contradicted components are
@@ -1,10 +1,5 @@
1
1
  {
2
2
  "apps": {
3
- "codex-security-access": {
4
- "id": "connector_openai_codex_security_access",
5
- "category": "Security",
6
- "required": false
7
- },
8
3
  "linear": {
9
4
  "id": "asdk_app_69a089a326dc8191b32a3f2553f5be2c",
10
5
  "category": "Work Tracking & Coordination"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.94",
3
+ "version": "0.1.95",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -49,6 +49,7 @@
49
49
  "NODE_EXTRA_CA_CERTS",
50
50
  "XDG_CACHE_HOME"
51
51
  ],
52
+ "startup_timeout_sec": 120,
52
53
  "tool_timeout_sec": 349200
53
54
  }
54
55
  }
@@ -84,6 +84,6 @@ Present applicable remediation in the Codex thread. Ask before editing persisten
84
84
 
85
85
  Codex CLI and other hosts use the same prompt-based preflight before substantive work. Explain the exact reasons and remediation in chat. Interactive CLI sessions ask before editing persistent config; non-interactive CLI sessions use the narrow automatic-remediation path above and continue only after a `ready` rerun.
86
86
 
87
- ## TAC Status Advisory
87
+ ## Daybreak Access Advisory
88
88
 
89
- After capability preflight is `ready` and immediately before the workflow's first substantive scan action, use the hosted Codex Security Access app [$codex-security-access](app://connector_openai_codex_security_access) to call its `get_tac_status` action exactly once as the automatic pre-scan advisory. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and TAC grant levels. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that TAC access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, or the app or action is unavailable, instead warn that TAC access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or TAC access change, call the action again for a fresh result; this user-requested refresh is the only repeat.
89
+ After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool exactly once when available as the automatic pre-scan advisory. ChatGPT-authenticated desktop and CLI sessions both support this advisory; API-key-only sessions cannot verify account access. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and available Daybreak programs. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, `stale` is `true`, or the tool is unavailable or fails, instead warn that Daybreak access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or Daybreak access change, call the tool again when available for a fresh result; this user-requested refresh is the only repeat.
@@ -16,11 +16,11 @@ Use `report.md` as the primary readable entry point. Explain report-relevant art
16
16
 
17
17
  In the final response, link the generated markdown report path as the primary readable artifact.
18
18
 
19
- Every scan mode uses the same final report pipeline. Workbench-owned Standard and workbench-backed diff scans submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`; the workbench supplies authoritative metadata and writes the unsealed canonical draft. Deep Standard scan workers submit complete semantic results through their bound draft tool, and the coordinator aggregates them and writes the parent scan's unsealed canonical draft. SDK-owned Standard scans instead write unsealed canonical files with the exact SDK-provided metadata and leave finalization to the SDK. Terminal scans without a `scanId` retain their existing canonical JSON workflow. No mode authors, repairs, or treats an existing `report.md` as input. Finalization validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates `report.md`. Supply report prose through structured canonical semantics rather than a separately authored report.
19
+ Every scan mode uses the same final report pipeline. Workbench-owned Standard and workbench-backed diff scans submit canonical semantics with `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, coverage })`; the workbench supplies authoritative metadata and writes the unsealed canonical draft. For Deep scans, the coordinator writes the parent scan's unsealed canonical draft from its accepted aggregate. SDK-owned Standard scans instead write unsealed canonical files with the exact SDK-provided metadata and leave finalization to the SDK. Terminal scans without a `scanId` retain their existing canonical JSON workflow. No mode authors, repairs, or treats an existing `report.md` as input. Finalization validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates `report.md`. Supply report prose through structured canonical semantics rather than a separately authored report.
20
20
 
21
21
  For each finding, supply an evidence-supported lowercase vulnerability-family `ruleId`; `taxonomy: { category, cwe }` using its exact known CWEs; verified locations; and `provenance.source`, using `"local_plugin"` only when this plugin actually discovered the finding. Preserve genuine worker or source provenance and any existing canonical candidate identity in the finding extensions. A finding with no known CWE retains `cwe: []`; never invent a classification. Include optional `codeEvidence` only when its actual code is nonempty and every referenced evidence ID is present.
22
22
 
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.
23
+ For Standard scan drafts, including Deep worker results, and diff drafts, 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
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
26
 
@@ -59,7 +59,7 @@ Group observations only when they share the same broken security control and eff
59
59
 
60
60
  Set the finding category and CWE from the primary broken control. Do not add secondary support-impact CWEs, such as data exposure or missing authentication, to an injection/RCE/path/file/parser finding merely because they make exploitation worse; mention those impacts in prose or emit a separate finding if that secondary control is independently vulnerable.
61
61
 
62
- Workbench-owned Standard scans submit their source-backed final findings and coverage directly through `record_codex_security_scan_draft`; SDK-owned Standard scans write the same semantics into unsealed canonical files. Deep scans semantically aggregate complete Standard worker results, preserving validated findings, attack-path analysis, affected locations, threat-model context, and honest coverage. The coordinator writes the parent scan's canonical draft; the parent does not read candidate ledgers, run separate validation or attack-path phases, or submit another draft. Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
62
+ Canonical `severity.changeConditions` must be one non-empty string; when `attack_path.change_conditions` contains multiple strings, join them into one prose string before writing `findings.json`.
63
63
 
64
64
  For workbench-backed diff candidates, apply row outcomes in this order: validation disposition `reportable` plus attack-path decision `reportable` becomes a finding with its distinct instance and all relevant entrypoint, root-control, sink, and supporting locations; otherwise, a `deferred` result from either phase becomes `needs_follow_up` coverage and a `coverage.deferred` entry using the recorded uncertainty or proof gap; otherwise, validation disposition `not_applicable` becomes `not_applicable` coverage; otherwise, validation disposition `suppressed` or attack-path decision `ignore` becomes `rejected` coverage. A missing required phase record leaves the candidate unresolved and prevents complete coverage. Do not require phase receipts, per-candidate narratives, or another reconciliation pass.
65
65
 
@@ -73,6 +73,8 @@ Use this report structure:
73
73
 
74
74
  `## Scope`
75
75
 
76
+ Deep reports present the configured include and exclude paths and execution outcome alongside aggregated findings, with their validation, attack paths, affected locations, and any supplied scope and threat-model context. When the discovery time limit expires before any source review completes, the report explains the incomplete review.
77
+
76
78
  Populate `scan.scope` with in-scope context, artifacts reviewed, runtime or test status, validation mode, and explicit limitations. Include/exclude paths and coverage fields supply the remaining projected scope content. If the threat model was generated during Phase 1 rather than provided by the user, say that in canonical scope context. Do not call generated threat-model material an external input.
77
79
 
78
80
  After the scope bullets, include a compact `### Scan Summary` table when the scan has findings or repository-wide coverage. Use columns `Field` and `Value`. Include the count of reportable findings, severity mix, confidence mix, coverage, and validation mode when those values are known. Keep artifact paths below this table.
@@ -40,7 +40,11 @@ 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 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.
43
+ Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Workbench-backed diff scans use the compact artifacts described below.
44
+
45
+ Deep scans run ordinary Standard scan workers. Workers save progress with `complete: false` and submit final results through `record_codex_security_scan_draft`. Their checkpoints and results contain findings and coverage, with optional scope and threat-model context. Pending candidates and their evidence are recorded in worker coverage. Immutable checkpoints store progress across retries, cancellation, and failure. The coordinator passes completed workers' findings and context to the reducer.
46
+
47
+ Deep reducer inputs, results, and checkpoints contain findings and optional scope and threat-model context. The host writes the parent scan's unsealed `scan-manifest.json` and `findings.json` from the accepted aggregate, and derives `coverage.json` from the configured include and exclude paths and the coordinator's outcome. The parent completes the scan from these artifacts. If the discovery time limit expires before any source review completes, the parent records partial coverage with that reason. See `scan-contract.md` for canonical field definitions.
44
48
 
45
49
  - 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
50
  - 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.
@@ -104,9 +104,13 @@ Use CWE taxonomy separately. Do not include file names, line numbers, scan IDs,
104
104
 
105
105
  ## Coverage
106
106
 
107
- `coverage.json` prevents downstream consumers from confusing `not observed` with `not scanned`.
107
+ `coverage.json` records scan scope and completion information. Standard and diff summaries also describe reviewed surfaces and outstanding work.
108
108
 
109
- Record:
109
+ For a Deep parent scan, the host copies the configured paths into `includePaths` and `excludePaths` and sets `completeness` from the coordinator's outcome. A successful aggregate uses `complete`; `surfaces`, `explicitExclusions`, and `deferred` are empty arrays, and `openQuestions` is omitted. If the configured time limit expires before any review completes, the coordinator writes `partial` and records the explanation in `deferred`. Stopped outcomes follow the [stopped-result recovery rules](#stopped-result-recovery).
110
+
111
+ Each Deep worker writes an ordinary Standard result, including its own coverage. A reducer submits `record_codex_security_deep_reduction({ scanId, findings, scope?, threatModel? })`; its saved results and checkpoints contain the accepted findings and optional scope and threat-model context.
112
+
113
+ For Standard and diff scans, record:
110
114
 
111
115
  - scan mode and inventory strategy
112
116
  - included and excluded paths
@@ -140,7 +144,7 @@ For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repe
140
144
  | `directory` | Deterministic non-Git directory inventory |
141
145
  | `custom` | Producer-defined inventory described by detailed receipts |
142
146
 
143
- Use `complete` when the requested scope was fully reviewed, `partial` when in-scope work was deferred, and `unknown` when the producer cannot establish enough coverage to make that distinction.
147
+ For Standard and diff scans, use `complete` when the requested scope was fully reviewed, `partial` when in-scope work was deferred, and `unknown` when the producer cannot establish enough coverage to make that distinction.
144
148
 
145
149
  Map detailed ledger closure into completed surface summaries in this order:
146
150
 
@@ -9,7 +9,33 @@
9
9
  "additionalProperties": false
10
10
  },
11
11
  "reductionInput": {
12
- "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scanDraftInput"
12
+ "type": "object",
13
+ "properties": {
14
+ "complete": {
15
+ "type": "boolean",
16
+ "description": "Omit or set true when submitting the finished aggregate."
17
+ },
18
+ "scanId": {
19
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scanId"
20
+ },
21
+ "handoffClaimToken": {
22
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/handoffClaimToken"
23
+ },
24
+ "scope": {
25
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scope"
26
+ },
27
+ "threatModel": {
28
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/threatModel"
29
+ },
30
+ "findings": {
31
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scanDraftInput/properties/findings"
32
+ }
33
+ },
34
+ "required": [
35
+ "scanId",
36
+ "findings"
37
+ ],
38
+ "additionalProperties": false
13
39
  }
14
40
  }
15
41
  }
@@ -1877,6 +1877,7 @@ def finish_deep_scan_locked(
1877
1877
  """
1878
1878
  SELECT 1 FROM deep_scan_workers AS failed
1879
1879
  WHERE failed.scan_id = ? AND failed.status = 'failed'
1880
+ AND (? != 'saturated' OR failed.kind != 'discovery')
1880
1881
  AND (
1881
1882
  failed.kind != 'dedup'
1882
1883
  OR NOT EXISTS (
@@ -1902,10 +1903,14 @@ def finish_deep_scan_locked(
1902
1903
  )
1903
1904
  LIMIT 1
1904
1905
  """,
1905
- (scan_id,),
1906
+ (scan_id, args.terminal_reason),
1906
1907
  ).fetchone()
1907
1908
  if failed_worker is not None and not failure_capped:
1908
1909
  raise SystemExit("Deep Scan cannot finish after a worker has failed.")
1910
+ if args.terminal_reason == "saturated":
1911
+ # Mark any remaining workers canceled, including those whose own
1912
+ # cancellation writes failed, so they cannot block completion.
1913
+ cancel_active_workers(connection, scan_id, now())
1909
1914
  active_worker = connection.execute(
1910
1915
  """
1911
1916
  SELECT 1 FROM deep_scan_workers
@@ -1252,12 +1252,9 @@ def _normalize_unsealed_deep_repository_inventory_strategy(
1252
1252
  *,
1253
1253
  expected_coverage_mode: str | None,
1254
1254
  ) -> None:
1255
- """Normalize the old Deep workflow label to the ordinary repository inventory."""
1255
+ """Label whole-repository Deep scans as using the repository inventory."""
1256
1256
 
1257
- if (
1258
- expected_coverage_mode == "deep_repository"
1259
- and coverage.get("inventoryStrategy") == "deep_repository_repeated_discovery"
1260
- ):
1257
+ if expected_coverage_mode == "deep_repository":
1261
1258
  coverage["inventoryStrategy"] = "repository"
1262
1259
 
1263
1260
 
@@ -814,7 +814,7 @@ def build_report_markdown(
814
814
  "",
815
815
  _text(
816
816
  scope.get("summary"),
817
- "The scan reviewed the canonical include paths and exclusions listed below.",
817
+ "The scan was configured for the include paths and exclusions listed below.",
818
818
  ),
819
819
  "",
820
820
  f"- Scan mode: {coverage['mode']}",
@@ -354,6 +354,9 @@ def parse_args(description: str) -> argparse.Namespace:
354
354
  subparsers.add_parser("database-info")
355
355
  subparsers.add_parser("dashboard")
356
356
  subparsers.add_parser("finding-workflow")
357
+ subparsers.add_parser("severity-classification")
358
+ severity = subparsers.add_parser("read-severity-classification")
359
+ severity.add_argument("--scan-id", required=True)
357
360
  subparsers.add_parser("store-findings")
358
361
  subparsers.add_parser("store-dedupe-groups")
359
362
  dedupe_groups = subparsers.add_parser("list-dedupe-groups")
@@ -40,6 +40,7 @@ import workbench_remediation as remediation
40
40
  import workbench_saved_results as saved_results
41
41
  import workbench_scan_history as scan_history
42
42
  import workbench_scan_usage as scan_usage
43
+ import workbench_severity as severity
43
44
  from filesystem_identity import (
44
45
  serialize_filesystem_identity as serialize_filesystem_identity,
45
46
  )
@@ -1535,7 +1536,9 @@ def complete_scan_locked(
1535
1536
  scan_dir,
1536
1537
  expected_coverage_mode=expected_coverage_mode(scan),
1537
1538
  completion_binding=completion_binding,
1538
- completion_warnings=warnings,
1539
+ # Save the finished Deep result as submitted. Worker drafts and
1540
+ # recovery repairs belong to the stopped-scan path.
1541
+ completion_warnings=warnings if scan["mode"] != "deep" else None,
1539
1542
  draft_documents=saved_results.merge_saved_results(
1540
1543
  scan_dir,
1541
1544
  scan["id"],
@@ -1548,7 +1551,7 @@ def complete_scan_locked(
1548
1551
  stopped=False,
1549
1552
  reason="",
1550
1553
  )
1551
- if current_manifest_path is not None and not already_sealed
1554
+ if scan["mode"] != "deep" and current_manifest_path is not None and not already_sealed
1552
1555
  else None,
1553
1556
  )
1554
1557
  add_warning()
@@ -3451,6 +3454,10 @@ def main() -> None:
3451
3454
  result = inspect_setup(args)
3452
3455
  print(json.dumps(result, allow_nan=False, sort_keys=True))
3453
3456
  return
3457
+ if args.command == "read-severity-classification":
3458
+ result = severity.read_classification(database_path(), args.scan_id)
3459
+ print(json.dumps(result, allow_nan=False, sort_keys=True))
3460
+ return
3454
3461
  if args.command == "inspect-linear-publication":
3455
3462
  result = inspect_linear_publication(args)
3456
3463
  print(json.dumps(result, allow_nan=False, sort_keys=True))
@@ -3621,6 +3628,8 @@ def main() -> None:
3621
3628
  result = export_findings(connection, args)
3622
3629
  elif args.command == "database-info":
3623
3630
  result = {"databasePath": str(database_path())}
3631
+ elif args.command == "severity-classification":
3632
+ result = severity.checkpoint(connection, json.load(sys.stdin), now())
3624
3633
  elif args.command == "finding-workflow":
3625
3634
  result = finding_workflow(connection, json.load(sys.stdin), now())
3626
3635
  elif args.command == "dashboard":