@openai/codex-security 0.1.28 → 0.1.30

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 (80) hide show
  1. package/README.md +93 -4
  2. package/_bundled_plugin/examples/completed-scan/report.md +0 -1
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -0
  8. package/_bundled_plugin/scripts/generate_in_scope_files.py +12 -2
  9. package/_bundled_plugin/scripts/generate_rank_input.py +1 -6
  10. package/_bundled_plugin/scripts/rank_preview.py +8 -7
  11. package/_bundled_plugin/scripts/report_projection.py +0 -1
  12. package/_bundled_plugin/scripts/workbench_dashboard.py +24 -3
  13. package/_bundled_plugin/scripts/workbench_saved_results.py +5 -0
  14. package/dist/cli-scan-logs-json.d.ts +3 -0
  15. package/dist/cli-scan-logs-json.d.ts.map +1 -0
  16. package/dist/cli-scan-logs-json.js +22 -0
  17. package/dist/cli-scan-logs-json.js.map +1 -0
  18. package/dist/cli.d.ts +2 -0
  19. package/dist/cli.d.ts.map +1 -1
  20. package/dist/cli.js +206 -34
  21. package/dist/cli.js.map +1 -1
  22. package/dist/deduplication/codex-review.d.ts +2 -7
  23. package/dist/deduplication/codex-review.d.ts.map +1 -1
  24. package/dist/deduplication/codex-review.js +26 -4
  25. package/dist/deduplication/codex-review.js.map +1 -1
  26. package/dist/deduplication/deduplication-prompts.d.ts +2 -0
  27. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  28. package/dist/deduplication/deduplication-prompts.js +2 -2
  29. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  30. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  31. package/dist/deduplication/deduplication-reviewer.js +4 -10
  32. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  33. package/dist/deduplication/deduplication.d.ts +12 -1
  34. package/dist/deduplication/deduplication.d.ts.map +1 -1
  35. package/dist/deduplication/deduplication.js +41 -7
  36. package/dist/deduplication/deduplication.js.map +1 -1
  37. package/dist/deduplication/finding-schema.d.ts +4 -0
  38. package/dist/deduplication/finding-schema.d.ts.map +1 -0
  39. package/dist/deduplication/finding-schema.js +14 -0
  40. package/dist/deduplication/finding-schema.js.map +1 -0
  41. package/dist/deduplication/records-protocol.d.ts +9 -0
  42. package/dist/deduplication/records-protocol.d.ts.map +1 -0
  43. package/dist/deduplication/records-protocol.js +191 -0
  44. package/dist/deduplication/records-protocol.js.map +1 -0
  45. package/dist/deduplication/records.d.ts +33 -0
  46. package/dist/deduplication/records.d.ts.map +1 -0
  47. package/dist/deduplication/records.js +134 -0
  48. package/dist/deduplication/records.js.map +1 -0
  49. package/dist/deduplication/refusal.d.ts +3 -0
  50. package/dist/deduplication/refusal.d.ts.map +1 -0
  51. package/dist/deduplication/refusal.js +16 -0
  52. package/dist/deduplication/refusal.js.map +1 -0
  53. package/dist/deduplication/review.d.ts +21 -0
  54. package/dist/deduplication/review.d.ts.map +1 -0
  55. package/dist/deduplication/review.js +2 -0
  56. package/dist/deduplication/review.js.map +1 -0
  57. package/dist/errors.d.ts +1 -1
  58. package/dist/errors.d.ts.map +1 -1
  59. package/dist/errors.js.map +1 -1
  60. package/dist/index.d.ts +4 -0
  61. package/dist/index.d.ts.map +1 -1
  62. package/dist/index.js +1 -0
  63. package/dist/index.js.map +1 -1
  64. package/dist/scan-logs.d.ts.map +1 -1
  65. package/dist/scan-logs.js +34 -8
  66. package/dist/scan-logs.js.map +1 -1
  67. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +3 -3
  68. package/dist/server/dashboard/app.css +1 -1
  69. package/dist/server/dashboard/app.js +7 -7
  70. package/dist/server/dashboard-types.d.ts +4 -1
  71. package/dist/server/dashboard-types.d.ts.map +1 -1
  72. package/dist/server/dashboard-types.js.map +1 -1
  73. package/dist/server/dashboard.d.ts.map +1 -1
  74. package/dist/server/dashboard.js +18 -4
  75. package/dist/server/dashboard.js.map +1 -1
  76. package/dist/targets.d.ts.map +1 -1
  77. package/dist/targets.js +4 -4
  78. package/dist/targets.js.map +1 -1
  79. package/docs/dedupe-records.md +305 -0
  80. package/package.json +14 -13
