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
fix(remediation)!: use the CLI verdict contract for hosted verification (#1951)
mluck-openaib88e775a6c7b
diff --git a/sdk/typescript/docs/hosted-remediation.md b/sdk/typescript/docs/hosted-remediation.mdindex 3d379826a..9b4d827ae 100644--- a/sdk/typescript/docs/hosted-remediation.md+++ b/sdk/typescript/docs/hosted-remediation.md@@ -78,22 +78,22 @@ result validation finished; it does not imply that a patch fixed the finding:require a reason. The host must inspect the actual changes, collect thecanonical diff, and run separate verification.- `verification` contains `id`, `status` (`fixed`, `still_vulnerable`, or- `inconclusive`), nonempty `evidence`, and a nonempty `checks` array. Each check- contains a nonempty `name`, `status` (`passed`, `failed`, or `not_run`),- nonempty `evidence`, and optional `command`. Names and evidence distinguish- static assessment from executed tests; `command` records an actual attempted- command, not a suggestion. A required check that could not be completed is- `not_run` with its blocker in `evidence`. An inconclusive result is preserved- as an assessment outcome rather than converted to execution failure.--Hosted verification requests these checks explicitly and rejects a result with-missing or empty checks, or a `fixed` verdict with a failed or unrun check. The-model must report the required vulnerability and legitimate-behavior checks;-the SDK does not reconstruct checks from prose. A malformed result retains the-execution receipt and returns `status: "failed"` with `INVALID_RESULT`, rather-than claiming verification succeeded. Shared result types keep `checks`-optional for older and local results; the local CLI command and result contract-are unchanged.+ `inconclusive`), and nonempty `evidence`, the same fields used by local+ `verify-fix`. The finding ID must match the request. A `fixed` verdict needs+ evidence that the original exploit path is closed and legitimate behavior+ still works. If the selected mode cannot establish that, use `inconclusive`+ unless the evidence shows the finding is still vulnerable.++Hosted and local verification use the same verdict parser and do not require+`checks`. At the hosted boundary, a `fixed` verdict is rejected if a nonempty+`checks` array matches the SDK 0.6.0 check format and reports a `failed` or+`not_run` required check. Other extra fields are ignored.++When upgrading from SDK 0.6.0, remove imports of `FindingVerificationCheck`+and read `verification.status` and `verification.evidence`. The SDK no longer+returns `verification.checks`. The executor's original report, when supplied,+remains in `execution.finalResponse`. Invalid or contradictory verdicts return+`INVALID_RESULT` with the execution receipt.The host owns durable attempts, cancellation/reconciliation, usage, artifactstorage and publication. No operation publishes a pull request or marks adiff --git a/sdk/typescript/src/hosted-remediation.ts b/sdk/typescript/src/hosted-remediation.tsindex db9f12822..902abbd81 100644--- a/sdk/typescript/src/hosted-remediation.ts+++ b/sdk/typescript/src/hosted-remediation.ts@@ -124,7 +124,6 @@ export async function runHostedRemediation({ occurrenceId: input.finding.id, context: input.finding.context },],structuredPatch: true,- structuredVerification: true,verificationIds: [input.finding.id],instructions: input.instructions,validationInstructions: input.validationInstructions,@@ -180,11 +179,7 @@ export async function runHostedRemediation(input.operation === "patch"? { patch: parseFindingPatch(response, input.finding.id) }: {- verification: parseFindingVerifications(- response,- [input.finding.id],- { requireChecks: true },- )[0]!,+ verification: parseHostedVerification(response, input.finding.id),};return { ...base, status: "completed", execution, ...outcome };} catch (error) {@@ -199,3 +194,25 @@ export async function runHostedRemediation(};}}++function parseHostedVerification(response: string, findingId: string) {+ const verification = parseFindingVerifications(response, [findingId])[0]!;+ if (verification.status !== "fixed") return verification;+ // Recognize SDK 0.6.0 checks in the original report without requiring them.+ const checks = z+ .array(+ z.object({+ name: z.string().trim().min(1),+ status: z.enum(["passed", "failed", "not_run"]),+ evidence: z.string().trim().min(1),+ command: z.string().trim().min(1).optional(),+ }),+ )+ .safeParse(JSON.parse(response).results[0].checks);+ if (checks.success && checks.data.some(({ status }) => status !== "passed")) {+ throw new Error(+ "A fixed verification result contradicts a failed or unrun required check.",+ );+ }+ return verification;+}diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex c8364acdb..7c9cc96e3 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -19,11 +19,7 @@ export type {RemediationExecutionEvent,} from "./hosted-remediation.js";export { runHostedRemediationProtocol } from "./hosted-remediation-protocol.js";-export type {- FindingPatch,- FindingVerification,- FindingVerificationCheck,-} from "./remediation.js";+export type { FindingPatch, FindingVerification } from "./remediation.js";export {runHostedScan,HostedScanInputSchema,diff --git a/sdk/typescript/src/remediation.ts b/sdk/typescript/src/remediation.tsindex 37d6e3307..971b9c448 100644--- a/sdk/typescript/src/remediation.ts+++ b/sdk/typescript/src/remediation.ts@@ -13,22 +13,10 @@ export const FindingPatchSchema = z.object({export type FindingPatch = z.infer<typeof FindingPatchSchema>;-export const FindingVerificationCheckSchema = z.object({- name: z.string().trim().min(1),- status: z.enum(["passed", "failed", "not_run"]),- evidence: z.string().trim().min(1),- command: z.string().trim().min(1).optional(),-});--export type FindingVerificationCheck = z.infer<- typeof FindingVerificationCheckSchema->;-export const FindingVerificationSchema = z.object({id: z.string(),status: z.enum(["fixed", "still_vulnerable", "inconclusive"]),evidence: z.string().trim().min(1),- checks: z.array(FindingVerificationCheckSchema).optional(),});export type FindingVerification = z.infer<typeof FindingVerificationSchema>;@@ -43,7 +31,6 @@ export interface RemediationPromptInput {pluginRoot: string;contents: readonly unknown[];structuredPatch?: boolean;- structuredVerification?: boolean;verificationIds?: readonly string[];findingInstructions?: Readonly<Record<string, string>>;instructions?: string;@@ -71,12 +58,6 @@ export async function remediationPrompt(input: RemediationPromptInput) {`Expected result identifiers (JSON array): ${JSON.stringify(input.verificationIds)}`,"Return exactly one evidence-backed result per expected identifier in the same order, following the skill's JSON result contract.",);- if (input.structuredVerification) {- prompt.push(- 'For hosted verification, extend each result with a nonempty "checks" array: {"name":"specific check name","status":"passed|failed|not_run","evidence":"specific source, observed result, or blocker","command":"exact command, only when one was attempted"}. Retain the skill\'s id, status, and evidence fields. Report the checks needed to establish that the original vulnerability is fixed and legitimate behavior remains intact, including all requested validation checks within the selected verification scope.',- 'Distinguish static source assessment from executed tests in each check\'s name and evidence. Do not invent commands, tests, or passing checks from a prose summary. Use "passed" only for a completed check supported by evidence, "failed" for a completed check that did not pass, and "not_run" when a required check could not be completed, with the blocker in evidence. Omit command for static assessment and checks that were not attempted. Use "fixed" only when all required checks passed; unavailable or omitted required checks, an unproven legitimate control, and other material proof gaps require "inconclusive". Preserve the read-only boundary.',- );- }} else {prompt.push(`Use the bundled $codex-security:fix-finding skill at ${JSON.stringify(join(input.pluginRoot, "skills", "fix-finding", "SKILL.md"))}.`,@@ -125,7 +106,6 @@ export async function remediationPrompt(input: RemediationPromptInput) {export function parseFindingVerifications(response: string,identifiers: readonly string[],- options: { requireChecks?: boolean } = {},): FindingVerification[] {let reported: unknown;try {@@ -134,13 +114,7 @@ export function parseFindingVerifications(throw new CodexSecurityError("Verification results were not valid JSON.");}const parsed = z- .object({- results: z.array(- options.requireChecks- ? FindingVerificationSchema- : FindingVerificationSchema.omit({ checks: true }),- ),- })+ .object({ results: z.array(FindingVerificationSchema) }).safeParse(reported);if (!parsed.success ||@@ -151,21 +125,7 @@ export function parseFindingVerifications("Codex did not return an evidence-backed verification result for every finding.",);}- const results: FindingVerification[] = parsed.data.results;- if (- options.requireChecks &&- results.some(- ({ status, checks }) =>- !checks?.length ||- (status === "fixed" &&- checks.some((check) => check.status !== "passed")),- )- ) {- throw new CodexSecurityError(- "Hosted verification requires evidence-backed checks; a fixed result requires every reported check to pass.",- );- }- return results;+ return parsed.data.results;}export function parseFindingPatch(diff --git a/sdk/typescript/tests-ts/hosted-remediation.test.ts b/sdk/typescript/tests-ts/hosted-remediation.test.tsindex 52a053822..9e3ba41e3 100644--- a/sdk/typescript/tests-ts/hosted-remediation.test.ts+++ b/sdk/typescript/tests-ts/hosted-remediation.test.ts@@ -7,10 +7,7 @@ import {type HostedRemediationInput,type RemediationExecutor,} from "../src/index.js";-import {- parseFindingPatch,- parseFindingVerifications,-} from "../src/remediation.js";+import { parseFindingPatch } from "../src/remediation.js";import { main } from "../src/cli.js";import { capture, dependencies } from "./cli-fixtures.js";import { git } from "./git-fixture.js";@@ -20,7 +17,6 @@ import { parseJsonLines } from "./support/json.js";import { rejecting } from "./support/errors.js";import {exerciseRemediationProtocol,- passedChecks,remediationInput,remediationReceipt as receipt,verificationResult,@@ -64,7 +60,6 @@ test.each([};const evidence ="guard.ts rejects unauthorized requests before dispatch and preserves authorized callers. Runtime checks were not performed.";- const staticChecks = [{ ...passedChecks[1]!, evidence }];const run = mock<RemediationExecutor["run"]>(async (request, options) => {expect(request).toMatchObject({operation,@@ -84,6 +79,8 @@ test.each([? "$codex-security:fix-finding": "$codex-security:verify-fix",);+ if (operation === "verify")+ expect(request.prompt).not.toContain('"checks"');options.onEvent?.({ type: "activity", description: "Checking guard" });if (!staticVerification) return receipt(request);expect(request.prompt).toContain("Verification mode: static");@@ -108,9 +105,7 @@ test.each([],}: {- results: [- { ...verificationResult, evidence, checks: staticChecks },- ],+ results: [{ ...verificationResult, evidence }],},),});@@ -137,10 +132,6 @@ test.each([expect(result.patch?.verification ?? result.verification?.evidence).toBe(staticVerification ? evidence : verificationResult.evidence,);- if (operation === "verify")- expect(result.verification?.checks).toEqual(- staticVerification ? staticChecks : passedChecks,- );if (!staticVerification) {await runHostedRemediation({ ...input, verificationMode: "standard" },@@ -152,59 +143,65 @@ test.each([);test.each([- ["still_vulnerable", "failed"],- ["inconclusive", "not_run"],+ {+ status: "still_vulnerable",+ evidence: "The alternate route still reaches the unguarded handler.",+ },+ {+ status: "inconclusive",+ evidence:+ "The source does not establish whether authorized callers still work.",+ },+ { checks: [{ status: "not_run" }] },] as const)(- "verification preserves %s with a %s check",- (status, checkStatus) => {- const verification = {- ...verificationResult,- status,- checks: [{ ...passedChecks[0]!, status: checkStatus }],+ "hosted static verification preserves the CLI verdict for %p",+ async (fields) => {+ const input = {+ ...(await fixture("verify")),+ verificationMode: "static" as const,};- expect(- parseFindingVerifications(- JSON.stringify({ results: [verification] }),- [verification.id],- {- requireChecks: true,- },- ),- ).toEqual([verification]);+ const verdict = { ...verificationResult, ...fields };+ const result = await runHostedRemediation(input, {+ executor: {+ run: async (request) =>+ receipt(request, {+ finalResponse: JSON.stringify({ results: [verdict] }),+ }),+ },+ });+ expect(result.status).toBe("completed");+ const { id, status, evidence } = verdict;+ expect(result.verification).toEqual({ id, status, evidence });},);-test("local verification ignores extra hosted checks", () => {- const { checks: _, ...verification } = verificationResult;- expect(- parseFindingVerifications(- JSON.stringify({- results: [{ ...verification, checks: [{ result: "legacy summary" }] }],- }),- [verification.id],- ),- ).toEqual([verification]);-});-test.each([- ["missing", undefined],- ["empty", []],- ["missing evidence", [{ ...passedChecks[0], evidence: " " }]],- ["missing name", [{ ...passedChecks[0], name: " " }]],- ["failed", [{ ...passedChecks[0], status: "failed" }]],- ["not run", [{ ...passedChecks[0], status: "not_run" }]],-])(- "hosted verification rejects fixed results with %s checks",- (_name, checks) => {- expect(() =>- parseFindingVerifications(- JSON.stringify({ results: [{ ...verificationResult, checks }] }),- [verificationResult.id],- { requireChecks: true },- ),- ).toThrow();+ {+ name: "Replay original request",+ status: "failed",+ evidence: "The unauthorized request returned 200.",+ command: "bun test tests/authorization.test.ts",},-);+ {+ name: "Required legitimate-user control",+ status: "not_run",+ evidence: "The test runner is unavailable.",+ },+])("hosted verification rejects fixed with a $status check", async (check) => {+ const finalResponse = JSON.stringify({+ results: [{ ...verificationResult, checks: [check] }],+ });+ const result = await runHostedRemediation(await fixture("verify"), {+ executor: { run: async (request) => receipt(request, { finalResponse }) },+ });+ expect(result.status).toBe("failed");+ expect(result.error?.code).toBe("INVALID_RESULT");+ expect(result.verification).toBeUndefined();+ expect(result.execution).toMatchObject({+ sessionId: "host-session",+ finalResponse,+ });+});test.each([{ status: "verified", verification: undefined },diff --git a/sdk/typescript/tests-ts/support/hosted-remediation.mjs b/sdk/typescript/tests-ts/support/hosted-remediation.mjsindex 16bb09208..6eda3a600 100644--- a/sdk/typescript/tests-ts/support/hosted-remediation.mjs+++ b/sdk/typescript/tests-ts/support/hosted-remediation.mjs@@ -2,27 +2,11 @@ import assert from "node:assert/strict";import { spawn } from "node:child_process";import { createInterface } from "node:readline";-/** @type {import("../../src/remediation.js").FindingVerificationCheck[]} */-export const passedChecks = [- {- name: "Authorization regression tests",- status: "passed",- command: "bun test tests/authorization.test.ts",- evidence: "Original request rejected; legitimate control passed.",- },- {- name: "Static assessment of equivalent authorization paths",- status: "passed",- evidence: "All handlers in guard.ts use the shared authorization check.",- },-];-/** @type {import("../../src/remediation.js").FindingVerification} */export const verificationResult = {id: "finding-1",status: "fixed",evidence: "Original request rejected; legitimate control passed.",- checks: passedChecks,};/**@@ -167,10 +151,11 @@ export async function exerciseRemediationProtocol(if (!cancel) {if (input.operation === "patch")assert.equal(result.patch.status, "verified");- else {- assert.equal(result.verification.status, "fixed");- assert.deepEqual(result.verification.checks, passedChecks);- }+ else+ assert.deepEqual(result.verification, {+ ...verificationResult,+ id: input.finding.id,+ });}return result;} finally {