feat(scan): support custom validation instructions

README.md

@@ -72,6 +72,19 @@ root cause, reuses saved matches, and identifies new, persisting, reopened,
 resolved, or unknown findings. Missing findings remain unknown when coverage is
 incomplete or their original location was not reviewed.
 
+## Custom validation instructions
+
+Use a scan prompt file to explain how to run and check your application:
+
+```bash
+npx @openai/codex-security scan . --scan-prompt-file validation.md
+```
+
+For example, `validation.md` can tell the scanner to start the application from
+the repository root, check its local health endpoint, compare authenticated and
+unauthenticated access, stop the application afterward, and use source review
+if it cannot start.
+
 ## Verbose diagnostics
 
 Add `--verbose` to print redacted scan diagnostics to stderr:

sdk/typescript/README.md

@@ -76,6 +76,7 @@ Pass scan configuration to `security.run(repository, options)` or
 | `target`                | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
 | `mode`                  | Select `"standard"` or `"deep"`; deep mode supports repositories and paths.           |
 | `knowledgeBasePaths`    | Add architecture documents, security policies, threat models, or directories.         |
+| `scanPrompt`            | Add instructions for the scan, including application setup and validation.            |
 | `outputDir`             | Choose an artifact directory outside the enclosing Git worktree.                      |
 | `archiveExisting`       | Archive results already in `outputDir` before starting a scan.                        |
 | `maxCostUsd`            | Stop after the estimated model cost exceeds a positive USD amount.                    |

sdk/typescript/src/api.ts

@@ -2093,7 +2093,11 @@ async function scanPrompt(
     targetInstruction(target),
     "Write the complete canonical scan-manifest.json, findings.json, and coverage.json, but do not finalize or seal them; the SDK workbench owns authoritative metadata, finalization, report generation, and sealing.",
     ...(additionalPrompt?.trim()
-      ? ["Additional scan instructions:", additionalPrompt]
+      ? [
+          "Apply setup and testing instructions during validation.",
+          "Additional scan instructions:",
+          additionalPrompt,
+        ]
       : []),
   ].join("\n");
 }

sdk/typescript/tests-ts/api.test.ts

@@ -1921,7 +1921,7 @@ describe("CodexSecurity orchestration", () => {
       ),
     ).toBe(false);
     expect(prompt).toContain(
-      "Additional scan instructions:\nFocus on authentication and authorization.",
+      "Apply setup and testing instructions during validation.\nAdditional scan instructions:\nFocus on authentication and authorization.",
     );
     expect(followUpPrompt).toBe("Draft fixes for confirmed findings.");
     expect(