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 tool registration and annotations (#1485)
mldangelo-oaifed9fa04d863
diff --git a/plugins/codex-security/mcp-app/server.ts b/plugins/codex-security/mcp-app/server.tsindex 9762fb389..a6f92409e 100644--- a/plugins/codex-security/mcp-app/server.ts+++ b/plugins/codex-security/mcp-app/server.ts@@ -501,11 +501,6 @@ const findingRemediationSchema = {summary: z.string().trim().max(2400).optional(),verificationSummary: z.string().trim().max(2400).optional(),};-const findingRemediationRequestSchema = {- actionToken: z.string().uuid(),- occurrenceId: occurrenceIdSchema,- requestId: z.string().uuid(),-};const findingRemediationActionRequestSchema = {action: z.enum(["apply", "verify"]),actionToken: z.string().uuid(),@@ -783,12 +778,7 @@ export function createCodexSecurityServer(): McpServer {description:"Fallback for interactive Codex Security workflows when the host-native request_user_input tool is unavailable. Presents one to three non-sensitive multiple-choice questions through standard MCP form elicitation and waits for the user's response. Never call this tool in headless, automation, or other non-interactive sessions.",inputSchema: requestUserInputSchema,- annotations: {- readOnlyHint: true,- destructiveHint: false,- idempotentHint: false,- openWorldHint: false,- },+ annotations: { ...readingAnnotations, idempotentHint: false },_meta: modelActionMeta,},async ({ questions }, extra) => {@@ -1694,7 +1684,7 @@ export function createCodexSecurityServer(): McpServer {title: "Request Codex Security Finding Remediation",description:"App-only. Queue a completed finding for Codex remediation before sending the host a generate or regenerate request.",- inputSchema: findingRemediationRequestSchema,+ inputSchema: findingRemediationClaimSchema,annotations: writingAnnotations,_meta: appMeta,},@@ -1742,105 +1732,69 @@ export function createCodexSecurityServer(): McpServer {),);- server.registerTool(- "claim_codex_security_finding_remediation_resend",+ for (const { name, title, description, annotations, command, message } of [{+ name: "claim_codex_security_finding_remediation_resend",title: "Claim Codex Security Finding Remediation Resend",description:"App-only. Atomically take ownership of an unowned or stale remediation host request before resending it.",- inputSchema: findingRemediationClaimSchema,annotations: writingAnnotations,- _meta: appMeta,+ command: "claim-finding-remediation-resend",+ message: "Claimed the local Codex Security finding remediation resend.",},- async ({ occurrenceId, requestId, actionToken }) =>- scanActionResult(- await runWorkbench([- "claim-finding-remediation-resend",- "--occurrence-id",- occurrenceId,- "--request-id",- requestId,- "--action-token",- actionToken,- ]),- "Claimed the local Codex Security finding remediation resend.",- ),- );-- server.registerTool(- "release_codex_security_finding_remediation_claim",{+ name: "release_codex_security_finding_remediation_claim",title: "Release Codex Security Finding Remediation Claim",description:"App-only. Release a locally owned remediation host request after message delivery fails.",- inputSchema: findingRemediationClaimSchema,annotations: writingAnnotations,- _meta: appMeta,+ command: "release-finding-remediation-claim",+ message: "Released the local Codex Security finding remediation claim.",},- async ({ occurrenceId, requestId, actionToken }) =>- scanActionResult(- await runWorkbench([- "release-finding-remediation-claim",- "--occurrence-id",- occurrenceId,- "--request-id",- requestId,- "--action-token",- actionToken,- ]),- "Released the local Codex Security finding remediation claim.",- ),- );-- server.registerTool(- "cancel_codex_security_finding_remediation_request",{+ name: "cancel_codex_security_finding_remediation_request",title: "Cancel Codex Security Finding Remediation Request",description:"App-only. Roll back an owned remediation request after the user declines its host follow-up.",- inputSchema: findingRemediationClaimSchema,annotations: destructiveAnnotations,- _meta: appMeta,+ command: "cancel-finding-remediation-request",+ message: "Canceled the local Codex Security finding remediation request.",},- async ({ occurrenceId, requestId, actionToken }) =>- scanActionResult(- await runWorkbench([- "cancel-finding-remediation-request",- "--occurrence-id",- occurrenceId,- "--request-id",- requestId,- "--action-token",- actionToken,- ]),- "Canceled the local Codex Security finding remediation request.",- ),- );-- server.registerTool(- "mark_codex_security_finding_remediation_delivered",{+ name: "mark_codex_security_finding_remediation_delivered",title: "Mark Codex Security Finding Remediation Delivered",description:"App-only. Seal host-message delivery ownership before Codex starts a remediation worker.",- inputSchema: findingRemediationClaimSchema,annotations: writingAnnotations,- _meta: appMeta,- },- async ({ occurrenceId, requestId, actionToken }) =>- scanActionResult(- await runWorkbench([- "mark-finding-remediation-delivered",- "--occurrence-id",- occurrenceId,- "--request-id",- requestId,- "--action-token",- actionToken,- ]),+ command: "mark-finding-remediation-delivered",+ message:"Marked the local Codex Security finding remediation request as delivered.",- ),- );+ },+ ]) {+ server.registerTool(+ name,+ {+ title,+ description,+ inputSchema: findingRemediationClaimSchema,+ annotations,+ _meta: appMeta,+ },+ async ({ occurrenceId, requestId, actionToken }) =>+ scanActionResult(+ await runWorkbench([+ command,+ "--occurrence-id",+ occurrenceId,+ "--request-id",+ requestId,+ "--action-token",+ actionToken,+ ]),+ message,+ ),+ );+ }server.registerTool("set_codex_security_finding_remediation",diff --git a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts b/plugins/codex-security/mcp-app/src/server/handoff-tools.tsindex ed9667aaa..1e41ca01c 100644--- a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts+++ b/plugins/codex-security/mcp-app/src/server/handoff-tools.ts@@ -27,111 +27,79 @@ export const handoffClaimTokenSchema = z.union([z.string().uuid(),recoveryHandoffClaimTokenSchema,]);-const handoffClaimSchema = {+const handoffClaimSchema = z.object({claimToken: handoffClaimTokenSchema,scanId: z.string().uuid(),-};-const handoffTakeoverSchema = {- ...handoffClaimSchema,+});+const handoffTakeoverSchema = handoffClaimSchema.extend({takeOverStale: z.boolean().optional(),-};-const scanContinuationThreadSchema = {- ...handoffClaimSchema,+});+const scanContinuationThreadSchema = handoffClaimSchema.extend({threadId: z.string().trim().min(1).max(512),-};+});export function registerScanHandoffTools(server: McpServer,{ appMeta, runWorkbench, workspaceResult }: ScanHandoffToolDependencies,) {- server.registerTool(- "mark_codex_security_scan_handoff_delivered",+ for (const { name, title, description, inputSchema, command } of [{+ name: "mark_codex_security_scan_handoff_delivered",title: "Record Delivered Codex Security Handoff",description:"App-only. Record that the launched scan instructions were delivered to Codex.",inputSchema: handoffClaimSchema,- annotations: writingAnnotations,- _meta: appMeta,+ command: "mark-handoff-delivered",},- async ({ scanId, claimToken }) => {- const workspace = (await runWorkbench([- "mark-handoff-delivered",- "--scan-id",- scanId,- "--claim-token",- claimToken,- ])) as HandoffWorkspaceState;- return workspaceResult(workspace);- },- );-- server.registerTool(- "claim_codex_security_scan_handoff_delivery",{+ name: "claim_codex_security_scan_handoff_delivery",title: "Claim Codex Security Handoff Delivery",description:"App-only. Durably claim scan handoff delivery before sending continuation instructions to Codex.",inputSchema: handoffTakeoverSchema,- annotations: writingAnnotations,- _meta: appMeta,+ command: "claim-handoff-delivery",},- async ({ scanId, claimToken, takeOverStale }) => {- const workspace = (await runWorkbench([- "claim-handoff-delivery",- "--scan-id",- scanId,- "--claim-token",- claimToken,- ...(takeOverStale ? ["--take-over-stale"] : []),- ])) as HandoffWorkspaceState;- return workspaceResult(workspace);- },- );-- server.registerTool(- "release_codex_security_scan_handoff_delivery",{+ name: "release_codex_security_scan_handoff_delivery",title: "Release Codex Security Handoff Delivery",description:"App-only. Release a failed scan handoff delivery claim so the app can retry it.",inputSchema: handoffClaimSchema,- annotations: writingAnnotations,- _meta: appMeta,+ command: "release-handoff-delivery",},- async ({ scanId, claimToken }) => {- const workspace = (await runWorkbench([- "release-handoff-delivery",- "--scan-id",- scanId,- "--claim-token",- claimToken,- ])) as HandoffWorkspaceState;- return workspaceResult(workspace);- },- );-- server.registerTool(- "attach_codex_security_scan_continuation_thread",{+ name: "attach_codex_security_scan_continuation_thread",title: "Attach Codex Security Scan Thread",description:"App-only. Persist the normal local Codex thread created for a claimed scan handoff.",inputSchema: scanContinuationThreadSchema,- annotations: writingAnnotations,- _meta: appMeta,+ command: "attach-scan-continuation-thread",},- async ({ scanId, claimToken, threadId }) => {- const workspace = (await runWorkbench([- "attach-scan-continuation-thread",- "--scan-id",- scanId,- "--claim-token",- claimToken,- "--thread-id",- threadId,- ])) as HandoffWorkspaceState;- return workspaceResult(workspace);- },- );+ ] as const) {+ server.registerTool(+ name,+ {+ title,+ description,+ inputSchema,+ annotations: writingAnnotations,+ _meta: appMeta,+ },+ async (input: z.infer<typeof inputSchema>) => {+ const arguments_ = [+ command,+ "--scan-id",+ input.scanId,+ "--claim-token",+ input.claimToken,+ ];+ if ("takeOverStale" in input && input.takeOverStale)+ arguments_.push("--take-over-stale");+ if ("threadId" in input) arguments_.push("--thread-id", input.threadId);+ return workspaceResult(+ (await runWorkbench(arguments_)) as HandoffWorkspaceState,+ );+ },+ );+ }}diff --git a/plugins/codex-security/mcp-app/src/server/tool-annotations.ts b/plugins/codex-security/mcp-app/src/server/tool-annotations.tsindex 0253fdced..124c601a3 100644--- a/plugins/codex-security/mcp-app/src/server/tool-annotations.ts+++ b/plugins/codex-security/mcp-app/src/server/tool-annotations.ts@@ -6,8 +6,6 @@ export const readingAnnotations = {};export const writingAnnotations = {+ ...readingAnnotations,readOnlyHint: false,- destructiveHint: false,- idempotentHint: true,- openWorldHint: false,};diff --git a/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts b/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.tsindex bf7f86456..8384b770c 100644--- a/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts+++ b/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts@@ -2434,15 +2434,22 @@ try {);const handoffClaimToken = randomUUID();- const claimedHandoff = await testServer.callTool(2002, {- name: "claim_codex_security_scan_handoff_delivery",- arguments: { claimToken: handoffClaimToken, scanId },- });- assertNoError(claimedHandoff);- assert.equal(- claimedHandoff.result.structuredContent.workspace.results.handoffClaimToken,- handoffClaimToken,- );+ for (const [index, name] of [+ "claim_codex_security_scan_handoff_delivery",+ "release_codex_security_scan_handoff_delivery",+ "claim_codex_security_scan_handoff_delivery",+ ].entries()) {+ const claimedHandoff = await testServer.callTool(200200 + index, {+ name,+ arguments: { claimToken: handoffClaimToken, scanId },+ });+ assertNoError(claimedHandoff);+ assert.equal(+ claimedHandoff.result.structuredContent.workspace.results+ .handoffClaimToken,+ index === 1 ? null : handoffClaimToken,+ );+ }const attachedHandoff = await testServer.callTool(20021, {name: "attach_codex_security_scan_continuation_thread",arguments: {@@ -2912,20 +2919,28 @@ try {},);- const requestedPatch = await testServer.callTool(61, {- name: "request_codex_security_finding_remediation",- arguments: {- actionToken: generationActionToken,- occurrenceId,- requestId: remediationRequestId,- },- });- assertNoError(requestedPatch);- assert.equal(- requestedPatch.result.structuredContent.scan.findings[0].remediationState- .state,- "requested",- );+ for (const [index, name] of [+ "request_codex_security_finding_remediation",+ "release_codex_security_finding_remediation_claim",+ "claim_codex_security_finding_remediation_resend",+ ].entries()) {+ const requestedPatch = await testServer.callTool(6100 + index, {+ name,+ arguments: {+ actionToken: generationActionToken,+ occurrenceId,+ requestId: remediationRequestId,+ },+ });+ assertNoError(requestedPatch);+ const remediation =+ requestedPatch.result.structuredContent.scan.findings[0].remediationState;+ assert.equal(remediation.state, "requested");+ assert.equal(+ remediation.actionClaimToken,+ index === 1 ? null : generationActionToken,+ );+ }const rejectedPendingClose = await testServer.callTool(161, {name: "set_codex_security_finding_triage",arguments: { occurrenceId, status: "closed", closeReason: "already_fixed" },