OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
feat(dedupe): attribute records reviews to participating observations (#1145)
Kyle Brown9329e47098ff
diff --git a/sdk/typescript/docs/dedupe-records.md b/sdk/typescript/docs/dedupe-records.mdindex f7fd5de12..c04778475 100644--- a/sdk/typescript/docs/dedupe-records.md+++ b/sdk/typescript/docs/dedupe-records.md@@ -95,6 +95,11 @@ The CLI sends one review at a time:"method": "review.run","params": {"requestId": "<same review UUID>",+ "attribution": {+ "version": 1,+ "beneficiaryObservationIds": ["observation-1"],+ "contextObservationIds": ["observation-2"]+ },"stage": "screening","model": "gpt-5.6-luna","effort": "xhigh",@@ -106,6 +111,25 @@ The CLI sends one review at a time:}```+Every records review includes `attribution.version: 1`. The two ID arrays name+the exact original host observations participating in that screening or pair+review, using the structured assignment rather than the prompt or final groups.+`beneficiaryObservationIds` contains participants that have an anchor entry in+this invocation's `candidateRelationships`; `contextObservationIds` contains+the remaining participants. Both arrays are sorted, distinct, and disjoint,+and beneficiaries are nonempty. Candidate-only observations never become+beneficiaries, even when selected as the final representative. An incoming+observation participating in several reviews appears in each review's metadata.++This is additive metadata: JSON-RPC remains 2.0 and input/result versions remain 1.+Older hosts may ignore it; hosts that require attribution must validate it+and reject missing or unknown identities before executing a review. Persist the+request UUID and attribution before provisioning remote execution. The host owns+accounting and any partitioning of invocation anchors by origin scan; the CLI+preserves the supplied batch and does not assign costs or infer scan ownership.+The `model` field remains the configured review model. A new invocation produces+new request UUIDs; this metadata does not introduce cross-invocation replay.+`stage` is `screening` or `pair-review`. Screening uses `gpt-5.6-luna`/`xhigh`;independent pair validation uses `gpt-5.6-sol`/`high`. Execute each request in afresh review context: pair reviews must not inherit screening answers or priordiff --git a/sdk/typescript/src/deduplication/codex-review.ts b/sdk/typescript/src/deduplication/codex-review.tsindex 4ba30f9aa..719877893 100644--- a/sdk/typescript/src/deduplication/codex-review.ts+++ b/sdk/typescript/src/deduplication/codex-review.ts@@ -50,6 +50,8 @@ export interface CodexReview<T> extends Pick<DeduplicationReviewRequest,"stage" | "model" | "effort" | "prompt" | "schema"> {+ /** Exact comparison participants, supplied by the structured reviewer. */+ findingIds?: readonly string[];validate(value: unknown): T;}diff --git a/sdk/typescript/src/deduplication/deduplication-reviewer.ts b/sdk/typescript/src/deduplication/deduplication-reviewer.tsindex df1af9055..62b3a04a9 100644--- a/sdk/typescript/src/deduplication/deduplication-reviewer.ts+++ b/sdk/typescript/src/deduplication/deduplication-reviewer.ts@@ -130,6 +130,7 @@ export class CodexDeduplicationReviewer implements DeduplicationReviewer {async screen(findings: readonly Finding[]): Promise<ScreeningResult> {return await this.runner.run({stage: "screening",+ findingIds: findings.map((finding) => finding.findingId),model: "gpt-5.6-luna",effort: "xhigh",prompt: screeningPrompt(findings),@@ -141,6 +142,7 @@ export class CodexDeduplicationReviewer implements DeduplicationReviewer {async reviewPair(findings: readonly Finding[]): Promise<DuplicateDecision> {return await this.runner.run({stage: "pair-review",+ findingIds: findings.map((finding) => finding.findingId),model: "gpt-5.6-sol",effort: "high",prompt: pairReviewPrompt(findings),diff --git a/sdk/typescript/src/deduplication/records.ts b/sdk/typescript/src/deduplication/records.tsindex 5a5d86b7d..a45cd1f38 100644--- a/sdk/typescript/src/deduplication/records.ts+++ b/sdk/typescript/src/deduplication/records.ts@@ -14,7 +14,39 @@ import {screeningFindingFormatInstructions,pairFindingFormatInstructions,} from "./deduplication-prompts.js";-import type { DeduplicationReviewRunner } from "./review.js";+import type {+ DeduplicationReviewAttribution,+ DeduplicationReviewRunner,+} from "./review.js";++export function recordsReviewAttribution(+ findingIds: readonly string[] | undefined,+ references: ReadonlyMap<string, string>,+ anchors: ReadonlyMap<string, readonly string[]>,+): DeduplicationReviewAttribution {+ if (!findingIds?.length)+ throw new Error("Records review is missing its comparison participants.");+ const participants = new Set(+ findingIds.map((findingId) => {+ const observationId = references.get(findingId);+ if (observationId === undefined)+ throw new Error(`Unknown records review finding ID: ${findingId}`);+ return observationId;+ }),+ );+ const beneficiaryObservationIds = [...participants]+ .filter((id) => anchors.has(id))+ .sort();+ if (beneficiaryObservationIds.length === 0)+ throw new Error("Records review has no incoming observation participants.");+ return {+ version: 1,+ beneficiaryObservationIds,+ contextObservationIds: [...participants]+ .filter((id) => !anchors.has(id))+ .sort(),+ };+}const id = z.string().min(1);const record = z@@ -117,7 +149,11 @@ export async function deduplicateRecords(observations.get(id)!,);const reviewer = new CodexDeduplicationReviewer({- async run<T>({ validate, ...review }: CodexReview<T>): Promise<T> {+ async run<T>({+ validate,+ findingIds,+ ...review+ }: CodexReview<T>): Promise<T> {try {return await abortable(async () => {options.signal?.throwIfAborted();@@ -126,6 +162,11 @@ export async function deduplicateRecords({...review,requestId: randomUUID(),+ attribution: recordsReviewAttribution(+ findingIds,+ references,+ relationships,+ ),trustedInstructions: [sourceReviewInstructions,review.stage === "screening"diff --git a/sdk/typescript/src/deduplication/review.ts b/sdk/typescript/src/deduplication/review.tsindex c2bd66240..25d21be22 100644--- a/sdk/typescript/src/deduplication/review.ts+++ b/sdk/typescript/src/deduplication/review.ts@@ -1,8 +1,16 @@import type { DeduplicationReviewStage } from "../errors.js";+export interface DeduplicationReviewAttribution {+ version: 1;+ beneficiaryObservationIds: string[];+ contextObservationIds: string[];+}+/** Serializable review contract shared by local and host-provided execution. */export interface DeduplicationReviewRequest {requestId: string;+ /** Present in records mode; IDs identify this review's host observations. */+ attribution?: DeduplicationReviewAttribution;stage: DeduplicationReviewStage;model: string;effort: string;diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex 13a01255e..982ea0c60 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -137,6 +137,7 @@ export type {} from "./deduplication/records.js";export type {DeduplicationReviewRequest,+ DeduplicationReviewAttribution,DeduplicationReviewRunner,} from "./deduplication/review.js";export {diff --git a/sdk/typescript/tests-ts/dedupe-records.test.ts b/sdk/typescript/tests-ts/dedupe-records.test.tsindex 1e957a6f1..edfa1031a 100644--- a/sdk/typescript/tests-ts/dedupe-records.test.ts+++ b/sdk/typescript/tests-ts/dedupe-records.test.ts@@ -10,6 +10,7 @@ import { PassThrough, Writable } from "node:stream";import type { Finding, FindingsDocument } from "../src/models.js";import {deduplicateRecords,+ recordsReviewAttribution,type DeduplicateRecordsInput,} from "../src/deduplication/records.js";import type { DeduplicationReviewRequest } from "../src/deduplication/review.js";@@ -17,6 +18,41 @@ import { runRecordsProtocol } from "../src/deduplication/records-protocol.js";import { main } from "../src/cli.js";import { capture, dependencies, FakeSignals } from "./cli-fixtures.js";import { PLUGIN_ROOT } from "./plugin-root.js";+import attributionFixtures from "./fixtures/records-review-attribution.json";++test("attribution maps exact structured participants to sorted host identities", () => {+ const references = new Map(+ ["A", "B", "C", "D"].map((id) => [`finding-${id}`, id]),+ );+ for (const fixture of attributionFixtures) {+ const participants = fixture.participants.map((id) => `finding-${id}`);+ expect(+ recordsReviewAttribution(+ [...participants].reverse().concat(participants),+ references,+ new Map(fixture.anchors.map((id) => [id, []])),+ ),+ ).toEqual({ ...fixture.attribution, version: 1 });+ }+});++test("attribution rejects absent, unknown, and context-only participants", () => {+ const references = new Map([+ ["finding-A", "A"],+ ["finding-C", "C"],+ ]);+ const anchors = new Map([["A", ["C"]]]);+ for (const participants of [+ undefined,+ [],+ ["unknown"],+ ["finding-C"],+ ["finding-A", "unknown"],+ ])+ expect(() =>+ recordsReviewAttribution(participants, references, anchors),+ ).toThrow();+});const document: FindingsDocument = JSON.parse(await readFile(@@ -93,6 +129,7 @@ test("records groups original observations and retrieved neighbors with unique rexpect(review.trustedInstructions).toContain("approved repository");expect(review.findingSchema).toHaveProperty("required");expect(review).not.toHaveProperty("validate");+ expect(review).not.toHaveProperty("findingIds");for (const finding of assigned(review))expect(finding.provenance).toHaveProperty("revision",@@ -116,6 +153,20 @@ test("records groups original observations and retrieved neighbors with unique r2,);expect(original).toEqual(input());+ for (const request of requests) {+ const participants = assigned(request).map((finding) =>+ finding.provenance!.source!.slice("synthetic/".length),+ );+ expect(request.attribution).toEqual({+ version: 1,+ beneficiaryObservationIds: participants+ .filter((id) => id !== "neighbor")+ .sort(),+ contextObservationIds: participants+ .filter((id) => id === "neighbor")+ .sort(),+ });+ }});test("records honors explicit observation neighborhoods and handles empty/isolated inputs without reviews", async () => {@@ -171,6 +222,52 @@ test("candidate-only observations are grouped without becoming additional anchor"screening","pair-review",]);+ for (const request of requests)+ expect(request.attribution).toEqual({+ version: 1,+ beneficiaryObservationIds: ["a"],+ contextObservationIds: ["b"],+ });+});++test("records retries in a new invocation preserve membership with fresh review UUIDs", async () => {+ const requests: DeduplicationReviewRequest[] = [];+ const data: DeduplicateRecordsInput = {+ version: 1,+ observations: [record("A", "same"), record("D", "same")],+ candidateRelationships: [+ { observationId: "A", candidateObservationIds: ["D"] },+ ],+ };+ const failed = await deduplicateRecords(data, {+ reviewRunner: {+ async run(review) {+ requests.push(review);+ throw new Error("Remote acceptance unknown");+ },+ },+ });+ expect(failed.status).toBe("unresolved");+ const completed = await deduplicateRecords(data, {+ reviewRunner: {+ async run(review) {+ requests.push(review);+ return answer(review);+ },+ },+ });+ expect(completed.status).toBe("completed");+ expect(requests).toHaveLength(3);+ expect(new Set(requests.map((request) => request.requestId)).size).toBe(3);+ for (const request of requests) {+ expect(request.requestId).toMatch(+ /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,+ );+ expect(request.attribution).toEqual({+ ...attributionFixtures[3]!.attribution,+ version: 1,+ });+ }});test.each([@@ -327,9 +424,26 @@ function fakeHost(const run = { jsonrpc: "2.0", id: "run-1", method: "run", params: input() };test("CLI records mode uses only the fake host, bypassing saved scans, persistence, auth, and updates", async () => {- const host = fakeHost((message, send) =>- send({ jsonrpc: "2.0", id: message.id, result: answer(message.params) }),- );+ const host = fakeHost((message, send) => {+ expect(message.jsonrpc).toBe("2.0");+ expect(message.id).toBe(message.params.requestId);+ expect(message.params.attribution?.version).toBe(1);+ const participants = assigned(message.params).map((finding) =>+ finding.provenance!.source!.slice("synthetic/".length),+ );+ expect(message.params.attribution).toEqual({+ version: 1,+ beneficiaryObservationIds: participants+ .filter((id) => id !== "neighbor")+ .sort(),+ contextObservationIds: participants+ .filter((id) => id === "neighbor")+ .sort(),+ });+ // An older host can ignore additive metadata and use the original request.+ const { attribution: _attribution, ...legacyRequest } = message.params;+ send({ jsonrpc: "2.0", id: message.id, result: answer(legacyRequest) });+ });const deps = dependencies();for (const key of Object.keys(deps)) {if (typeof deps[key as keyof typeof deps] === "function")@@ -482,14 +596,36 @@ test("real CLI pipes exit after a fake-host run without local Codex or state writry {child.stdin.write(`${JSON.stringify(run)}\n`);let final: Message | undefined;+ const reviews: DeduplicationReviewRequest[] = [];for await (const line of createInterface({ input: child.stdout })) {const message = JSON.parse(line) as Message;- if (message.method === "review.run")+ if (message.method === "review.run") {+ reviews.push(message.params);+ expect(message.jsonrpc).toBe("2.0");+ expect(message.id).toBe(message.params.requestId);+ const participants = assigned(message.params).map((finding) =>+ finding.provenance!.source!.slice("synthetic/".length),+ );+ expect(message.params.attribution).toEqual({+ version: 1,+ beneficiaryObservationIds: participants+ .filter((id) => id !== "neighbor")+ .sort(),+ contextObservationIds: participants+ .filter((id) => id === "neighbor")+ .sort(),+ });child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: answer(message.params) })}\n`,);- else final = message;+ } else final = message;}+ expect(+ reviews.filter((review) => review.stage === "screening"),+ ).toHaveLength(4);+ expect(+ reviews.filter((review) => review.stage === "pair-review"),+ ).toHaveLength(2);expect(await closed).toBe(0);expect(stderr).toBe("");expect(final).toMatchObject({diff --git a/sdk/typescript/tests-ts/fixtures/records-review-attribution.json b/sdk/typescript/tests-ts/fixtures/records-review-attribution.jsonnew file mode 100644index 000000000..89b52fe88--- /dev/null+++ b/sdk/typescript/tests-ts/fixtures/records-review-attribution.json@@ -0,0 +1,38 @@+[+ {+ "anchors": ["A", "B", "D"],+ "participants": ["A", "B", "C"],+ "attribution": {+ "version": 1,+ "beneficiaryObservationIds": ["A", "B"],+ "contextObservationIds": ["C"]+ }+ },+ {+ "anchors": ["A", "B", "D"],+ "participants": ["A", "C"],+ "attribution": {+ "version": 1,+ "beneficiaryObservationIds": ["A"],+ "contextObservationIds": ["C"]+ }+ },+ {+ "anchors": ["A", "B", "D"],+ "participants": ["A", "B"],+ "attribution": {+ "version": 1,+ "beneficiaryObservationIds": ["A", "B"],+ "contextObservationIds": []+ }+ },+ {+ "anchors": ["A"],+ "participants": ["A", "D"],+ "attribution": {+ "version": 1,+ "beneficiaryObservationIds": ["A"],+ "contextObservationIds": ["D"]+ }+ }+]