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): simplify artifact schemas and saved-finding handling (#1356)
mldangelo-oai985a6dc34e24
diff --git a/plugins/codex-security/mcp-app/src/artifact-attack-path.ts b/plugins/codex-security/mcp-app/src/artifact-attack-path.tsindex ee02eaf64..305559efc 100644--- a/plugins/codex-security/mcp-app/src/artifact-attack-path.ts+++ b/plugins/codex-security/mcp-app/src/artifact-attack-path.ts@@ -1,3 +1,4 @@+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";@@ -156,14 +157,6 @@ export async function recordCodexSecurityCandidateAttackPaths(}function isAttackPathEligible(candidate: Record<string, unknown>): boolean {- const validation = candidate.validation;- if (- !validation ||- typeof validation !== "object" ||- Array.isArray(validation)- ) {- return false;- }- const disposition = (validation as Record<string, unknown>).disposition;+ const disposition = asRecord(candidate.validation)?.disposition;return disposition === "reportable" || disposition === "deferred";}diff --git a/plugins/codex-security/mcp-app/src/artifact-deep-reducer-pages.ts b/plugins/codex-security/mcp-app/src/artifact-deep-reducer-pages.tsindex ac787f86f..97643723a 100644--- a/plugins/codex-security/mcp-app/src/artifact-deep-reducer-pages.ts+++ b/plugins/codex-security/mcp-app/src/artifact-deep-reducer-pages.ts@@ -24,8 +24,7 @@ type Finding = DeepReductionInput["findings"][number];interface ReducerDocuments {inputs: string;- findings: Map<string, Finding>;- serializedFindings: Map<string, string>;+ findings: Map<string, Finding | string>;}// Each artifact server binds one immutable reducer assignment. Cache that@@ -62,16 +61,14 @@ export async function getCodexSecurityDeepReducerInputsPage(throw new Error("The requested findingRef is not assigned to this reducer.",);- const cached = snapshot.serializedFindings.get(input.findingRef);- json = cached ?? JSON.stringify(finding);- if (cached === undefined)- snapshot.serializedFindings.set(input.findingRef, json);+ json = typeof finding === "string" ? finding : JSON.stringify(finding);+ snapshot.findings.set(input.findingRef, json);}return pageDocument(json, input);}function createDocuments(sources: DeepReductionSources): ReducerDocuments {- const findings = new Map<string, Finding>();+ const findings = new Map<string, Finding | string>();const discoveries = sources.discoveries.map((discovery) => ({workerId: discovery.workerId,result: {@@ -107,7 +104,6 @@ function createDocuments(sources: DeepReductionSources): ReducerDocuments {return {inputs: JSON.stringify({ discoveries, previous }),findings,- serializedFindings: new Map(),};}diff --git a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts b/plugins/codex-security/mcp-app/src/artifact-scan-draft.tsindex 7a5a13ffb..411019b8f 100644--- a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts+++ b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts@@ -1,5 +1,5 @@import type { JsonObject } from "./types.js";-import { isRecord as isObject } from "./record.js";+import { isRecord as isObject, isNonEmptyString } from "./record.js";import { createHash, randomUUID } from "node:crypto";import { promises as fs } from "node:fs";import { dirname, join, sep } from "node:path";@@ -1885,7 +1885,7 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {canonicalEvidence.flatMap((evidence) => {if (!isObject(evidence)) return [];const id = evidence.id;- return typeof id === "string" && id.trim().length > 0 ? [id] : [];+ return isNonEmptyString(id) ? [id] : [];}),);if (Array.isArray(finding.code_evidence)) {@@ -1895,10 +1895,8 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {const id = evidence.id;const code = evidence.code;if (- typeof id !== "string" ||- id.trim().length === 0 ||- typeof code !== "string" ||- code.trim().length === 0 ||+ !isNonEmptyString(id) ||+ !isNonEmptyString(code) ||evidenceIds.has(id)) {continue;@@ -1942,15 +1940,11 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {const section = finding[sectionName];if (!isObject(section)) continue;normalizePersistedStringLists(section, listFields);- filterPersistedEvidenceRefs(section, evidenceIds);}const rootCause = finding.rootCause;if (isObject(rootCause)) {- if (- typeof rootCause.summary !== "string" ||- rootCause.summary.trim().length === 0- ) {+ if (!isNonEmptyString(rootCause.summary)) {delete finding.rootCause;} else {removeUnsupportedPersistedStrings(rootCause, ["code", "language"]);@@ -1963,10 +1957,7 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {"code","language",]);- } else if (- "root_cause" in finding &&- (typeof legacyRootCause !== "string" || legacyRootCause.trim().length === 0)- ) {+ } else if ("root_cause" in finding && !isNonEmptyString(legacyRootCause)) {delete finding.root_cause;}@@ -1986,16 +1977,8 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {removeUnsupportedPersistedStrings(attackPath, ["summary"]);for (const field of ["dataFlow", "data_flow", "dataflow", "reachability"]) {const detail = attackPath[field];- if (detail === null) {- delete attackPath[field];- continue;- }- if (typeof detail === "string") {- if (detail.trim().length === 0) delete attackPath[field];- continue;- }if (!isObject(detail)) {- if (field in attackPath) delete attackPath[field];+ if (!isNonEmptyString(detail)) delete attackPath[field];continue;}removeUnsupportedPersistedStrings(detail, [@@ -2011,7 +1994,6 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {"transformations",...(field === "reachability" ? ["preconditions"] : []),]);- filterPersistedEvidenceRefs(detail, evidenceIds);}for (const field of ["impact", "likelihood"]) {const detail = attackPath[field];@@ -2020,49 +2002,32 @@ function normalizePersistedFindingDetails(finding: JsonObject): void {} else if (detail !== undefined &&detail !== null &&- (typeof detail !== "string" || detail.trim().length === 0)+ !isNonEmptyString(detail)) {delete attackPath[field];}}-}-function normalizePersistedStringLists(- section: JsonObject,- fields: string[],-): void {- for (const field of fields) {- if (!(field in section)) continue;- const value = section[field];- const normalized =- typeof value === "string"- ? value.trim().length > 0- ? [value]- : []+ function normalizePersistedStringLists(+ section: JsonObject,+ fields: string[],+ ): void {+ for (const field of fields) {+ if (!(field in section)) continue;+ const value = section[field];+ const normalized = isNonEmptyString(value)+ ? [value]: Array.isArray(value)- ? value.filter(- (item): item is string =>- typeof item === "string" && item.trim().length > 0,- )+ ? value.filter(isNonEmptyString): [];- if (normalized.length > 0) section[field] = normalized;- else delete section[field];- }-}--function filterPersistedEvidenceRefs(- section: JsonObject,- evidenceIds: Set<string>,-): void {- for (const field of ["evidenceRefs", "evidence_refs"]) {- const refs = section[field];- if (!Array.isArray(refs)) continue;- section[field] = refs.filter(- (ref): ref is string =>- typeof ref === "string" &&- ref.trim().length > 0 &&- evidenceIds.has(ref),- );+ if (normalized.length > 0) section[field] = normalized;+ else delete section[field];+ }+ for (const field of ["evidenceRefs", "evidence_refs"]) {+ const refs = section[field];+ if (!Array.isArray(refs)) continue;+ section[field] = refs.filter((ref) => evidenceIds.has(ref));+ }}}@@ -2071,10 +2036,7 @@ function removeUnsupportedPersistedStrings(fields: string[],): void {for (const field of fields) {- if (- field in section &&- (typeof section[field] !== "string" || section[field].trim().length === 0)- ) {+ if (field in section && !isNonEmptyString(section[field])) {delete section[field];}}diff --git a/plugins/codex-security/mcp-app/src/artifact-schema-loader.ts b/plugins/codex-security/mcp-app/src/artifact-schema-loader.tsindex a04450cd4..c4ea6bd32 100644--- a/plugins/codex-security/mcp-app/src/artifact-schema-loader.ts+++ b/plugins/codex-security/mcp-app/src/artifact-schema-loader.ts@@ -33,12 +33,71 @@ export function bundleArtifactSchema(if (!source || typeof source !== "object" || Array.isArray(source)) {throw new Error("Unknown Codex Security schema definition: " + definition);}- return dereferenceArtifactSchema(- source,- document,- documentsById,- new Set<string>(),- ) as ArtifactSchemaObject;++ const activeReferences = new Set<string>();++ function dereferenceArtifactSchema(+ value: unknown,+ document: SchemaDocument,+ ): unknown {+ if (Array.isArray(value)) {+ return value.map((item) => dereferenceArtifactSchema(item, document));+ }+ if (!value || typeof value !== "object") return value;++ const object = value as ArtifactSchemaObject;+ if (typeof object.$ref !== "string") {+ return Object.fromEntries(+ Object.entries(object).map(([name, child]) => [+ name,+ dereferenceArtifactSchema(child, document),+ ]),+ );+ }++ const reference = object.$ref;+ const separator = reference.indexOf("#");+ const referencedDocumentId =+ separator < 0 ? reference : reference.slice(0, separator);+ const pointer = separator < 0 ? "" : reference.slice(separator + 1);+ const referencedDocument = referencedDocumentId+ ? documentsById.get(referencedDocumentId)+ : document;+ if (!referencedDocument) {+ throw new Error("Unknown Codex Security schema reference: " + reference);+ }++ const referenceKey = referencedDocument.$id + "#" + pointer;+ if (activeReferences.has(referenceKey)) {+ throw new Error("Cyclic Codex Security schema reference: " + reference);+ }+ activeReferences.add(referenceKey);+ const resolved = dereferenceArtifactSchema(+ readSchemaPointer(referencedDocument, pointer),+ referencedDocument,+ );+ // A recursive failure exits this bundle. Siblings use the parent path.+ activeReferences.delete(referenceKey);+ const siblings = Object.fromEntries(+ Object.entries(object).filter(([name]) => name !== "$ref"),+ );+ if (Object.keys(siblings).length === 0) return resolved;+ if (!resolved || typeof resolved !== "object" || Array.isArray(resolved)) {+ throw new Error(+ "Codex Security schema reference cannot have sibling fields: " ++ reference,+ );+ }+ return {+ ...resolved,+ ...(dereferenceArtifactSchema(+ siblings,+ document,+ ) as ArtifactSchemaObject),+ };+ }++ return dereferenceArtifactSchema(source, document) as ArtifactSchemaObject;}/**@@ -58,84 +117,6 @@ export function loadArtifactZodSchema();}-function dereferenceArtifactSchema(- value: unknown,- document: SchemaDocument,- documentsById: ReadonlyMap<string, SchemaDocument>,- activeReferences: ReadonlySet<string>,-): unknown {- if (Array.isArray(value)) {- return value.map((item) =>- dereferenceArtifactSchema(- item,- document,- documentsById,- activeReferences,- ),- );- }- if (!value || typeof value !== "object") return value;-- const object = value as ArtifactSchemaObject;- if (typeof object.$ref !== "string") {- return Object.fromEntries(- Object.entries(object).map(([name, child]) => [- name,- dereferenceArtifactSchema(- child,- document,- documentsById,- activeReferences,- ),- ]),- );- }-- const reference = object.$ref;- const separator = reference.indexOf("#");- const referencedDocumentId =- separator < 0 ? reference : reference.slice(0, separator);- const pointer = separator < 0 ? "" : reference.slice(separator + 1);- const referencedDocument = referencedDocumentId- ? documentsById.get(referencedDocumentId)- : document;- if (!referencedDocument) {- throw new Error("Unknown Codex Security schema reference: " + reference);- }-- const referenceKey = referencedDocument.$id + "#" + pointer;- if (activeReferences.has(referenceKey)) {- throw new Error("Cyclic Codex Security schema reference: " + reference);- }- const nextReferences = new Set(activeReferences);- nextReferences.add(referenceKey);- const resolved = dereferenceArtifactSchema(- readSchemaPointer(referencedDocument, pointer),- referencedDocument,- documentsById,- nextReferences,- );- const siblings = Object.fromEntries(- Object.entries(object).filter(([name]) => name !== "$ref"),- );- if (Object.keys(siblings).length === 0) return resolved;- if (!resolved || typeof resolved !== "object" || Array.isArray(resolved)) {- throw new Error(- "Codex Security schema reference cannot have sibling fields: " +- reference,- );- }- return {- ...resolved,- ...(dereferenceArtifactSchema(- siblings,- document,- documentsById,- activeReferences,- ) as ArtifactSchemaObject),- };-}-function readSchemaPointer(document: SchemaDocument, pointer: string): unknown {if (!pointer) return document;if (!pointer.startsWith("/")) {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 afa92607c..cb01ffdbe 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@@ -109,14 +109,11 @@ export function registerCompactArtifactTools(});/** Record diff candidates and read existing diff or Deep candidates. */- const writerSchema = workbenchDiscoveryCandidatesInputSchema;- const readerSchema = workbenchListCodexSecurityCandidatesInputSchema;-registerCompactTool(server, {name: "record_codex_security_discovery_candidates",title: "Record Codex Security Discovery Candidates",description: "Normalize and replace the selected diff scan's candidates.",- inputSchema: writerSchema,+ inputSchema: workbenchDiscoveryCandidatesInputSchema,readOnly: false,handler: async (input, requestContext) => {return recordCodexSecurityDiscoveryCandidates(@@ -130,7 +127,7 @@ export function registerCompactArtifactTools(name: "list_codex_security_candidates",title: "List Codex Security Candidates",description: "Read one page of diff or Deep scan discovery candidates.",- inputSchema: readerSchema,+ inputSchema: workbenchListCodexSecurityCandidatesInputSchema,readOnly: true,handler: async (input, requestContext) => {return listCodexSecurityCandidates(diff --git a/plugins/codex-security/mcp-app/tests/support/reducer-paging/deep-reducer-paging-fixture.ts b/plugins/codex-security/mcp-app/tests/support/reducer-paging/deep-reducer-paging-fixture.tsindex 75c635a18..c263e1109 100644--- a/plugins/codex-security/mcp-app/tests/support/reducer-paging/deep-reducer-paging-fixture.ts+++ b/plugins/codex-security/mcp-app/tests/support/reducer-paging/deep-reducer-paging-fixture.ts@@ -1,3 +1,4 @@+import { workerDraft } from "../../scan-draft-fixture.ts";import { readJson, writeJson } from "../json.ts";import assert from "node:assert/strict";import { createHash } from "node:crypto";@@ -88,12 +89,7 @@ export async function createReducerPagingFixture(root: string) {const previousPath = path.join(previousRoot, "result.json");await writeJson(workerPath, {...result,- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,});await writeJson(previousPath, previous);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 92f397989..d12ac1d8c 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@@ -38,9 +38,9 @@ async function testSchemaMatchesDocumentedAttackPathDecisions() {);assert.equal(schema.$schema, "https://json-schema.org/draft/2020-12/schema");- assert.deepEqual(schema.required, ["scanId", "attackPaths"]);- assert.equal(schema.additionalProperties, false);- assert.deepEqual(schema.$defs.input.required, schema.required);+ assert.deepEqual(schema.$defs.input.required, ["scanId", "attackPaths"]);+ assert.equal(schema.$defs.input.additionalProperties, false);+ assert.equal(schema.$ref, "#/$defs/input");assert.deepEqual(schema.$defs.updatesPayload.required, ["attackPaths"]);assert.deepEqual(schema.$defs.reportableAttackPath.properties.severity.enum, ["critical",diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_deep_reducer_pages.ts b/plugins/codex-security/mcp-app/tests/test_artifact_deep_reducer_pages.tsindex 950fe60ec..ce5649058 100644--- a/plugins/codex-security/mcp-app/tests/test_artifact_deep_reducer_pages.ts+++ b/plugins/codex-security/mcp-app/tests/test_artifact_deep_reducer_pages.ts@@ -1,5 +1,5 @@import { readJson } from "./support/json.ts";-import { finding as draftFinding } from "./scan-draft-fixture.ts";+import { workerDraft, finding as draftFinding } from "./scan-draft-fixture.ts";import { temporaryDirectory } from "./support/temporary-directories.ts";import type { ArtifactContext } from "../src/artifact-io.js";import type {@@ -111,12 +111,7 @@ try {scanId,findings: [fresh],scope: { summary: largeText },- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,};const previous = {scanId,diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.tsindex b96ed3142..f91f1571e 100644--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts@@ -1,3 +1,4 @@+import { workerDraft } from "./scan-draft-fixture.ts";import { readJson, snapshotScanDraft, writeJsonLine } from "./support/json.ts";import { mock } from "node:test";import { temporaryDirectory } from "./support/temporary-directories.ts";@@ -795,12 +796,7 @@ try {const acceptedDeepDraft = {...input,complete: true,- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,};await recordCodexSecurityScanDraft(deepParentContext, acceptedDeepDraft);const acceptedDeepFindings = await readJson(deepParentRoot, "findings.json");@@ -3033,12 +3029,7 @@ try {const noFindings = {...input,findings: [],- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,};const clean = await recordFreshScanDraft(context, noFindings);assert.equal(clean.findingCount, 0);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 453d639cd..a12d9bc38 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@@ -22,7 +22,8 @@ assert.equal(toolSchema.$schema,"https://json-schema.org/draft/2020-12/schema",);-assert.deepEqual(toolSchema.required, ["scanId", "validations"]);+assert.deepEqual(toolSchema.$defs.input.required, ["scanId", "validations"]);+assert.equal(toolSchema.$ref, "#/$defs/input");assert.deepEqual(toolSchema.$defs.validationUpdate.required, ["candidateId","validation",diff --git a/plugins/codex-security/mcp-app/tests/test_compact_artifact_server.ts b/plugins/codex-security/mcp-app/tests/test_compact_artifact_server.tsindex 564fda830..2bab97e39 100644--- a/plugins/codex-security/mcp-app/tests/test_compact_artifact_server.ts+++ b/plugins/codex-security/mcp-app/tests/test_compact_artifact_server.ts@@ -1,5 +1,5 @@import { readJson, snapshotScanDraft, writeJson } from "./support/json.ts";-import { finding } from "./scan-draft-fixture.ts";+import { workerDraft, finding } from "./scan-draft-fixture.ts";import { gitText } from "../scripts/git.mjs";import { temporaryDirectory } from "./support/temporary-directories.ts";import type { TextContent } from "@modelcontextprotocol/sdk/types.js";@@ -1290,12 +1290,7 @@ async function testDiscoveryWorkerToolList(bundle: string) {const input = {scanId,findings: [],- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,};requireToolError(@@ -1412,12 +1407,7 @@ async function testReducerWorkerToolList(bundle: string) {await writeJson(workerResultPath, {scanId,findings: [workerFinding],- coverage: {- completeness: "complete",- surfaces: [],- explicitExclusions: [],- deferred: [],- },+ coverage: workerDraft([]).coverage,});await writeJson(previousReducerResultPath, {scanId,diff --git a/plugins/codex-security/schemas/tools/candidate-attack-paths.schema.json b/plugins/codex-security/schemas/tools/candidate-attack-paths.schema.jsonindex 5e16c09a8..86049ed4b 100644--- a/plugins/codex-security/schemas/tools/candidate-attack-paths.schema.json+++ b/plugins/codex-security/schemas/tools/candidate-attack-paths.schema.json@@ -2,20 +2,7 @@"$schema": "https://json-schema.org/draft/2020-12/schema","$id": "codex-security://schemas/tools/candidate-attack-paths.schema.json","title": "Record Codex Security candidate attack paths",- "type": "object",- "additionalProperties": false,- "required": ["scanId", "attackPaths"],- "properties": {- "scanId": {- "$ref": "codex-security://schemas/definitions/artifact-common.schema.json#/$defs/scanId"- },- "attackPaths": {- "type": "array",- "items": {- "$ref": "#/$defs/attackPathUpdate"- }- }- },+ "$ref": "#/$defs/input","$defs": {"input": {"type": "object",diff --git a/plugins/codex-security/schemas/tools/candidate-validations.schema.json b/plugins/codex-security/schemas/tools/candidate-validations.schema.jsonindex b017d1281..5674acf90 100644--- a/plugins/codex-security/schemas/tools/candidate-validations.schema.json+++ b/plugins/codex-security/schemas/tools/candidate-validations.schema.json@@ -2,20 +2,7 @@"$schema": "https://json-schema.org/draft/2020-12/schema","$id": "codex-security://schemas/tools/candidate-validations.schema.json","title": "Record compact Codex Security candidate validations",- "type": "object",- "additionalProperties": false,- "required": ["scanId", "validations"],- "properties": {- "scanId": {- "$ref": "codex-security://schemas/definitions/artifact-common.schema.json#/$defs/scanId"- },- "validations": {- "type": "array",- "items": {- "$ref": "#/$defs/validationUpdate"- }- }- },+ "$ref": "#/$defs/input","$defs": {"input": {"type": "object",