Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat(sdk): accept a host-supplied severity rubric for Standard scans (#2253)

Aismit205684e64b7a
diff --git a/sdk/typescript/docs/hosted-scans.md b/sdk/typescript/docs/hosted-scans.md
index dc49252bf..83169ff08 100644
--- a/sdk/typescript/docs/hosted-scans.md
+++ b/sdk/typescript/docs/hosted-scans.md
@@ -74,6 +74,18 @@ Standard scan lifecycle. Omit `scope` for the entire repository, or pass literal
repository-relative folders/files. Model settings come from the frozen input;
local profiles and other local scan options are not accepted.
+To supply grading rules, pass `severityRubric` with the Markdown text in
+`markdown`, a positive integer `revision`, and the lowercase `sha256` digest of
+the exact UTF-8 text, including any trailing newline. The SDK verifies the digest
+before dispatch, includes the rubric in the model prompt, and echoes the snapshot
+in `execution.run` and the terminal scan receipt. Omit the field to use the
+existing Standard scan grading rules.
+
+When a logical run spans multiple attempts, save the selected snapshot in the
+host's durable run state before starting its first CLI process. Send that saved
+snapshot with every subsequent attempt for the same run, including attempts in
+a fresh checkout or container. A configuration change then applies to new runs.
+
Set `ownerSuggestions: true` to record ownership evidence during the existing
scan execution. The scan agent may include an optional hint on each finding:
@@ -271,7 +283,10 @@ with `{id: <original run RPC id>, event}`. Invalid optional event payloads are
ignored; mismatched request IDs are rejected. Stdout contains JSON-RPC only.
Send `{"jsonrpc":"2.0","method":"cancel","params":{"id":"run"}}` with the
-original run request ID. The CLI aborts its executor signal, emits
+original run request ID. If canceled during checkout verification, the CLI returns
+a canceled receipt with the requested checkout, scope, and rubric before starting
+the executor. Invalid request fields still return a JSON-RPC error.
+After dispatch the CLI aborts its executor signal, emits
`execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
before returning a canceled result. The host must continue reading notifications
while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
diff --git a/sdk/typescript/schemas/hosted-scan-v2.fixture.json b/sdk/typescript/schemas/hosted-scan-v2.fixture.json
index 9bf196867..f1060f81e 100644
--- a/sdk/typescript/schemas/hosted-scan-v2.fixture.json
+++ b/sdk/typescript/schemas/hosted-scan-v2.fixture.json
@@ -14,6 +14,11 @@
"stateDirectory": "/scan/state",
"model": "fixture-model",
"reasoningEffort": "medium",
+ "severityRubric": {
+ "markdown": "# Security team rubric\n\nGrade the impact on the affected tenant.\n",
+ "revision": 3,
+ "sha256": "0735ad8680e64cc58dae0f2ac171cfbe98816494176fe95ca28b122476b61cfa"
+ },
"identity": {
"runId": "run-1",
"attemptId": "attempt-1",
@@ -39,9 +44,14 @@
},
"model": "fixture-model",
"reasoningEffort": "medium",
+ "severityRubric": {
+ "markdown": "# Security team rubric\n\nGrade the impact on the affected tenant.\n",
+ "revision": 3,
+ "sha256": "0735ad8680e64cc58dae0f2ac171cfbe98816494176fe95ca28b122476b61cfa"
+ },
"requestId": "request-1",
"scanId": "scan-1",
- "prompt": "Scan the selected paths.",
+ "prompt": "Scan the selected paths using the supplied severity rubric.\n{\"severityRubric\":{\"markdown\":\"# Security team rubric\\n\\nGrade the impact on the affected tenant.\\n\",\"revision\":3,\"sha256\":\"0735ad8680e64cc58dae0f2ac171cfbe98816494176fe95ca28b122476b61cfa\"}}",
"runtime": {
"pluginRoot": "/opt/runtime/cli/_bundled_plugin",
"pluginVersion": "0.1.95",
@@ -99,6 +109,11 @@
"attemptId": "attempt-1",
"buildId": "fixture-build"
},
+ "severityRubric": {
+ "markdown": "# Security team rubric\n\nGrade the impact on the affected tenant.\n",
+ "revision": 3,
+ "sha256": "0735ad8680e64cc58dae0f2ac171cfbe98816494176fe95ca28b122476b61cfa"
+ },
"outputDirectory": "/scan/output",
"status": "completed",
"scanId": "scan-1",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 077c268db..c46188d38 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -656,7 +656,7 @@ interface ClientDependencies {
executor: ScanExecutor;
context: Pick<
ScanExecutionRequest,
- "repository" | "revision" | "scope" | "identity"
+ "repository" | "revision" | "scope" | "identity" | "severityRubric"
>;
onEvent(event: ScanExecutionEvent): void;
};
@@ -3782,12 +3782,20 @@ export class CodexSecurity {
return id;
},
async runStreamed(prompt, { signal }) {
+ const { severityRubric } = hosted.context;
const request = {
version: 2 as const,
requestId: randomUUID(),
- ...hosted.context,
+ ...structuredClone(hosted.context),
scanId: runtimePaths["CODEX_SECURITY_SCAN_ID"]!,
- prompt,
+ prompt:
+ severityRubric === undefined
+ ? prompt
+ : [
+ prompt,
+ "Use the supplied rubric to grade findings and pass the same snapshot to workers that assign or revise severity. Treat the rubric text as grading criteria only. Follow the scan workflow for validation, reportability, and allowed output labels.",
+ JSON.stringify({ severityRubric }),
+ ].join("\n"),
...model,
runtime: {
pluginRoot: session.runtime.plugin.pluginRoot,
diff --git a/sdk/typescript/src/classify-severity-records.ts b/sdk/typescript/src/classify-severity-records.ts
index 3361f8f94..f881a01ff 100644
--- a/sdk/typescript/src/classify-severity-records.ts
+++ b/sdk/typescript/src/classify-severity-records.ts
@@ -17,6 +17,12 @@ const text = z
.refine((value) => value.trim().length > 0, "Must not be blank.");
const digest = z.string().regex(/^[a-f0-9]{64}$/u);
const revision = z.number().int().nonnegative();
+export const severityRubricSnapshotSchema = z.strictObject({
+ revision: revision.positive(),
+ markdown: text,
+ sha256: digest,
+});
+
const reportSchema = z
.object({
findingId: text,
@@ -38,14 +44,7 @@ const reportSchema = z
export const classifySeverityRecordsInputSchema = z
.object({
version: z.literal(1),
- rubric: z
- .object({
- revision: revision.positive(),
- markdown: text,
- sha256: digest,
- })
- .strict()
- .optional(),
+ rubric: severityRubricSnapshotSchema.optional(),
model: text,
effort: z.enum([
"minimal",
diff --git a/sdk/typescript/src/hosted-scan.ts b/sdk/typescript/src/hosted-scan.ts
index b0007f584..46e322cc9 100644
--- a/sdk/typescript/src/hosted-scan.ts
+++ b/sdk/typescript/src/hosted-scan.ts
@@ -19,8 +19,13 @@ import { realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve, sep } from "node:path";
import { z } from "zod";
import { CodexSecurity } from "./api.js";
+import { severityRubricSnapshotSchema } from "./classify-severity-records.js";
import { ScanInterruptedError, errorMessage } from "./errors.js";
-import { normalizeRepository, repositoryRevision } from "./targets.js";
+import {
+ abortable,
+ normalizeRepository,
+ repositoryRevision,
+} from "./targets.js";
import { isWithin } from "./trusted-executable.js";
/** Hosted v2 mirrors repository/paths targets; only Standard scans are supported. */
@@ -35,6 +40,12 @@ export const HostedScanInputSchema = z.strictObject({
stateDirectory: z.string().min(1),
model: z.string().min(1),
reasoningEffort: z.string(),
+ severityRubric: severityRubricSnapshotSchema
+ .refine(
+ ({ markdown, sha256 }) => hash("sha256", markdown) === sha256,
+ "Rubric SHA-256 does not match its exact UTF-8 Markdown.",
+ )
+ .optional(),
ownerSuggestions: z.boolean().optional(),
identity: z.strictObject({
runId: z.string().min(1),
@@ -110,21 +121,24 @@ export function normalizeHostedPaths(
}
/** Validate every path at the frozen commit before registering a scan/executing. */
-async function prepareHostedScan(input: HostedScanInput, signal?: AbortSignal) {
- const scope = { paths: normalizeHostedPaths(input.scope?.paths) };
+async function prepareHostedRepository(
+ input: Pick<ScanExecutionRequest, "repository" | "revision" | "scope">,
+ signal?: AbortSignal,
+) {
const repository = await normalizeRepository(input.repository, signal);
if ((await repositoryRevision(repository, signal)) !== input.revision)
throw new HostedScanPreparationError(
"revision_mismatch",
"Checkout does not match the frozen revision.",
);
- for (const path of scope.paths) {
+ for (const path of input.scope.paths) {
const selected = resolve(repository, path);
let target: string;
try {
- target = await realpath(selected);
+ target = await abortable(() => realpath(selected), signal);
} catch (error) {
if (
+ (signal?.aborted && error === signal.reason) ||
!(error instanceof Error) ||
!("code" in error) ||
error.code !== "ENOENT"
@@ -149,12 +163,7 @@ async function prepareHostedScan(input: HostedScanInput, signal?: AbortSignal) {
);
}
}
- return {
- repository,
- revision: input.revision,
- scope,
- identity: input.identity,
- };
+ return repository;
}
function hostedScanEnvironment(stateDirectory: string): Record<string, string> {
@@ -195,10 +204,54 @@ export async function runHostedScan(
options: HostedScanOptions,
) {
const input = HostedScanInputSchema.parse(value);
- const context = await prepareHostedScan(input, options.signal);
+ const context = {
+ repository: input.repository,
+ revision: input.revision,
+ scope: { paths: normalizeHostedPaths(input.scope?.paths) },
+ identity: input.identity,
+ ...(input.severityRubric === undefined
+ ? {}
+ : { severityRubric: input.severityRubric }),
+ };
let execution: ScanExecutionResult | undefined;
let request: ScanExecutionRequest | undefined;
let scanId: string | undefined;
+ let outputDirectory = resolve(input.outputDirectory);
+ const base = () => ({
+ version: 2 as const,
+ ...context,
+ outputDirectory,
+ ...(scanId === undefined ? {} : { scanId }),
+ ...(request === undefined
+ ? {}
+ : {
+ pluginVersion: request.runtime.pluginVersion,
+ }),
+ provenance: {
+ cliVersion: VERSION,
+ buildId: input.identity.buildId,
+ ...(request === undefined
+ ? {}
+ : { pluginVersion: request.runtime.pluginVersion }),
+ },
+ ...(execution === undefined ? {} : { execution }),
+ });
+ try {
+ context.repository = await prepareHostedRepository(context, options.signal);
+ } catch (error) {
+ if (
+ options.signal?.aborted &&
+ (Object.is(error, options.signal.reason) ||
+ (error instanceof DOMException && error.name === "AbortError"))
+ )
+ return {
+ ...base(),
+ status: "canceled" as const,
+ error: `Canceled before checkout verification finished: ${errorMessage(error)}`,
+ artifacts: [],
+ };
+ throw error;
+ }
const onEvent = (event: ScanExecutionEvent): void => {
void Promise.resolve()
.then(() => options.onEvent?.(event))
@@ -230,26 +283,6 @@ export async function runHostedScan(
},
{ surface: "sdk" },
);
- let outputDirectory = resolve(input.outputDirectory);
- const base = () => ({
- version: 2 as const,
- ...context,
- outputDirectory,
- ...(scanId === undefined ? {} : { scanId }),
- ...(request === undefined
- ? {}
- : {
- pluginVersion: request.runtime.pluginVersion,
- }),
- provenance: {
- cliVersion: VERSION,
- buildId: input.identity.buildId,
- ...(request === undefined
- ? {}
- : { pluginVersion: request.runtime.pluginVersion }),
- },
- ...(execution === undefined ? {} : { execution }),
- });
try {
const result = await client.run(context.repository, {
target:
diff --git a/sdk/typescript/src/scan-executor.ts b/sdk/typescript/src/scan-executor.ts
index 8761e2fb4..45715aa57 100644
--- a/sdk/typescript/src/scan-executor.ts
+++ b/sdk/typescript/src/scan-executor.ts
@@ -1,4 +1,5 @@
import { z } from "zod";
+import type { severityRubricSnapshotSchema } from "./classify-severity-records.js";
import { CodexSecurityError } from "./errors.js";
import type { ScanActivity } from "./scan-activity.js";
import { scanPhaseSchema, type ScanProgress } from "./worker-progress.js";
@@ -12,6 +13,7 @@ export interface ScanExecutionRequest {
revision: string;
scope: { paths: string[] };
identity: { runId: string; attemptId: string; buildId: string };
+ severityRubric?: z.infer<typeof severityRubricSnapshotSchema>;
prompt: string;
model: string;
reasoningEffort: string;
diff --git a/sdk/typescript/tests-ts/hosted-scan.test.ts b/sdk/typescript/tests-ts/hosted-scan.test.ts
index fd5805d9e..03307fd5b 100644
--- a/sdk/typescript/tests-ts/hosted-scan.test.ts
+++ b/sdk/typescript/tests-ts/hosted-scan.test.ts
@@ -13,6 +13,7 @@ import {
import { tmpdir } from "node:os";
import { delimiter, dirname, isAbsolute, join } from "node:path";
import { afterEach, expect, mock, spyOn, test } from "bun:test";
+import hostedContract from "../schemas/hosted-scan-v2.fixture.json" with { type: "json" };
import {
normalizeHostedScope,
normalizeHostedPaths,
@@ -48,6 +49,7 @@ import { parseJsonLines, readJson, writeJson } from "./support/json.js";
import { rejecting } from "./support/errors.js";
import { writeSource } from "./support/shell.js";
+const { severityRubric } = hostedContract.run.params;
const { cleanup, temporaryDirectory } = createApiTestFixtures("hosted-scan-");
afterEach(cleanup);
@@ -554,7 +556,10 @@ test.each(["missing", "file"] as const)(
signal: controller.signal,
});
if (timing === "during") queueMicrotask(() => controller.abort(reason));
- await expect(pending).rejects.toBe(reason);
+ await expect(pending).resolves.toMatchObject({
+ status: "canceled",
+ error: expect.stringContaining(reason.message),
+ });
}
for (const options of [{}, { signal: new AbortController().signal }]) {
await expect(
@@ -755,12 +760,14 @@ test("hosted receipts hash MCP checkpoints as written", async () => {
test("a changed checkout cannot produce accepted completed output", async () => {
const input = await fixture();
+ input.severityRubric = severityRubric;
const result = await runHostedScan(input, {
executor: draftExecutor(() => {
git(input.repository, "commit", "--allow-empty", "-qm", "changed");
}),
});
expect(result.status).toBe("failed");
+ expect(result.severityRubric).toEqual(severityRubric);
expect(result.artifacts).toEqual([]);
});
@@ -768,6 +775,53 @@ test("malformed run input returns one protocol error", async () => {
expect((await protocolError({ version: 2 })).code).toBe(-32602);
});
+test.each(["valid", "tampered"] as const)(
+ "scan --host receives an immediate cancellation with a %s rubric",
+ async (rubric) => {
+ const params = await fixture();
+ params.severityRubric =
+ rubric === "valid"
+ ? severityRubric
+ : { ...severityRubric, markdown: severityRubric.markdown.trimEnd() };
+ const input = new PassThrough();
+ const output = capture();
+ const run = main(["scan", "--host"], output.stream, capture().stream, {
+ ...dependencies(),
+ recordsInput: input,
+ });
+ try {
+ send(input, { id: "run", method: "run", params });
+ send(input, { method: "cancel", params: { id: "run" } });
+ expect(await run).toBe(rubric === "valid" ? 1 : 2);
+ const messages = parseJsonLines(output.text());
+ expect(messages).toHaveLength(1);
+ expect(messages[0]).toMatchObject({ jsonrpc: "2.0", id: "run" });
+ if (rubric === "tampered") {
+ expect(messages[0].error).toMatchObject({
+ code: -32602,
+ message: expect.stringContaining("SHA-256"),
+ });
+ } else {
+ expect(messages[0].result).toMatchObject({
+ status: "canceled",
+ identity: params.identity,
+ repository: params.repository,
+ revision: params.revision,
+ scope: params.scope,
+ severityRubric,
+ outputDirectory: params.outputDirectory,
+ provenance: { buildId: params.identity.buildId },
+ artifacts: [],
+ });
+ expect(messages[0].result).not.toHaveProperty("scanId");
+ expect(messages[0].result).not.toHaveProperty("execution");
+ }
+ } finally {
+ input.destroy();
+ }
+ },
+);
+
test.each([
{ path: "missing", reason: "scope_missing" },
{ path: "C:part.ts", reason: "scope_syntax" },
@@ -803,6 +857,7 @@ test.each([false, true])(
if (!cancel) {
input.reasoningEffort = "synthetic-future-effort";
input.ownerSuggestions = true;
+ input.severityRubric = severityRubric;
}
const child = spawn(
process.execPath,
@@ -834,6 +889,15 @@ test.each([false, true])(
messages.push(message);
if (message.method === "execution.run") {
expect(message.params.reasoningEffort).toBe(input.reasoningEffort);
+ if (cancel) {
+ expect(message.params).not.toHaveProperty("severityRubric");
+ expect(message.params.prompt).not.toContain('"severityRubric"');
+ } else {
+ expect(message.params.severityRubric).toEqual(severityRubric);
+ expect(message.params.prompt).toContain(
+ JSON.stringify({ severityRubric: message.params.severityRubric }),
+ );
+ }
requestId = message.params.requestId;
for (const event of [
progressEvent,
@@ -886,7 +950,10 @@ test.each([false, true])(
execution: { sessionId: "fake-host", usage },
},
});
- if (!cancel) {
+ if (cancel) {
+ expect(response.result).not.toHaveProperty("severityRubric");
+ } else {
+ expect(response.result.severityRubric).toEqual(severityRubric);
expect(response.result).not.toHaveProperty("ownerSuggestionsError");
expect(response.result.artifacts).toContainEqual(
expect.objectContaining({ path: "owner-suggestions.json" }),
@@ -1235,10 +1302,13 @@ test("cancellation after registration retains scan identity before executor disp
test("SDK cancellation waits for the executor receipt without losing known session/usage", async () => {
const input = await fixture();
const controller = new AbortController();
- const result = await runHostedScan(input, {
+ input.severityRubric = { ...severityRubric };
+ const pending = runHostedScan(input, {
signal: controller.signal,
executor: {
async run(request, options) {
+ expect(request.severityRubric).toEqual(severityRubric);
+ Reflect.set(request.severityRubric!, "markdown", "Edited by executor.");
controller.abort();
expect(options.signal.aborted).toBe(true);
await Promise.resolve();
@@ -1250,7 +1320,10 @@ test("SDK cancellation waits for the executor receipt without losing known sessi
},
},
});
+ input.severityRubric.markdown = "Edited by caller.";
+ const result = await pending;
expect(result.status).toBe("canceled");
+ expect(result.severityRubric).toEqual(severityRubric);
expect(result.execution).toMatchObject({
status: "canceled",
sessionId: "canceled-session",
@@ -1301,6 +1374,50 @@ test("same Cloud attempt does not create CLI cross-invocation replay decisions",
expect(requests[0]).not.toBe(requests[1]);
});
+test("a host retry can resupply the saved rubric in a fresh attempt", async () => {
+ const input = await fixture();
+ const saved = join(dirname(input.repository), "host-rubric.json");
+ await writeJson(saved, severityRubric);
+ const requestIds = new Set<string>();
+ for (const [attemptId, status] of [
+ ["first", "canceled"],
+ ["retry", "completed"],
+ ] as const) {
+ const identity = { ...input.identity, attemptId };
+ const executor = {
+ run: mock<ScanExecutor["run"]>(async (request) => {
+ if (status === "completed") await writeDraft(request);
+ return receipt(request, { status });
+ }),
+ };
+ const result = await runHostedScan(
+ {
+ ...input,
+ identity,
+ outputDirectory: join(input.outputDirectory, attemptId),
+ stateDirectory: join(input.stateDirectory, attemptId),
+ severityRubric: await readJson<typeof severityRubric>(saved),
+ },
+ { executor },
+ );
+ expect(executor.run).toHaveBeenCalledTimes(1);
+ const [request] = executor.run.mock.calls[0]!;
+ expect(request.identity).toEqual(identity);
+ expect(request.severityRubric).toEqual(severityRubric);
+ expect(request.prompt).toContain(
+ JSON.stringify({ severityRubric: request.severityRubric }),
+ );
+ expect(result).toMatchObject({
+ identity,
+ status,
+ severityRubric,
+ execution: { requestId: request.requestId, status },
+ });
+ requestIds.add(request.requestId);
+ }
+ expect(requestIds.size).toBe(2);
+});
+
test.each(["cancel", "disconnect", "signal"])(
"blocked execution request terminates on %s",
async (action) => {
@@ -1361,10 +1478,11 @@ test.each(["result", "error"])(
);
test("the exported contract fixture matches v2 and rejects explicit empty scope", async () => {
- const fixture = await readJson<any>(
- join(import.meta.dirname, "../schemas/hosted-scan-v2.fixture.json"),
- );
- expect(HostedScanInputSchema.parse(fixture.run.params).scope).toEqual({
+ const fixture = hostedContract;
+ const input = HostedScanInputSchema.parse(fixture.run.params);
+ expect(input.severityRubric).toEqual(severityRubric);
+ expect(fixture.execution.params.severityRubric).toEqual(severityRubric);
+ expect(input.scope).toEqual({
paths: ["service-a", "service-b"],
});
expect(
@@ -1383,6 +1501,7 @@ test("the exported contract fixture matches v2 and rejects explicit empty scope"
status: "completed",
identity: fixture.run.params.identity,
scope: fixture.run.params.scope,
+ severityRubric,
scanId: fixture.execution.params.scanId,
execution: ScanExecutionResultSchema.parse(fixture.response.result),
});