@openai/codex-security 0.1.21 → 0.1.24

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 (183) hide show
  1. package/README.md +549 -1
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/config-preflight.md +2 -30
  7. package/_bundled_plugin/references/core-scan.md +1 -1
  8. package/_bundled_plugin/references/final-report.md +1 -1
  9. package/_bundled_plugin/references/finding-detail-fields.md +5 -10
  10. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  11. package/_bundled_plugin/references/scan-contract.md +10 -0
  12. package/_bundled_plugin/scripts/config_preflight.py +2 -8
  13. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  14. package/_bundled_plugin/scripts/finalize_scan_contract.py +115 -76
  15. package/_bundled_plugin/scripts/finding_preview.py +22 -4
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +29 -9
  17. package/_bundled_plugin/scripts/generate_rank_input.py +1 -5
  18. package/_bundled_plugin/scripts/rank_preview.py +1 -0
  19. package/_bundled_plugin/scripts/report_projection.py +8 -14
  20. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -3
  21. package/_bundled_plugin/scripts/windows_scan_local_files.py +90 -6
  22. package/_bundled_plugin/scripts/workbench_cli.py +27 -1
  23. package/_bundled_plugin/scripts/workbench_dashboard.py +138 -0
  24. package/_bundled_plugin/scripts/workbench_db.py +110 -539
  25. package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
  26. package/_bundled_plugin/scripts/workbench_finding_workflows.py +208 -0
  27. package/_bundled_plugin/scripts/workbench_findings.py +221 -0
  28. package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -2
  29. package/_bundled_plugin/scripts/workbench_publication.py +520 -0
  30. package/_bundled_plugin/scripts/workbench_remediation.py +37 -0
  31. package/_bundled_plugin/scripts/workbench_saved_results.py +322 -89
  32. package/_bundled_plugin/scripts/workbench_scan_history.py +1 -2
  33. package/_bundled_plugin/scripts/workbench_scan_usage.py +9 -33
  34. package/_bundled_plugin/scripts/workbench_schema.py +276 -58
  35. package/_bundled_plugin/scripts/workbench_target.py +30 -6
  36. package/_bundled_plugin/scripts/workbench_validation.py +1 -5
  37. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +1 -5
  38. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +6 -1
  39. package/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
  40. package/dist/api.d.ts +5 -1
  41. package/dist/api.d.ts.map +1 -1
  42. package/dist/api.js +135 -27
  43. package/dist/api.js.map +1 -1
  44. package/dist/cli.d.ts +4 -0
  45. package/dist/cli.d.ts.map +1 -1
  46. package/dist/cli.js +158 -62
  47. package/dist/cli.js.map +1 -1
  48. package/dist/cloud-publish.js +5 -1
  49. package/dist/cloud-publish.js.map +1 -1
  50. package/dist/contract.d.ts +1 -0
  51. package/dist/contract.d.ts.map +1 -1
  52. package/dist/contract.js +9 -0
  53. package/dist/contract.js.map +1 -1
  54. package/dist/custom-publish.d.ts +22 -0
  55. package/dist/custom-publish.d.ts.map +1 -0
  56. package/dist/custom-publish.js +47 -0
  57. package/dist/custom-publish.js.map +1 -0
  58. package/dist/custom-validation-prompt.js +1 -1
  59. package/dist/custom-validation-prompt.js.map +1 -1
  60. package/dist/deduplication/checkpointed-review.d.ts +16 -0
  61. package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
  62. package/dist/deduplication/checkpointed-review.js +76 -0
  63. package/dist/deduplication/checkpointed-review.js.map +1 -0
  64. package/dist/deduplication/codex-review.d.ts +21 -0
  65. package/dist/deduplication/codex-review.d.ts.map +1 -0
  66. package/dist/deduplication/codex-review.js +252 -0
  67. package/dist/deduplication/codex-review.js.map +1 -0
  68. package/dist/deduplication/deduplication-prompts.d.ts +8 -0
  69. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
  70. package/dist/deduplication/deduplication-prompts.js +35 -0
  71. package/dist/deduplication/deduplication-prompts.js.map +1 -0
  72. package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
  73. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
  74. package/dist/deduplication/deduplication-reviewer.js +105 -0
  75. package/dist/deduplication/deduplication-reviewer.js.map +1 -0
  76. package/dist/deduplication/deduplication.d.ts +6 -0
  77. package/dist/deduplication/deduplication.d.ts.map +1 -0
  78. package/dist/deduplication/deduplication.js +85 -0
  79. package/dist/deduplication/deduplication.js.map +1 -0
  80. package/dist/deduplication/scan.d.ts +16 -0
  81. package/dist/deduplication/scan.d.ts.map +1 -0
  82. package/dist/deduplication/scan.js +101 -0
  83. package/dist/deduplication/scan.js.map +1 -0
  84. package/dist/deep-progress.d.ts +21 -0
  85. package/dist/deep-progress.d.ts.map +1 -0
  86. package/dist/deep-progress.js +108 -0
  87. package/dist/deep-progress.js.map +1 -0
  88. package/dist/finding-dedupe-groups.d.ts +7 -0
  89. package/dist/finding-dedupe-groups.d.ts.map +1 -0
  90. package/dist/finding-dedupe-groups.js +2 -0
  91. package/dist/finding-dedupe-groups.js.map +1 -0
  92. package/dist/finding-retrieval.d.ts +13 -0
  93. package/dist/finding-retrieval.d.ts.map +1 -0
  94. package/dist/finding-retrieval.js +2 -0
  95. package/dist/finding-retrieval.js.map +1 -0
  96. package/dist/finding-workflow.d.ts +53 -0
  97. package/dist/finding-workflow.d.ts.map +1 -0
  98. package/dist/finding-workflow.js +117 -0
  99. package/dist/finding-workflow.js.map +1 -0
  100. package/dist/findings-client.d.ts +15 -0
  101. package/dist/findings-client.d.ts.map +1 -0
  102. package/dist/findings-client.js +60 -0
  103. package/dist/findings-client.js.map +1 -0
  104. package/dist/index.d.ts +5 -0
  105. package/dist/index.d.ts.map +1 -1
  106. package/dist/index.js +2 -0
  107. package/dist/index.js.map +1 -1
  108. package/dist/publication.js +28 -40
  109. package/dist/publication.js.map +1 -1
  110. package/dist/runtime.d.ts +5 -1
  111. package/dist/runtime.d.ts.map +1 -1
  112. package/dist/runtime.js +119 -13
  113. package/dist/runtime.js.map +1 -1
  114. package/dist/saved-scan.d.ts +15 -0
  115. package/dist/saved-scan.d.ts.map +1 -0
  116. package/dist/saved-scan.js +68 -0
  117. package/dist/saved-scan.js.map +1 -0
  118. package/dist/scan-activity.d.ts.map +1 -1
  119. package/dist/scan-activity.js +12 -2
  120. package/dist/scan-activity.js.map +1 -1
  121. package/dist/scan-comparison.d.ts +3 -2
  122. package/dist/scan-comparison.d.ts.map +1 -1
  123. package/dist/scan-comparison.js +1 -1
  124. package/dist/scan-comparison.js.map +1 -1
  125. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
  126. package/dist/server/dashboard/app.css +2 -0
  127. package/dist/server/dashboard/app.js +66 -0
  128. package/dist/server/dashboard/index.html +18 -0
  129. package/dist/server/dashboard-types.d.ts +45 -0
  130. package/dist/server/dashboard-types.d.ts.map +1 -0
  131. package/dist/server/dashboard-types.js +2 -0
  132. package/dist/server/dashboard-types.js.map +1 -0
  133. package/dist/server/dashboard.d.ts +6 -0
  134. package/dist/server/dashboard.d.ts.map +1 -0
  135. package/dist/server/dashboard.js +45 -0
  136. package/dist/server/dashboard.js.map +1 -0
  137. package/dist/server/embeddings.d.ts +16 -0
  138. package/dist/server/embeddings.d.ts.map +1 -0
  139. package/dist/server/embeddings.js +114 -0
  140. package/dist/server/embeddings.js.map +1 -0
  141. package/dist/server/errors.d.ts +5 -0
  142. package/dist/server/errors.d.ts.map +1 -0
  143. package/dist/server/errors.js +8 -0
  144. package/dist/server/errors.js.map +1 -0
  145. package/dist/server/findings-service.d.ts +20 -0
  146. package/dist/server/findings-service.d.ts.map +1 -0
  147. package/dist/server/findings-service.js +31 -0
  148. package/dist/server/findings-service.js.map +1 -0
  149. package/dist/server/index.d.ts +2 -0
  150. package/dist/server/index.d.ts.map +1 -0
  151. package/dist/server/index.js +6 -0
  152. package/dist/server/index.js.map +1 -0
  153. package/dist/server/routes.d.ts +6 -0
  154. package/dist/server/routes.d.ts.map +1 -0
  155. package/dist/server/routes.js +86 -0
  156. package/dist/server/routes.js.map +1 -0
  157. package/dist/server/serve.d.ts +2 -0
  158. package/dist/server/serve.d.ts.map +1 -0
  159. package/dist/server/serve.js +28 -0
  160. package/dist/server/serve.js.map +1 -0
  161. package/dist/server/server.d.ts +10 -0
  162. package/dist/server/server.d.ts.map +1 -0
  163. package/dist/server/server.js +17 -0
  164. package/dist/server/server.js.map +1 -0
  165. package/dist/server/sqlite-store.d.ts +22 -0
  166. package/dist/server/sqlite-store.d.ts.map +1 -0
  167. package/dist/server/sqlite-store.js +82 -0
  168. package/dist/server/sqlite-store.js.map +1 -0
  169. package/dist/server/storage.d.ts +32 -0
  170. package/dist/server/storage.d.ts.map +1 -0
  171. package/dist/server/storage.js +2 -0
  172. package/dist/server/storage.js.map +1 -0
  173. package/dist/server/validation.d.ts +17 -0
  174. package/dist/server/validation.d.ts.map +1 -0
  175. package/dist/server/validation.js +53 -0
  176. package/dist/server/validation.js.map +1 -0
  177. package/dist/trusted-executable.d.ts.map +1 -1
  178. package/dist/trusted-executable.js +2 -1
  179. package/dist/trusted-executable.js.map +1 -1
  180. package/dist/version.d.ts +1 -1
  181. package/dist/version.js +1 -1
  182. package/dist/version.js.map +1 -1
  183. package/package.json +17 -5