@@ -0,0 +1,305 @@
1
+ # Host-provided records deduplication (protocol v1)
2
+
3
+ Run `codex-security dedupe --records` inside the authorized checkout. Use this
4
+ flag alone. Unlike saved-scan dedupe, this mode needs neither scan history nor a
5
+ Findings API. It performs no authentication, update checks, local Codex launches,
6
+ candidate retrieval, or persistence. The host owns repository authorization,
7
+ model execution, sessions, credentials, cancellation of remote work, and cleanup.
8
+
9
+ The SDK equivalent is:
10
+
11
+ ```typescript
12
+ import { deduplicateRecords } from "@openai/codex-security";
13
+
14
+ const result = await deduplicateRecords(input, {
15
+ reviewRunner: {
16
+ async run(request, { signal } = {}) {
17
+ return await hostReview(request, signal); // Return the structured answer.
18
+ },
19
+ },
20
+ signal: controller.signal,
21
+ });
22
+ ```
23
+
24
+ `DeduplicateRecordsInput`, `DeduplicateRecordsResult`,
25
+ `DeduplicationReviewRequest`, and `DeduplicationReviewRunner` are exported types.
26
+ The entry point validates the input structure, unique identities, and candidate
27
+ references before any review.
28
+
29
+ ## Input and identities
30
+
31
+ Send one UTF-8 JSON object per line, using JSON-RPC 2.0. Keep stdin open until the
32
+ final response; EOF is a disconnect, not an end-of-request marker. No batches,
33
+ interactive prompts, or additional runs are supported. Stdout is exclusively
34
+ protocol messages; CLI diagnostics use stderr. IDs are strings or safe integers
35
+ from -9007199254740991 through 9007199254740991 and are compared without coercion.
36
+ Use strings for larger numeric identifiers. Review IDs are generated strings;
37
+ request and response ID namespaces are directional.
38
+
39
+ The host sends:
40
+
41
+ ```json
42
+ {
43
+ "jsonrpc": "2.0",
44
+ "id": "run-1",
45
+ "method": "run",
46
+ "params": {
47
+ "version": 1,
48
+ "observations": [
49
+ { "id": "observation-1", "finding": "<complete Finding object>" },
50
+ { "id": "observation-2", "finding": "<complete Finding object>" }
51
+ ],
52
+ "candidateRelationships": [
53
+ {
54
+ "observationId": "observation-1",
55
+ "candidateObservationIds": ["observation-2"]
56
+ }
57
+ ]
58
+ }
59
+ }
60
+ ```
61
+
62
+ Replace the illustrative `finding` strings with complete SDK `Finding` objects
63
+ from `schemas/findings.schema.json` in the bundled plugin, including provenance,
64
+ locations, evidence, and all available source/revision information. Provenance
65
+ must describe the actual source; it does not authorize additional repository
66
+ access. Unknown extension fields are preserved. This does not require creating
67
+ scan manifests or other saved-scan artifacts.
68
+
69
+ Observation IDs are host-owned, nonempty strings, unique within `observations`.
70
+ Supply the pending observations and their retrieved neighbors together as original
71
+ observations. Each `candidateRelationships` entry selects one anchor to process;
72
+ its `candidateObservationIds` nominate comparisons to other supplied observations.
73
+ Anchors must be distinct, and candidate IDs must be distinct within an entry and
74
+ must not include the anchor itself. An empty candidate list produces a singleton
75
+ without a model call. Observations without an anchor entry are candidates only.
76
+
77
+ Only the supplied relationships are compared; there is no implicit all-pairs
78
+ comparison. The host owns candidate coverage. There is no fixed batch limit
79
+ (the expected number of anchors is at most 50). Canonical records are not accepted.
80
+
81
+ For model comparisons only, `findingId` is replaced with a stable, opaque
82
+ comparison ID derived from the host ID. Thus observations with
83
+ the same original finding ID remain separate records. All other finding fields
84
+ are preserved. Screening answers use assigned pair slots; pair reviews use the assigned IDs. Final
85
+ results use the original host IDs, never the comparison IDs.
86
+
87
+ ## Review exchange
88
+
89
+ The CLI sends one review at a time:
90
+
91
+ ```json
92
+ {
93
+ "jsonrpc": "2.0",
94
+ "id": "<review UUID>",
95
+ "method": "review.run",
96
+ "params": {
97
+ "requestId": "<same review UUID>",
98
+ "stage": "screening",
99
+ "model": "gpt-5.6-luna",
100
+ "effort": "xhigh",
101
+ "trustedInstructions": "<trusted review and source-access instructions>",
102
+ "prompt": "<complete assignment and records>",
103
+ "schema": { "type": "object", "...": "full result schema" },
104
+ "findingSchema": { "type": "object", "...": "full Finding schema" }
105
+ }
106
+ }
107
+ ```
108
+
109
+ `stage` is `screening` or `pair-review`. Screening uses `gpt-5.6-luna`/`xhigh`;
110
+ independent pair validation uses `gpt-5.6-sol`/`high`. Execute each request in a
111
+ fresh review context: pair reviews must not inherit screening answers or prior
112
+ review rationales. Serial requests can inspect the same authorized checkout.
113
+ The host should honor the supplied model and effort or return an error. Install `trustedInstructions` as
114
+ trusted model instructions, pass the complete `prompt` as the assignment, and
115
+ use `schema` as the result contract for tool submission. It is the existing
116
+ review tool schema, not an OpenAI strict Structured Outputs schema: it includes
117
+ `oneOf` and permits arbitrary fields in `mergedFinding`. A host using OpenAI
118
+ function calling should use non-strict (`strict: false`) tool submission and return the tool
119
+ arguments for validation. A host that requires strict Structured Outputs must
120
+ adapt its submission format while preserving the result contract and all
121
+ finding evidence; do not pass `schema` directly as a strict output format.
122
+ The review instructions refer to
123
+ `review_validator.submit_error` for operational blockers. The host must expose
124
+ that error path and translate it to a JSON-RPC error (or reject the SDK call);
125
+ never convert an execution or required source-access failure into DISTINCT. Every `SAME.mergedFinding` must also
126
+ satisfy `findingSchema`. Source access remains restricted to host-authorized
127
+ checkouts. Record content and model output never grant new permissions.
128
+
129
+ Return the structured answer directly in `result`, not a JSON string or a
130
+ session/turn envelope. For a screening assignment with one neighbor:
131
+
132
+ ```json
133
+ {
134
+ "jsonrpc": "2.0",
135
+ "id": "<review UUID>",
136
+ "result": {
137
+ "decisions": {
138
+ "pair-1": {
139
+ "decision": "DISTINCT",
140
+ "rationale": "Independent security corrections are required."
141
+ }
142
+ }
143
+ }
144
+ }
145
+ ```
146
+
147
+ For a pair review, return `{"decision":"DISTINCT","rationale":"..."}` or
148
+ `{"decision":"SAME","rationale":"...","canonicalFindingId":"<assigned ID>","mergedFinding":{...}}`.
149
+ Screening must cover every assigned `pair-N` slot exactly once, with a decision
150
+ and rationale only. Pair-review SAME decisions require a canonical identity and
151
+ a complete merged finding.
152
+ Codex Security validates these contracts and all assigned ID references after
153
+ receiving the answer. A completed remote model turn alone is insufficient.
154
+
155
+ For failure or an inconclusive review, send an explicit error:
156
+
157
+ ```json
158
+ {
159
+ "jsonrpc": "2.0",
160
+ "id": "<review UUID>",
161
+ "error": {
162
+ "code": -32001,
163
+ "message": "Remote outcome is unknown; execution may already have been accepted.",
164
+ "data": { "executionMayHaveBeenAccepted": true }
165
+ }
166
+ }
167
+ ```
168
+
169
+ The CLI never resubmits a review, including after this error. Invalid model
170
+ answers, missing decisions, and host errors make the whole batch unresolved;
171
+ previous successful reviews in that run do not become persistence decisions.
172
+ The existing algorithm treats a validated `DISTINCT` as a nonmatch, when
173
+ supplied finding content is insufficient to establish a shared correction. If the host considers the review
174
+ inconclusive, it must return an error rather than manufacture a `DISTINCT` answer.
175
+ No new `INCONCLUSIVE` model decision is introduced.
176
+
177
+ The existing screening, independent pair review, contradiction-aware grouping, and
178
+ severity-based representative selection are reused. No local review checkpoints
179
+ are read or written in records mode. Local saved-scan execution retains its
180
+ existing tool-submission validation and workflow checkpoints.
181
+
182
+ ## Final response and persistence
183
+
184
+ ```json
185
+ {
186
+ "jsonrpc": "2.0",
187
+ "id": "run-1",
188
+ "result": {
189
+ "version": 1,
190
+ "status": "completed",
191
+ "groups": [
192
+ {
193
+ "representativeObservationId": "observation-1",
194
+ "observationIds": ["observation-1", "observation-2"]
195
+ }
196
+ ],
197
+ "unresolved": []
198
+ }
199
+ }
200
+ ```
201
+
202
+ Each successful anchor occurs in exactly one group's `observationIds`, including
203
+ singleton groups. Candidate-only observations appear only when grouped with an
204
+ anchor; they are not assigned singleton dispositions. Groups can join observations
205
+ from different scans and include a severity-selected representative from any
206
+ member. All returned IDs identify original observations, never canonical records.
207
+
208
+ A failed or inconclusive review returns no groups and marks every anchor unresolved
209
+ with reason `review_failed`, an `observationId`, and a diagnostic `message`.
210
+ Any unresolved entry makes `status` equal `unresolved`.
211
+
212
+ The host creates canonical records and memberships, then removes pending
213
+ observations only after that persistence succeeds. Results contain decisions,
214
+ not persisted records or a synthesized final merged document. Preserve all
215
+ original evidence. Do not treat a failed run, absent final response, or unresolved
216
+ observation as unique. Cross-run replay/idempotency and reconciliation of remote
217
+ work whose acceptance is uncertain belong to the host; a new process creates
218
+ new review IDs and does not resume earlier remote execution.
219
+
220
+ ## Cancellation and protocol failures
221
+
222
+ To cancel the active run, send a notification:
223
+
224
+ ```json
225
+ { "jsonrpc": "2.0", "method": "cancel", "params": { "id": "run-1" } }
226
+ ```
227
+
228
+ Cancellation stops scheduling and returns a run error with code `-32800`.
229
+ If a terminal response is already being written, cancellation closes the output
230
+ instead of sending a second response; the host must discard an incomplete reply.
231
+ The host must also cancel/reconcile its remote turn; terminating this CLI cannot
232
+ cancel host-owned execution. SIGINT/SIGTERM also stop the run. EOF, pipe errors,
233
+ or closed pipes stop scheduling; an error is returned when stdout remains usable.
234
+
235
+ Malformed JSON yields `-32700`; malformed envelopes, duplicate/unknown/mismatched
236
+ review responses, multiple runs, and mismatched cancellation yield `-32600`.
237
+ Invalid run parameters yield `-32602`. Disconnects use `-32000`. Fatal errors
238
+ use the active run ID, or `null` if no run was accepted, and provide no decisions.
239
+ Envelopes must contain exactly one of `result` or `error` for a response.
240
+
241
+ Exit codes: `0` completed; `1` unresolved decisions; `2` input/protocol failure,
242
+ disconnect, or protocol cancellation; `130` SIGINT; `143` SIGTERM. The host
243
+ controls timeouts by sending cancellation or terminating the process. It must
244
+ keep reading both stdout and stderr and must not share one execution session or
245
+ workspace concurrently on the assumption that reviews are independent.
246
+
247
+ ## Runnable Python fake host
248
+
249
+ This demonstrates the bidirectional process boundary only. It does **not** call
250
+ Managed Agents or assess real duplicates. Save as `fake_host.py` and run
251
+ `python fake_host.py request.json`, where `request.json` contains the `params`
252
+ object described above with complete synthetic findings. With a source checkout,
253
+ first build the SDK and replace the command with
254
+ `["node", "sdk/typescript/bin/codex-security.mjs", "dedupe", "--records"]`.
255
+
256
+ ```python
257
+ import json
258
+ import subprocess
259
+ import sys
260
+
261
+ with open(sys.argv[1], encoding="utf-8") as source:
262
+ params = json.load(source)
263
+
264
+ with subprocess.Popen(
265
+ ["codex-security", "dedupe", "--records"],
266
+ stdin=subprocess.PIPE, stdout=subprocess.PIPE,
267
+ stderr=None, text=True, encoding="utf-8", bufsize=1,
268
+ ) as child:
269
+ def send(message):
270
+ child.stdin.write(json.dumps(message) + "\n")
271
+ child.stdin.flush()
272
+
273
+ send({"jsonrpc": "2.0", "id": "run-1", "method": "run", "params": params})
274
+ for line in child.stdout:
275
+ message = json.loads(line)
276
+ if message.get("method") == "review.run":
277
+ request = message["params"]
278
+ assert request["requestId"] == message["id"]
279
+ # Fake only: read the records suffix and declare every pair distinct.
280
+ # The real adapter executes trustedInstructions/prompt/model/effort
281
+ # through its own remote session and returns schema-conforming output.
282
+ records = json.loads(request["prompt"].rsplit("\n\n", 1)[1])["findings"]
283
+ distinct = {"decision": "DISTINCT", "rationale": "Synthetic fake-host nonmatch."}
284
+ result = distinct if request["stage"] == "pair-review" else {
285
+ "decisions": {
286
+ f"pair-{index}": distinct
287
+ for index in range(1, len(records))
288
+ }
289
+ }
290
+ send({"jsonrpc": "2.0", "id": message["id"], "result": result})
291
+ else:
292
+ assert message["id"] == "run-1"
293
+ print(json.dumps(message, indent=2))
294
+ break
295
+ child.stdin.close()
296
+ returncode = child.wait()
297
+ if returncode:
298
+ raise SystemExit(returncode)
299
+ ```
300
+
301
+ The production Python adapter replaces the fake answer block, returns explicit
302
+ errors for incomplete/uncertain remote outcomes, and owns remote cancellation
303
+ and persistence. Fake-host tests do not establish live Managed Agents
304
+ compatibility; that requires an integration test with the separately implemented
305
+ adapter.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openai/codex-security",
3
- "version": "0.1.28",
3
+ "version": "0.1.30",
4
4
  "description": "TypeScript SDK and CLI for Codex Security",
