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
refactor(sdk): derive result interfaces from schemas (#1579)
Michael D'Angelo92be965c51e2
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, {