package/README.md CHANGED
@@ -152,7 +152,10 @@ Options for `security.run(repository, options)` and
152
152
  | `signal` | `AbortSignal` to cancel a scan. |
153
153
 
154
154
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
155
- saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.
155
+ saved events with thread IDs and worker numbers. Deep scans can additionally use
156
+ `onDeepProgress` for durable independent-review counts: `completed`, `active`,
157
+ and `maximum`. The maximum is a configured cap, not a percentage denominator.
158
+ `ScanOptions` lists all callbacks.
156
159
 
157
160
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
158
161
  using the network. They don't authenticate, verify model access, resolve Python,
@@ -910,6 +913,551 @@ command manifest, `scan --schema --format json` for a command schema, and
910
913
  MCP exposes only the read-only `info` command because the transport cannot
911
914
  cancel active scans.
912
915
 
916
+ ## Findings service (preview)
917
+
918
+ The findings API uses the same `ghcr.io/openai/codex-security` image as the
919
+ scanner, for Linux `amd64` and `arm64`. `compose.findings.yaml` starts the API
920
+ in a separate container with its own state volume and server configuration.
921
+ Once a release is published, it can be pulled without a GitHub login. See
922
+ [container release setup](../../docker/README.md) for the required maintainer
923
+ setup and publication process.
924
+
925
+ From the repository root, copy the example if you do not already have a `.env`:
926
+
927
+ ```bash
928
+ cp .env.example .env
929
+ ```
930
+
931
+ Set `OPENAI_API_KEY` in `.env`, then pull and start the findings API:
932
+
933
+ ```bash
934
+ docker compose -f compose.findings.yaml pull
935
+ docker compose -f compose.findings.yaml up --no-build -d
936
+ curl -i http://127.0.0.1:3000/v1/findings
937
+ ```
938
+
939
+ You can deploy with just `compose.findings.yaml` and a private `.env`; no source
940
+ checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
941
+ defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
942
+ version, `sha-<commit>` tag, or digest for repeatable deployments.
943
+
944
+ To build from a source checkout instead:
945
+
946
+ ```bash
947
+ docker build --target scanner -t codex-security:local .
948
+ export CODEX_SECURITY_FINDINGS_IMAGE=codex-security:local
949
+ docker compose -f compose.findings.yaml up --no-build -d
950
+ ```
951
+
952
+ For an existing deployment using the separate findings image or
953
+ `--target findings-service`, follow the [single-image migration guide](../../docker/README.md#migrating-the-findings-service).
954
+
955
+ ### Read-only dashboard
956
+
957
+ Open `http://localhost:3000/dashboard` on the running findings service. The UI
958
+ uses the public OpenAI Apps SDK UI design system, follows the browser's light
959
+ or dark preference, and polls the service every five seconds. It never starts,
960
+ cancels, resumes, publishes, edits, or deduplicates anything.
961
+
962
+ The dashboard opens on Findings, followed by Duplicate groups. Both views
963
+ support search, repository filtering, sorting, pagination, and record details.
964
+ Findings show stored content and links to their duplicate groups. Groups link
965
+ back to their member findings, preserving separate overlapping groups and the
966
+ original finding records.
967
+
968
+ The dashboard reads only findings, repository associations, and duplicate groups
969
+ stored in the service's configured database. It does not display scans or
970
+ workflows: publication sends findings, not remote scan or workflow history. It
971
+ does not read report or source paths from stored records. The UI retains the last
972
+ successful data on a refresh failure and shows a connection warning until polling
973
+ succeeds.
974
+
975
+ `GET /v1/dashboard` returns a consistent read snapshot with overview counts,
976
+ repository choices, a page of records, and optional selected-record details:
977
+
978
+ - `view`: `findings` (default) or `groups`.
979
+ - `query`, `repository`: optional search text and exact repository ID.
980
+ - `sort`: `activity` (default; most recently updated first) or `newest`.
981
+ - `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
982
+ - `id`: optional exact record ID to include in `detail`; unknown IDs return
983
+ `detail: null` without hiding the list.
984
+
985
+ Overview counts are service-wide, not filtered page totals. Responses and UI
986
+ assets are served by the same Node process; no separate frontend server, CDN,
987
+ model credentials, or new CLI flags are needed to view the dashboard. Compiled
988
+ HTML, JavaScript, and CSS are included in the npm package and container. Frontend
989
+ source, build tools, and tests are not shipped as runtime dependencies.
990
+
991
+ The existing preview access boundary is unchanged. The dashboard contains
992
+ sensitive finding content: keep the service on a trusted local endpoint or behind
993
+ an authenticated proxy. It does not add authentication or broaden the default
994
+ network binding.
995
+
996
+ ### API
997
+
998
+ `POST /v1/bulk/findings` accepts `{"findings": [...]}`, using the existing SDK
999
+ `Finding` model, including `findingId`, `occurrenceId`, and `fingerprints`.
1000
+ A complete exported `findings.json` document is also accepted; only its
1001
+ `findings` array is imported. No files or source paths referenced by the
1002
+ findings are opened. Only the supplied JSON is processed.
1003
+
1004
+ Include `repositoryId` alongside `findings` to associate every imported finding
1005
+ with a repository. For SDK/CLI scans, use `scan.target.targetId` from the sealed
1006
+ `scan-manifest.json`. IDs are matched exactly; the service does not infer a
1007
+ repository from titles, paths, or URLs. Reimports add associations without
1008
+ removing earlier ones, so a finding can belong to more than one repository.
1009
+ Imports without this metadata remain accepted, but unassociated findings are
1010
+ only available to explicit all-repository retrieval until imported with an ID.
1011
+
1012
+ | Method | Path | Response |
1013
+ | ------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
1014
+ | `POST` | `/v1/bulk/findings` | HTTP 201 with an array of stored finding IDs, in request order |
1015
+ | `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200 with a page of complete findings |
1016
+ | `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200 with the stored finding and up to 50 potential duplicates, without vectors |
1017
+ | `POST` | `/v1/dedupe-groups` | HTTP 201 with the persisted duplicate groups |
1018
+ | `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200 with every stored group containing this finding |
1019
+
1020
+ Bulk insertion generates embeddings and then writes the findings and vectors
1021
+ in one SQLite transaction. If embedding generation fails or a finding identity
1022
+ conflicts with another stored identity, no part of the batch is written.
1023
+ Reusing a `findingId` updates that finding and replaces its embedding; retries
1024
+ do not create extra rows. An existing ID's fingerprint, rule, and identity
1025
+ anchor/instance cannot be replaced. Repeated IDs in one request are applied in order,
1026
+ with the last supplied record retained. Stored scan occurrences are unchanged.
1027
+
1028
+ For example, add `repositoryId` to a copy of an exported findings document
1029
+ saved as `findings-import.json` (leave the sealed scan artifacts unchanged),
1030
+ then import it with the API key configured before starting Compose:
1031
+
1032
+ ```bash
1033
+ curl http://127.0.0.1:3000/v1/bulk/findings \
1034
+ -H 'Content-Type: application/json' \
1035
+ --data-binary @findings-import.json
1036
+ ```
1037
+
1038
+ ```json
1039
+ ["csf_852f90d6e1177502ff113d4a"]
1040
+ ```
1041
+
1042
+ The potential-duplicates response contains `finding` (the complete stored
1043
+ anchor) and `potentialDuplicates` (an array of complete `Finding` records).
1044
+ Neither includes embedding vectors. The anchor is not repeated in the array.
1045
+ Specify one scope explicitly on the request:
1046
+
1047
+ ```text
1048
+ GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example
1049
+ GET /v1/finding/{id}/potential-duplicates?allRepositories=true
1050
+ ```
1051
+
1052
+ Repository scope requires the anchor and each candidate to be associated with
1053
+ that repository. All-repository scope includes tagged and untagged findings.
1054
+ Omitting scope or combining a repository with `allRepositories=true` returns
1055
+ HTTP 400. Scope selects candidates; it is not an authorization boundary.
1056
+
1057
+ Candidates have cosine similarity at least 0.55 and the same embedding model
1058
+ and dimensions as the anchor. They are ordered by descending similarity, with
1059
+ ties resolved by insertion time and finding ID, and limited to 50. Each request
1060
+ reads a current snapshot; separate requests do not share a database snapshot.
1061
+ SQLite first filters repository associations, reads only IDs and embedding
1062
+ vectors (plus the anchor's model), and performs exact cosine ranking. It then
1063
+ loads complete documents only for the anchor and the selected top 50 candidates,
1064
+ all within the same read transaction.
1065
+ The API does not run Codex or decide whether candidates are duplicates.
1066
+
1067
+ ### Publishing to a custom findings service
1068
+
1069
+ Publish a completed scan directly from the local CLI to the Docker service:
1070
+
1071
+ ```bash
1072
+ codex-security publish scan --scan SCAN_ID --to custom \
1073
+ --findings-url http://localhost:3000 --json
1074
+ ```
1075
+
1076
+ `--findings-url` is required for `--to custom`, with no default. It is the
1077
+ service base URL, including `http://` or `https://`; the client appends
1078
+ `/v1/bulk/findings`, preserving any base path. A different endpoint must
1079
+ implement that API and return the stored finding IDs. The command sends the
1080
+ complete sealed findings and their manifest's `scan.target.targetId` as
1081
+ `repositoryId`, without changing scan artifacts or forwarding model credentials.
1082
+ The service creates embeddings and commits the batch before acknowledging it.
1083
+
1084
+ The existing saved-scan selector, external `--scan-dir`, and interactive picker
1085
+ work with custom publication. Custom publication accepts one scan, not CSV
1086
+ input or Linear options. Add `--dry-run` to validate and preview the payload
1087
+ without making an HTTP request. Existing Linear and Cloud destinations are
1088
+ unchanged. Upload failures and incomplete receipts fail the command; uploads
1089
+ are not automatically retried because a lost response may have been committed.
1090
+
1091
+ ```typescript
1092
+ import { publishScanToCustom } from "@openai/codex-security";
1093
+
1094
+ const receipt = await publishScanToCustom("/path/to/completed-scan", {
1095
+ findingsUrl: "http://localhost:3000",
1096
+ // dryRun: true,
1097
+ // signal: controller.signal,
1098
+ });
1099
+ console.log(receipt.repositoryId, receipt.findingIds);
1100
+ ```
1101
+
1102
+ ### Deduplication from the SDK and CLI
1103
+
1104
+ Publish the scan with `--to custom` (or import it through the bulk API with its
1105
+ `repositoryId`) before deduplicating. The
1106
+ workflow reads a completed saved scan, queries candidates by finding ID, and
1107
+ runs Luna and Sol in the calling SDK/CLI process. Once all reviews succeed,
1108
+ it posts accepted groups to the service. It does not re-upload findings or
1109
+ change scan artifacts.
1110
+
1111
+ ```bash
1112
+ codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
1113
+ ```
1114
+
1115
+ The default scope is the saved scan's repository, identified by
1116
+ `scan.target.targetId` in its manifest. Add `--all-repositories` to search the
1117
+ entire stored corpus explicitly; the flag defaults to false. The SDK has the
1118
+ equivalent optional `allRepositories: true` setting. This narrows the previous
1119
+ preview's implicit all-repository behavior.
1120
+
1121
+ Both `--scan` and `--findings-url` are required, with no implicit scan or service
1122
+ URL. As with `publish scan --scan`, the selector accepts a full ID, unique
1123
+ prefix, or `latest` for the current repository. The saved scan must be complete
1124
+ and its sealed artifacts must be available.
1125
+
1126
+ ```typescript
1127
+ import { deduplicateScan } from "@openai/codex-security";
1128
+
1129
+ const result = await deduplicateScan("scan_example_001", {
1130
+ findingsUrl: "http://127.0.0.1:3000",
1131
+ // allRepositories: true, // Omit to search only this scan's repository.
1132
+ // signal: controller.signal,
1133
+ });
1134
+ console.log(result.duplicateGroups);
1135
+ ```
1136
+
1137
+ The CLI and SDK return the same result:
1138
+
1139
+ ```json
1140
+ {
1141
+ "scanId": "scan_example_001",
1142
+ "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
1143
+ "duplicateGroups": [],
1144
+ "deduplicationStatus": "completed"
1145
+ }
1146
+ ```
1147
+
1148
+ `uniqueFindingIds` contains one representative for each selected finding after
1149
+ accepted duplicate groups are collapsed. A representative can be an existing
1150
+ stored finding outside the scan. Each `duplicateGroups` entry contains all
1151
+ members of an accepted group, with its canonical finding first. The canonical
1152
+ has the highest reported severity; ties use finding ID. Results do not delete,
1153
+ merge, or change stored finding documents. Accepted groups are saved as durable
1154
+ associations in the service before `deduplicationStatus` becomes `completed`.
1155
+
1156
+ ### Stored duplicate groups
1157
+
1158
+ `POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
1159
+
1160
+ ```json
1161
+ {
1162
+ "groups": [
1163
+ ["csf_000000000000000000000001", "csf_000000000000000000000002"],
1164
+ ["csf_000000000000000000000002", "csf_000000000000000000000003"]
1165
+ ]
1166
+ }
1167
+ ```
1168
+
1169
+ Each group must contain at least two distinct, existing finding IDs. The entire
1170
+ batch is committed in one transaction; a missing finding returns HTTP 409 and
1171
+ writes none of the batch. A response contains `groupId`, `findingIds`, and
1172
+ `createdAt` for each group. Group identity depends on membership, not member
1173
+ order, so submitting the same set again returns its original ID and timestamp.
1174
+
1175
+ SQLite stores groups in `finding_dedupe_groups` and memberships in
1176
+ `finding_dedupe_group_members`. A finding may belong to multiple groups:
1177
+ `[A, B]`, `[B, C]`, and `[C, A]` are three separate reviewed sets. Overlapping
1178
+ groups are not automatically united or promoted into an unreviewed larger
1179
+ group. Stored members are sorted by ID; their order does not designate a
1180
+ canonical. The CLI result retains its existing canonical-first ordering.
1181
+
1182
+ `GET /v1/finding/{id}/dedupe-groups` returns every group containing that finding,
1183
+ including each group's full membership, or `[]` if it has no groups. These
1184
+ associations do not rewrite original findings, fingerprints, scan artifacts,
1185
+ embeddings, or external tickets. They do not require an embedding API key or
1186
+ trigger model calls. Review-generated merged findings remain review outputs;
1187
+ they do not replace stored documents.
1188
+
1189
+ ### Resuming a local findings workflow
1190
+
1191
+ Add `--workflow-id` to opt into durable state shared by `scan`, `publish scan
1192
+ --to custom`, and `dedupe`. The SDK equivalents are the optional `workflowId`
1193
+ fields on `ScanOptions`, `PublishScanToCustomOptions`, and `DeduplicateScanOptions`.
1194
+ Without a workflow ID, existing command behavior and output shapes are unchanged.
1195
+
1196
+ ```bash
1197
+ codex-security scan /path/to/repository --workflow-id run-001
1198
+ codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000
1199
+ codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json
1200
+ ```
1201
+
1202
+ Repeat this sequence with the same ID after a process stops. Completed scans and
1203
+ acknowledged publications are reused; unfinished stages run again. If the scan
1204
+ completed before the workflow recorded its receipt, recovery verifies the saved
1205
+ scan and its sealed artifacts instead of scanning again. Scan IDs and artifact
1206
+ locations are recorded in the scan-registration transaction. This resumes between
1207
+ completed steps; it does not resume individual model turns inside an unfinished
1208
+ scan. Existing output-directory and archive safeguards still apply to scan retries.
1209
+
1210
+ Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
1211
+ scan selector must identify that same scan. A workflow can also begin at custom
1212
+ publication of a completed scan. Dedupe still requires local scan history to locate
1213
+ the approved source checkout. For a workflow, dedupe first completes publication
1214
+ if its receipt is missing. `--all-repositories` retains its existing default of
1215
+ false. Changing a workflow's scan, destination, or bound scope is an error: choose
1216
+ a different workflow ID. Use one coordinating process per workflow.
1217
+
1218
+ Workflow metadata, stage statuses, errors, publication receipts, and results live
1219
+ in the local workbench SQLite database under `CODEX_SECURITY_STATE_DIR`, outside
1220
+ the sealed scan artifacts. Identity, scan/artifact references, destination, scope,
1221
+ hashes, stage statuses, and errors use explicit columns; only receipts and result
1222
+ payloads use JSON. Review source, scope, model settings, and contract/hash bindings
1223
+ also use columns; review results remain JSON. Existing workflows and checkpoints
1224
+ are migrated atomically in place without changing their review keys.
1225
+ Successful empty results are stored as completed
1226
+ results, not treated as missing work. An empty scan can complete workflow
1227
+ publication with an empty receipt. Dry-run never advances a workflow stage.
1228
+
1229
+ A completed `dedupe --workflow-id` returns its saved result without repeating
1230
+ reviews or group writes. A publication whose acknowledgement was lost is retried
1231
+ using the service's existing idempotent upsert.
1232
+
1233
+ Each validated screening and pair review is checkpointed locally,
1234
+ including DISTINCT decisions. Every SAME checkpoint retains its required
1235
+ `canonicalFindingId` and generated `mergedFinding`. The merged record must satisfy
1236
+ the Finding schema and preserve the canonical finding ID. Validation still happens
1237
+ through `review_validator.submit_decisions`; invalid submissions are corrected in
1238
+ the same review conversation, and invalid or unfinished reviews are not cached.
1239
+
1240
+ Checkpoints bind to the exact original records and ordering, approved source path,
1241
+ Git revision and current file contents (including ignored files), repository scope,
1242
+ model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
1243
+ inputs cause a new review rather than reusing a decision. Source changes during
1244
+ review stop that attempt before group writes; restart with the same ID to review
1245
+ the changed source. Original findings, never prior rationales or merged findings,
1246
+ are supplied to later independent reviews. Source snapshots do not follow directory
1247
+ links outside the approved checkout.
1248
+
1249
+ Before posting groups, the workflow saves the exact final result and write payload.
1250
+ If posting fails or its acknowledgement is lost, rerunning dedupe replays that
1251
+ payload without looking up candidates or running models. Group persistence reuses
1252
+ the existing membership identity, so replay does not create another group. The
1253
+ dedupe stage completes only after acknowledgement. Empty results are also retained.
1254
+ A completed workflow or pending write represents its already reviewed snapshot;
1255
+ use another workflow ID for a fresh review rather than changing that saved result.
1256
+
1257
+ ### Deduplication workflow
1258
+
1259
+ 1. For each distinct finding ID in the scan, request
1260
+ `/v1/finding/{id}/potential-duplicates` with the selected repository or
1261
+ explicit all-repository scope. Use the complete stored anchor and
1262
+ candidates returned by that request.
1263
+ 2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1264
+ effort. The review covers every anchor-neighbor pair; nominations between
1265
+ neighbors are rejected.
1266
+ 3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
1267
+ reasoning effort. Only accepted pairs contribute to duplicate groups.
1268
+ 4. Group connected findings deterministically, treating accepted duplicate
1269
+ pairs as transitive: if A matches B and B matches C, all three belong to one
1270
+ group. There is no additional whole-group review. A mistaken accepted pair
1271
+ can therefore join otherwise distinct findings.
1272
+ 5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
1273
+ only after the service accepts the write. An empty result requires no write.
1274
+
1275
+ Each review uses a fresh, ephemeral Codex app-server thread with the complete
1276
+ original finding records, not earlier model rationales, vector scores, or
1277
+ summaries. Reviews can inspect source in the saved scan's local checkout,
1278
+ starting with cited paths and revisions. Source inspection establishes duplicate
1279
+ identity and shared remediation. Reviews preserve the originals' severity and
1280
+ priority metadata without reassessment or normalization. The baseline
1281
+ filesystem profile is read-only and excludes credentials
1282
+ and Codex state. Screening denies approval requests; final reviews use Codex's
1283
+ automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
1284
+ Finding content never authorizes access to another target.
1285
+
1286
+ Decisions must arrive through the direct `review_validator.submit_decisions`
1287
+ tool; invalid submissions can be corrected in the same session. A final text
1288
+ answer alone is insufficient. Every `SAME` decision, including screening
1289
+ nominations, requires an assigned `canonicalFindingId` and a generated,
1290
+ inclusive `mergedFinding`; missing or null values are rejected. Screening
1291
+ canonicals must belong to the nominated pair. Sol reviews use only the complete
1292
+ originals, never earlier merged findings. These review fields do not change
1293
+ the command's ID-only result or stored findings.
1294
+
1295
+ Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
1296
+ `OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
1297
+ credentials are not sent to the findings API. Larger scans can take time and
1298
+ incur multiple model calls per finding. Empty scans and findings without
1299
+ eligible neighbors do not invoke review models. `completed` means this
1300
+ retrieval, review, and group persistence completed, not that every possible pair in the
1301
+ database was compared or that model decisions are infallible. An API, review, or write-back
1302
+ failure fails the command without claiming a completed result. Retry after
1303
+ fixing the failure; stored findings remain unchanged. A lost write-back response
1304
+ may have committed groups; retrying the same memberships does not duplicate
1305
+ them. Failed or interrupted reviews write no groups. The CLI supports Ctrl-C
1306
+ and SIGTERM, and the SDK accepts an `AbortSignal`.
1307
+
1308
+ ### Listing and errors
1309
+
1310
+ Listing defaults to `limit=50` and `offset=0`; `limit` must be a positive
1311
+ integer and `offset` a non-negative integer. Records are ordered by their first
1312
+ insertion time, then finding ID. Follow `nextOffset` until it is `null`:
1313
+
1314
+ ```json
1315
+ {
1316
+ "findings": [],
1317
+ "limit": 50,
1318
+ "offset": 0,
1319
+ "total": 0,
1320
+ "nextOffset": null
1321
+ }
1322
+ ```
1323
+
1324
+ The list includes API imports and complete finding documents from existing CLI
1325
+ scan history. It returns the latest stored document for each finding ID,
1326
+ without embedding vectors. Legacy identities without a complete document are
1327
+ not included. Pagination reflects current database contents, not a snapshot
1328
+ held between HTTP requests.
1329
+
1330
+ Malformed JSON, invalid finding objects, repository metadata, groups, scopes, and pagination return HTTP
1331
+ 400 (`invalid_request`). Identity conflicts or missing dedupe group members return 409 (`finding_conflict`),
1332
+ embedding provider failures or unusable vectors return 502 (`embedding_failed`),
1333
+ and missing embedding credentials return 503 (`embedding_unavailable`). A
1334
+ potential-duplicates query without a current embedding returns 404
1335
+ (`finding_not_indexed`), including findings outside the requested repository or
1336
+ whose embedding was invalidated by an update; import the finding with the
1337
+ matching `repositoryId` before retrying. This is an error, not an
1338
+ empty candidate list. Unknown routes return 404 (`not_found`); unexpected
1339
+ server failures return 500 (`internal_error`). Errors have an `error` code and,
1340
+ for expected failures, a `message`. Request bodies and provider error bodies
1341
+ are not logged.
1342
+
1343
+ ### Embeddings and storage
1344
+
1345
+ Set `OPENAI_API_KEY` in the repository-root `.env`, using `.env.example` as a
1346
+ template, or export `OPENAI_API_KEY` or `CODEX_API_KEY` in the host environment.
1347
+ Compose passes the key to the service; exported values override `.env` values.
1348
+ The `.env` file is excluded from Git and Docker builds. `OPENAI_API_KEY` takes
1349
+ precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
1350
+ `CODEX_API_KEY` instead. Listing and empty imports do not require a key.
1351
+ A Codex ChatGPT login is not an embedding API credential.
1352
+
1353
+ The service calls the OpenAI embeddings API with `text-embedding-3-large` and
1354
+ 1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
1355
+ bundled `cl100k_base` encoding. Long inputs are split without truncation;
1356
+ their vectors are combined by token weight and normalized. Requests respect
1357
+ the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.
1358
+ See the [embedding API contract](https://developers.openai.com/api/reference/resources/embeddings/methods/create).
1359
+
1360
+ Storage initializes before the server listens. The SQLite adapter reuses the
1361
+ bundled workbench's schema and migrations at
1362
+ `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. An append-only migration adds
1363
+ complete finding documents and an embedding table, while retaining the existing
1364
+ finding identity table and scan history. Both the API and current CLI indexing
1365
+ use the same finding upsert operation. Changing a stored document invalidates
1366
+ its old embedding so later matching cannot use a stale vector. Historical
1367
+ findings are not automatically embedded; submit them to a bulk endpoint first.
1368
+
1369
+ The `findings-state` named volume persists `/state`, including the database,
1370
+ across container replacements. Keep the same Compose project name to reuse it.
1371
+ The image runs as UID/GID `10001:10001`; a bind mount must be writable by that
1372
+ UID/GID if used instead of the named volume.
1373
+
1374
+ Stop the service with
1375
+ `docker compose -f compose.findings.yaml down`; add `--volumes` only when you
1376
+ intend to delete the stored data.
1377
+
1378
+ The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
1379
+ `CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
1380
+ changing these settings. Compose binds only to host loopback; the API has no
1381
+ authentication. Use an authenticated TLS proxy before sharing access. Finding
1382
+ JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and
1383
+ generated embeddings stay in the local volume.
1384
+
1385
+ ### Upgrades and backups
1386
+
1387
+ Read the release notes and stop the service before backing up the entire
1388
+ `/state` directory. For the published-image Compose configuration:
1389
+
1390
+ ```bash
1391
+ docker compose -f compose.findings.yaml stop findings
1392
+ mkdir -p backups
1393
+ chmod 700 backups
1394
+ docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \
1395
+ --entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz
1396
+ chmod 600 backups/findings-state.tgz
1397
+ ```
1398
+
1399
+ Keep backups separately; this command overwrites an existing backup of the same
1400
+ name. Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest and repeat
1401
+ the pull/start commands above, retaining the volume. Startup applies SQLite
1402
+ migrations automatically. To roll back, stop the service, restore the pre-upgrade
1403
+ backup, and select the previous image digest; an older image may not support the
1404
+ migrated database.
1405
+
1406
+ ### Running without Docker
1407
+
1408
+ With Node.js and Python 3 installed:
1409
+
1410
+ ```bash
1411
+ npm install -g @openai/codex-security
1412
+ CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000
1413
+ ```
1414
+
1415
+ `--port` overrides `PORT` (default: `3000`). Open
1416
+ `http://127.0.0.1:3000/dashboard`. Stop with Ctrl+C or SIGTERM.
1417
+
1418
+ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
1419
+ Startup and listing need no key. The service does not load `.env` or authenticate
1420
+ requests; keep it on loopback or behind an authenticated TLS proxy.
1421
+
1422
+ From a source checkout's `sdk/typescript` directory:
1423
+
1424
+ ```bash
1425
+ pnpm install --frozen-lockfile
1426
+ npm ci --prefix ../../plugins/codex-security/mcp-app
1427
+ pnpm run build:plugin
1428
+ pnpm run build
1429
+ node bin/codex-security.mjs serve --port 3000
1430
+ ```
1431
+
1432
+ `pnpm run start:server` and `node dist/server/index.js` still work.
1433
+
1434
+ Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
1435
+ `CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
1436
+ without a state override, the service uses the same default state directory as
1437
+ the CLI. These settings also work on Windows.
1438
+
1439
+ HTTP routing, orchestration, embedding generation, and the SQLite adapter live
1440
+ separately under `src/server/`. `FindingsService` receives a `FindingEmbedder`
1441
+ whose `embed(findings)` method returns one `{ model, vector }` per finding in
1442
+ input order. `OpenAiFindingEmbedder` handles tokenization, batching, API calls,
1443
+ and vector normalization; it does not access storage. The `FindingsStore`
1444
+ interface stores findings and vectors and exposes
1445
+ `findPotentialDuplicates(findingId, scope)`. Repository filtering, vector ranking,
1446
+ and fetching selected documents stay inside the store implementation; replacing
1447
+ SQLite with an indexed store does not change the service or SDK/CLI. Repository
1448
+ associations are stored separately from finding documents, with an append-only
1449
+ migration that also imports known associations from stored scan occurrences.
1450
+ New scan findings retain their target associations when indexed locally.
1451
+ The server entrypoint selects the concrete
1452
+ embedder and store, so either can be replaced independently.
1453
+ The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
1454
+ receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
1455
+ separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
1456
+ and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
1457
+ `deduplicateScan` validates saved scan artifacts before running the workflow.
1458
+ The SDK reuses the existing Codex runtime and credentials without additional
1459
+ runtime dependencies.
1460
+
913
1461
  ## Containerized bulk scans
914
1462
 
915
1463
  Create `repositories.csv` as described under [Bulk scans](#bulk-scans).
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.60",
3
+ "version": "0.1.79",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -14,6 +14,7 @@
14
14
  "CODEX_ELECTRON_RESOURCES_PATH",
15
15
  "CODEX_MANAGED_PACKAGE_ROOT",
16
16
  "CODEX_MCP_NODE_PATH",
17
+ "OPENAI_API_KEY",
17
18
  "OPENROUTER_API_KEY",
18
19
  "FIREWORKS_API_KEY",
19
20
  "AWS_BEARER_TOKEN_BEDROCK",
@@ -72,39 +72,11 @@ After a native handoff or direct conversation start provides a `scanId`, use its
72
72
 
73
73
  For standard and diff scans, the app handoff starts preflight without an item count. After every structured helper result, call `update_codex_security_scan_progress` without changing phase and set `preflightChecks` to every entry from the helper's `results` array, projecting each entry to only `capability`, `reason`, `severity`, and `status`. Do not send `phaseItemsTotal`, `phaseItemsCompleted`, or `phaseProgressUnit` with `preflightChecks`: the server derives the total from the array length, counts `pass` and `fail` as completed, excludes `unknown` from completed, and derives the visible `block` or `warn` attention items. Send the full fresh results array after a clean rerun so stale issues disappear. Do not interpret item-count completion as readiness: remain in preflight for every blocked, incomplete, or error result while remediation or retry remains pending, even when every returned check was evaluated. Only after a `ready` result has published its fresh `preflightChecks` should a separate progress call advance to `threat_model`. These counts and issues belong to the current scan rather than the legacy setup-time workspace preflight, and remain visible after the scan advances. Deep Scan preflight and discovery progress remain owned by `start_codex_security_deep_scan`.
74
74
 
75
- Continue after a `ready` result. Explain warn or suggest issues when they materially affect scan quality, capacity, or resumability, and use the documented degraded path. If the result is `blocked` or `incomplete`, follow the remediation handling below. If the helper cannot run or returns its top-level `status: "error"` envelope, report the exact blocker and retry the documented recovery path when possible. Do not call `fail_codex_security_scan` merely because the helper is temporarily unavailable or errors; leave the durable scan running and hand off for a later retry while recovery may still be possible.
76
-
77
- When blocked or incomplete preflight includes actionable remediation, first classify the current session before choosing a remediation control. Treat `codex exec`, headless runs, automation runs, and any host that cannot actually pause for a human reply as non-interactive even if `request_user_input` or `request_codex_security_user_input` is named in this document or appears callable. In a non-interactive session, never call either user-input tool and never fall back to a chat question; go directly to the automatic-remediation path below. Only after the session is confirmed interactive, present the exact reasons and config delta in the Codex thread and optimistically call the native `request_user_input` tool so the paused scan is visibly waiting for the user's decision instead of asking only in plain chat prose:
78
-
79
- ```text
80
- request_user_input(
81
- questions=[
82
- {
83
- "header": "Preflight?",
84
- "id": "apply_preflight_remediation",
85
- "question": "Apply the recommended remediation and retry the preflight?",
86
- "options": [
87
- {
88
- "label": "Apply and retry (Recommended)",
89
- "description": "Apply the approved remediation, then rerun the capability preflight."
90
- },
91
- {
92
- "label": "Leave paused",
93
- "description": "Keep the scan running for a later retry without changing configuration."
94
- },
95
- {
96
- "label": "Cancel scan",
97
- "description": "Cancel this scan without applying the remediation."
98
- }
99
- ]
100
- }
101
- ]
102
- )
103
- ```
75
+ Continue only after a `ready` result. Explain material warnings and use the documented degraded path. For a blocked, incomplete, or error result, report the exact reason and preserve any durable running scan while recovery remains possible; do not review source or start workers early.
104
76
 
105
77
  Do not set `autoResolutionMs`; in an interactive session, an explicit answer is required before persistent configuration changes or scan continuation. If native `request_user_input` is unavailable or errors, call `request_codex_security_user_input` with the same `questions` payload. This MCP fallback is interactive and must remain prohibited in non-interactive sessions. If it returns `accepted`, follow its answer. If it is unavailable or errors, ask the same choices in chat. If it returns `declined` or `cancelled`, do not infer a choice; preserve the running scan, stop, and state that an explicit answer is still required. In every interactive waiting case, stop for the user's answer before creating or adopting a scan goal. Do not call `fail_codex_security_scan` while waiting for that answer. Apply only the approved remediation after `Apply and retry`, preserve the running scan and stop after `Leave paused`, and call `cancel_codex_security_scan` after `Cancel scan`.
106
78
 
107
- In a non-interactive Codex session, do not leave the run waiting for an answer it cannot receive. After showing the exact blocker and config delta, automatically apply only the helper's concrete Codex config patches with ordinary `value` or `remove` operations to the active writable user config, preserving unrelated settings. Never automatically apply `host_setting` remediation or invent a patch. Rerun the same preflight once with the same verified runtime facts and any newly observable effective config. Continue only after that rerun returns `ready`; do not create or adopt scan goals or start substantive scan work earlier. If the new config needs a fresh session before the active runtime can use it, the rerun remains blocked or incomplete, remediation is unavailable, or the helper errors, do not loop, call `fail_codex_security_scan`, or cancel automatically. Preserve an app-generated durable scan and hand it off for a later retry; in CLI or another host without a durable scan, report the exact remaining blocker and end without claiming that a scan is paused.
79
+ In a non-interactive session, never request user input. Automatically apply only the helper's concrete `value` or `remove` patches to its writable `user_config_path`, preserving unrelated settings; never apply `host_setting` patches automatically. Rerun once with the same verified runtime facts and continue only if the result is `ready`. If remediation is unavailable, needs a new session, remains blocked, or errors, report the blocker without looping, canceling, or marking the scan failed; preserve a durable scan for later continuation.
108
80
 
109
81
  For any non-ready result, do not fail automatically. If an interactive chat fallback declines required remediation without choosing whether to cancel or leave the scan running, ask that follow-up before taking either action. If remediation is unavailable, the helper cannot run, the helper returns an error envelope, or a rerun remains blocked or incomplete, preserve a durable running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` with the exact reasons only after the documented recovery path is exhausted and the blocker is confirmed unrecoverable. When the user explicitly cancels, call `cancel_codex_security_scan`.
110
82
 
@@ -11,7 +11,7 @@ Perform one complete, evidence-backed security audit of the exact supplied repos
11
11
  5. Launch focused investigator subagents with `fork_turns: "none"` as soon as useful packet groups exist. Choose their number and assignments from the amount, complexity, and independence of source-backed work, bounded by the supplied available subagent allowance; use fewer for related packets and more only when distinct surfaces justify them. Keep mapping other surfaces while they run. Send each only its focused-investigator prompt below, assigned packets, investigator perspective, repository path, authorized scope, any supplied scoped-source inventory, exact user context, supplied threat model, applicable packet-specific security guidance and its resolver command, the optional authoritative knowledge-base location, and verified search command. Do not include this reference or another worker's prompt. Supporting code may be outside a requested path, but an affected entry point, control, or operation must be in scope.
12
12
  6. Before combining or revalidating any returned baseline or investigator result, persist it through the caller's bound `record_codex_security_scan_draft` tool when available, using `complete: false` and partial coverage. Give each candidate a stable `candidateId`; put candidates awaiting parent validation in `coverage.deferred` with a meaningful reason and their original finding payload under `candidate`. Preserve returned counterevidence and unresolved questions too. Checkpoint again after each validation decision, without waiting for other workers or the final report. Put source-validated findings in `findings` with the same `provenance.candidateId`; for a rejection, retain the candidate ID, original evidence, and source-backed counterevidence on a `rejected` coverage surface. An unfinished scan must retain its saved findings and pending candidates without presenting pending work as validated. Reconcile source coverage before combining findings. Union only the baseline and focused investigators' `fully_reviewed_files` with files the parent fully security-audited, then intersect that set with the supplied authorized inventory or an inventory of the selected current scope. Architecture mapping alone and supporting files outside that inventory do not count toward completed audit coverage. Finish the remaining in-scope files in coherent groups, reusing available investigators within the same allowance. Inspect implementation-owning generated or compressed code as data. Do not add overlapping worker counts or claim that a search hit completed a file. Keep this one transient set; do not create a separate progress ledger or receipt format. If a user limit or unavailable source prevents completion, identify the actual remaining paths and report partial coverage. Then combine baseline and investigator findings once. Group observations only when they share the same broken security control and effective remediation; preserve every affected route, operation, sink, and supporting source location. Never merge different security failures solely because they share a CWE.
13
13
  7. Independently validate each unique finding against local source once. Establish its attacker, entry point, trust boundary, attacker-controlled dataflow, transformations, broken control, sensitive operation, prerequisites, effective mitigations, strongest counterevidence, and concrete impact. Record concise, source-backed `rootCause.summary`, `validation.summary`, `attackPath.dataflow.summary`, and `attackPath.reachability.summary` alongside their supporting facts; determine impact, likelihood, and severity from those established facts. State optional configuration, dependency-version, or deployment prerequisites; do not require proof of a real deployment or runtime reproduction. A public library or parser boundary is sufficient when callers control the input. Reject only with source-backed counterevidence, preserve valid baseline findings, record material unresolved proof gaps, and apply the severity rules below.
14
- 8. Assemble complete semantic `scope`, `threatModel`, `findings`, and `coverage` using the plugin's `examples/completed-scan/` and `schemas/` as shape references, never as values to copy. Use the canonical field mapping and scenario reconciliation in `threat-model.md`, preserving supplied models unchanged and retaining source-backed architecture, capability, deployment, and uncertainty facts. Give each finding a stable lowercase vulnerability-family `ruleId`, its precise `taxonomy.category` and `taxonomy.cwe` values, genuine `provenance.source`, an instance when separately reported findings would otherwise collide, a `root_control` location when identifiable, all materially affected locations, calibrated severity and rationale, confidence and rationale, verified nonempty source evidence, attacker-to-sink reachability, and practical remediation. Use actual coverage surface labels and dispositions; report reviewed surfaces, explicit exclusions, deferred work, and unresolved questions honestly, and mark coverage `complete` only when the requested source scope was actually reviewed. Preserve every genuine finding, evidence item, user-supplied assumption, and unresolved proof gap in the caller's complete semantic result.
14
+ 8. Assemble complete semantic `scope`, `threatModel`, `findings`, and `coverage` using the plugin's `examples/completed-scan/` and `schemas/` as shape references, never as values to copy. Use the canonical field mapping and scenario reconciliation in `threat-model.md`, preserving supplied models unchanged and retaining source-backed architecture, capability, deployment, and uncertainty facts. Give each finding a stable lowercase vulnerability-family `ruleId`, its precise `taxonomy.category` and `taxonomy.cwe` values, genuine `provenance.source`, an instance when separately reported findings would otherwise collide, a `root_control` location when identifiable, all materially affected locations, calibrated severity and rationale, confidence and rationale, verified nonempty source evidence, attacker-to-sink reachability, and practical remediation. Write source evidence as `codeEvidence` entries with required `id`, `label`, `path`, `startLine`, `code`, and `explanation` fields; `endLine`, `language`, and `role` are optional. Use `code`, never `snippet`, and write new root-cause details as `rootCause`, never `root_cause`. Follow `finding-detail-fields.md` when constructing rich finding details. Use actual coverage surface labels and dispositions; report reviewed surfaces, explicit exclusions, deferred work, and unresolved questions honestly, and mark coverage `complete` only when the requested source scope was actually reviewed. Preserve every genuine finding, evidence item, user-supplied assumption, and unresolved proof gap in the caller's complete semantic result.
15
15
 
16
16
  Keep discovery, validation, and attack-path reasoning within this one self-contained audit; do not invoke separate phase skills. Do not create ranking phases, per-file or per-candidate ledgers, separate phase worker pools, repeated phase reports, or receipt files.
17
17