@openai/codex-security 0.1.29 → 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.
- package/README.md +15 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +52 -7
- package/dist/cli.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts +2 -7
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +2 -0
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +2 -2
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js +4 -10
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/deduplication/finding-schema.d.ts +4 -0
- package/dist/deduplication/finding-schema.d.ts.map +1 -0
- package/dist/deduplication/finding-schema.js +14 -0
- package/dist/deduplication/finding-schema.js.map +1 -0
- package/dist/deduplication/records-protocol.d.ts +9 -0
- package/dist/deduplication/records-protocol.d.ts.map +1 -0
- package/dist/deduplication/records-protocol.js +191 -0
- package/dist/deduplication/records-protocol.js.map +1 -0
- package/dist/deduplication/records.d.ts +33 -0
- package/dist/deduplication/records.d.ts.map +1 -0
- package/dist/deduplication/records.js +134 -0
- package/dist/deduplication/records.js.map +1 -0
- package/dist/deduplication/review.d.ts +21 -0
- package/dist/deduplication/review.d.ts.map +1 -0
- package/dist/deduplication/review.js +2 -0
- package/dist/deduplication/review.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/docs/dedupe-records.md +305 -0
- package/package.json +8 -7
|
@@ -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.
|
|
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",
|
|
@@ -51,8 +52,8 @@
|
|
|
51
52
|
"@inquirer/prompts": "8.7.2",
|
|
52
53
|
"@linear/sdk": "95.0.0",
|
|
53
54
|
"@octokit/core": "7.0.8",
|
|
54
|
-
"@openai/codex": "0.
|
|
55
|
-
"@openai/codex-sdk": "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",
|
|
@@ -65,7 +66,7 @@
|
|
|
65
66
|
"semver": "7.8.5",
|
|
66
67
|
"smol-toml": "1.8.0",
|
|
67
68
|
"yaml": "2.9.0",
|
|
68
|
-
"zod": "4.6.
|
|
69
|
+
"zod": "4.6.2"
|
|
69
70
|
},
|
|
70
71
|
"devDependencies": {
|
|
71
72
|
"@openai/apps-sdk-ui": "0.2.2",
|
|
@@ -78,7 +79,7 @@
|
|
|
78
79
|
"@types/react-dom": "19.3.0",
|
|
79
80
|
"@types/semver": "7.8.0",
|
|
80
81
|
"esbuild": "0.28.2",
|
|
81
|
-
"fast-check": "4.
|
|
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",
|
|
@@ -89,7 +90,7 @@
|
|
|
89
90
|
"tailwindcss": "4.3.3",
|
|
90
91
|
"typescript": "7.0.2"
|
|
91
92
|
},
|
|
92
|
-
"gitHead": "
|
|
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})\"",
|