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: share MCP response and annotation construction (#1444)
mldangelo-oai39a7ffcb8625
diff --git a/plugins/codex-security/mcp-app/server.ts b/plugins/codex-security/mcp-app/server.tsindex 2cd55f305..f9c42a2d3 100644--- a/plugins/codex-security/mcp-app/server.ts+++ b/plugins/codex-security/mcp-app/server.ts@@ -610,6 +610,14 @@ export function createCodexSecurityServer(): McpServer {deepScanCoordinators.shutdown("mcp_transport_closed");const appMeta = { ui: { visibility: ["app"] as const } };const modelActionMeta = { ui: { visibility: ["model"] as const } };+ const destructiveAnnotations = {+ ...writingAnnotations,+ destructiveHint: true,+ };+ const nonIdempotentWritingAnnotations = {+ ...writingAnnotations,+ idempotentHint: false,+ };server.registerTool("get_codex_security_daybreak_access",@@ -671,15 +679,10 @@ export function createCodexSecurityServer(): McpServer {access.status === "not_granted"? " This ChatGPT account check is advisory: a scan may run, but protected results associated with this account may not be displayable. It does not determine Amazon Bedrock model access or access to local CLI results.": "";- return {- content: [- {- type: "text" as const,- text: `Codex Security Daybreak access: status=${access.status}; programs=${programs.join(", ") || "none"}; checkedAt=${access.checkedAt}; stale=${access.stale}.${warning}`,- },- ],- structuredContent: access,- };+ return scanActionResult(+ access,+ `Codex Security Daybreak access: status=${access.status}; programs=${programs.join(", ") || "none"}; checkedAt=${access.checkedAt}; stale=${access.stale}.${warning}`,+ );},);@@ -741,20 +744,15 @@ export function createCodexSecurityServer(): McpServer {claimToken: handoffClaimToken,threadId,});- return {- content: [- {- type: "text" as const,- text: `${started.startDisposition === "created" ? "Started" : "Rejoined"} Standard scan ${scanId}. When the scan is in preflight, complete security_scan preflight before reviewing the target or creating a goal. Preserve the returned handoffClaimToken for scan progress, the semantic draft, and completion.`,- },- ],- structuredContent: {+ return scanActionResult(+ {...redactHandoffClaimToken(started),scanId,scanDir,handoffClaimToken,},- };+ `${started.startDisposition === "created" ? "Started" : "Rejoined"} Standard scan ${scanId}. When the scan is in preflight, complete security_scan preflight before reviewing the target or creating a goal. Preserve the returned handoffClaimToken for scan progress, the semantic draft, and completion.`,+ );},);@@ -869,12 +867,7 @@ export function createCodexSecurityServer(): McpServer {description:"App-only. Create a native Codex Security workspace with the target and requested standard, diff, or deep mode, or reopen one owned by this thread by passing only sessionId. Scope is inside targetPath; use '.' or omit scope for the whole target.",inputSchema: openSchema,- annotations: {- readOnlyHint: false,- destructiveHint: false,- idempotentHint: false,- openWorldHint: false,- },+ annotations: nonIdempotentWritingAnnotations,_meta: appMeta,},async (input, extra) => {@@ -933,15 +926,10 @@ export function createCodexSecurityServer(): McpServer {"--target-path",targetPath,]);- return {- content: [- {- type: "text" as const,- text: "Validated the local Codex Security target.",- },- ],- structuredContent: { target },- };+ return scanActionResult(+ { target },+ "Validated the local Codex Security target.",+ );},);@@ -966,15 +954,10 @@ export function createCodexSecurityServer(): McpServer {mode,...diffTargetArgs(diffTarget),]);- return {- content: [- {- type: "text" as const,- text: "Validated the local Codex Security setup.",- },- ],- structuredContent: { setup },- };+ return scanActionResult(+ { setup },+ "Validated the local Codex Security setup.",+ );},);@@ -1026,12 +1009,7 @@ export function createCodexSecurityServer(): McpServer {description:"App-only. Create a scan record and its local artifact directory before Codex analysis begins.",inputSchema: startScanSchema,- annotations: {- readOnlyHint: false,- destructiveHint: false,- idempotentHint: false,- openWorldHint: false,- },+ annotations: nonIdempotentWritingAnnotations,_meta: appMeta,},async ({ sessionId, model, reasoningEffort }) => {@@ -1253,12 +1231,7 @@ export function createCodexSecurityServer(): McpServer {description:"Stop a running scan from its owning Codex thread, prevent further progress or completion updates, and cancel any active deterministic Deep Scan SDK workers.",inputSchema: scanSchema,- annotations: {- readOnlyHint: false,- destructiveHint: true,- idempotentHint: true,- openWorldHint: false,- },+ annotations: destructiveAnnotations,_meta: modelActionMeta,},async ({ scanId }, extra) => {@@ -1279,12 +1252,7 @@ export function createCodexSecurityServer(): McpServer {description:"App-only. Stop a running scan from the native Codex Security workbench, prevent further progress or completion updates, and cancel any active deterministic Deep Scan SDK workers.",inputSchema: scanSchema,- annotations: {- readOnlyHint: false,- destructiveHint: true,- idempotentHint: true,- openWorldHint: false,- },+ annotations: destructiveAnnotations,_meta: appMeta,},async ({ scanId }) => cancelSecurityScan(scanId),@@ -1297,12 +1265,7 @@ export function createCodexSecurityServer(): McpServer {description:"App-only. Explicitly validate and republish retained checkpoints for one stopped scan, updating its artifacts, finding index, and counts.",inputSchema: scanSchema,- annotations: {- readOnlyHint: false,- destructiveHint: true,- idempotentHint: true,- openWorldHint: false,- },+ annotations: destructiveAnnotations,_meta: appMeta,},async ({ scanId }) =>@@ -1476,12 +1439,7 @@ export function createCodexSecurityServer(): McpServer {title: "Rename Codex Security Scan",description: "App-only. Change the display name of a saved scan.",inputSchema: { ...scanSchema, name: z.string() },- annotations: {- readOnlyHint: false,- destructiveHint: false,- idempotentHint: true,- openWorldHint: false,- },+ annotations: writingAnnotations,_meta: appMeta,},async ({ scanId, name }) =>@@ -1721,12 +1679,7 @@ export function createCodexSecurityServer(): McpServer {description:"Permanently mark a launched Codex Security scan as failed only after a confirmed unrecoverable blocker. For explicit user cancellation, use cancel_codex_security_scan instead. This terminal action cannot be resumed; incomplete or otherwise resumable work must remain running.",inputSchema: failSchema,- annotations: {- readOnlyHint: false,- destructiveHint: true,- idempotentHint: true,- openWorldHint: false,- },+ annotations: destructiveAnnotations,_meta: modelActionMeta,},async ({ scanId, message, handoffClaimToken }) => {@@ -1882,12 +1835,7 @@ export function createCodexSecurityServer(): McpServer {description:"App-only. Roll back an owned remediation request after the user declines its host follow-up.",inputSchema: findingRemediationClaimSchema,- annotations: {- readOnlyHint: false,- destructiveHint: true,- idempotentHint: true,- openWorldHint: false,- },+ annotations: destructiveAnnotations,_meta: appMeta,},async ({ occurrenceId, requestId, actionToken }) =>@@ -1937,12 +1885,7 @@ export function createCodexSecurityServer(): McpServer {description:"Persist the bounded local remediation workflow state for a completed finding. The UI may mark a request as queued; Codex records generated, applied, verifying, verified, or failed states after performing the corresponding work.",inputSchema: findingRemediationSchema,- annotations: {- readOnlyHint: false,- destructiveHint: false,- idempotentHint: false,- openWorldHint: false,- },+ annotations: nonIdempotentWritingAnnotations,_meta: modelActionMeta,},async ({@@ -2191,12 +2134,7 @@ function workspaceResult(workspace: WorkspaceState) {results && typeof results.scanDir === "string"? ` Scan state is attached at ${results.scanDir}.`: "";- return {- content: [- { type: "text" as const, text: `${setupSummary}${resultsSummary}` },- ],- structuredContent: { workspace },- };+ return scanActionResult({ workspace }, `${setupSummary}${resultsSummary}`);}function promptOnlyScanResult(promptOnly: JsonObject) {@@ -2222,18 +2160,13 @@ function promptOnlyScanResult(promptOnly: JsonObject) {"Codex Security prompt-only scan returned malformed context; no prompt-driven scan was started.",);}- return {- content: [- {- type: "text" as const,- text: `${startDisposition === "joined" ? "Rejoined" : "Started"} prompt-driven scan ${scanId}. Use the returned scanId and scanDir for every phase. Save progress and the final semantic draft with record_codex_security_scan_draft; the workbench writes the unsealed canonical files. Then call complete_codex_security_scan once to seal and index the completed findings.`,- },- ],- structuredContent: promptOnly,- };+ return scanActionResult(+ promptOnly,+ `${startDisposition === "joined" ? "Rejoined" : "Started"} prompt-driven scan ${scanId}. Use the returned scanId and scanDir for every phase. Save progress and the final semantic draft with record_codex_security_scan_draft; the workbench writes the unsealed canonical files. Then call complete_codex_security_scan once to seal and index the completed findings.`,+ );}-function scanActionResult(result: JsonObject, summary: string) {+function scanActionResult<T extends JsonObject>(result: T, summary: string) {return {content: [{ type: "text" as const, text: summary }],structuredContent: result,@@ -2297,13 +2230,7 @@ function userInputToolResult(: status === "cancelled"? "The Codex Security input request was cancelled. Do not infer an answer.": "Structured Codex Security input is unavailable in this host. Use the documented plain-chat fallback.";- return {- content: [{ type: "text" as const, text }],- structuredContent: {- status,- ...(answers ? { answers } : {}),- },- };+ return scanActionResult({ status, ...(answers ? { answers } : {}) }, text);}async function logUserInputFailure(@@ -2346,28 +2273,28 @@ function deepScanTerminalResult(run: DeepScanRunState) {if (run.status === "succeeded") {if (!run.manifestPath) return undefined;const instructions = `Deep Scan discovery completed. Independent Standard scans have already performed validation and attack-path analysis and have been consolidated into the canonical scan-manifest.json, findings.json, and coverage.json under ${run.scanDir}. The returned manifestPath is the canonical scan-manifest.json, not a legacy discovery manifest. Any instructions requiring parent candidate listing, centralized validation, attack-path analysis, or another draft apply only to the old discovery-only workflow and must be skipped. The authoritative scan ID is ${run.scanId}. Immediately call complete_codex_security_scan once using that scan ID to seal and publish the scan. Return output only after completion succeeds and generated report.md exists. If completion fails, surface that exact error and return no final, no-findings, structured, or benchmark response.`;- return {- content: [{ type: "text" as const, text: instructions }],- structuredContent: {+ return scanActionResult(+ {scanId: run.scanId,scanDir: run.scanDir,manifestPath: run.manifestPath,instructions,},- };+ instructions,+ );}if (run.status === "canceled") {if (run.error?.trim()) return toolErrorResult(deepScanFailureMessage(run));const instructions = `Deep Scan ${run.scanId} was canceled. Saved findings and pending candidates remain available in the scan's retained results. Do not start additional scan work or claim complete coverage.`;- return {- content: [{ type: "text" as const, text: instructions }],- structuredContent: {+ return scanActionResult(+ {status: "canceled",scanId: run.scanId,scanDir: run.scanDir,instructions,},- };+ instructions,+ );}if (run.status === "failed" || run.status === "interrupted") {return toolErrorResult(deepScanFailureMessage(run));diff --git a/sdk/typescript/tests-ts/completed-scan-handoff.test.ts b/sdk/typescript/tests-ts/completed-scan-handoff.test.tsindex 965e29853..dd0526af5 100644--- a/sdk/typescript/tests-ts/completed-scan-handoff.test.ts+++ b/sdk/typescript/tests-ts/completed-scan-handoff.test.ts@@ -7,12 +7,15 @@ test("does not request completed findings after a prompt-only scan", async () =>runtime,)?.[0];expect(source).toBeDefined();+ const actionSource =+ /function scanActionResult\([^\n]*\) \{[\s\S]*?\n\}/u.exec(runtime)?.[0];+ expect(actionSource).toBeDefined();const promptOnlyScanResult = new Function("isRecord","string2","toolErrorResult",- `${source}\nreturn promptOnlyScanResult;`,+ `${source}\n${actionSource}\nreturn promptOnlyScanResult;`,)((value: unknown) => value !== null && typeof value === "object",() => ({ uuid: () => ({ safeParse: () => ({ success: true }) }) }),