5
5
  "license": "Apache-2.0",
6
6
  "author": "OpenAI",
@@ -39,7 +39,8 @@
39
39
  "schemas",
40
40
  "_bundled_plugin",
41
41
  "LICENSE",
42
- "README.md"
42
+ "README.md",
43
+ "docs/dedupe-records.md"
43
44
  ],
44
45
  "publishConfig": {
45
46
  "access": "public",
@@ -49,10 +50,10 @@
49
50
  },
50
51
  "dependencies": {
51
52
  "@inquirer/prompts": "8.7.2",
52
- "@linear/sdk": "93.0.1",
53
+ "@linear/sdk": "95.0.0",
53
54
  "@octokit/core": "7.0.8",
54
- "@openai/codex": "0.154.0",
55
- "@openai/codex-sdk": "0.154.0",
55
+ "@openai/codex": "0.155.0",
56
+ "@openai/codex-sdk": "0.155.0",
56
57
  "ajv": "8.20.0",
57
58
  "extract-zip": "2.0.1",
58
59
  "fflate": "0.8.3",
@@ -61,35 +62,35 @@
61
62
  "js-tiktoken": "1.0.21",
62
63
  "papaparse": "5.7.0",
63
64
  "pdfjs-dist": "6.3.289",
64
- "react": "19.2.8",
65
+ "react": "19.3.0",
65
66
  "semver": "7.8.5",
66
67
  "smol-toml": "1.8.0",
67
68
  "yaml": "2.9.0",
68
- "zod": "4.5.4"
69
+ "zod": "4.6.2"
69
70
  },
