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(mcp): share candidate ledger updates (#1490)
mldangelo-oaid549f60ac738
diff --git a/plugins/codex-security/mcp-app/src/artifact-attack-path.ts b/plugins/codex-security/mcp-app/src/artifact-attack-path.tsdeleted file mode 100644index 534c42ff6..000000000--- a/plugins/codex-security/mcp-app/src/artifact-attack-path.ts+++ /dev/null@@ -1,156 +0,0 @@-import { asRecord } from "./record.js";-import type * as z from "zod/v4";-import commonSchema from "../../schemas/definitions/artifact-common.schema.json";-import attackPathSchema from "../../schemas/tools/candidate-attack-paths.schema.json";-import { candidateSchemaV1 } from "./deep-scan/artifact-contracts.js";-import {- artifactDestination,- readArtifactJsonl,- replaceArtifactJsonl,-} from "./artifact-io.js";-import type { ArtifactContext } from "./artifact-io.js";-import {- loadArtifactZodSchema,- type SchemaDocument,-} from "./artifact-schema-loader.js";--const documents = [commonSchema, attackPathSchema] as SchemaDocument[];--type ImpactLevel = "high" | "medium" | "low" | "ignore" | "unknown";-type ReportableSeverity = "critical" | "high" | "medium" | "low";--interface CandidateAttackPathFields {- dataflow: string;- reachability: string;- counterevidence: string;- impact: ImpactLevel;- likelihood: ImpactLevel;- severity_rationale: string;- change_conditions: string;- [field: string]: unknown;-}--export type CandidateAttackPathRecord = CandidateAttackPathFields &- (- | { decision: "reportable"; severity: ReportableSeverity }- | { decision: "ignore"; severity: "ignore" }- | {- decision: "deferred";- severity: ReportableSeverity | "unknown";- proof_gap: string;- }- );--interface CandidateAttackPathUpdate {- candidateId: string;- attackPath: CandidateAttackPathRecord;-}--interface CandidateAttackPathsPayload {- attackPaths: CandidateAttackPathUpdate[];-}--/** The checked-in public schema controls both tools/list and call validation. */-export const candidateAttackPathsInputSchema = loadArtifactZodSchema(- documents,- attackPathSchema.$id,- "input",-) as z.ZodType<CandidateAttackPathsPayload & { scanId: string }>;--const candidateLedgerRowSchema = candidateSchemaV1.passthrough();--const candidateLedgerComponents = [- "artifacts",- "02_discovery",- "candidate_ledger.jsonl",-] as const;--/** Add attack-path judgments to eligible canonical Deep candidate rows. */-export async function recordCodexSecurityCandidateAttackPaths(- context: ArtifactContext,- input: CandidateAttackPathsPayload,-): Promise<{- kind: "candidate_attack_paths";- operation: "replace";- rowsWritten: number;-}> {- if (context.layout !== "scan") {- throw new Error(- "Candidate attack-path analysis requires a scan-bound artifact context.",- );- }-- // The MCP registry validates this request before invoking the writer.- const { attackPaths } = input;- const updates = new Map<string, CandidateAttackPathRecord>();- for (const update of attackPaths) {- if (updates.has(update.candidateId)) {- throw new Error(- `Candidate attack-path update repeats candidate ${update.candidateId}.`,- );- }- updates.set(update.candidateId, update.attackPath);- }-- const rows = await readArtifactJsonl(- context,- candidateLedgerComponents,- "Compact candidate ledger",- candidateLedgerRowSchema,- );- const candidates = new Map<string, (typeof rows)[number]>();- for (const row of rows) {- if (candidates.has(row.candidate_id)) {- throw new Error(- `Candidate ledger repeats candidate ${row.candidate_id}.`,- );- }- candidates.set(row.candidate_id, row);- }-- for (const candidateId of updates.keys()) {- const candidate = candidates.get(candidateId);- if (!candidate) {- throw new Error(- `Candidate attack-path update refers to unknown candidate ${candidateId}.`,- );- }- if (!isAttackPathEligible(candidate)) {- throw new Error(- `Candidate ${candidateId} must have a reportable or deferred validation before attack-path analysis.`,- );- }- }-- const missing = [...candidates.values()]- .filter(isAttackPathEligible)- .map((candidate) => candidate.candidate_id)- .filter((candidateId) => !updates.has(candidateId));- if (missing.length > 0) {- throw new Error(- `Attack-path analysis must include every reportable or deferred candidate; missing ${missing.join(", ")}.`,- );- }-- const updatedRows = rows.map((row) => {- const attackPath = updates.get(row.candidate_id);- return attackPath ? { ...row, attack_path: attackPath } : row;- });- const destination = await artifactDestination(- context,- candidateLedgerComponents,- "Compact candidate ledger",- );- await replaceArtifactJsonl(destination, updatedRows);-- return {- kind: "candidate_attack_paths",- operation: "replace",- rowsWritten: updates.size,- };-}--function isAttackPathEligible(candidate: Record<string, unknown>): boolean {- const disposition = asRecord(candidate.validation)?.disposition;- return disposition === "reportable" || disposition === "deferred";-}diff --git a/plugins/codex-security/mcp-app/src/artifact-candidate-ledger.ts b/plugins/codex-security/mcp-app/src/artifact-candidate-ledger.tsnew file mode 100644index 000000000..e811f7797--- /dev/null+++ b/plugins/codex-security/mcp-app/src/artifact-candidate-ledger.ts@@ -0,0 +1,257 @@+import { asRecord } from "./record.js";+import type * as z from "zod/v4";+import commonSchema from "../../schemas/definitions/artifact-common.schema.json";+import validationSchema from "../../schemas/tools/candidate-validations.schema.json";+import attackPathSchema from "../../schemas/tools/candidate-attack-paths.schema.json";+import { candidateSchemaV1 } from "./deep-scan/artifact-contracts.js";+import {+ artifactDestination,+ readArtifactJsonl,+ replaceArtifactJsonl,+ type ArtifactContext,+} from "./artifact-io.js";+import {+ loadArtifactZodSchema,+ type SchemaDocument,+} from "./artifact-schema-loader.js";++const documents = [+ commonSchema,+ validationSchema,+ attackPathSchema,+] as SchemaDocument[];++export interface CandidateValidationRecord {+ disposition: "reportable" | "suppressed" | "not_applicable" | "deferred";+ method: string;+ confidence: "high" | "medium" | "low";+ confidence_rationale: string;+ rubric:+ string | Record<string, unknown> | Array<string | Record<string, unknown>>;+ evidence: string | string[];+ counterevidence_or_proof_gap: string;+ remaining_uncertainty: string;+ artifact_paths?: string[];+ source?: string;+ control?: string;+ sink?: string;+ preconditions?: string | string[];+ [field: string]: unknown;+}++interface CandidateValidationUpdates {+ validations: {+ candidateId: string;+ validation: CandidateValidationRecord;+ }[];+}++/** Public workbench input; the bound context, never the caller, selects the artifact. */+export const candidateValidationsInputSchema = loadArtifactZodSchema(+ documents,+ validationSchema.$id,+ "input",+) as z.ZodType<CandidateValidationUpdates & { scanId: string }>;++/** Complete one existing validation phase without changing discovery or attack-path data. */+export async function recordCodexSecurityCandidateValidations(+ context: ArtifactContext,+ input: CandidateValidationUpdates,+): Promise<{+ kind: "candidate_validations";+ operation: "replace";+ rowsWritten: number;+}> {+ if (context.layout !== "scan") {+ throw new Error(+ "Candidate validation requires a scan-bound artifact context.",+ );+ }++ // The MCP registry validates this request before invoking the writer.+ const { validations } = input;+ const candidates = await readCandidateLedger(+ context,+ "Compact candidate ledger",+ );++ const validationByCandidateId = new Map<string, CandidateValidationRecord>();+ for (const update of validations) {+ if (!candidates.has(update.candidateId)) {+ throw new Error(+ `Validation names unknown candidate ${update.candidateId}.`,+ );+ }+ if (validationByCandidateId.has(update.candidateId)) {+ throw new Error(`Validation repeats candidate ${update.candidateId}.`);+ }+ validationByCandidateId.set(update.candidateId, update.validation);+ }++ const missing = [...candidates.keys()].filter(+ (candidateId) => !validationByCandidateId.has(candidateId),+ );+ if (missing.length > 0) {+ throw new Error(+ `Validation must include every existing candidate; missing ${missing.join(", ")}.`,+ );+ }++ const updatedRows = [...candidates.values()].map((row) => ({+ ...row,+ validation: validationByCandidateId.get(row.candidate_id)!,+ }));+ await replaceCandidateLedger(context, updatedRows);+ return {+ kind: "candidate_validations",+ operation: "replace",+ rowsWritten: updatedRows.length,+ };+}++type ImpactLevel = "high" | "medium" | "low" | "ignore" | "unknown";+type ReportableSeverity = "critical" | "high" | "medium" | "low";++export type CandidateAttackPathRecord = {+ dataflow: string;+ reachability: string;+ counterevidence: string;+ impact: ImpactLevel;+ likelihood: ImpactLevel;+ severity_rationale: string;+ change_conditions: string;+ [field: string]: unknown;+} & (+ | { decision: "reportable"; severity: ReportableSeverity }+ | { decision: "ignore"; severity: "ignore" }+ | {+ decision: "deferred";+ severity: ReportableSeverity | "unknown";+ proof_gap: string;+ }+);++interface CandidateAttackPathsPayload {+ attackPaths: {+ candidateId: string;+ attackPath: CandidateAttackPathRecord;+ }[];+}++/** The checked-in public schema controls both tools/list and call validation. */+export const candidateAttackPathsInputSchema = loadArtifactZodSchema(+ documents,+ attackPathSchema.$id,+ "input",+) as z.ZodType<CandidateAttackPathsPayload & { scanId: string }>;++/** Add attack-path judgments to eligible canonical Deep candidate rows. */+export async function recordCodexSecurityCandidateAttackPaths(+ context: ArtifactContext,+ input: CandidateAttackPathsPayload,+): Promise<{+ kind: "candidate_attack_paths";+ operation: "replace";+ rowsWritten: number;+}> {+ if (context.layout !== "scan") {+ throw new Error(+ "Candidate attack-path analysis requires a scan-bound artifact context.",+ );+ }++ // The MCP registry validates this request before invoking the writer.+ const { attackPaths } = input;+ const updates = new Map<string, CandidateAttackPathRecord>();+ for (const update of attackPaths) {+ if (updates.has(update.candidateId)) {+ throw new Error(+ `Candidate attack-path update repeats candidate ${update.candidateId}.`,+ );+ }+ updates.set(update.candidateId, update.attackPath);+ }++ const candidates = await readCandidateLedger(context, "Candidate ledger");++ for (const candidateId of updates.keys()) {+ const candidate = candidates.get(candidateId);+ if (!candidate) {+ throw new Error(+ `Candidate attack-path update refers to unknown candidate ${candidateId}.`,+ );+ }+ if (!isAttackPathEligible(candidate)) {+ throw new Error(+ `Candidate ${candidateId} must have a reportable or deferred validation before attack-path analysis.`,+ );+ }+ }++ const missing = [...candidates.values()]+ .filter(isAttackPathEligible)+ .map((candidate) => candidate.candidate_id)+ .filter((candidateId) => !updates.has(candidateId));+ if (missing.length > 0) {+ throw new Error(+ `Attack-path analysis must include every reportable or deferred candidate; missing ${missing.join(", ")}.`,+ );+ }++ const updatedRows = [...candidates.values()].map((row) => {+ const attackPath = updates.get(row.candidate_id);+ return attackPath ? { ...row, attack_path: attackPath } : row;+ });+ await replaceCandidateLedger(context, updatedRows);++ return {+ kind: "candidate_attack_paths",+ operation: "replace",+ rowsWritten: updates.size,+ };+}++function isAttackPathEligible(candidate: Record<string, unknown>): boolean {+ const disposition = asRecord(candidate.validation)?.disposition;+ return disposition === "reportable" || disposition === "deferred";+}++const components = [+ "artifacts",+ "02_discovery",+ "candidate_ledger.jsonl",+] as const;+const rowSchema = candidateSchemaV1.passthrough();++async function readCandidateLedger(+ context: ArtifactContext,+ duplicateLabel: string,+) {+ const rows = await readArtifactJsonl(+ context,+ components,+ "Compact candidate ledger",+ rowSchema,+ );+ const candidates = new Map<string, (typeof rows)[number]>();+ for (const row of rows) {+ if (candidates.has(row.candidate_id))+ throw new Error(+ `${duplicateLabel} repeats candidate ${row.candidate_id}.`,+ );+ candidates.set(row.candidate_id, row);+ }+ return candidates;+}++async function replaceCandidateLedger(+ context: ArtifactContext,+ rows: Record<string, unknown>[],+): Promise<void> {+ const destination = await artifactDestination(+ context,+ components,+ "Compact candidate ledger",+ );+ await replaceArtifactJsonl(destination, rows);+}diff --git a/plugins/codex-security/mcp-app/src/artifact-validation-phase.ts b/plugins/codex-security/mcp-app/src/artifact-validation-phase.tsdeleted file mode 100644index 47aa2fcb6..000000000--- a/plugins/codex-security/mcp-app/src/artifact-validation-phase.ts+++ /dev/null@@ -1,129 +0,0 @@-import type * as z from "zod/v4";-import commonSchema from "../../schemas/definitions/artifact-common.schema.json";-import validationSchema from "../../schemas/tools/candidate-validations.schema.json";-import { candidateSchemaV1 } from "./deep-scan/artifact-contracts.js";-import {- artifactDestination,- readArtifactJsonl,- replaceArtifactJsonl,-} from "./artifact-io.js";-import type { ArtifactContext } from "./artifact-io.js";-import {- loadArtifactZodSchema,- type SchemaDocument,-} from "./artifact-schema-loader.js";--const documents = [commonSchema, validationSchema] as SchemaDocument[];--export interface CandidateValidationRecord {- disposition: "reportable" | "suppressed" | "not_applicable" | "deferred";- method: string;- confidence: "high" | "medium" | "low";- confidence_rationale: string;- rubric:- string | Record<string, unknown> | Array<string | Record<string, unknown>>;- evidence: string | string[];- counterevidence_or_proof_gap: string;- remaining_uncertainty: string;- artifact_paths?: string[];- source?: string;- control?: string;- sink?: string;- preconditions?: string | string[];- [field: string]: unknown;-}--interface CandidateValidationUpdate {- candidateId: string;- validation: CandidateValidationRecord;-}--interface CandidateValidationUpdates {- validations: CandidateValidationUpdate[];-}--/** Public workbench input; the bound context, never the caller, selects the artifact. */-export const candidateValidationsInputSchema = loadArtifactZodSchema(- documents,- validationSchema.$id,- "input",-) as z.ZodType<CandidateValidationUpdates & { scanId: string }>;--const compactCandidateLedgerRowSchema = candidateSchemaV1.passthrough();-const candidateLedgerComponents = [- "artifacts",- "02_discovery",- "candidate_ledger.jsonl",-] as const;--/** Complete one existing validation phase without changing discovery or attack-path data. */-export async function recordCodexSecurityCandidateValidations(- context: ArtifactContext,- input: CandidateValidationUpdates,-): Promise<{- kind: "candidate_validations";- operation: "replace";- rowsWritten: number;-}> {- if (context.layout !== "scan") {- throw new Error(- "Candidate validation requires a scan-bound artifact context.",- );- }-- // The MCP registry validates this request before invoking the writer.- const { validations } = input;- const rows = await readArtifactJsonl(- context,- candidateLedgerComponents,- "Compact candidate ledger",- compactCandidateLedgerRowSchema,- );- const candidateIds = new Set<string>();- for (const row of rows) {- if (candidateIds.has(row.candidate_id)) {- throw new Error(- `Compact candidate ledger repeats candidate ${row.candidate_id}.`,- );- }- candidateIds.add(row.candidate_id);- }-- const validationByCandidateId = new Map<string, CandidateValidationRecord>();- for (const update of validations) {- if (!candidateIds.has(update.candidateId)) {- throw new Error(- `Validation names unknown candidate ${update.candidateId}.`,- );- }- if (validationByCandidateId.has(update.candidateId)) {- throw new Error(`Validation repeats candidate ${update.candidateId}.`);- }- validationByCandidateId.set(update.candidateId, update.validation);- }-- const missing = [...candidateIds].filter(- (candidateId) => !validationByCandidateId.has(candidateId),- );- if (missing.length > 0) {- throw new Error(- `Validation must include every existing candidate; missing ${missing.join(", ")}.`,- );- }-- const updatedRows = rows.map((row) => ({- ...row,- validation: validationByCandidateId.get(row.candidate_id)!,- }));- const destination = await artifactDestination(- context,- candidateLedgerComponents,- "Compact candidate ledger",- );- await replaceArtifactJsonl(destination, updatedRows);- return {- kind: "candidate_validations",- operation: "replace",- rowsWritten: updatedRows.length,- };-}diff --git a/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts b/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.tsindex 5dea2670e..6a03e7687 100644--- a/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts+++ b/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts@@ -22,11 +22,9 @@ import {import {candidateValidationsInputSchema,recordCodexSecurityCandidateValidations,-} from "../artifact-validation-phase.js";-import {candidateAttackPathsInputSchema,recordCodexSecurityCandidateAttackPaths,-} from "../artifact-attack-path.js";+} from "../artifact-candidate-ledger.js";import {deepReducerInputsInputSchema,deepReductionInputSchema,diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_attack_path.ts b/plugins/codex-security/mcp-app/tests/test_artifact_attack_path.tsindex 859bea80f..61d074bac 100644--- a/plugins/codex-security/mcp-app/tests/test_artifact_attack_path.ts+++ b/plugins/codex-security/mcp-app/tests/test_artifact_attack_path.ts@@ -1,7 +1,7 @@import { jsonLines, readJson, readJsonLines } from "./support/json.ts";import { createTemporaryDirectories } from "./support/temporary-directories.ts";import type { RawDiscoveryCandidate } from "../src/artifact-discovery.js";-import type { CandidateValidationRecord } from "../src/artifact-validation-phase.js";+import type { CandidateValidationRecord } from "../src/artifact-candidate-ledger.js";import assert from "node:assert/strict";import { mkdir, readFile, writeFile } from "node:fs/promises";import path from "node:path";@@ -11,7 +11,7 @@ const {candidateAttackPathsInputSchema,recordCodexSecurityCandidateAttackPaths,} = await importSource(- path.join(import.meta.dirname, "../src/artifact-attack-path.ts"),+ path.join(import.meta.dirname, "../src/artifact-candidate-ledger.ts"),);const scanId = "11111111-1111-4111-8111-111111111111";diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_validation_phase.ts b/plugins/codex-security/mcp-app/tests/test_artifact_validation_phase.tsindex ff6c1aa4d..b6087edc6 100644--- a/plugins/codex-security/mcp-app/tests/test_artifact_validation_phase.ts+++ b/plugins/codex-security/mcp-app/tests/test_artifact_validation_phase.ts@@ -11,7 +11,7 @@ const {candidateValidationsInputSchema,recordCodexSecurityCandidateValidations,} = await importSource(- path.join(import.meta.dirname, "../src/artifact-validation-phase.ts"),+ path.join(import.meta.dirname, "../src/artifact-candidate-ledger.ts"),);const toolSchema = await readJson(