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): reuse runtime message and result handling (#1583)

Michael D'Angelo3b47a02aa412
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 (