@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.
- package/README.md +549 -1
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/references/config-preflight.md +2 -30
- package/_bundled_plugin/references/core-scan.md +1 -1
- package/_bundled_plugin/references/final-report.md +1 -1
- package/_bundled_plugin/references/finding-detail-fields.md +5 -10
- package/_bundled_plugin/references/sarif-adapter.md +1 -1
- package/_bundled_plugin/references/scan-contract.md +10 -0
- package/_bundled_plugin/scripts/config_preflight.py +2 -8
- package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +115 -76
- package/_bundled_plugin/scripts/finding_preview.py +22 -4
- package/_bundled_plugin/scripts/generate_in_scope_files.py +29 -9
- package/_bundled_plugin/scripts/generate_rank_input.py +1 -5
- package/_bundled_plugin/scripts/rank_preview.py +1 -0
- package/_bundled_plugin/scripts/report_projection.py +8 -14
- package/_bundled_plugin/scripts/validate_scan_contract.py +1 -3
- package/_bundled_plugin/scripts/windows_scan_local_files.py +90 -6
- package/_bundled_plugin/scripts/workbench_cli.py +27 -1
- package/_bundled_plugin/scripts/workbench_dashboard.py +138 -0
- package/_bundled_plugin/scripts/workbench_db.py +110 -539
- package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +208 -0
- package/_bundled_plugin/scripts/workbench_findings.py +221 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -2
- package/_bundled_plugin/scripts/workbench_publication.py +520 -0
- package/_bundled_plugin/scripts/workbench_remediation.py +37 -0
- package/_bundled_plugin/scripts/workbench_saved_results.py +322 -89
- package/_bundled_plugin/scripts/workbench_scan_history.py +1 -2
- package/_bundled_plugin/scripts/workbench_scan_usage.py +9 -33
- package/_bundled_plugin/scripts/workbench_schema.py +276 -58
- package/_bundled_plugin/scripts/workbench_target.py +30 -6
- package/_bundled_plugin/scripts/workbench_validation.py +1 -5
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +1 -5
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +6 -1
- package/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
- package/dist/api.d.ts +5 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +135 -27
- package/dist/api.js.map +1 -1
- package/dist/cli.d.ts +4 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +158 -62
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js +5 -1
- package/dist/cloud-publish.js.map +1 -1
- package/dist/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +9 -0
- package/dist/contract.js.map +1 -1
- package/dist/custom-publish.d.ts +22 -0
- package/dist/custom-publish.d.ts.map +1 -0
- package/dist/custom-publish.js +47 -0
- package/dist/custom-publish.js.map +1 -0
- package/dist/custom-validation-prompt.js +1 -1
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts +16 -0
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
- package/dist/deduplication/checkpointed-review.js +76 -0
- package/dist/deduplication/checkpointed-review.js.map +1 -0
- package/dist/deduplication/codex-review.d.ts +21 -0
- package/dist/deduplication/codex-review.d.ts.map +1 -0
- package/dist/deduplication/codex-review.js +252 -0
- package/dist/deduplication/codex-review.js.map +1 -0
- package/dist/deduplication/deduplication-prompts.d.ts +8 -0
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
- package/dist/deduplication/deduplication-prompts.js +35 -0
- package/dist/deduplication/deduplication-prompts.js.map +1 -0
- package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
- package/dist/deduplication/deduplication-reviewer.js +105 -0
- package/dist/deduplication/deduplication-reviewer.js.map +1 -0
- package/dist/deduplication/deduplication.d.ts +6 -0
- package/dist/deduplication/deduplication.d.ts.map +1 -0
- package/dist/deduplication/deduplication.js +85 -0
- package/dist/deduplication/deduplication.js.map +1 -0
- package/dist/deduplication/scan.d.ts +16 -0
- package/dist/deduplication/scan.d.ts.map +1 -0
- package/dist/deduplication/scan.js +101 -0
- package/dist/deduplication/scan.js.map +1 -0
- package/dist/deep-progress.d.ts +21 -0
- package/dist/deep-progress.d.ts.map +1 -0
- package/dist/deep-progress.js +108 -0
- package/dist/deep-progress.js.map +1 -0
- package/dist/finding-dedupe-groups.d.ts +7 -0
- package/dist/finding-dedupe-groups.d.ts.map +1 -0
- package/dist/finding-dedupe-groups.js +2 -0
- package/dist/finding-dedupe-groups.js.map +1 -0
- package/dist/finding-retrieval.d.ts +13 -0
- package/dist/finding-retrieval.d.ts.map +1 -0
- package/dist/finding-retrieval.js +2 -0
- package/dist/finding-retrieval.js.map +1 -0
- package/dist/finding-workflow.d.ts +53 -0
- package/dist/finding-workflow.d.ts.map +1 -0
- package/dist/finding-workflow.js +117 -0
- package/dist/finding-workflow.js.map +1 -0
- package/dist/findings-client.d.ts +15 -0
- package/dist/findings-client.d.ts.map +1 -0
- package/dist/findings-client.js +60 -0
- package/dist/findings-client.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/publication.js +28 -40
- package/dist/publication.js.map +1 -1
- package/dist/runtime.d.ts +5 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +119 -13
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan.d.ts +15 -0
- package/dist/saved-scan.d.ts.map +1 -0
- package/dist/saved-scan.js +68 -0
- package/dist/saved-scan.js.map +1 -0
- package/dist/scan-activity.d.ts.map +1 -1
- package/dist/scan-activity.js +12 -2
- package/dist/scan-activity.js.map +1 -1
- package/dist/scan-comparison.d.ts +3 -2
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +1 -1
- package/dist/scan-comparison.js.map +1 -1
- package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
- package/dist/server/dashboard/app.css +2 -0
- package/dist/server/dashboard/app.js +66 -0
- package/dist/server/dashboard/index.html +18 -0
- package/dist/server/dashboard-types.d.ts +45 -0
- package/dist/server/dashboard-types.d.ts.map +1 -0
- package/dist/server/dashboard-types.js +2 -0
- package/dist/server/dashboard-types.js.map +1 -0
- package/dist/server/dashboard.d.ts +6 -0
- package/dist/server/dashboard.d.ts.map +1 -0
- package/dist/server/dashboard.js +45 -0
- package/dist/server/dashboard.js.map +1 -0
- package/dist/server/embeddings.d.ts +16 -0
- package/dist/server/embeddings.d.ts.map +1 -0
- package/dist/server/embeddings.js +114 -0
- package/dist/server/embeddings.js.map +1 -0
- package/dist/server/errors.d.ts +5 -0
- package/dist/server/errors.d.ts.map +1 -0
- package/dist/server/errors.js +8 -0
- package/dist/server/errors.js.map +1 -0
- package/dist/server/findings-service.d.ts +20 -0
- package/dist/server/findings-service.d.ts.map +1 -0
- package/dist/server/findings-service.js +31 -0
- package/dist/server/findings-service.js.map +1 -0
- package/dist/server/index.d.ts +2 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +6 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/routes.d.ts +6 -0
- package/dist/server/routes.d.ts.map +1 -0
- package/dist/server/routes.js +86 -0
- package/dist/server/routes.js.map +1 -0
- package/dist/server/serve.d.ts +2 -0
- package/dist/server/serve.d.ts.map +1 -0
- package/dist/server/serve.js +28 -0
- package/dist/server/serve.js.map +1 -0
- package/dist/server/server.d.ts +10 -0
- package/dist/server/server.d.ts.map +1 -0
- package/dist/server/server.js +17 -0
- package/dist/server/server.js.map +1 -0
- package/dist/server/sqlite-store.d.ts +22 -0
- package/dist/server/sqlite-store.d.ts.map +1 -0
- package/dist/server/sqlite-store.js +82 -0
- package/dist/server/sqlite-store.js.map +1 -0
- package/dist/server/storage.d.ts +32 -0
- package/dist/server/storage.d.ts.map +1 -0
- package/dist/server/storage.js +2 -0
- package/dist/server/storage.js.map +1 -0
- package/dist/server/validation.d.ts +17 -0
- package/dist/server/validation.d.ts.map +1 -0
- package/dist/server/validation.js +53 -0
- package/dist/server/validation.js.map +1 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +2 -1
- package/dist/trusted-executable.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- 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
|
|
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).
|
|
Binary file
|
|
Binary file
|
|
@@ -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
|
|
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
|
|
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
|
|