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

refactor(sdk): derive result interfaces from schemas (#1579)

Michael D'Angelo92be965c51e2
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index f18ade1b9..137e5a74d 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -30,7 +30,7 @@ import {
type ThreadOptions,
type TurnOptions,
} from "@openai/codex-sdk";
-import { z } from "incur";
+import { z } from "zod";
import { readThreatModelPath } from "./artifact-export.js";
import { isRecord } from "./record.js";
import {
@@ -365,21 +365,19 @@ export interface ValidationOptions extends Pick<
finding: string | object;
}
-const VALIDATION_DISPOSITIONS = [
- "reportable",
- "suppressed",
- "not_applicable",
- "deferred",
-] as const;
-
const validationResponseSchema = z.strictObject({
- disposition: z.enum(VALIDATION_DISPOSITIONS),
+ disposition: z.enum([
+ "reportable",
+ "suppressed",
+ "not_applicable",
+ "deferred",
+ ]),
report: z.string().trim().min(1),
});
-export interface ValidationResult {
- disposition: (typeof VALIDATION_DISPOSITIONS)[number];
- report: string;
+export interface ValidationResult extends z.infer<
+ typeof validationResponseSchema
+> {
outputDir: string;
threadId: string | null;
}
@@ -4441,7 +4439,7 @@ async function collectResult(
["scan-manifest.json", "findings.json", "coverage.json", "report.md"],
signal,
);
- const { manifest, findings, coverage } = await loadContract(scanDir, {
+ const contract = await loadContract(scanDir, {
pluginRoot,
expectation,
workbenchValidated,
@@ -4459,9 +4457,7 @@ async function collectResult(
if (signal.aborted) throw signal.reason ?? error;
}
return new ScanResult({
- manifest,
- findings,
- coverage,
+ ...contract,
scanDir,
threadId,
turnResult,
diff --git a/sdk/typescript/src/classify-severity.ts b/sdk/typescript/src/classify-severity.ts
index 1ae17b83b..43154c65f 100644
--- a/sdk/typescript/src/classify-severity.ts
+++ b/sdk/typescript/src/classify-severity.ts
@@ -1,9 +1,9 @@
import { findingEntry } from "./value.js";
-import { z } from "incur";
+import { z } from "zod";
import { CodexSecurityError } from "./errors.js";
import { workflowDigest } from "./finding-workflow.js";
import { readKnowledgeBaseDocuments } from "./knowledge-base.js";
-import type { Finding, SeverityLevel } from "./models.js";
+import type { Finding } from "./models.js";
import {
runReadOnlyCodex,
type ReadOnlyCodexOptions,
@@ -35,17 +35,10 @@ export interface ClassifySeverityOptions extends Pick<
codex?: ReadOnlyCodexOptions["codex"];
}
-export interface SeverityAssessment {
- findingId: string;
+export interface SeverityAssessment extends z.infer<typeof decisionSchema> {
occurrenceId: string | null;
inputSha256: string;
source: "existing-severity" | "rubric";
- decision: "assessed" | "excluded";
- level: SeverityLevel | null;
- rubricLabel: string | null;
- rationale: string;
- confidence: "high" | "medium" | "low" | null;
- reviewTrigger: string | null;
}
export interface SeverityClassification {
diff --git a/sdk/typescript/src/component-plan.ts b/sdk/typescript/src/component-plan.ts
index 8b702b37b..afe75a30e 100644
--- a/sdk/typescript/src/component-plan.ts
+++ b/sdk/typescript/src/component-plan.ts
@@ -3,7 +3,6 @@ import { tmpdir } from "node:os";
import { join, posix } from "node:path";
import { z } from "incur";
import type { CodexSecuritySurface, ScanAuthMode } from "./api.js";
-import type { CodexSecurityConfig } from "./config.js";
import {
runReadOnlyCodex,
type ReadOnlyCodexOptions,
@@ -34,16 +33,16 @@ export interface ComponentPlan {
components: Array<{ name: string; paths: string[] }>;
}
-export interface ComponentPlanningOptions {
+export interface ComponentPlanningOptions extends Pick<
+ ReadOnlyCodexOptions,
+ "config" | "environment" | "signal"
+> {
/** @internal Calling surface, inherited from the component scan. */
surface?: CodexSecuritySurface;
/** @internal Authentication already selected by the calling scan. */
auth?: ScanAuthMode;
/** @internal Cyber access program already selected by the calling scan. */
cyberAccessProgram?: ReadOnlyCodexOptions["cyberAccessProgram"];
- config?: CodexSecurityConfig;
- environment?: NodeJS.ProcessEnv;
- signal?: AbortSignal;
/** @internal */
codex?: ReadOnlyCodexOptions["codex"];
}
diff --git a/sdk/typescript/src/custom-validation.ts b/sdk/typescript/src/custom-validation.ts
index 41087b2db..d2ab615b1 100644
--- a/sdk/typescript/src/custom-validation.ts
+++ b/sdk/typescript/src/custom-validation.ts
@@ -15,9 +15,8 @@ import type { CoverageDocument, FindingsDocument } from "./models.js";
import { requirePrivateOutputDirectory } from "./runtime.js";
import type { NormalizedTarget } from "./targets.js";
-type CanonicalFinding = FindingsDocument["findings"][number];
type Finding = Pick<
- CanonicalFinding,
+ FindingsDocument["findings"][number],
| "title"
| "locations"
| "severity"
diff --git a/sdk/typescript/src/deduplication/deduplication-reviewer.ts b/sdk/typescript/src/deduplication/deduplication-reviewer.ts
index bd6b514b1..52b3d46c7 100644
--- a/sdk/typescript/src/deduplication/deduplication-reviewer.ts
+++ b/sdk/typescript/src/deduplication/deduplication-reviewer.ts
@@ -26,32 +26,15 @@ const reviewSchema = z.discriminatedUnion("decision", [
sameSchema,
distinctSchema,
]);
-const screeningSameSchema = z.object({
- decision: z.literal("SAME"),
- rationale,
-});
-const screeningDistinctSchema = z.object({
- decision: z.literal("DISTINCT"),
- rationale,
-});
const screeningDecisionSchema = z.discriminatedUnion("decision", [
- screeningSameSchema.strict(),
- screeningDistinctSchema.strict(),
+ sameSchema.pick({ decision: true, rationale: true }).strict(),
+ distinctSchema.pick({ decision: true, rationale: true }).strict(),
]);
// The host assigns exact slot names; finding IDs stay out of model output.
const screeningSchema = z.strictObject({
decisions: z.record(z.string(), screeningDecisionSchema),
});
-function requireMergedFinding(result: DuplicateDecision): void {
- if (result.decision !== "SAME") return;
- const finding = requireFinding(result.mergedFinding);
- if (finding.findingId !== result.canonicalFindingId)
- throw new Error(
- "Every SAME decision requires the canonical finding's identity.",
- );
-}
-
export type ScreeningResult = z.infer<typeof screeningSchema>;
export type DuplicateDecision = z.infer<typeof reviewSchema>;
export type GroupingDecision = z.infer<typeof screeningDecisionSchema>;
@@ -74,9 +57,13 @@ export function validateReview(
findings: readonly Finding[],
): DuplicateDecision {
const result = reviewSchema.parse(value);
- requireMergedFinding(result);
+ if (result.decision !== "SAME") return result;
+ const finding = requireFinding(result.mergedFinding);
+ if (finding.findingId !== result.canonicalFindingId)
+ throw new Error(
+ "Every SAME decision requires the canonical finding's identity.",
+ );
if (
- result.decision === "SAME" &&
!findings.some((finding) => finding.findingId === result.canonicalFindingId)
) {
throw new Error(
@@ -105,27 +92,18 @@ export function validateScreening(
}
function screeningToolSchema(neighborCount: number): object {
- const decisionSchema = z.toJSONSchema(screeningDecisionSchema, {
- target: "openapi-3.0",
- });
- const slots = Array.from({ length: neighborCount }, (_value, index) =>
- screeningPairSlot(index),
+ const slots = Object.fromEntries(
+ Array.from({ length: neighborCount }, (_value, index) => [
+ screeningPairSlot(index),
+ screeningDecisionSchema,
+ ]),
);
- return {
- type: "object",
- properties: {
- decisions: {
- type: "object",
- properties: Object.fromEntries(
- slots.map((slot) => [slot, decisionSchema]),
- ),
- required: slots,
- additionalProperties: false,
- },
+ return z.toJSONSchema(z.strictObject({ decisions: z.strictObject(slots) }), {
+ target: "openapi-3.0",
+ override: ({ jsonSchema }) => {
+ if (jsonSchema.type === "object") jsonSchema.required ??= [];
},
- required: ["decisions"],
- additionalProperties: false,
- };
+ });
}
class CodexReviewer {
diff --git a/sdk/typescript/src/deduplication/records-protocol.ts b/sdk/typescript/src/deduplication/records-protocol.ts
index fe09faa87..a0c6c11e7 100644
--- a/sdk/typescript/src/deduplication/records-protocol.ts
+++ b/sdk/typescript/src/deduplication/records-protocol.ts
@@ -4,21 +4,19 @@ import { z } from "incur";
import { deduplicateRecords, type DeduplicateRecordsInput } from "./records.js";
const rpcId = z.union([z.string(), z.number().int()]);
-const request = z.strictObject({
- jsonrpc: z.literal("2.0"),
+const envelope = z.strictObject({ jsonrpc: z.literal("2.0") });
+const request = envelope.extend({
id: rpcId,
method: z.literal("run"),
params: z.unknown(),
});
-const cancellation = z.strictObject({
- jsonrpc: z.literal("2.0"),
+const cancellation = envelope.extend({
method: z.literal("cancel"),
params: z.strictObject({ id: rpcId }),
});
const response = z.union([
- z.strictObject({ jsonrpc: z.literal("2.0"), id: rpcId, result: z.unknown() }),
- z.strictObject({
- jsonrpc: z.literal("2.0"),
+ envelope.extend({ id: rpcId, result: z.unknown() }),
+ envelope.extend({
id: rpcId,
error: z.strictObject({
code: z.number().int(),
diff --git a/sdk/typescript/src/deduplication/records.ts b/sdk/typescript/src/deduplication/records.ts
index 5174aa072..1a36b0ed2 100644
--- a/sdk/typescript/src/deduplication/records.ts
+++ b/sdk/typescript/src/deduplication/records.ts
@@ -1,5 +1,5 @@
import { hash, randomUUID } from "node:crypto";
-import { z } from "incur";
+import { z } from "zod";
import { DeduplicationReviewError } from "../errors.js";
import type { Finding } from "../models.js";
import { abortable } from "../targets.js";
@@ -52,26 +52,20 @@ const record = z.strictObject({
finding: z.unknown().transform((value) => requireFinding(value)),
});
-const deduplicateRecordsInputSchema: z.ZodType<DeduplicateRecordsInput> =
- z.strictObject({
- version: z.literal(1),
- observations: z.array(record),
- candidateRelationships: z.array(
- z.strictObject({
- observationId: id,
- candidateObservationIds: z.array(id),
- }),
- ),
- });
+const deduplicateRecordsInputSchema = z.strictObject({
+ version: z.literal(1),
+ observations: z.array(record),
+ candidateRelationships: z.array(
+ z.strictObject({
+ observationId: id,
+ candidateObservationIds: z.array(id),
+ }),
+ ),
+});
-export interface DeduplicateRecordsInput {
- version: 1;
- observations: { id: string; finding: Finding }[];
- candidateRelationships: {
- observationId: string;
- candidateObservationIds: string[];
- }[];
-}
+export interface DeduplicateRecordsInput extends z.infer<
+ typeof deduplicateRecordsInputSchema
+> {}
export interface DeduplicateRecordsOptions {
reviewRunner: DeduplicationReviewRunner;
signal?: AbortSignal;
diff --git a/sdk/typescript/src/scan-comparison.ts b/sdk/typescript/src/scan-comparison.ts
index 07813ada8..9332e37f1 100644
--- a/sdk/typescript/src/scan-comparison.ts
+++ b/sdk/typescript/src/scan-comparison.ts
@@ -9,7 +9,7 @@ import {
type ThreadOptions,
type TurnOptions,
} from "@openai/codex-sdk";
-import { z } from "incur";
+import { z } from "zod";
import { parse, stringify } from "smol-toml";
import type { CodexSecuritySurface, ScanAuthMode } from "./api.js";
import {
@@ -97,22 +97,12 @@ export interface ScanComparisonProgress {
pages?: number;
}
-interface ScanComparisonMatch {
- beforeOccurrenceIds: string[];
- afterOccurrenceIds: string[];
- confidence: "high";
- reason: string;
-}
+type ScanComparisonPair = z.infer<typeof findingPairSchema>;
-interface ScanComparisonPair {
- beforeOccurrenceId: string;
- afterOccurrenceId: string;
- reason: string;
-}
-
-export interface ScanComparisonResult {
- matches: ScanComparisonMatch[];
- uncertain: ScanComparisonPair[];
+export interface ScanComparisonResult extends Omit<
+ z.infer<typeof comparisonSchema>,
+ "related"
+> {
related?: ScanComparisonPair[];
}
diff --git a/sdk/typescript/src/security-policy.ts b/sdk/typescript/src/security-policy.ts
index a40da768b..43a049f3b 100644
--- a/sdk/typescript/src/security-policy.ts
+++ b/sdk/typescript/src/security-policy.ts
@@ -23,7 +23,7 @@ import {
sep,
} from "node:path";
import { promisify } from "node:util";
-import { z } from "incur";
+import { z } from "zod";
import type { ScanAuthentication, ScanOptions } from "./api.js";
import { jsonForPrompt } from "./codex-prompt.js";
import type { ScanModelConfiguration } from "./config.js";
@@ -137,12 +137,9 @@ const securityPolicyStageSchema = z.strictObject({
blockedReason: z.string().nullable(),
});
-export interface SecurityPolicyStageResult {
- markdown: string;
- questions: string[];
- reviewNotes: string[];
- blockedReason: string | null;
-}
+export interface SecurityPolicyStageResult extends z.infer<
+ typeof securityPolicyStageSchema
+> {}
export function securityPolicyStageOutputSchema(): Record<string, unknown> {
return z.toJSONSchema(securityPolicyStageSchema, {