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): reuse runtime message and result handling (#1583)
Michael D'Angelo3b47a02aa412
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 137e5a74d..2cc524ad6 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -2787,10 +2787,7 @@ export class CodexSecurity {await this.close();}- async #authentication(): Promise<{- codexHome: string;- environment: Record<string, string>;- }> {+ async #authentication() {this.#requireOpen();const environment = selectedScanEnvironment(this.#runtime?.environment ?? this.#dependencies.environment,diff --git a/sdk/typescript/src/auth.ts b/sdk/typescript/src/auth.tsindex 17dbe0518..a1439c1c3 100644--- a/sdk/typescript/src/auth.ts+++ b/sdk/typescript/src/auth.ts@@ -78,12 +78,9 @@ export async function readCodexHomeConfig(}}-export interface LoginResult {- success: boolean;- exitCode: number | null;- stdout: string;- stderr: string;-}+export interface LoginResult extends Awaited<+ ReturnType<typeof runCodexCommand>+> {}export interface AccountStatus {authenticated: boolean;diff --git a/sdk/typescript/src/classify-severity.ts b/sdk/typescript/src/classify-severity.tsindex 43154c65f..68fa56e7d 100644--- a/sdk/typescript/src/classify-severity.ts+++ b/sdk/typescript/src/classify-severity.ts@@ -1,3 +1,4 @@+import { SCAN_SEVERITIES } from "./scan-settings.js";import { findingEntry } from "./value.js";import { z } from "zod";import { CodexSecurityError } from "./errors.js";@@ -59,13 +60,7 @@ export interface SeverityClassificationCheckpoint {): Promise<void>;}-const levelSchema = z.enum([- "critical",- "high",- "medium",- "low",- "informational",-]);+const levelSchema = z.enum(SCAN_SEVERITIES);const textSchema = z.string().min(1)diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 31a5675aa..1e16daa96 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -374,6 +374,8 @@ const PROVIDER_OPTION = z.enum(["openai", "openrouter", "fireworks", "amazon-bedrock"]).default("openai").describe("Inference provider for scans.");+const positiveInteger = z.number().int().positive();+const SHOW_COST_OPTION = z.boolean().default(false)@@ -1749,12 +1751,8 @@ export async function main(const frameworkCapture = captureOutput();let rawExportOutput = false;let streamedLogs: Awaited<ReturnType<typeof readSavedScanLogs>> | undefined;- let renderedHistory: string | undefined;- let renderedPublication: string | undefined;- let renderedPolicy: string | undefined;- let renderedPatch: string | undefined;- let patchStructuredError = false;- let scanStructuredError = false;+ let renderedOutput: string | undefined;+ let structuredError = false;let incompleteScanOutput:{ format: "json" | "jsonl"; message: string } | undefined;const recordIncompleteScanOutput = (outcome: ScanOutcome, format: string) => {@@ -1768,7 +1766,6 @@ export async function main(};let filteredScanFailure:{ format: string; data: Record<string, unknown> } | undefined;- let renderedScanFailure: string | undefined;const finishScan = (outcome: ScanOutcome,format: string,@@ -1793,7 +1790,7 @@ export async function main(return data;}// Incur would wrap returned data in an ok: true envelope.- scanStructuredError = true;+ structuredError = true;return incurError({ code, message, exitCode });}return incurError({ code, message: outcome.error, exitCode });@@ -1947,7 +1944,7 @@ export async function main() {return result;}- renderedHistory = renderScanHistory(result, command, {+ renderedOutput = renderScanHistory(result, command, {columns: output.columns,color:dependencies.environment["NO_COLOR"] === undefined &&@@ -3184,7 +3181,7 @@ export async function main(!options.dryRun &&!argv.some((argument) => OUTPUT_OPTION.test(argument))) {- renderedPublication = renderPublicationSummary(+ renderedOutput = renderPublicationSummary(result,output.isTTY === true &&dependencies.environment["NO_COLOR"] === undefined &&@@ -3272,7 +3269,7 @@ export async function main(z.object({source: z.literal("github-code-scanning"),repository: z.string(),- number: z.number().int().positive(),+ number: positiveInteger,url: z.string(),alert: z.record(z.string(), z.unknown()),}),@@ -3491,7 +3488,7 @@ export async function main(outcome.markdown !== undefined &&!filterOutput) {- if (!transformOutput) renderedPolicy = outcome.markdown;+ if (!transformOutput) renderedOutput = outcome.markdown;return outcome.markdown;}return format === "toon" && !explicitOutput && !options.dryRun@@ -4007,10 +4004,7 @@ export async function main(destructive: true,mcp: false,options: z.object({- concurrency: z- .number()- .int()- .positive()+ concurrency: positiveInteger.default(DEFAULT_DEDUPE_CONCURRENCY).describe("Maximum concurrent dedupe jobs across Luna and Sol; use 1 for serial execution.",@@ -4231,10 +4225,7 @@ export async function main(outputDir: optionValue("--output-dir").optional().describe("Empty results directory outside the repository."),- workers: z- .number()- .int()- .positive()+ workers: positiveInteger.default(4).describe("Concurrent component scans; deep workers are configured per scan.",@@ -4470,10 +4461,7 @@ export async function main(.optional().meta({ default: [] }).describe("Read shared security docs for every repository."),- workers: z- .number()- .int()- .positive()+ workers: positiveInteger.default(4).describe("Concurrent repository scans. Per-scan Codex workers are separate.",@@ -4496,10 +4484,7 @@ export async function main(`OpenAI model for each repository (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`,).shape,provider: PROVIDER_OPTION,- maxAttempts: z- .number()- .int()- .positive()+ maxAttempts: positiveInteger.default(1).describe("Maximum scan attempts per repository."),maxCost: ScanSettingsSchema.shape.maxCostUsd.describe(@@ -5486,14 +5471,14 @@ export async function main(const message = errorMessage(error);errorOutput.write(`codex-security: ${diagnosticValue(message)}\n`);if (!structuredOutput) return;- patchStructuredError = true;+ structuredError = true;const failure = {code:error instanceof PatchCommandError ? error.code : "PATCH_FAILED",message,};if (!fullOutput) {- renderedPatch =+ renderedOutput =JSON.stringify({ok: false,...patchResult,@@ -6183,12 +6168,12 @@ export async function main(stdout: failureOutput.stream.write,exit: () => undefined,});- renderedScanFailure = failureOutput.text();+ renderedOutput = failureOutput.text();}let frameworkOutput = frameworkCapture.text();if (notice !== undefined) errorOutput.write(formatUpdateNotice(notice));if (frameworkExit !== undefined) {- if (policyFullOutput || patchStructuredError || scanStructuredError) {+ if (policyFullOutput || structuredError) {if (exitCode === 0) exitCode = 2;} else {if (exitCode !== 0) return exitCode;@@ -6202,7 +6187,7 @@ export async function main(if (frameworkOutput.length === 0 &&streamedLogs === undefined &&- renderedScanFailure === undefined+ filteredScanFailure === undefined)return exitCode;try {@@ -6235,11 +6220,7 @@ export async function main(await writeCliOutput(output,logOutput ??- renderedScanFailure ??- renderedPolicy ??- renderedPatch ??- renderedPublication ??- renderedHistory ??+ renderedOutput ??formatCliHelp(frameworkOutput, output.columns),);return exitCode;@@ -7394,10 +7375,9 @@ async function runFindingPatches(: [];const matches = entries.filter((entry) =>- typeof entry === "object" &&- entry !== null &&+ isJsonObject(entry) &&"occurrenceId" in entry &&- entry.occurrenceId === finding.occurrenceId,+ entry["occurrenceId"] === finding.occurrenceId,);const parsed = findingPatchSchema.safeParse(matches[0]);if (matches.length !== 1 || !parsed.success) {@@ -8021,24 +8001,16 @@ export async function readSkillCommandOutput(if (value["type"] === "item.completed") {const item = value["item"];if (- typeof item === "object" &&- item !== null &&- "type" in item &&- item.type === "agent_message" &&- "text" in item &&- typeof item.text === "string"+ isJsonObject(item) &&+ item["type"] === "agent_message" &&+ typeof item["text"] === "string") {- message = item.text;+ message = item["text"];}} else if (value["type"] === "turn.failed") {const detail = value["error"];- if (- typeof detail === "object" &&- detail !== null &&- "message" in detail &&- typeof detail.message === "string"- ) {- error = detail.message;+ if (isJsonObject(detail) && typeof detail["message"] === "string") {+ error = detail["message"];}} else if (value["type"] === "error" &&diff --git a/sdk/typescript/src/contract.ts b/sdk/typescript/src/contract.tsindex 448d07c18..cbdbc6f1b 100644--- a/sdk/typescript/src/contract.ts+++ b/sdk/typescript/src/contract.ts@@ -16,6 +16,7 @@ import { ContractValidationError, abortReason } from "./errors.js";import { isRecord } from "./record.js";import type {CoverageDocument,+ Finding,FindingsDocument,ScanManifest,} from "./models.js";@@ -91,9 +92,14 @@ export async function loadContractWithScanDirectory();}throwIfAborted(options.signal);- let findingsPayload: unknown = payloads["findings.json"];- const ajv = createValidator();+ // The plugin schemas are the immutable v0 contract. They are valid Draft+ // 2020-12 but intentionally omit redundant local `type` keywords that Ajv's+ // optional strict-schema linter requires.+ const ajv = new Ajv2020({ allErrors: false, strict: false }).addFormat(+ "date-time",+ { type: "string", validate: validRfc3339DateTime },+ );for (const [filename, schemaName] of Object.entries(DOCUMENTS)) {const schema = await readJson(join(options.pluginRoot, "schemas", schemaName),@@ -104,8 +110,7 @@ export async function loadContractWithScanDirectory(let valid: boolean;try {validate = ajv.compile(schema);- payload =- filename === "findings.json" ? findingsPayload : payloads[filename];+ payload = payloads[filename];const validatePayload = (payload: unknown) => {const result = validate(payload);if (typeof result !== "boolean") {@@ -124,12 +129,12 @@ export async function loadContractWithScanDirectory(if (!valid) {throw schemaError(filename, validate.errors ?? []);}- if (filename === "findings.json") findingsPayload = payload;+ payloads[filename] = payload;throwIfAborted(options.signal);}- const manifest = payloads["scan-manifest.json"] as unknown as ScanManifest;- const findings = findingsPayload as FindingsDocument;- const coverage = payloads["coverage.json"] as unknown as CoverageDocument;+ const manifest = payloads["scan-manifest.json"] as ScanManifest;+ const findings = payloads["findings.json"] as FindingsDocument;+ const coverage = payloads["coverage.json"] as CoverageDocument;if (options.expectedScanId !== undefined &&manifest.scan.id !== options.expectedScanId@@ -296,21 +301,12 @@ function validateCanonicalContract(}}- const fingerprint = `codex-security/v1:sha256:${hash(- "sha256",- [- "codex-security/v1",- manifest.scan.target.targetId,- finding.ruleId,- finding.identity.anchor,- finding.identity.instance ?? "",- ].join("\0"),- )}`;- const findingId = `csf_${hash("sha256", fingerprint).slice(0, 24)}`;- const occurrenceId = `occ_${hash(- "sha256",- [manifest.scan.id, fingerprint].join("\0"),- ).slice(0, 24)}`;+ const { findingId, occurrenceId, fingerprints } = deriveFindingIdentity(+ manifest.scan.id,+ manifest.scan.target.targetId,+ finding.ruleId,+ finding.identity,+ );if (finding.findingId !== findingId) {throw new ContractValidationError(`${context}.findingId: does not match derived fingerprint identity.`,@@ -321,7 +317,7 @@ function validateCanonicalContract(`${context}.occurrenceId: does not match scan occurrence identity.`,);}- if (finding.fingerprints.primary !== fingerprint) {+ if (finding.fingerprints.primary !== fingerprints.primary) {throw new ContractValidationError(`${context}.fingerprints: does not match derived fingerprint.`,);@@ -838,18 +834,6 @@ function validateParsedJson(value: unknown, context: string): void {}}-function createValidator(): Ajv2020 {- // The plugin schemas are the immutable v0 contract. They are valid Draft- // 2020-12 but intentionally omit redundant local `type` keywords that Ajv's- // optional strict-schema linter requires.- const ajv = new Ajv2020({ allErrors: false, strict: false });- ajv.addFormat("date-time", {- type: "string",- validate: validRfc3339DateTime,- });- return ajv;-}-async function sha256ScanFile(scanDir: string,relativePath: string,@@ -1026,3 +1010,30 @@ function nodeErrorCode(error: unknown): string | undefined {export function sha256Text(value: string): string {return hash("sha256", value);}++export function deriveFindingIdentity(+ scanId: string,+ targetId: string,+ ruleId: string,+ identity: Finding["identity"],+) {+ const fingerprint = `codex-security/v1:sha256:${sha256Text(+ [+ "codex-security/v1",+ targetId,+ ruleId,+ identity.anchor,+ identity.instance ?? "",+ ].join("\0"),+ )}`;+ return {+ findingId: `csf_${sha256Text(fingerprint).slice(0, 24)}`,+ occurrenceId: `occ_${sha256Text([scanId, fingerprint].join("\0")).slice(0, 24)}`,+ ruleId,+ identity,+ fingerprints: {+ algorithm: "codex-security/v1" as const,+ primary: fingerprint,+ },+ };+}diff --git a/sdk/typescript/src/cost-model.ts b/sdk/typescript/src/cost-model.tsindex a820aaaf8..5be059464 100644--- a/sdk/typescript/src/cost-model.ts+++ b/sdk/typescript/src/cost-model.ts@@ -28,12 +28,7 @@ export interface ScanCost {};}-interface TokenPrices {- input: number;- cacheRead: number;- cacheWrite: number;- output: number;-}+type TokenPrices = ReturnType<typeof usdPerMillionTokens>;type ModelPricing = readonly [input: number,@@ -123,10 +118,7 @@ const LONG_CONTEXT_PRICING_NANODOLLARS: Readonly<Record<string, ModelPricing>> ="gpt-daybreak-blue-latest": [8_000, 800, 10_000, 30_000],};-function usdPerMillionTokens(- pricing: ModelPricing,- unitsPerUsd: number,-): TokenPrices {+function usdPerMillionTokens(pricing: ModelPricing, unitsPerUsd: number) {const [input, cacheRead, cacheWrite, output] = pricing;const unitsPerMillion = unitsPerUsd / 1_000_000;return {diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.tsindex f6e9bda36..a485b0e7b 100644--- a/sdk/typescript/src/cost.ts+++ b/sdk/typescript/src/cost.ts@@ -11,6 +11,7 @@ import {} from "./cost-model.js";import {scanActivityFromSessionEvent,+ sessionContentText,type ScanActivity,} from "./scan-activity.js";import {@@ -40,37 +41,15 @@ export interface ScanSessionEvent {event: Record<string, unknown>;}-interface SessionReasoning {- id: string;- text: string;- raw: boolean;- activity: ScanActivity | null;+type SessionReasoning = ReturnType<typeof createSessionReasoning>;++function createSessionReasoning(id: string, text = "") {+ return { id, text, raw: false, activity: null as ScanActivity | null };}-interface SessionUsage {- offset: number;- decoder: StringDecoder;- pendingLine: string[];- unreadable: boolean;- threadId: string | null;- parentThreadId: string | null;- workingDirectory: string | null;- startedAt: number | null;- inheritedUsage: ScanTokenUsage | null;- replaying: boolean;- usage: ScanTokenUsage | null;- responseUsage: ScanTokenUsage | null;- responseIds: Set<string>;- calls: Map<string, ScanActivity>;- activities: ScanActivity[];- progress: ScanProgress[];- filesCompleted: number;- filesTotal: number | null;- prose: Set<string>;- reasoning: SessionReasoning | null;- reasoningCount: number;+type SessionUsage = ReturnType<typeof createSessionUsage> & {events?: Record<string, unknown>[];-}+};interface ScanCostTrackerOptions {codexHome: string;@@ -96,28 +75,28 @@ interface ScanCostSnapshot {const COST_POLL_INTERVAL_MS = 100;const SESSION_READ_SIZE = 64 * 1_024;-function createSessionUsage(): SessionUsage {+function createSessionUsage() {return {offset: 0,decoder: new StringDecoder("utf8"),- pendingLine: [],+ pendingLine: [] as string[],unreadable: false,- threadId: null,- parentThreadId: null,- workingDirectory: null,- startedAt: null,- inheritedUsage: null,+ threadId: null as string | null,+ parentThreadId: null as string | null,+ workingDirectory: null as string | null,+ startedAt: null as number | null,+ inheritedUsage: null as ScanTokenUsage | null,replaying: false,- usage: null,- responseUsage: null,- responseIds: new Set(),- calls: new Map(),- activities: [],- progress: [],+ usage: null as ScanTokenUsage | null,+ responseUsage: null as ScanTokenUsage | null,+ responseIds: new Set<string>(),+ calls: new Map<string, ScanActivity>(),+ activities: [] as ScanActivity[],+ progress: [] as ScanProgress[],filesCompleted: 0,- filesTotal: null,- prose: new Set(),- reasoning: null,+ filesTotal: null as number | null,+ prose: new Set<string>(),+ reasoning: null as SessionReasoning | null,reasoningCount: 0,};}@@ -581,12 +560,10 @@ function readSessionEvent() {continue;}- session.reasoning = {- id: activity.id,- text: activity.description,- raw: false,- activity: null,- };+ session.reasoning = createSessionReasoning(+ activity.id,+ activity.description,+ );recordReasoningActivity(session, activity);}return;@@ -594,12 +571,10 @@ function readSessionEvent(const activity = scanActivityFromSessionEvent(event, repository);if (activity !== null) {if (activity.kind === "reasoning") {- const reasoning = (session.reasoning ??= {- id: activity.id,- text: activity.description,- raw: false,- activity: null,- });+ const reasoning = (session.reasoning ??= createSessionReasoning(+ activity.id,+ activity.description,+ ));recordReasoningActivity(session, {...activity,id: reasoning.id,@@ -723,12 +698,9 @@ function readSessionReasoning() {session.reasoning = null;}- const reasoning = (session.reasoning ??= {- id: `reasoning-${++session.reasoningCount}`,- text: "",- raw: false,- activity: null,- });+ const reasoning = (session.reasoning ??= createSessionReasoning(+ `reasoning-${++session.reasoningCount}`,+ ));if (reasoning.raw && !raw) return;if (raw && !reasoning.raw) {reasoning.text = "";@@ -770,9 +742,7 @@ function sessionProgressUpdates(payload: Readonly<Record<string, unknown>>,): ScanProgress[] {if (payload["type"] === "message" && payload["role"] === "assistant") {- const content = payload["content"];- if (!Array.isArray(content)) return [];- return scanProgressUpdatesFromText(sessionContentText(content, false));+ return scanProgressUpdatesFromText(sessionContentText(payload["content"]));}if (payload["type"] !== "function_call_output" &&@@ -785,31 +755,13 @@ function sessionProgressUpdates(const output =typeof value === "string"? value- : Array.isArray(value)- ? sessionContentText(value, true)- : null;- if (payload["status"] === "failed" || output === null) {+ : sessionContentText(value, ["output_text", "input_text"]);+ if (payload["status"] === "failed") {return [];}return scanProgressUpdatesFromText(output);}-function sessionContentText(- content: readonly unknown[],- includeInputText: boolean,-): string {- return content- .filter(- (item): item is Record<string, unknown> & { text: string } =>- isRecord(item) &&- (item["type"] === "output_text" ||- (includeInputText && item["type"] === "input_text")) &&- typeof item["text"] === "string",- )- .map((item) => item.text)- .join("\n");-}-function addTokenUsage(previous: ScanTokenUsage | null,next: ScanTokenUsage,diff --git a/sdk/typescript/src/deduplication/deduplication.ts b/sdk/typescript/src/deduplication/deduplication.tsindex b4545cca1..41e88b343 100644--- a/sdk/typescript/src/deduplication/deduplication.ts+++ b/sdk/typescript/src/deduplication/deduplication.ts@@ -1,3 +1,4 @@+import { SCAN_SEVERITIES } from "../scan-settings.js";import { findingGroupRoots } from "../finding-catalogue.js";import type { Finding } from "../models.js";import type { FindingNeighborhood } from "../finding-retrieval.js";@@ -84,14 +85,6 @@ export interface DeduplicationResult {refusals?: DeduplicationRefusal[];}-const severityOrder: Record<Finding["severity"]["level"], number> = {- critical: 0,- high: 1,- medium: 2,- low: 3,- informational: 4,-};-/** @internal */export interface ContradictionGroupingMetrics {candidateEvaluations: number;@@ -373,8 +366,8 @@ export class FindingDeduplicator {if (!groupMembers.some((member) => selected.has(member))) continue;groupMembers.sort((left, right) =>- severityOrder[findings.get(left)!.severity.level] -- severityOrder[findings.get(right)!.severity.level] ||+ SCAN_SEVERITIES.indexOf(findings.get(left)!.severity.level) -+ SCAN_SEVERITIES.indexOf(findings.get(right)!.severity.level) ||(left < right ? -1 : left > right ? 1 : 0),);duplicateGroups.push(groupMembers);diff --git a/sdk/typescript/src/deep-config.ts b/sdk/typescript/src/deep-config.tsindex 88d8381e6..5937cdc49 100644--- a/sdk/typescript/src/deep-config.ts+++ b/sdk/typescript/src/deep-config.ts@@ -1,3 +1,4 @@+import { isRecord } from "./record.js";import { lstat, readFile } from "node:fs/promises";import { basename, dirname, join } from "node:path";import { parse as parseToml, type TomlTable } from "smol-toml";@@ -68,9 +69,7 @@ export async function resolveDeepScanConfig(const existing = document["deep_scan"];if (existing !== undefined &&- (typeof existing !== "object" ||- existing === null ||- Array.isArray(existing) ||+ (!isRecord(existing) ||![Object.prototype, null].includes(Object.getPrototypeOf(existing)))) {throw new CodexSecurityError(diff --git a/sdk/typescript/src/findings-import.ts b/sdk/typescript/src/findings-import.tsindex 7e369dc47..91ae00408 100644--- a/sdk/typescript/src/findings-import.ts+++ b/sdk/typescript/src/findings-import.ts@@ -1,4 +1,5 @@-import { sha256Text as sha256 } from "./contract.js";+import { isRecord } from "./record.js";+import { deriveFindingIdentity, sha256Text as sha256 } from "./contract.js";import { readFile } from "node:fs/promises";import { isAbsolute, join, posix } from "node:path";import Ajv2020 from "ajv/dist/2020.js";@@ -123,11 +124,7 @@ export async function parseImportedFindings({ cause: error },);}- if (- payload === null ||- typeof payload !== "object" ||- Array.isArray(payload)- ) {+ if (!isRecord(payload)) {throw new CodexSecurityError("Findings JSON must contain a findings document or an object with a findings array.",);@@ -174,24 +171,14 @@ export function bindImportedFindings(targetId: string,): Finding[] {return findings.map((finding) => {- const ruleId = `import.${format}`;- const anchor = finding.occurrenceId;- const fingerprint = `codex-security/v1:sha256:${sha256(- ["codex-security/v1", targetId, ruleId, anchor, ""].join("\0"),- )}`;// A source report path names another scan's artifact. Preserve it as// provenance without treating the imported path as permission to read it.const { writeup, ...content } = finding;return {...content,- findingId: `csf_${sha256(fingerprint).slice(0, 24)}`,- occurrenceId: `occ_${sha256([scanId, fingerprint].join("\0")).slice(0, 24)}`,- ruleId,- identity: { anchor },- fingerprints: {- algorithm: "codex-security/v1",- primary: fingerprint,- },+ ...deriveFindingIdentity(scanId, targetId, `import.${format}`, {+ anchor: finding.occurrenceId,+ }),provenance: { source: `${format}_import` },extensions: {...finding.extensions,diff --git a/sdk/typescript/src/mock-scan.ts b/sdk/typescript/src/mock-scan.tsindex 62bddf48d..46cee361c 100644--- a/sdk/typescript/src/mock-scan.ts+++ b/sdk/typescript/src/mock-scan.ts@@ -2,7 +2,7 @@ import { writeFile } from "node:fs/promises";import { createHash } from "node:crypto";import { join } from "node:path";import type { JsonObject } from "./config.js";-import type { Finding, SeverityLevel } from "./models.js";+import type { Finding } from "./models.js";import type { NormalizedTarget } from "./targets.js";type DraftFinding = Omit<@@ -10,18 +10,8 @@ type DraftFinding = Omit<"findingId" | "occurrenceId" | "fingerprints">;-interface MockFinding {- id: string;- title: string;- severity: SeverityLevel;- cwe: string;- summary: string;- code: string;- remediation: string;-}-// Entirely synthetic examples; the paths and snippets do not come from the target.-const EXAMPLES: readonly MockFinding[] = [+const EXAMPLES = [{id: "command-injection",title: "Export filename reaches a shell command",@@ -129,7 +119,7 @@ const EXAMPLES: readonly MockFinding[] = [code: 'response.cookie("session", sessionId, { secure: true });',remediation: "Set HttpOnly on the session cookie.",},-];+] as const;function mockFindings(scanId: string): DraftFinding[] {const findings = EXAMPLES.map((example, index): DraftFinding => {diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.tsindex 2d281bedb..fbabe1fb5 100644--- a/sdk/typescript/src/multiscan.ts+++ b/sdk/typescript/src/multiscan.ts@@ -62,14 +62,7 @@ const LOCK_HEARTBEAT_MS = 5_000;const WINDOWS_DEVICE_PATH_NAME =/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;-interface MultiscanTask {- id: string;- repository: string;- revision: string;- mode: ScanMode;- scope?: string;- prompt?: string;-}+type MultiscanTask = ReturnType<typeof parseInventory>[number];interface MultiscanReceipt extends MultiscanTask {status: "completed" | "completed_with_incomplete_coverage" | "failed";@@ -1070,7 +1063,7 @@ function parseInventory(source: string,directory: string,defaultMode: ScanMode,-): MultiscanTask[] {+) {const { data: rows, errors } = Papa.parse<string[]>(source, {delimiter: ",",skipEmptyLines: "greedy",@@ -1132,7 +1125,7 @@ function parseInventory(id,repository: normalizeRepository(get("repository"), directory),revision,- mode,+ mode: mode as ScanMode,...(scope ? { scope } : {}),...(prompt ? { prompt } : {}),};diff --git a/sdk/typescript/src/publication-events.ts b/sdk/typescript/src/publication-events.tsindex 251e973ea..30df10f43 100644--- a/sdk/typescript/src/publication-events.ts+++ b/sdk/typescript/src/publication-events.ts@@ -25,22 +25,20 @@ export type ClaimResolution =url?: string;};-export interface CompletedCreateEvidence {+interface CreateEvidence {source: "event";- status: "completed";rawLine: string;ownerFindingId?: string;argumentsValid: boolean;resolution: ClaimResolution;}-export interface FailedCreateEvidence {- source: "event";+export interface CompletedCreateEvidence extends CreateEvidence {+ status: "completed";+}++export interface FailedCreateEvidence extends CreateEvidence {status: "failed";- rawLine: string;- ownerFindingId?: string;- argumentsValid: boolean;- resolution: ClaimResolution;error: string;}@@ -68,31 +66,27 @@ export function collectPublicationEvents(const argumentsValid =owner !== undefined &&hasExpectedPublicationArguments(publication, owner, arguments_);- if (item["status"] === "completed") {- evidence.push({- source: "event",- status: "completed",- rawLine,- ...(owner === undefined ? {} : { ownerFindingId: owner.findingId }),- argumentsValid,- resolution: resolvePublicationClaims(item["result"]),- });- continue;- }-- const error = item["error"];- evidence.push({+ const completed: CompletedCreateEvidence = {source: "event",- status: "failed",+ status: "completed",rawLine,...(owner === undefined ? {} : { ownerFindingId: owner.findingId }),argumentsValid,resolution: resolvePublicationClaims(item["result"]),- error:- isRecord(error) && typeof error["message"] === "string"- ? error["message"]- : failureMessage,- });+ };+ if (item["status"] === "completed") {+ evidence.push(completed);+ } else {+ const error = item["error"];+ evidence.push({+ ...completed,+ status: "failed",+ error:+ isRecord(error) && typeof error["message"] === "string"+ ? error["message"]+ : failureMessage,+ });+ }}return evidence;diff --git a/sdk/typescript/src/publication-store.ts b/sdk/typescript/src/publication-store.tsindex 643840df2..b8eb4a983 100644--- a/sdk/typescript/src/publication-store.ts+++ b/sdk/typescript/src/publication-store.ts@@ -1,3 +1,4 @@+import { z } from "zod";import { findingEntry } from "./value.js";import { stat } from "node:fs/promises";import { join } from "node:path";@@ -23,12 +24,12 @@ export async function inspectPublicationStore(undefined,signal,);- const recorded = result["recorded"];+ const recorded = publicationRecordsSchema.safeParse(result["recorded"]);if (!matchesPublication(result, publication) ||result["findingCount"] !==(publication.sourceFindings ?? publication.issues).length ||- !Array.isArray(recorded)+ !recorded.success) {throw invalidPublicationRecords();}@@ -39,8 +40,7 @@ export async function inspectPublicationStore(]),);const found = new Map<string, PublishedScanIssue>();- for (const value of recorded) {- const issue = readPublicationRecord(value);+ for (const issue of recorded.data) {if (expected.get(issue.findingId) !== issue.occurrenceId ||found.has(issue.findingId)@@ -86,11 +86,11 @@ export async function recordPublishedIssues(environment,issues,);- const created = result["created"];+ const created = publicationRecordsSchema.safeParse(result["created"]);if (!matchesPublication(result, publication) ||- !Array.isArray(created) ||- created.length !== issues.length+ !created.success ||+ created.data.length !== issues.length) {throw invalidPublicationRecords();}@@ -104,9 +104,8 @@ export async function recordPublishedIssues(throw invalidPublicationRecords();}- return created.map((value, index) => {+ return created.data.map((issue, index) => {const expectedIssue = ordered[index]!;- const issue = readPublicationRecord(value);if (issue.findingId !== expectedIssue.findingId ||issue.occurrenceId !== expectedIssue.occurrenceId ||@@ -192,24 +191,14 @@ function matchesPublication();}-function readPublicationRecord(value: unknown): PublishedScanIssue {- if (- !isRecord(value) ||- typeof value["findingId"] !== "string" ||- typeof value["occurrenceId"] !== "string" ||- typeof value["issueIdentifier"] !== "string" ||- !value["issueIdentifier"].trim() ||- (value["url"] !== undefined && typeof value["url"] !== "string")- ) {- throw invalidPublicationRecords();- }- return {- findingId: value["findingId"],- occurrenceId: value["occurrenceId"],- issueIdentifier: value["issueIdentifier"],- ...(typeof value["url"] === "string" ? { url: value["url"] } : {}),- };-}+const publicationRecordsSchema = z+ .object({+ findingId: z.string(),+ occurrenceId: z.string(),+ issueIdentifier: z.string().refine((value) => Boolean(value.trim())),+ url: z.string().optional(),+ })+ .array();function invalidPublicationRecords(): CodexSecurityError {return new CodexSecurityError(diff --git a/sdk/typescript/src/publish.ts b/sdk/typescript/src/publish.tsindex 0b6abb9f9..b2cac0e2a 100644--- a/sdk/typescript/src/publish.ts+++ b/sdk/typescript/src/publish.ts@@ -65,18 +65,17 @@ import {type CodexCommand,} from "./runtime.js";-export interface PublishScanOptions {+export interface PublishScanOptions extends Pick<+ PrepareScanPublicationOptions,+ "destination" | "teamId" | "projectId" | "signal"+> {findingIds?: PrepareScanPublicationOptions["findingIds"];classification?: PrepareScanPublicationOptions["classification"];expectedScanId?: string;- destination: "linear";- teamId: string;- projectId?: string;linearApiKey?: string;assigneeId?: string;dryRun?: boolean;skipExisting?: boolean;- signal?: AbortSignal;onProgress?: (event: PublishScanProgress) => void;}@@ -218,12 +217,6 @@ type PublicationHandoffEvidence = {type PublicationEvidence =PublicationEventEvidence | PublicationHandoffEvidence;-interface ReconciledPublication {- created: PublishedScanIssue[];- failed: FailedScanPublication[];- indeterminate?: boolean;-}-interface FindingReconciliation {issue: PreparedPublicationIssue;created?: PublishedScanIssue;@@ -1092,7 +1085,7 @@ function reconcilePublicationEvidence(publication: PreparedScanPublication,evidence: readonly PublicationEvidence[],failureMessage: string,-): ReconciledPublication {+) {const byOwner = Map.groupBy(evidence, (item) => item.ownerFindingId);const claimLedger = new Map<string,diff --git a/sdk/typescript/src/saved-scan-bootstrap.ts b/sdk/typescript/src/saved-scan-bootstrap.tsindex 3fa7ce081..d9cb80c13 100644--- a/sdk/typescript/src/saved-scan-bootstrap.ts+++ b/sdk/typescript/src/saved-scan-bootstrap.ts@@ -1,3 +1,4 @@+import { isRecord } from "./record.js";import { environmentEntry } from "./auth.js";import { inspectTrustedExecutable } from "./trusted-executable.js";import { realpath } from "node:fs/promises";@@ -137,12 +138,7 @@ export async function savedScanWorkbench();if (typeof requestedId !== "string" && args[0] === "finding-workflow") {const workflow = result["workflow"];- if (- typeof workflow !== "object" ||- workflow === null ||- Array.isArray(workflow) ||- workflow["scanId"] !== targets[0]!.id- )+ if (!isRecord(workflow) || workflow["scanId"] !== targets[0]!.id)throw new CodexSecurityError("Saved workflow changed during lookup. Retry the command.",);@@ -150,9 +146,7 @@ export async function savedScanWorkbench(if (target) {const scan = result["scan"];if (- typeof scan !== "object" ||- scan === null ||- Array.isArray(scan) ||+ !isRecord(scan) ||scan["scanId"] !== target.id ||typeof scan["targetPath"] !== "string" ||resolve(scan["targetPath"]) !== resolve(target.target_path)diff --git a/sdk/typescript/src/scan-activity.ts b/sdk/typescript/src/scan-activity.tsindex 39126b3a9..ee4b9af1b 100644--- a/sdk/typescript/src/scan-activity.ts+++ b/sdk/typescript/src/scan-activity.ts@@ -242,17 +242,30 @@ function sessionProse(kind: "reasoning" | "message",value: unknown,): ScanActivity | null {- if (!Array.isArray(value)) return null;- const text = value+ return proseActivity(+ id,+ kind,+ "completed",+ sessionContentText(value, ["summary_text", "output_text"], " "),+ );+}++/** @internal */+export function sessionContentText(+ content: unknown,+ types: readonly string[] = ["output_text"],+ separator = "\n",+): string {+ if (!Array.isArray(content)) return "";+ return content.filter((item): item is Record<string, unknown> & { text: string } =>isRecord(item) &&- (item["type"] === "summary_text" || item["type"] === "output_text") &&+ types.some((type) => item["type"] === type) &&typeof item["text"] === "string",)- .map((item) => item["text"])- .join(" ");- return proseActivity(id, kind, "completed", text);+ .map((item) => item.text)+ .join(separator);}function proseActivity(diff --git a/sdk/typescript/src/scan-comparison.ts b/sdk/typescript/src/scan-comparison.tsindex 9332e37f1..45306f0ea 100644--- a/sdk/typescript/src/scan-comparison.ts+++ b/sdk/typescript/src/scan-comparison.ts@@ -1,5 +1,6 @@import { existsSync } from "node:fs";import { isRecord } from "./record.js";+import { notify } from "./value.js";import { dirname, join } from "node:path";import {Codex,@@ -309,19 +310,15 @@ export async function matchScanFindingsInternal(after: new Map<string, EvidenceCursor>(),};const progress = (phase: ScanComparisonProgress["phase"], page?: number) => {- try {- void Promise.resolve(- options.onProgress?.({- phase,- beforeFindings: input.before.length,- beforeIssues: catalogue.size,- afterFindings: input.after.length,- ...(page === undefined ? {} : { page, pages: pages.length }),- }),- ).catch(() => {});- } catch {- // Progress observers must not interrupt matching.- }+ notify(() =>+ options.onProgress?.({+ phase,+ beforeFindings: input.before.length,+ beforeIssues: catalogue.size,+ afterFindings: input.after.length,+ ...(page === undefined ? {} : { page, pages: pages.length }),+ }),+ );};const turnOptions = {// Native structured output requires every field; saved results can omit related.diff --git a/sdk/typescript/src/scan-logs.ts b/sdk/typescript/src/scan-logs.tsindex 26cda210d..33a284760 100644--- a/sdk/typescript/src/scan-logs.ts+++ b/sdk/typescript/src/scan-logs.ts@@ -70,18 +70,9 @@ export function readSavedScanLogs(// zstd, so they still read plain rollouts only.const readsCompressedSessions = typeof zlib.createZstdDecompress === "function";-interface SessionLog {- threadId: string;- parentThreadId: string | null;- startedAt: number | null;- workingDirectory: string | null;- path: string;-}+type SessionLog = NonNullable<Awaited<ReturnType<typeof findScanSession>>>;-async function* scanSessions(- codexHome: string,- directory = "sessions",-): AsyncGenerator<SessionLog> {+async function* scanSessions(codexHome: string, directory = "sessions") {for await (const path of sessionFiles(join(codexHome, directory),readsCompressedSessions,@@ -106,10 +97,7 @@ async function* scanSessions(}}-export async function findScanSession(- codexHome: string,- threadId: string,-): Promise<SessionLog | null> {+export async function findScanSession(codexHome: string, threadId: string) {for await (const session of scanSessions(codexHome)) {if (session.threadId === threadId) return session;}diff --git a/sdk/typescript/src/severity-store.ts b/sdk/typescript/src/severity-store.tsindex fcc05df09..20013ca04 100644--- a/sdk/typescript/src/severity-store.ts+++ b/sdk/typescript/src/severity-store.ts@@ -2,7 +2,6 @@ import { stat } from "node:fs/promises";import { join } from "node:path";import {severityClassificationSchema,- type SeverityAssessment,type SeverityClassification,type SeverityClassificationCheckpoint,} from "./classify-severity.js";@@ -46,10 +45,10 @@ export class SeverityStore {});return reprocess? []- : matchingAssessments(+ : matchingClassification(response["assessments"] as JsonObject[],result,- );+ ).assessments;},save: async (finding, assessment, result) => {await this.run("severity-classification", {@@ -80,16 +79,14 @@ export class SeverityStore {}const saved = await this.run("read-severity-classification", { scanId });if (saved["scanId"] === undefined) return undefined;- const result: SeverityClassification = {- schemaVersion: 1,- assessedAt: saved["assessedAt"] as string,- rubricSha256: saved["rubricSha256"] as string | null,- knowledgeBaseSha256: saved["knowledgeBaseSha256"] as string | null,- assessments: [],- };- result.assessments = matchingAssessments(+ const result = matchingClassification(saved["assessments"] as JsonObject[],- result,+ {+ schemaVersion: 1,+ assessedAt: saved["assessedAt"] as string,+ rubricSha256: saved["rubricSha256"] as string | null,+ knowledgeBaseSha256: saved["knowledgeBaseSha256"] as string | null,+ },);const findingIds = saved["findingIds"] as string[];if (result.assessments.length !== findingIds.length) {@@ -131,10 +128,10 @@ export class SeverityStore {}}-function matchingAssessments(+function matchingClassification(stored: JsonObject[],- result: SeverityClassification,-): SeverityAssessment[] {+ result: Omit<SeverityClassification, "assessments">,+): SeverityClassification {return severityClassificationSchema.parse({...result,assessments: stored@@ -151,5 +148,5 @@ function matchingAssessments(...assessment}) => assessment,),- }).assessments;+ });}diff --git a/sdk/typescript/src/version.ts b/sdk/typescript/src/version.tsindex 2740db35f..fa4d4ce5c 100644--- a/sdk/typescript/src/version.ts+++ b/sdk/typescript/src/version.ts@@ -146,11 +146,7 @@ export function formatUpdateNotice(notice: UpdateNotice): string {].join("\n");}-function packageVersions(url: URL): {- package: string;- sdk: string;- executable: string;-} {+function packageVersions(url: URL) {try {const manifest: unknown = JSON.parse(readFileSync(url, "utf8"));if (