70
71
  "devDependencies": {
71
72
  "@openai/apps-sdk-ui": "0.2.2",
72
73
  "@stryker-mutator/core": "10.0.0",
73
74
  "@tailwindcss/postcss": "4.3.3",
74
75
  "@types/bun": "1.4.2",
75
- "@types/node": "26.5.0",
76
+ "@types/node": "26.5.1",
76
77
  "@types/papaparse": "5.5.2",
77
- "@types/react": "19.2.18",
78
- "@types/react-dom": "19.2.7",
78
+ "@types/react": "19.3.0",
79
+ "@types/react-dom": "19.3.0",
79
80
  "@types/semver": "7.8.0",
80
81
  "esbuild": "0.28.2",
81
- "fast-check": "4.9.0",
82
+ "fast-check": "4.10.0",
82
83
  "ink-testing-library": "4.0.0",
83
84
  "json-schema-to-typescript": "16.0.0",
84
85
  "minimatch": "10.2.6",
85
86
  "postcss": "8.5.28",
86
87
  "prettier": "3.9.6",
87
- "react-dom": "19.2.8",
88
+ "react-dom": "19.3.0",
88
89
  "saxes": "6.0.0",
89
90
  "tailwindcss": "4.3.3",
90
91
  "typescript": "7.0.2"
91
92
  },
92
- "gitHead": "f5adb33ab7d1f86b252d703a8af45d47de7f9486",
93
+ "gitHead": "6eecd8ca2587fe44d3b971026d32d591b5ecd315",
93
94
  "scripts": {
94
95
  "audit:prod": "pnpm audit --prod --audit-level high",
95
96
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",