@openai/codex-security 0.1.21 → 0.1.23

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 (157) hide show
  1. package/README.md +529 -0
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/references/config-preflight.md +2 -30
  6. package/_bundled_plugin/references/core-scan.md +1 -1
  7. package/_bundled_plugin/references/final-report.md +1 -1
  8. package/_bundled_plugin/references/finding-detail-fields.md +5 -10
  9. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  10. package/_bundled_plugin/scripts/config_preflight.py +2 -8
  11. package/_bundled_plugin/scripts/finalize_scan_contract.py +114 -24
  12. package/_bundled_plugin/scripts/finding_preview.py +22 -4
  13. package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -1
  14. package/_bundled_plugin/scripts/windows_scan_local_files.py +101 -7
  15. package/_bundled_plugin/scripts/workbench_cli.py +21 -1
  16. package/_bundled_plugin/scripts/workbench_dashboard.py +115 -0
  17. package/_bundled_plugin/scripts/workbench_db.py +29 -2
  18. package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
  19. package/_bundled_plugin/scripts/workbench_finding_workflows.py +190 -0
  20. package/_bundled_plugin/scripts/workbench_findings.py +216 -0
  21. package/_bundled_plugin/scripts/workbench_saved_results.py +30 -5
  22. package/_bundled_plugin/scripts/workbench_schema.py +263 -58
  23. package/_bundled_plugin/scripts/workbench_target.py +22 -3
  24. package/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
  25. package/dist/api.d.ts +2 -0
  26. package/dist/api.d.ts.map +1 -1
  27. package/dist/api.js +115 -27
  28. package/dist/api.js.map +1 -1
  29. package/dist/cli.d.ts +4 -0
  30. package/dist/cli.d.ts.map +1 -1
  31. package/dist/cli.js +124 -58
  32. package/dist/cli.js.map +1 -1
  33. package/dist/cloud-publish.js +5 -1
  34. package/dist/cloud-publish.js.map +1 -1
  35. package/dist/contract.d.ts +1 -0
  36. package/dist/contract.d.ts.map +1 -1
  37. package/dist/contract.js +9 -0
  38. package/dist/contract.js.map +1 -1
  39. package/dist/custom-publish.d.ts +22 -0
  40. package/dist/custom-publish.d.ts.map +1 -0
  41. package/dist/custom-publish.js +47 -0
  42. package/dist/custom-publish.js.map +1 -0
  43. package/dist/custom-validation-prompt.js +1 -1
  44. package/dist/custom-validation-prompt.js.map +1 -1
  45. package/dist/deduplication/checkpointed-review.d.ts +16 -0
  46. package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
  47. package/dist/deduplication/checkpointed-review.js +76 -0
  48. package/dist/deduplication/checkpointed-review.js.map +1 -0
  49. package/dist/deduplication/codex-review.d.ts +21 -0
  50. package/dist/deduplication/codex-review.d.ts.map +1 -0
  51. package/dist/deduplication/codex-review.js +252 -0
  52. package/dist/deduplication/codex-review.js.map +1 -0
  53. package/dist/deduplication/deduplication-prompts.d.ts +8 -0
  54. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
  55. package/dist/deduplication/deduplication-prompts.js +35 -0
  56. package/dist/deduplication/deduplication-prompts.js.map +1 -0
  57. package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
  58. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
  59. package/dist/deduplication/deduplication-reviewer.js +105 -0
  60. package/dist/deduplication/deduplication-reviewer.js.map +1 -0
  61. package/dist/deduplication/deduplication.d.ts +6 -0
  62. package/dist/deduplication/deduplication.d.ts.map +1 -0
  63. package/dist/deduplication/deduplication.js +85 -0
  64. package/dist/deduplication/deduplication.js.map +1 -0
  65. package/dist/deduplication/scan.d.ts +16 -0
  66. package/dist/deduplication/scan.d.ts.map +1 -0
  67. package/dist/deduplication/scan.js +101 -0
  68. package/dist/deduplication/scan.js.map +1 -0
  69. package/dist/finding-dedupe-groups.d.ts +7 -0
  70. package/dist/finding-dedupe-groups.d.ts.map +1 -0
  71. package/dist/finding-dedupe-groups.js +2 -0
  72. package/dist/finding-dedupe-groups.js.map +1 -0
  73. package/dist/finding-retrieval.d.ts +13 -0
  74. package/dist/finding-retrieval.d.ts.map +1 -0
  75. package/dist/finding-retrieval.js +2 -0
  76. package/dist/finding-retrieval.js.map +1 -0
  77. package/dist/finding-workflow.d.ts +53 -0
  78. package/dist/finding-workflow.d.ts.map +1 -0
  79. package/dist/finding-workflow.js +117 -0
  80. package/dist/finding-workflow.js.map +1 -0
  81. package/dist/findings-client.d.ts +15 -0
  82. package/dist/findings-client.d.ts.map +1 -0
  83. package/dist/findings-client.js +60 -0
  84. package/dist/findings-client.js.map +1 -0
  85. package/dist/index.d.ts +4 -0
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +2 -0
  88. package/dist/index.js.map +1 -1
  89. package/dist/publication.js +28 -40
  90. package/dist/publication.js.map +1 -1
  91. package/dist/runtime.d.ts +5 -1
  92. package/dist/runtime.d.ts.map +1 -1
  93. package/dist/runtime.js +113 -12
  94. package/dist/runtime.js.map +1 -1
  95. package/dist/saved-scan.d.ts +15 -0
  96. package/dist/saved-scan.d.ts.map +1 -0
  97. package/dist/saved-scan.js +68 -0
  98. package/dist/saved-scan.js.map +1 -0
  99. package/dist/scan-comparison.d.ts +3 -2
  100. package/dist/scan-comparison.d.ts.map +1 -1
  101. package/dist/scan-comparison.js +1 -1
  102. package/dist/scan-comparison.js.map +1 -1
  103. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
  104. package/dist/server/dashboard/app.css +2 -0
  105. package/dist/server/dashboard/app.js +66 -0
  106. package/dist/server/dashboard/index.html +18 -0
  107. package/dist/server/dashboard-types.d.ts +45 -0
  108. package/dist/server/dashboard-types.d.ts.map +1 -0
  109. package/dist/server/dashboard-types.js +2 -0
  110. package/dist/server/dashboard-types.js.map +1 -0
  111. package/dist/server/dashboard.d.ts +6 -0
  112. package/dist/server/dashboard.d.ts.map +1 -0
  113. package/dist/server/dashboard.js +45 -0
  114. package/dist/server/dashboard.js.map +1 -0
  115. package/dist/server/embeddings.d.ts +16 -0
  116. package/dist/server/embeddings.d.ts.map +1 -0
  117. package/dist/server/embeddings.js +114 -0
  118. package/dist/server/embeddings.js.map +1 -0
  119. package/dist/server/errors.d.ts +5 -0
  120. package/dist/server/errors.d.ts.map +1 -0
  121. package/dist/server/errors.js +8 -0
  122. package/dist/server/errors.js.map +1 -0
  123. package/dist/server/findings-service.d.ts +20 -0
  124. package/dist/server/findings-service.d.ts.map +1 -0
  125. package/dist/server/findings-service.js +31 -0
  126. package/dist/server/findings-service.js.map +1 -0
  127. package/dist/server/index.d.ts +2 -0
  128. package/dist/server/index.d.ts.map +1 -0
  129. package/dist/server/index.js +32 -0
  130. package/dist/server/index.js.map +1 -0
  131. package/dist/server/routes.d.ts +6 -0
  132. package/dist/server/routes.d.ts.map +1 -0
  133. package/dist/server/routes.js +86 -0
  134. package/dist/server/routes.js.map +1 -0
  135. package/dist/server/server.d.ts +10 -0
  136. package/dist/server/server.d.ts.map +1 -0
  137. package/dist/server/server.js +17 -0
  138. package/dist/server/server.js.map +1 -0
  139. package/dist/server/sqlite-store.d.ts +22 -0
  140. package/dist/server/sqlite-store.d.ts.map +1 -0
  141. package/dist/server/sqlite-store.js +82 -0
  142. package/dist/server/sqlite-store.js.map +1 -0
  143. package/dist/server/storage.d.ts +32 -0
  144. package/dist/server/storage.d.ts.map +1 -0
  145. package/dist/server/storage.js +2 -0
  146. package/dist/server/storage.js.map +1 -0
  147. package/dist/server/validation.d.ts +17 -0
  148. package/dist/server/validation.d.ts.map +1 -0
  149. package/dist/server/validation.js +53 -0
  150. package/dist/server/validation.js.map +1 -0
  151. package/dist/trusted-executable.d.ts.map +1 -1
  152. package/dist/trusted-executable.js +2 -1
  153. package/dist/trusted-executable.js.map +1 -1
  154. package/dist/version.d.ts +1 -1
  155. package/dist/version.js +1 -1
  156. package/dist/version.js.map +1 -1
  157. package/package.json +17 -5
