Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(scan): clarify tool selection and worker follow-ups (#1591)

Michael D'Angelo54359a1d67bc
diff --git a/plugins/codex-security/references/core-scan.md b/plugins/codex-security/references/core-scan.md
index fabac952d..2f38a9851 100644
--- a/plugins/codex-security/references/core-scan.md
+++ b/plugins/codex-security/references/core-scan.md
@@ -17,10 +17,14 @@ Before deciding whether a candidate is reportable, read existing reviewer false-
Keep discovery, validation, and attack-path reasoning within this one self-contained audit; do not invoke separate phase skills. Do not create ranking phases, per-file or per-candidate ledgers, separate phase worker pools, repeated phase reports, or receipt files.
+Use `followup_task` when a returned worker must perform another review or answer a required recheck. `send_message` is an update to an existing turn, not a request that starts another turn; sending at a worker's final-response tail does not establish that it acted on the message. Wait only while assigned work or a required follow-up is still pending. When the parent has finished its remaining in-scope source review and all assigned reviews have returned, reconcile their evidence and submit the result; do not enter an idle wait for unspecified future updates. If work remains incomplete at a user limit, retain it as deferred work in a partial result.
+
## Offline Source Search
Resolve one working native local search command before scanning and pass its verified path to every worker. Prefer an existing ripgrep executable; reject DotSlash, bootstrap, or other download-capable wrappers, and fall back to local `git grep`, `find`, or `grep`. Do not install tools or trigger network downloads.
+Prefer quoted interpreter `-c` programs or pipes when shell heredocs or here-strings require unavailable temporary storage. When analysis needs files, use only the managed temporary staging already authorized by the assigned workflow (`artifact-storage.md`). Keep target source read-only and do not widen permissions. Check command exit status and tool errors, including MCP `isError`, before parsing successful JSON output; an error or truncated preview is not a JSON document. Code mode is a fresh JavaScript isolate: use only its documented globals and tools, not assumed Node.js APIs or `structuredClone`. When available, use `load`/`store` for serializable state between cells, with `null` for absent values.
+
## Secrets Exposed in Source
Review the authorized current source offline for embedded credentials and private keys. Inspect literals and their context in code, configuration, documentation, tests, examples, and inactive code; do not restrict this review to executable paths or production files. Assign this review to the baseline auditor, or do it yourself when delegation is unavailable, and reconcile it with the existing source coverage.
@@ -33,6 +37,8 @@ Distinguish credential material from public keys or certificates, identifiers, e
Resolve and cache directory-specific security guidance with `<plugin_dir>/scripts/launch_codex_security_mcp --helper resolve-security-md --repo <repo_root> --scope <file_or_directory> --out -` (use `launch_codex_security_mcp.cmd` on Windows). Resolve once per distinct reviewed directory or investigation packet, pass the matching inherited policy to its worker, and let the closest nested `SECURITY.md` take precedence.
+Apply that policy when deciding reportability as well as when mapping the component. An intentionally vulnerable example or QA fixture can define application boundaries that remain in scope with synthetic data. If its applicable policy asks to assess those boundaries, retain source-supported findings and identify their fixture context, calibrating impact to the supported local scenario. Do not substitute the enclosing product's disclosure eligibility for that component's review policy or claim real credential, financial, or deployment impact from a simulation. Explicit user exclusions still control the requested scope.
+
## Threat Map And Investigation Packets
Use the architecture and scenarios from `threat-model.md` to group concrete security questions. Each packet contains its ID, shared attacker and protected asset, expected controls, entry points, sensitive operations, component relationships, meaningful capability gain, prerequisites, and actual repository-relative source paths and lines. When startup paths materialize credentials, sensitive state, or network destinations, include a backward trace from the consumer through effective configuration and documented guarantees. Include related questions in that shared context; add source excerpts when they materially clarify a lead. Do not invent source locations, attacker reachability, deployment assumptions, or complete coverage.
@@ -59,7 +65,9 @@ Send this prompt to the independent baseline subagent, followed only by the auth
Perform a thorough static security analysis of the repository in its actual implementation language or languages. Find every real vulnerability supported by specific source evidence.
-Follow this self-contained baseline audit only. Apply the supplied threat model, exact user security context, optional authoritative knowledge-base documents, and nearest inherited `SECURITY.md` policy; knowledge-base facts override generated assumptions and repository policies, but never explicit user instructions. Resolve and cache a more specific policy when entering a new source directory. Do not load Codex Security skills, start another scan, use security-scan tools, or delegate.
+Follow this self-contained baseline audit only. Apply the supplied threat model, exact user security context, optional authoritative knowledge-base documents, and nearest inherited `SECURITY.md` policy; knowledge-base facts override generated assumptions and repository policies, but never explicit user instructions. Resolve and cache a more specific policy when entering a new source directory. When that policy includes an example or QA fixture's application boundaries, assess them under that policy and calibrate its synthetic impact instead of excluding it under the enclosing product's disclosure criteria. Do not load Codex Security skills, start another scan, use security-scan tools, or delegate.
+
+Prefer quoted interpreter `-c` programs or pipes when shell heredocs or here-strings require unavailable temporary storage. When analysis needs files, use only the managed temporary staging already authorized by the assigned workflow (`artifact-storage.md`). Keep target source read-only and do not widen permissions. Check command exit status and tool errors before parsing successful JSON output; an error or truncated preview is not a JSON document. Code mode is a fresh JavaScript isolate: use only its documented globals and tools, not assumed Node.js APIs or `structuredClone`. When available, use `load`/`store` for serializable state between cells, with `null` for absent values.
Explore the architecture, entry points, attack surfaces, parsers, uploads, protocol handlers, and data inputs. Trace attacker-controlled input to security-sensitive operations. Verify effective controls and counterevidence before reporting a finding.
@@ -81,7 +89,9 @@ Send this prompt to each investigator, followed only by its assigned real packet
```markdown
Investigate the assigned source-backed security questions in the authorized repository. Treat every packet as a starting point, not a conclusion or a boundary on repository exploration.
-Follow this self-contained investigator prompt. Apply the supplied threat model, exact user security context, optional authoritative knowledge-base documents, and nearest inherited `SECURITY.md` policy; knowledge-base facts override generated assumptions and repository policies, but never explicit user instructions. Resolve and cache a more specific policy when entering a new source directory. Do not invoke Codex Security phase skills or MCP tools, load their references, or delegate to another worker.
+Follow this self-contained investigator prompt. Apply the supplied threat model, exact user security context, optional authoritative knowledge-base documents, and nearest inherited `SECURITY.md` policy; knowledge-base facts override generated assumptions and repository policies, but never explicit user instructions. Resolve and cache a more specific policy when entering a new source directory. When that policy includes an example or QA fixture's application boundaries, assess them under that policy and calibrate its synthetic impact instead of excluding it under the enclosing product's disclosure criteria. Do not invoke Codex Security phase skills or MCP tools, load their references, or delegate to another worker.
+
+Prefer quoted interpreter `-c` programs or pipes when shell heredocs or here-strings require unavailable temporary storage. When analysis needs files, use only the managed temporary staging already authorized by the assigned workflow (`artifact-storage.md`). Keep target source read-only and do not widen permissions. Check command exit status and tool errors before parsing successful JSON output; an error or truncated preview is not a JSON document. Code mode is a fresh JavaScript isolate: use only its documented globals and tools, not assumed Node.js APIs or `structuredClone`. When available, use `load`/`store` for serializable state between cells, with `null` for absent values.
Read the actual source, follow callers and dataflow, inspect authentication and authorization, ownership, tenant boundaries, parsing, state transitions, sensitive operations, effective controls, and counterevidence. Preserve independent vulnerable operations even when they share a helper. Continue investigating after finding one issue.
diff --git a/plugins/codex-security/references/scan-prologue.md b/plugins/codex-security/references/scan-prologue.md
index 54d0a51c1..dbb47568e 100644
--- a/plugins/codex-security/references/scan-prologue.md
+++ b/plugins/codex-security/references/scan-prologue.md
@@ -16,6 +16,12 @@ Preserve the complete exact user-provided security context, including user-suppl
For a running host-backed scan, immediately persist requested additions, edits, clearances, or replacements with `update_codex_security_scan_context`, passing the complete replacement and current handoff token when required. At each genuine parent-owned forward phase transition, use `structuredContent.scan.userContext` from `update_codex_security_scan_progress` as the immutable context for that phase and its workers. Prompt-only scans retain their original context; independent workers retain the exact immutable context captured by their owner. Never repeat a completed phase or publish progress belonging to a currently running coordinator.
+## Tool Results and Code Mode
+
+Check the result of each tool operation before using it: a completed code-mode cell can contain an MCP response with `isError: true`, or a shell command with a failing exit status. Preserve and act on that diagnostic before parsing output as JSON or emitting a success marker. Parse only the intended JSON output of a successful command; shell error text and truncated previews are not JSON documents.
+
+Code mode is a fresh JavaScript isolate, not a Node.js shell. Use only the host's documented globals and tools; do not assume `process`, `require`, `Buffer`, `TextEncoder`, or `structuredClone` exist. Use ordinary JSON operations for JSON data and the documented `load`/`store` helpers for state across cells. Store only serializable values, using `null` for an absent value, and commit dependent state together so a failed later operation cannot leave a stale cursor or count paired with new data.
+
## Standard Capability Preflight
Only a top-level Standard scan reads `config-preflight.md` and runs its existing `security_scan` capability profile once. A desktop Standard host also follows `desktop-config-preflight.md` after its authoritative scan context exists. Resolve only the minimum target, scope, revision, or launch arguments needed beforehand; do not inspect source or launch Standard scan workers until the helper returns `ready`. Retain the existing host-specific direct/delegated execution, remediation, fallback, and degraded-worker behavior; configured worker capacity is not a required number of running workers.
diff --git a/plugins/codex-security/skills/security-scan/SKILL.md b/plugins/codex-security/skills/security-scan/SKILL.md
index dcf0838f9..398aab5d8 100644
--- a/plugins/codex-security/skills/security-scan/SKILL.md
+++ b/plugins/codex-security/skills/security-scan/SKILL.md
@@ -28,6 +28,8 @@ When an SDK or terminal host sets `CODEX_SECURITY_SCAN_ID`, emit its standalone
Keep discovery, validation, and attack-path reasoning within this Standard workflow; do not invoke separate phase skills or load Deep or diff references. Never call Deep-only tools. Do not create ranking phases, per-file or per-candidate ledgers, separate phase worker pools, repeated phase reports, or receipt files.
+Once the assigned reviews and required follow-ups have returned, submit the semantic result and follow the host's completion path. Do not wait for an unspecified worker update after the review is settled. `complete: true` finishes the audit turn; coverage must still be `partial` when source review or candidate work remains deferred.
+
## Windows Scope Binding
In PowerShell, replace the placeholders inside single quotes with literal paths, doubling any single quote in a path. Keep the supplied `CODEX_SECURITY_TARGET_PATHS_FILE` value unchanged:
diff --git a/sdk/typescript/src/custom-validation-prompt.ts b/sdk/typescript/src/custom-validation-prompt.ts
index 7ba8aa8c6..201ecc9df 100644
--- a/sdk/typescript/src/custom-validation-prompt.ts
+++ b/sdk/typescript/src/custom-validation-prompt.ts
@@ -9,9 +9,9 @@ import { PLUGIN_NAME } from "./runtime.js";
// the ordinary validation sequence with a custom-validation request.
const SOURCES = {
"references/core-scan.md":
- "9e9211f6de6eb8138246474e2ec24a8506abf08537c2a5f572de4fe16c38c19c",
+ "11826b993499aa1a1bab35eb3f54da83376925afae00f9fcd375177847451916",
"skills/security-scan/SKILL.md":
- "5a565d8d0ba80d3048db75922b8b4f29e23c76690a5795b0d7dfbd24a233d3a0",
+ "7d66fe0bc471a4e13907c20f4167ff7a9de8bbf07e6e7dda6ccdab19117a945d",
"skills/security-diff-scan/SKILL.md":
"2dbe04cbe50f8a511327fa384e37f23cdf0630b233186a52d02c515082c4c881",
} as const;
@@ -63,6 +63,10 @@ export async function customDiscoveryPrompt(
.replace(
/^Keep discovery, validation, and attack-path reasoning.+$/m,
"Keep source-evidence and counterevidence checks within discovery. Do not run an independent final validation pass or invoke separate phase skills.",
+ )
+ .replace(
+ "reconcile their evidence and submit the result;",
+ "reconcile their evidence and preserve provisional candidates through the SDK-owned discovery handoff;",
);
workflow = [
skill.slice(
diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.ts
index 0220c5e62..d5fc5d000 100644
--- a/sdk/typescript/tests-ts/custom-validation.test.ts
+++ b/sdk/typescript/tests-ts/custom-validation.test.ts
@@ -878,6 +878,8 @@ describe("custom validation", () => {
expect(standard).toContain("security_scan` capability preflight");
expect(standard).toContain("use it for the same early model checkpoint");
expect(standard).toContain("retain the model in an early partial");
+ expect(standard).toContain("`followup_task`");
+ expect(standard).toContain("`send_message`");
expect(standard).not.toContain("undefined");
expect(standard).not.toContain(
"Independently validate each unique finding",