fix(plugin): require evidence before completing scans

evals/standard-time-budget/test_validation_survival.mts

@@ -57,10 +57,15 @@ for (const deferLast of [false, true]) {
     const accepted = (deferLast ? candidates.slice(0, -1) : candidates).map(
       (candidate) => ({
         ...candidate,
+        rootCause: `The ${candidate.ruleId} route omits the corresponding safe control.`,
+        attackPath: {
+          dataflow: `Request input reaches the cited sink in ${candidate.locations[0]!.path}.`,
+        },
         validation: {
           disposition: "reportable",
           method: "Static review",
           summary: `Verified ${candidate.ruleId} against its cited sink.`,
+          evidenceRefs: [candidate.ruleId],
           limitations: ["Synthetic review."],
         },
         provenance: {
@@ -96,6 +101,8 @@ for (const deferLast of [false, true]) {
         for (const field of [
           "identity",
           "locations",
+          "rootCause",
+          "attackPath",
           "validation",
           "codeEvidence",
         ] as const)

plugins/codex-security/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-security",
-  "version": "0.1.95",
+  "version": "0.1.96",
   "description": "Codex Security workflows for security scans, analysis, and investigation.",
   "author": {
     "name": "OpenAI"

plugins/codex-security/examples/completed-scan/findings.json

@@ -10,6 +10,17 @@
           "summary": "The caller must be able to supply an archive for extraction. The service account must have write access to the destination."
         }
       },
+      "codeEvidence": [
+        {
+          "code": "destination = output_dir / entry.name\nwith archive.open(entry) as source:\n    destination.parent.mkdir(parents=True, exist_ok=True)\n    destination.write_bytes(source.read())",
+          "endLine": 44,
+          "explanation": "The destination incorporates an untrusted archive entry name and is written without a containment check.",
+          "id": "archive-write",
+          "label": "Unchecked archive write",
+          "path": "src/extract.py",
+          "startLine": 41
+        }
+      ],
       "confidence": {
         "level": "high",
         "rationale": "The destination passed to the file writer is visible in the reviewed code."
@@ -42,6 +53,9 @@
       "remediationTests": [
         "Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
       ],
+      "rootCause": {
+        "summary": "The extractor joins the entry name to the output directory without checking whether the destination stays inside it."
+      },
       "ruleId": "path-traversal.archive-extraction",
       "severity": {
         "changeConditions": "A filesystem policy that confines writes to a disposable import directory would limit the impact.",
@@ -59,6 +73,12 @@
       },
       "title": "Unsafe archive extraction can escape the output directory",
       "validation": {
+        "evidence": [
+          "The untrusted entry name reaches the filesystem write without normalization or a containment check."
+        ],
+        "limitations": [
+          "The extraction route was not exercised dynamically."
+        ],
         "method": "Static source review",
         "summary": "The extractor combines the output directory with the entry name and passes the resulting path to the writer. It never checks that the destination stays inside the output directory."
       }

plugins/codex-security/examples/completed-scan/report.md

@@ -60,12 +60,22 @@ No explicit canonical threat-model summary was recorded.
 
 Archive extraction can overwrite files outside the directory chosen for the import.
 
+#### Root Cause
+
+The extractor joins the entry name to the output directory without checking whether the destination stays inside it.
+
 #### Validation
 
 The extractor combines the output directory with the entry name and passes the resulting path to the writer. It never checks that the destination stays inside the output directory.
 
 Validation method: Static source review
 
+Evidence:
+- The untrusted entry name reaches the filesystem write without normalization or a containment check.
+
+Limitations:
+- The extraction route was not exercised dynamically.
+
 #### Dataflow
 
 The archive supplies an entry name. The extractor uses that name to select the file it writes.

plugins/codex-security/examples/completed-scan/scan-manifest.json

@@ -5,7 +5,7 @@
       {
         "mediaType": "application/json",
         "path": "findings.json",
-        "sha256": "3c63586ea38b07b1d5ad9004ba2afc27f67e79ed164da508c7beae72648eb3b7"
+        "sha256": "c6a4d31e66342a60bf427e71f57b318236ac4c822d92303a716dd516165e0dd1"
       }
     ],
     "completedAt": "2026-05-31T18:09:00Z",

plugins/codex-security/mcp-app/deep-scan-main.ts

@@ -60,7 +60,7 @@ export async function runCliDeepScan(): Promise<void> {
     if (controller.signal.aborted)
       throw new Error("Deep Scan canceled before coordinator startup.");
     let terminal = run;
-    if (run.status === "running") {
+    if (run.status === "running" || run.evidenceRepairRequired) {
       const started = await startDeepScanEngine({
         run,
         store,

plugins/codex-security/mcp-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-security-mcp-app",
-  "version": "0.1.161",
+  "version": "0.1.162",
   "type": "module",
   "private": true,
   "scripts": {

plugins/codex-security/mcp-app/server.ts

@@ -1568,7 +1568,7 @@ export function createCodexSecurityServer(): McpServer {
     {
       title: "Complete Codex Security Scan",
       description:
-        "Finalization only: validate and seal already-authored scan-manifest.json and findings.json, generate report.md, index findings, and mark the scan complete. For an app-backed running scan, scan-manifest.json is an unsealed draft and must omit scan.sealedAt and scan.artifacts; this tool supplies the exact workbench timestamps, seal, artifact digests, and derived finding identities. Call only after those canonical files exist; this tool does not create missing artifacts or run skipped phases. If it fails, surface the exact error and stop the current response without retrying completion or returning a final, no-findings, structured, or benchmark response.",
+        "Finalization only: validate and seal already-authored scan-manifest.json and findings.json, generate report.md, index findings, and mark the scan complete. For an app-backed running scan, scan-manifest.json is an unsealed draft and must omit scan.sealedAt and scan.artifacts; this tool supplies the exact workbench timestamps, seal, artifact digests, and derived finding identities. Call only after those canonical files exist; this tool does not create missing artifacts or run skipped phases. If completion requests a corrected draft, repair the same scan and retry. For other failures, surface the exact error and stop the current response without retrying completion or returning a final, no-findings, structured, or benchmark response.",
       inputSchema: completeScanSchema,
       annotations: writingAnnotations,
       _meta: modelActionMeta,
@@ -2206,6 +2206,7 @@ function deepScanTerminalResult(
   run: DeepScanRunState,
   completion?: JsonObject,
 ) {
+  if (run.evidenceRepairRequired) return undefined;
   if (run.status === "succeeded") {
     if (!run.manifestPath) return undefined;
     const outcome =
@@ -2417,9 +2418,24 @@ function failureDiagnostic(error: unknown): string {
 }
 
 function completionFailureMessage(error: unknown): string {
+  const diagnostic = failureDiagnostic(error);
+  if (
+    diagnostic.startsWith(
+      "Scan result contains invalid findings; repair the finding records before completion.",
+    ) ||
+    diagnostic ===
+      "The latest saved scan draft is incomplete; continue the scan before completing it."
+  ) {
+    return [
+      "Codex Security scan completion needs a corrected draft.",
+      diagnostic,
+      "Continue the same scan, repair the named evidence gaps using actual source or validation evidence, and retry completion after saving the corrected draft. Preserve valid findings and deferred work; do not invent evidence or start another scan.",
+      "Do not return a final, no-findings, structured, or benchmark response until completion succeeds.",
+    ].join("\n");
+  }
   return [
     "Codex Security scan completion failed.",
-    failureDiagnostic(error),
+    diagnostic,
     "Stop the current response and surface this exact MCP error.",
     "Do not retry completion or return a final, no-findings, structured, or benchmark response.",
   ].join("\n");

plugins/codex-security/mcp-app/src/deep-scan/artifact-validation.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { dirname, join, posix, relative, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { asRecord } from "../record.js";
+import { asRecord, isNonEmptyString } from "../record.js";
 import type { JsonObject } from "../types.js";
 import { artifactSourcePath, type ArtifactContext } from "../artifact-io.js";
 import {
@@ -91,8 +91,11 @@ export async function validateDiscoveryArtifacts(
     throw new Error(
       "Standard scan worker wrote only a checkpoint; its audit is not complete.",
     );
-  // Preserve the existing publication of previously accepted historical payloads.
-  if (admission === "new") validateWorkerReport(result);
+  // Historical worker inputs are immutable. The host repairs their evidence on resume.
+  if (admission === "new") {
+    validateWorkerReport(result);
+    validateCompletedFindingEvidence(result.findings);
+  }
   validateRetainedCoverage(result.reviewState);
   // Check the worker's own task IDs before qualifying active and closed tasks.
   const closures = result.reviewState.resolvedDeferred ?? [];
@@ -296,3 +299,48 @@ export function parseStoredScanDraft<Result extends ScanUnion>(
   }
   return parsed;
 }
+
+/** Match the finalizer's evidence gate while worker validation can still retry. */
+export function validateCompletedFindingEvidence(findings: JsonObject[]): void {
+  for (const [index, finding] of findings.entries()) {
+    const requireText = (value: unknown, field: string) => {
+      if (!isNonEmptyString(value))
+        throw new Error(
+          `findings[${index}].${field}: include the supporting analysis before completing the worker.`,
+        );
+    };
+    if (
+      !Array.isArray(finding.codeEvidence) ||
+      finding.codeEvidence.length === 0
+    )
+      throw new Error(
+        `findings[${index}].codeEvidence: include the source snippets used as proof.`,
+      );
+    requireText(
+      asRecord(finding.rootCause)?.summary ?? finding.rootCause,
+      "rootCause",
+    );
+    const dataflow = asRecord(finding.attackPath)?.dataflow;
+    const flow = asRecord(dataflow);
+    if (flow) {
+      if (!flow.summary) {
+        requireText(flow.source, "attackPath.dataflow.source");
+        requireText(flow.sink, "attackPath.dataflow.sink");
+      }
+    } else {
+      requireText(dataflow, "attackPath.dataflow");
+    }
+    const validation = asRecord(finding.validation);
+    requireText(validation?.method, "validation.method");
+    if (!validation?.result)
+      requireText(validation?.summary, "validation.summary");
+    const hasEvidence = [validation?.evidence, validation?.evidenceRefs].some(
+      (value) =>
+        Array.isArray(value) ? value.length > 0 : isNonEmptyString(value),
+    );
+    if (!hasEvidence)
+      throw new Error(
+        `findings[${index}].validation: include observed evidence or evidenceRefs to the source proof.`,
+      );
+  }
+}