package/README.md CHANGED
@@ -910,6 +910,535 @@ command manifest, `scan --schema --format json` for a command schema, and
910
910
  MCP exposes only the read-only `info` command because the transport cannot
911
911
  cancel active scans.
912
912
 
913
+ ## Findings service (preview)
914
+
915
+ The findings API uses the same `ghcr.io/openai/codex-security` image as the
916
+ scanner, for Linux `amd64` and `arm64`. `compose.findings.yaml` starts the API
917
+ in a separate container with its own state volume and server configuration.
918
+ Once a release is published, it can be pulled without a GitHub login. See
919
+ [container release setup](../../docker/README.md) for the required maintainer
920
+ setup and publication process.
921
+
922
+ From the repository root, copy the example if you do not already have a `.env`:
923
+
924
+ ```bash
925
+ cp .env.example .env
926
+ ```
927
+
928
+ Set `OPENAI_API_KEY` in `.env`, then pull and start the findings API:
929
+
930
+ ```bash
931
+ docker compose -f compose.findings.yaml pull
932
+ docker compose -f compose.findings.yaml up --no-build -d
933
+ curl -i http://127.0.0.1:3000/v1/findings
934
+ ```
935
+
936
+ You can deploy with just `compose.findings.yaml` and a private `.env`; no source
937
+ checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
938
+ defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
939
+ version, `sha-<commit>` tag, or digest for repeatable deployments.
940
+
941
+ To build from a source checkout instead:
942
+
943
+ ```bash
944
+ docker build --target scanner -t codex-security:local .
945
+ export CODEX_SECURITY_FINDINGS_IMAGE=codex-security:local
946
+ docker compose -f compose.findings.yaml up --no-build -d
947
+ ```
948
+
949
+ For an existing deployment using the separate findings image or
950
+ `--target findings-service`, follow the [single-image migration guide](../../docker/README.md#migrating-the-findings-service).
951
+
952
+ ### Read-only dashboard
953
+
954
+ Open `http://localhost:3000/dashboard` on the running findings service. The UI
955
+ uses the public OpenAI Apps SDK UI design system, follows the browser's light
956
+ or dark preference, and polls the service every five seconds. It never starts,
957
+ cancels, resumes, publishes, edits, or deduplicates anything.
958
+
959
+ The dashboard opens on Findings, followed by Duplicate groups. Both views
960
+ support search, repository filtering, sorting, pagination, and record details.
961
+ Findings show stored content and links to their duplicate groups. Groups link
962
+ back to their member findings, preserving separate overlapping groups and the
963
+ original finding records.
964
+
965
+ The dashboard reads only findings, repository associations, and duplicate groups
966
+ stored in the service's configured database. It does not display scans or
967
+ workflows: publication sends findings, not remote scan or workflow history. It
968
+ does not read report or source paths from stored records. The UI retains the last
969
+ successful data on a refresh failure and shows a connection warning until polling
970
+ succeeds.
971
+
972
+ `GET /v1/dashboard` returns a consistent read snapshot with overview counts,
973
+ repository choices, a page of records, and optional selected-record details:
974
+
975
+ - `view`: `findings` (default) or `groups`.
976
+ - `query`, `repository`: optional search text and exact repository ID.
977
+ - `sort`: `activity` (default; most recently updated first) or `newest`.
978
+ - `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
979
+ - `id`: optional exact record ID to include in `detail`; unknown IDs return
980
+ `detail: null` without hiding the list.
981
+
982
+ Overview counts are service-wide, not filtered page totals. Responses and UI
983
+ assets are served by the same Node process; no separate frontend server, CDN,
984
+ model credentials, or new CLI flags are needed to view the dashboard. Compiled
985
+ HTML, JavaScript, and CSS are included in the npm package and container. Frontend
986
+ source, build tools, and tests are not shipped as runtime dependencies.
987
+
988
+ The existing preview access boundary is unchanged. The dashboard contains
989
+ sensitive finding content: keep the service on a trusted local endpoint or behind
990
+ an authenticated proxy. It does not add authentication or broaden the default
991
+ network binding.
992
+
993
+ ### API
994
+
995
+ `POST /v1/bulk/findings` accepts `{"findings": [...]}`, using the existing SDK
996
+ `Finding` model, including `findingId`, `occurrenceId`, and `fingerprints`.
997
+ A complete exported `findings.json` document is also accepted; only its
998
+ `findings` array is imported. No files or source paths referenced by the
999
+ findings are opened. Only the supplied JSON is processed.
1000
+
1001
+ Include `repositoryId` alongside `findings` to associate every imported finding
1002
+ with a repository. For SDK/CLI scans, use `scan.target.targetId` from the sealed
1003
+ `scan-manifest.json`. IDs are matched exactly; the service does not infer a
1004
+ repository from titles, paths, or URLs. Reimports add associations without
1005
+ removing earlier ones, so a finding can belong to more than one repository.
1006
+ Imports without this metadata remain accepted, but unassociated findings are
1007
+ only available to explicit all-repository retrieval until imported with an ID.
1008
+
1009
+ | Method | Path | Response |
1010
+ | ------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
1011
+ | `POST` | `/v1/bulk/findings` | HTTP 201 with an array of stored finding IDs, in request order |
1012
+ | `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200 with a page of complete findings |
1013
+ | `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200 with the stored finding and up to 50 potential duplicates, without vectors |
1014
+ | `POST` | `/v1/dedupe-groups` | HTTP 201 with the persisted duplicate groups |
1015
+ | `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200 with every stored group containing this finding |
1016
+
1017
+ Bulk insertion generates embeddings and then writes the findings and vectors
1018
+ in one SQLite transaction. If embedding generation fails or a finding identity
1019
+ conflicts with another stored identity, no part of the batch is written.
1020
+ Reusing a `findingId` updates that finding and replaces its embedding; retries
1021
+ do not create extra rows. An existing ID's fingerprint, rule, and identity
1022
+ anchor/instance cannot be replaced. Repeated IDs in one request are applied in order,
1023
+ with the last supplied record retained. Stored scan occurrences are unchanged.
1024
+
1025
+ For example, add `repositoryId` to a copy of an exported findings document
1026
+ saved as `findings-import.json` (leave the sealed scan artifacts unchanged),
1027
+ then import it with the API key configured before starting Compose:
1028
+
1029
+ ```bash
1030
+ curl http://127.0.0.1:3000/v1/bulk/findings \
1031
+ -H 'Content-Type: application/json' \
1032
+ --data-binary @findings-import.json
1033
+ ```
1034
+
1035
+ ```json
1036
+ ["csf_852f90d6e1177502ff113d4a"]
1037
+ ```
1038
+
1039
+ The potential-duplicates response contains `finding` (the complete stored
1040
+ anchor) and `potentialDuplicates` (an array of complete `Finding` records).
1041
+ Neither includes embedding vectors. The anchor is not repeated in the array.
1042
+ Specify one scope explicitly on the request:
1043
+
1044
+ ```text
1045
+ GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example
1046
+ GET /v1/finding/{id}/potential-duplicates?allRepositories=true
1047
+ ```
1048
+
1049
+ Repository scope requires the anchor and each candidate to be associated with
1050
+ that repository. All-repository scope includes tagged and untagged findings.
1051
+ Omitting scope or combining a repository with `allRepositories=true` returns
1052
+ HTTP 400. Scope selects candidates; it is not an authorization boundary.
1053
+
1054
+ Candidates have cosine similarity at least 0.55 and the same embedding model
1055
+ and dimensions as the anchor. They are ordered by descending similarity, with
1056
+ ties resolved by insertion time and finding ID, and limited to 50. Each request
1057
+ reads a current snapshot; separate requests do not share a database snapshot.
1058
+ SQLite first filters repository associations, reads only IDs and embedding
1059
+ vectors (plus the anchor's model), and performs exact cosine ranking. It then
1060
+ loads complete documents only for the anchor and the selected top 50 candidates,
1061
+ all within the same read transaction.
1062
+ The API does not run Codex or decide whether candidates are duplicates.
1063
+
1064
+ ### Publishing to a custom findings service
1065
+
1066
+ Publish a completed scan directly from the local CLI to the Docker service:
1067
+
1068
+ ```bash
1069
+ codex-security publish scan --scan SCAN_ID --to custom \
1070
+ --findings-url http://localhost:3000 --json
1071
+ ```
1072
+
1073
+ `--findings-url` is required for `--to custom`, with no default. It is the
1074
+ service base URL, including `http://` or `https://`; the client appends
1075
+ `/v1/bulk/findings`, preserving any base path. A different endpoint must
1076
+ implement that API and return the stored finding IDs. The command sends the
1077
+ complete sealed findings and their manifest's `scan.target.targetId` as
1078
+ `repositoryId`, without changing scan artifacts or forwarding model credentials.
1079
+ The service creates embeddings and commits the batch before acknowledging it.
1080
+
1081
+ The existing saved-scan selector, external `--scan-dir`, and interactive picker
1082
+ work with custom publication. Custom publication accepts one scan, not CSV
1083
+ input or Linear options. Add `--dry-run` to validate and preview the payload
1084
+ without making an HTTP request. Existing Linear and Cloud destinations are
1085
+ unchanged. Upload failures and incomplete receipts fail the command; uploads
1086
+ are not automatically retried because a lost response may have been committed.
1087
+
1088
+ ```typescript
1089
+ import { publishScanToCustom } from "@openai/codex-security";
1090
+
1091
+ const receipt = await publishScanToCustom("/path/to/completed-scan", {
1092
+ findingsUrl: "http://localhost:3000",
1093
+ // dryRun: true,
1094
+ // signal: controller.signal,
1095
+ });
1096
+ console.log(receipt.repositoryId, receipt.findingIds);
1097
+ ```
1098
+
1099
+ ### Deduplication from the SDK and CLI
1100
+
1101
+ Publish the scan with `--to custom` (or import it through the bulk API with its
1102
+ `repositoryId`) before deduplicating. The
1103
+ workflow reads a completed saved scan, queries candidates by finding ID, and
1104
+ runs Luna and Sol in the calling SDK/CLI process. Once all reviews succeed,
1105
+ it posts accepted groups to the service. It does not re-upload findings or
1106
+ change scan artifacts.
1107
+
1108
+ ```bash
1109
+ codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
1110
+ ```
1111
+
1112
+ The default scope is the saved scan's repository, identified by
1113
+ `scan.target.targetId` in its manifest. Add `--all-repositories` to search the
1114
+ entire stored corpus explicitly; the flag defaults to false. The SDK has the
1115
+ equivalent optional `allRepositories: true` setting. This narrows the previous
1116
+ preview's implicit all-repository behavior.
1117
+
1118
+ Both `--scan` and `--findings-url` are required, with no implicit scan or service
1119
+ URL. As with `publish scan --scan`, the selector accepts a full ID, unique
1120
+ prefix, or `latest` for the current repository. The saved scan must be complete
1121
+ and its sealed artifacts must be available.
1122
+
1123
+ ```typescript
1124
+ import { deduplicateScan } from "@openai/codex-security";
1125
+
1126
+ const result = await deduplicateScan("scan_example_001", {
1127
+ findingsUrl: "http://127.0.0.1:3000",
1128
+ // allRepositories: true, // Omit to search only this scan's repository.
1129
+ // signal: controller.signal,
1130
+ });
1131
+ console.log(result.duplicateGroups);
1132
+ ```
1133
+
1134
+ The CLI and SDK return the same result:
1135
+
1136
+ ```json
1137
+ {
1138
+ "scanId": "scan_example_001",
1139
+ "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
1140
+ "duplicateGroups": [],
1141
+ "deduplicationStatus": "completed"
1142
+ }
1143
+ ```
1144
+
1145
+ `uniqueFindingIds` contains one representative for each selected finding after
1146
+ accepted duplicate groups are collapsed. A representative can be an existing
1147
+ stored finding outside the scan. Each `duplicateGroups` entry contains all
1148
+ members of an accepted group, with its canonical finding first. The canonical
1149
+ has the highest reported severity; ties use finding ID. Results do not delete,
1150
+ merge, or change stored finding documents. Accepted groups are saved as durable
1151
+ associations in the service before `deduplicationStatus` becomes `completed`.
1152
+
1153
+ ### Stored duplicate groups
1154
+
1155
+ `POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
1156
+
1157
+ ```json
1158
+ {
1159
+ "groups": [
1160
+ ["csf_000000000000000000000001", "csf_000000000000000000000002"],
1161
+ ["csf_000000000000000000000002", "csf_000000000000000000000003"]
1162
+ ]
1163
+ }
1164
+ ```
1165
+
1166
+ Each group must contain at least two distinct, existing finding IDs. The entire
1167
+ batch is committed in one transaction; a missing finding returns HTTP 409 and
1168
+ writes none of the batch. A response contains `groupId`, `findingIds`, and
1169
+ `createdAt` for each group. Group identity depends on membership, not member
1170
+ order, so submitting the same set again returns its original ID and timestamp.
1171
+
1172
+ SQLite stores groups in `finding_dedupe_groups` and memberships in
1173
+ `finding_dedupe_group_members`. A finding may belong to multiple groups:
1174
+ `[A, B]`, `[B, C]`, and `[C, A]` are three separate reviewed sets. Overlapping
1175
+ groups are not automatically united or promoted into an unreviewed larger
1176
+ group. Stored members are sorted by ID; their order does not designate a
1177
+ canonical. The CLI result retains its existing canonical-first ordering.
1178
+
1179
+ `GET /v1/finding/{id}/dedupe-groups` returns every group containing that finding,
1180
+ including each group's full membership, or `[]` if it has no groups. These
1181
+ associations do not rewrite original findings, fingerprints, scan artifacts,
1182
+ embeddings, or external tickets. They do not require an embedding API key or
1183
+ trigger model calls. Review-generated merged findings remain review outputs;
1184
+ they do not replace stored documents.
1185
+
1186
+ ### Resuming a local findings workflow
1187
+
1188
+ Add `--workflow-id` to opt into durable state shared by `scan`, `publish scan
1189
+ --to custom`, and `dedupe`. The SDK equivalents are the optional `workflowId`
1190
+ fields on `ScanOptions`, `PublishScanToCustomOptions`, and `DeduplicateScanOptions`.
1191
+ Without a workflow ID, existing command behavior and output shapes are unchanged.
1192
+
1193
+ ```bash
1194
+ codex-security scan /path/to/repository --workflow-id run-001
1195
+ codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000
1196
+ codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json
1197
+ ```
1198
+
1199
+ Repeat this sequence with the same ID after a process stops. Completed scans and
1200
+ acknowledged publications are reused; unfinished stages run again. If the scan
1201
+ completed before the workflow recorded its receipt, recovery verifies the saved
1202
+ scan and its sealed artifacts instead of scanning again. Scan IDs and artifact
1203
+ locations are recorded in the scan-registration transaction. This resumes between
1204
+ completed steps; it does not resume individual model turns inside an unfinished
1205
+ scan. Existing output-directory and archive safeguards still apply to scan retries.
1206
+
1207
+ Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
1208
+ scan selector must identify that same scan. A workflow can also begin at custom
1209
+ publication of a completed scan. Dedupe still requires local scan history to locate
1210
+ the approved source checkout. For a workflow, dedupe first completes publication
1211
+ if its receipt is missing. `--all-repositories` retains its existing default of
1212
+ false. Changing a workflow's scan, destination, or bound scope is an error: choose
1213
+ a different workflow ID. Use one coordinating process per workflow.
1214
+
1215
+ Workflow metadata, stage statuses, errors, publication receipts, and results live
1216
+ in the local workbench SQLite database under `CODEX_SECURITY_STATE_DIR`, outside
1217
+ the sealed scan artifacts. Identity, scan/artifact references, destination, scope,
1218
+ hashes, stage statuses, and errors use explicit columns; only receipts and result
1219
+ payloads use JSON. Review source, scope, model settings, and contract/hash bindings
1220
+ also use columns; review results remain JSON. Existing workflows and checkpoints
1221
+ are migrated atomically in place without changing their review keys.
1222
+ Successful empty results are stored as completed
1223
+ results, not treated as missing work. An empty scan can complete workflow
1224
+ publication with an empty receipt. Dry-run never advances a workflow stage.
1225
+
1226
+ A completed `dedupe --workflow-id` returns its saved result without repeating
1227
+ reviews or group writes. A publication whose acknowledgement was lost is retried
1228
+ using the service's existing idempotent upsert.
1229
+
1230
+ Each validated screening and pair review is checkpointed locally,
1231
+ including DISTINCT decisions. Every SAME checkpoint retains its required
1232
+ `canonicalFindingId` and generated `mergedFinding`. The merged record must satisfy
1233
+ the Finding schema and preserve the canonical finding ID. Validation still happens
1234
+ through `review_validator.submit_decisions`; invalid submissions are corrected in
1235
+ the same review conversation, and invalid or unfinished reviews are not cached.
1236
+
1237
+ Checkpoints bind to the exact original records and ordering, approved source path,
1238
+ Git revision and current file contents (including ignored files), repository scope,
1239
+ model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
1240
+ inputs cause a new review rather than reusing a decision. Source changes during
1241
+ review stop that attempt before group writes; restart with the same ID to review
1242
+ the changed source. Original findings, never prior rationales or merged findings,
1243
+ are supplied to later independent reviews. Source snapshots do not follow directory
1244
+ links outside the approved checkout.
1245
+
1246
+ Before posting groups, the workflow saves the exact final result and write payload.
1247
+ If posting fails or its acknowledgement is lost, rerunning dedupe replays that
1248
+ payload without looking up candidates or running models. Group persistence reuses
1249
+ the existing membership identity, so replay does not create another group. The
1250
+ dedupe stage completes only after acknowledgement. Empty results are also retained.
1251
+ A completed workflow or pending write represents its already reviewed snapshot;
1252
+ use another workflow ID for a fresh review rather than changing that saved result.
1253
+
1254
+ ### Deduplication workflow
1255
+
1256
+ 1. For each distinct finding ID in the scan, request
1257
+ `/v1/finding/{id}/potential-duplicates` with the selected repository or
1258
+ explicit all-repository scope. Use the complete stored anchor and
1259
+ candidates returned by that request.
1260
+ 2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1261
+ effort. The review covers every anchor-neighbor pair; nominations between
1262
+ neighbors are rejected.
1263
+ 3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
1264
+ reasoning effort. Only accepted pairs contribute to duplicate groups.
1265
+ 4. Group connected findings deterministically, treating accepted duplicate
1266
+ pairs as transitive: if A matches B and B matches C, all three belong to one
1267
+ group. There is no additional whole-group review. A mistaken accepted pair
1268
+ can therefore join otherwise distinct findings.
1269
+ 5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
1270
+ only after the service accepts the write. An empty result requires no write.
1271
+
1272
+ Each review uses a fresh, ephemeral Codex app-server thread with the complete
1273
+ original finding records, not earlier model rationales, vector scores, or
1274
+ summaries. Reviews can inspect source in the saved scan's local checkout,
1275
+ starting with cited paths and revisions. Source inspection establishes duplicate
1276
+ identity and shared remediation. Reviews preserve the originals' severity and
1277
+ priority metadata without reassessment or normalization. The baseline
1278
+ filesystem profile is read-only and excludes credentials
1279
+ and Codex state. Screening denies approval requests; final reviews use Codex's
1280
+ automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
1281
+ Finding content never authorizes access to another target.
1282
+
1283
+ Decisions must arrive through the direct `review_validator.submit_decisions`
1284
+ tool; invalid submissions can be corrected in the same session. A final text
1285
+ answer alone is insufficient. Every `SAME` decision, including screening
1286
+ nominations, requires an assigned `canonicalFindingId` and a generated,
1287
+ inclusive `mergedFinding`; missing or null values are rejected. Screening
1288
+ canonicals must belong to the nominated pair. Sol reviews use only the complete
1289
+ originals, never earlier merged findings. These review fields do not change
1290
+ the command's ID-only result or stored findings.
1291
+
1292
+ Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
1293
+ `OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
1294
+ credentials are not sent to the findings API. Larger scans can take time and
1295
+ incur multiple model calls per finding. Empty scans and findings without
1296
+ eligible neighbors do not invoke review models. `completed` means this
1297
+ retrieval, review, and group persistence completed, not that every possible pair in the
1298
+ database was compared or that model decisions are infallible. An API, review, or write-back
1299
+ failure fails the command without claiming a completed result. Retry after
1300
+ fixing the failure; stored findings remain unchanged. A lost write-back response
1301
+ may have committed groups; retrying the same memberships does not duplicate
1302
+ them. Failed or interrupted reviews write no groups. The CLI supports Ctrl-C
1303
+ and SIGTERM, and the SDK accepts an `AbortSignal`.
1304
+
1305
+ ### Listing and errors
1306
+
1307
+ Listing defaults to `limit=50` and `offset=0`; `limit` must be a positive
1308
+ integer and `offset` a non-negative integer. Records are ordered by their first
1309
+ insertion time, then finding ID. Follow `nextOffset` until it is `null`:
1310
+
1311
+ ```json
1312
+ {
1313
+ "findings": [],
1314
+ "limit": 50,
1315
+ "offset": 0,
1316
+ "total": 0,
1317
+ "nextOffset": null
1318
+ }
1319
+ ```
1320
+
1321
+ The list includes API imports and complete finding documents from existing CLI
1322
+ scan history. It returns the latest stored document for each finding ID,
1323
+ without embedding vectors. Legacy identities without a complete document are
1324
+ not included. Pagination reflects current database contents, not a snapshot
1325
+ held between HTTP requests.
1326
+
1327
+ Malformed JSON, invalid finding objects, repository metadata, groups, scopes, and pagination return HTTP
1328
+ 400 (`invalid_request`). Identity conflicts or missing dedupe group members return 409 (`finding_conflict`),
1329
+ embedding provider failures or unusable vectors return 502 (`embedding_failed`),
1330
+ and missing embedding credentials return 503 (`embedding_unavailable`). A
1331
+ potential-duplicates query without a current embedding returns 404
1332
+ (`finding_not_indexed`), including findings outside the requested repository or
1333
+ whose embedding was invalidated by an update; import the finding with the
1334
+ matching `repositoryId` before retrying. This is an error, not an
1335
+ empty candidate list. Unknown routes return 404 (`not_found`); unexpected
1336
+ server failures return 500 (`internal_error`). Errors have an `error` code and,
1337
+ for expected failures, a `message`. Request bodies and provider error bodies
1338
+ are not logged.
1339
+
1340
+ ### Embeddings and storage
1341
+
1342
+ Set `OPENAI_API_KEY` in the repository-root `.env`, using `.env.example` as a
1343
+ template, or export `OPENAI_API_KEY` or `CODEX_API_KEY` in the host environment.
1344
+ Compose passes the key to the service; exported values override `.env` values.
1345
+ The `.env` file is excluded from Git and Docker builds. `OPENAI_API_KEY` takes
1346
+ precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
1347
+ `CODEX_API_KEY` instead. Listing and empty imports do not require a key.
1348
+ A Codex ChatGPT login is not an embedding API credential.
1349
+
1350
+ The service calls the OpenAI embeddings API with `text-embedding-3-large` and
1351
+ 1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
1352
+ bundled `cl100k_base` encoding. Long inputs are split without truncation;
1353
+ their vectors are combined by token weight and normalized. Requests respect
1354
+ the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.
1355
+ See the [embedding API contract](https://developers.openai.com/api/reference/resources/embeddings/methods/create).
1356
+
1357
+ Storage initializes before the server listens. The SQLite adapter reuses the
1358
+ bundled workbench's schema and migrations at
1359
+ `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. An append-only migration adds
1360
+ complete finding documents and an embedding table, while retaining the existing
1361
+ finding identity table and scan history. Both the API and current CLI indexing
1362
+ use the same finding upsert operation. Changing a stored document invalidates
1363
+ its old embedding so later matching cannot use a stale vector. Historical
1364
+ findings are not automatically embedded; submit them to a bulk endpoint first.
1365
+
1366
+ The `findings-state` named volume persists `/state`, including the database,
1367
+ across container replacements. Keep the same Compose project name to reuse it.
1368
+ The image runs as UID/GID `10001:10001`; a bind mount must be writable by that
1369
+ UID/GID if used instead of the named volume.
1370
+
1371
+ Stop the service with
1372
+ `docker compose -f compose.findings.yaml down`; add `--volumes` only when you
1373
+ intend to delete the stored data.
1374
+
1375
+ The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
1376
+ `CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
1377
+ changing these settings. Compose binds only to host loopback; the API has no
1378
+ authentication. Use an authenticated TLS proxy before sharing access. Finding
1379
+ JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and
1380
+ generated embeddings stay in the local volume.
1381
+
1382
+ ### Upgrades and backups
1383
+
1384
+ Read the release notes and stop the service before backing up the entire
1385
+ `/state` directory. For the published-image Compose configuration:
1386
+
1387
+ ```bash
1388
+ docker compose -f compose.findings.yaml stop findings
1389
+ mkdir -p backups
1390
+ chmod 700 backups
1391
+ docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \
1392
+ --entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz
1393
+ chmod 600 backups/findings-state.tgz
1394
+ ```
1395
+
1396
+ Keep backups separately; this command overwrites an existing backup of the same
1397
+ name. Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest and repeat
1398
+ the pull/start commands above, retaining the volume. Startup applies SQLite
1399
+ migrations automatically. To roll back, stop the service, restore the pre-upgrade
1400
+ backup, and select the previous image digest; an older image may not support the
1401
+ migrated database.
1402
+
1403
+ ### Running without Docker
1404
+
1405
+ To run locally, use Node.js and Python 3 as described in the prerequisites.
1406
+ Export the API key in your shell; the server does not load `.env` automatically.
1407
+ From `sdk/typescript`, install dependencies, build, and start:
1408
+
1409
+ ```bash
1410
+ pnpm install --frozen-lockfile
1411
+ pnpm run build
1412
+ pnpm run start:server
1413
+ ```
1414
+
1415
+ Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
1416
+ `CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
1417
+ without a state override, the service uses the same default state directory as
1418
+ the CLI. These settings also work on Windows.
1419
+
1420
+ HTTP routing, orchestration, embedding generation, and the SQLite adapter live
1421
+ separately under `src/server/`. `FindingsService` receives a `FindingEmbedder`
1422
+ whose `embed(findings)` method returns one `{ model, vector }` per finding in
1423
+ input order. `OpenAiFindingEmbedder` handles tokenization, batching, API calls,
1424
+ and vector normalization; it does not access storage. The `FindingsStore`
1425
+ interface stores findings and vectors and exposes
1426
+ `findPotentialDuplicates(findingId, scope)`. Repository filtering, vector ranking,
1427
+ and fetching selected documents stay inside the store implementation; replacing
1428
+ SQLite with an indexed store does not change the service or SDK/CLI. Repository
1429
+ associations are stored separately from finding documents, with an append-only
1430
+ migration that also imports known associations from stored scan occurrences.
1431
+ New scan findings retain their target associations when indexed locally.
1432
+ The server entrypoint selects the concrete
1433
+ embedder and store, so either can be replaced independently.
1434
+ The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
1435
+ receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
1436
+ separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
1437
+ and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
1438
+ `deduplicateScan` validates saved scan artifacts before running the workflow.
1439
+ The SDK reuses the existing Codex runtime and credentials without additional
1440
+ runtime dependencies.
1441
+
913
1442
  ## Containerized bulk scans
914
1443
 
915
1444
  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"
@@ -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
 
@@ -118,7 +118,7 @@ Affected lines must include the root broken control or dangerous sink line when
118
118
  Then render these subsections under each finding:
119
119
 
120
120
  - `#### Summary`
121
- - Explain why the issue matters, what the vulnerable path is, and why the current controls are insufficient.
121
+ - Start with how to reproduce the issue and what happens in the product, then explain why the code causes that behavior.
122
122
  - Wrap code identifiers, RPC names, functions, types, fields, parameters, configuration keys, and literal values in single backticks.
123
123
  - `#### Root Cause`
124
124
  - State the violated security invariant and explain exactly how the implementation breaks it.