deep-security-scan

# Deep Security Scan ## Setup Workspace Routing When this skill is the active top-level workflow, use the setup workspace only when the host context explicitly says it is running inside the Codex desktop app and both required setup continuation tools are available. Tool availability alone does not identify the app host. Otherwise, including Codex CLI interactive and headless runs, use the prompt-only terminal/chat workflow: do not call Codex Security app setup tools, ask the user to press Start scan, or wait for an app-generated `scanId`. Treat goal creation as scan execution, not setup. In the app setup path, do not create or adopt scan goals before the user presses Start scan, the authoritative scan context has been loaded from a `status: "started"` wait result or a direct continuation with a `scanId`, and the capability preflight has returned `ready`. This includes coordinator and worker-local goals. For an app continuation that already includes a `scanId` and optional `handoffClaimToken`, do not open another workspace: call `get_codex_security_scan_context` with the `scanId`, pass its `handoffClaimToken` when present, route elsewhere only if its validated mode differs, and use its target, optional `userContext`, and `scanDir`. The top-level coordinator must inspect `otherRunningDeepScans` only once for each newly launched scan: immediately after the first scan context load for that handoff and before preflight, goal creation, worklist creation, or worker creation. Treat this gate as passed for the current scan when the list is empty or the user chooses `Continue`. Do not repeat the check on later context loads, if another scan appears after the current scan already passed this gate, or after the current scan has progressed beyond preflight. Delegated workers do not perform this check. - If it is empty, continue normally. - If it is non-empty, show a compact warning. For each other scan, include only its target path, current phase in plain language, and human-friendly start time. Do not include scan IDs, raw timestamps, update times, or commentary about stale records or interrupted threads. Add one short sentence that running Deep Security Scans concurrently can increase CPU, memory, and token consumption and slow both scans. - After showing those details in an interactive Codex session, optimistically call `request_user_input` so the user can choose without typing: ```text request_user_input( questions=[ { "header": "Deep scan?", "id": "concurrent_deep_scan", "question": "Another Deep Security Scan is running. Continue this one?", "options": [ { "label": "Cancel (Recommended)", "description": "Stop this new scan before preflight or substantive work." }, { "label": "Continue", "description": "Proceed even though both scans may run more slowly and use more resources." } ] } ] ) ``` - If `request_user_input` is unavailable or errors, ask the user to choose `Continue` or `Cancel` in chat. In either case, stop for the answer. Do not run preflight, create or adopt goals, create shared worklists, or create workers while waiting. - Continue only after explicit confirmation. If the user chooses `Cancel`, call `fail_codex_security_scan` for the new scan with a concise cancellation reason and perform no substantive scan work. Do not modify or fail any previously running scan. Otherwise, in a host that renders MCP Apps and exposes the Codex Security setup continuation tools: 1. Resolve setup arguments directly from the user's initial prompt and known thread context: local `targetPath` (for scoped-path requests, use the scoped directory itself as `targetPath`), `mode: "deep"`, `scope: "."`, and only user-supplied security focus as `userContext`. 2. Perform only the minimal path resolution needed to construct those arguments. Do not run capability preflight, inspect the repository, threat model, discover findings, or create workers before setup opens. 3. Immediately call `open_codex_security_workspace` with the resolved arguments. Do not search for or substitute a separate scan command. 4. Immediately call `await_codex_security_scan_start` with the `sessionId` from the workspace returned by `open_codex_security_workspace`. A returned workspace with `setup.submitted=false` is the expected wait state. Keep the tool call pending while waiting for the user to review setup and press Start scan; do not create or adopt coordinator or worker-local goals, run preflight, or pivot to terminal/chat fallback while waiting. 5. If the wait returns `status: "started"`, require its `scanId`, call `get_codex_security_scan_context` with that `scanId`, and pass its `handoffClaimToken` when present. Apply the `otherRunningDeepScans` confirmation above, then run the preflight in `../../references/config-preflight.md` for the selected target and `deep_security_scan` profile before goal setup, threat modeling, worker creation, or other substantive scan work. 6. If the wait returns `status: "already_delivered"`, end the current turn without loading scan context or starting scan work. Another continuation already owns the scan. 7. If the wait returns `status: "timed_out"`, end the current turn and tell the user to finish setup and use **Continue in Codex** after pressing Start scan. Do not run preflight, create or adopt coordinator or worker-local goals, open another workspace, or pivot to terminal/chat fallback. 8. Continue after a `ready` result, explaining material warn or suggest limitations. If preflight is `blocked` or `incomplete` with actionable remediation, present the exact reasons and config delta, ask whether to apply the remediation, and stop for the user's answer before creating or adopting coordinator or worker-local goals or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun. Preserve the running scan and retry or hand off while recovery may still be possible. If the user declines required remediation, ask whether to cancel or leave the scan running for a later retry. Call `fail_codex_security_scan` with the exact reason only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. In Codex CLI, including interactive and headless runs, or hosts without those capabilities, use the existing prompt-only terminal/chat preflight and scan workflow and shared artifact paths. Do not call `open_codex_security_workspace` or `await_codex_security_scan_start` on this path. The terminal/chat fallback cannot use this app-backed concurrency check; continue its existing workflow unchanged. Once `open_codex_security_workspace` succeeds in an MCP Apps-capable host, remain on the app path: immediately call `await_codex_security_scan_start`; a `status: "timed_out"` result means end the turn and point the user to **Continue in Codex**, while `status: "already_delivered"` means stop because another continuation owns the scan. Do not start a terminal/chat fallback for either result. ## Overview Deep Security Scan is a higher-recall wrapper around Codex Security's repository-wide and scoped-path scan modes. It preserves the ordinary Codex Security phase model and final report shape, but repeats the most variance-sensitive phase, finding discovery, before centralized judgment. The wrapper owns orchestration only: 1. resolve one repository-wide or scoped-path scan target using Codex Security's exhaustive-scan semantics 2. run repeated independent discovery workers, each of which generates its own target-specific threat model before `$codex-security:finding-discovery` 3. semantically merge discovery outputs into one canonical candidate inventory 4. synthesize one canonical validation threat model from the worker threat models after discovery reaches a terminal state 5. run `$codex-security:validation`, `$codex-security:attack-path-analysis`, canonical JSON completion, and generated report finalization once Do not replace Codex Security's established scan rules with custom shortcuts. ## Required Capabilities Read `../../references/config-preflight.md` and dispatch and await the preflight execution described there with the `deep_security_scan` capability profile before evaluating the workflow-specific requirements below, including after an app wait or direct continuation has produced a `scanId` and loaded its authoritative scan context. Follow the returned block/warn/suggest results. For an app-generated scan, ask before applying actionable remediation and wait without creating coordinator or worker-local goals or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun; preserve the running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet. Before starting substantive scan phases, confirm that the Codex Security plugin skills needed by this workflow are available: - `$codex-security:security-scan` - `$codex-security:threat-model` - `$codex-security:finding-discovery` - `$codex-security:validation` - `$codex-security:attack-path-analysis` If any required skill is unavailable, stop and say that this Codex Security installation does not include the required scan skills. Do not silently degrade into a different workflow. This workflow also requires parallel delegated workers for repeated discovery. Treat explicit invocation of Deep Security Scan as the user's request for this delegated-worker workflow. If delegation is unavailable in the current environment, do not claim Deep Security Scan ran; explain the limitation and offer an ordinary Codex Security scan as the fallback path. When delegated discovery workers are spawned from the current scan thread, use the host's default `agent_type`, model, and reasoning effort. The canonical worker brief below is self-contained; on native v2, spawn each discovery worker with `fork_turns=none` so coordinator history is not inherited. ## Goal Setup After the app wait or direct continuation has provided a `scanId`, the authoritative scan context has been loaded, and the `deep_security_scan` capability preflight has returned `ready`, or after the same preflight is `ready` in Codex CLI or terminal/chat hosts without the setup app, create or adopt a Codex goal for the full Deep Security Scan if the runtime exposes `/goal` or goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the shared exhaustive worklists exist, discovery either reaches a terminal state or records the first-round no-plausible-candidates path, canonical discovery artifacts and any candidate ledgers are assembled, centralized validation and attack-path receipts are complete or explicitly deferred when those phases are required, and the final markdown report is written. Use objective wording shaped like: `Run the Codex Security Deep Security Scan for <resolved repository target>; do not stop until the shared exhaustive worklists exist, discovery is saturated, capped, or on the first-round no-plausible-candidates path, canonical discovery artifacts and any candidate ledgers are assembled, centralized validation and attack-path receipts are complete or explicitly deferred when those phases are required, and the final markdown report is written.` If a compatible active goal already exists in the coordinator thread, continue under it instead of creating a duplicate. If goal tools are unavailable, state the same coverage objective in the first visible scan update and continue. Every delegated discovery worker must also create or adopt a worker-local Codex goal before substantive worker discovery if the worker runtime exposes `/goal` or goal tools. Use objective wording shaped like: `Run Deep Security Scan discovery worker <round id>/<worker id> for <resolved repository target>; do not stop until the worker-specific threat model and discovery artifact set are written, every assigned shared worklist row has a worker-local completion receipt or explicit deferred closure, and the worker summary is returned to the coordinator.` If a compatible active goal already exists in the worker thread, continue under it instead of creating a duplicate. If goal tools are unavailable inside the worker, the worker must state the same objective in its first visible update and continue. Worker goals are discovery-worker scoped only. A worker must not mark its worker-local goal complete until its threat model, discovery report, repository-wide ledgers, candidate ledgers, and coordinator-facing summary are saved or returned for the assigned worker artifact paths. The coordinator owns the top-level Deep Security Scan goal and must not mark it complete until: - the shared `rank_input.jsonl` and exhaustive `deep_review_input.jsonl` exist at the standard discovery paths - every completed round has exactly six usable worker outputs, all workers idle, merge records, candidate inventories, and novelty comparison artifacts - the discovery loop has a recorded terminal state of `saturated` or `capped` - the canonical merged discovery report, deduped candidates, repository coverage ledger, and per-candidate ledgers are aligned - for scans that enter the centralized tail, centralized validation and attack-path analysis have written required receipts or explicit deferred reasons for every canonical candidate or closure row that requires them - the final markdown report has been written to the resolved final scan path When this skill is the active top-level workflow, keep the setup and scan execution boundaries separate. Follow `Setup Workspace Routing` above for a new app workspace, immediately call `await_codex_security_scan_start`, and keep that call pending while the user reviews setup and presses Start scan. Do not enter `Goal Setup` until a `status: "started"` wait result or direct continuation provides a `scanId`, the authoritative scan context has been loaded, and the capability preflight has returned `ready`. If the wait returns `status: "timed_out"`, end the current turn and direct the user to **Continue in Codex**. If it returns `status: "already_delivered"`, end the turn because another continuation owns the scan. A workspace with `setup.submitted=false` is still the app path and must not be treated as terminal/chat fallback. In Codex CLI or hosts without the required app capabilities, use the existing terminal/chat workflow and shared artifact paths. ## User-Facing Contract - The final answer should feel like an ordinary Codex Security result. - Do not expose discovery rounds, recurrence counts, worker-by-worker results, or merge bookkeeping in the final report unless the user explicitly asks. - Preserve Codex Security's normal canonical JSON, generated-report, and review-directive contract by using `../../references/final-report.md`. - Keep intermediate artifacts for auditability, but do not dump them into the user-facing result. ## Non-Negotiable Orchestration Invariants These invariants are part of the workflow contract. Do not relax, reinterpret, or replace them with coordinator improvisation. - exactly `6` usable discovery workers per completed round - the same canonical discovery brief for every worker, except for mechanical substitutions such as target metadata, round id, worker id, and worker-specific artifact paths - no themed lanes, candidate-family hints, prior-round novelty hints, or coordinator-added framing around worker prompts - no shared pre-discovery threat model; each worker must generate and use its own worker-specific threat model for the resolved target - the coordinator must create one shared authoritative `<discovery_dir>/rank_input.jsonl` plus one exhaustive shared `<discovery_dir>/deep_review_input.jsonl` before the first discovery round, and every discovery worker must consume that same shared worklist pair without regenerating, reranking, or overwriting it - collect all round outputs before merge - wait for every worker in the round to complete and become idle before any later round is spawned - merge only preserved artifacts from completed workers, never live worker state - during an active discovery round, the coordinator is orchestration-only: it may resolve paths, create shared worklists, monitor worker progress, verify artifact existence, and check parseability or schema conformance, but it must not perform repository-specific security discovery, sink hunting, candidate generation, or validation prep grounded in target code - before all six workers in a round have completed and become idle, the coordinator may inspect worker artifacts only for existence, completeness, parseability, and schema conformance; it must not read substantive candidate content or infer emerging vulnerability families from partial-round outputs - the canonical candidate inventory, novelty comparison, and semantic merge may be derived only from preserved completed worker artifacts collected after a round closes; coordinator-originated repo analysis, side notes, or pre-merge hypotheses are not discovery inputs - merge candidates only when the merged candidate's remediation would remediate every upstream candidate being merged; if fixing the merged issue would leave any upstream issue independently exploitable, independently reportable, or otherwise materially unresolved, keep them separate - maintain Codex Security's standard `finding_discovery_report.md` candidate shape through every merge pass; the merged report is the canonical candidate inventory, not a later summary derived from some other inventory - every canonical merged candidate must remain present in the merged discovery report passed to validation unless validation itself later rejects it; no candidate may disappear during artifact synthesis or support-artifact consolidation - every canonical merged candidate must have a standard canonical `findings/<candidate_id>/candidate_ledger.jsonl` record that names the absorbed worker candidates and ledgers it subsumes before centralized validation begins - do not spawn a later round until the prior round has fully completed its output collection, worker idle transition, merge, and novelty comparison - stop only after a fully completed round produces zero new canonical merged discovery candidates - an incomplete round, failed spawn, or partial merge is never evidence of saturation - if the initial worker spawn batch fails before any worker has started because the host cannot resolve the current sender thread, treat that as a transient orchestration failure and retry the full round cleanly rather than treating it as worker failure or partial progress ## Shared Setup Start this setup only after `Setup Workspace Routing` has either loaded the app-generated scan context with a `scanId`, or determined that the host is using the non-app terminal/chat workflow, and the `deep_security_scan` capability preflight has returned `ready`. 1. Read `$codex-security:security-scan` first and follow its repository-wide or scoped-path scan semantics exactly. 2. Resolve one target once: either the full checked-out repository or a user-specified path, package, folder, or submodule-like scope within it. Deep Security Scan does not support PR diffs, commits, branch diffs, or working-tree diffs; direct those requests to ordinary `$codex-security:security-diff-scan`. Never silently widen a scoped-path target to the repository root. 3. Create or adopt the coordinator scan goal described in `Goal Setup` for that active scan context. 4. Resolve the ordinary Codex Security scan paths once using its shared artifact-path rules: - `repo_name` - `security_scans_dir` - `scan_id` - `scan_dir` - `artifacts_dir` - `context_dir` - `discovery_dir` - `coverage_dir` - `reconciliation_dir` - `findings_dir` 5. Do not generate a shared pre-discovery threat model in the coordinator. 6. Reserve Codex Security's standard per-scan `<context_dir>/threat_model.md` path for the later canonical validation threat model that will be synthesized only after the discovery loop reaches a terminal state. 7. Create the fixed parent-provided coverage scope before any discovery worker starts: - generate `<discovery_dir>/rank_input.jsonl` once using Codex Security's ordinary deterministic exhaustive-scan worklist helper: `<python_command> <plugin_dir>/scripts/generate_rank_input.py make-repo-rank-input --repo <repo_root> --scope <scope> --out <discovery_dir>/rank_input.jsonl` - use the repository root as `<scope>` for a repository-wide target and the exact resolved relative or absolute scoped path for a scoped-path target - treat Deep Security Scan as exhaustive for this version: run `<python_command> <plugin_dir>/scripts/generate_rank_input.py copy-deep-review-input --rank-input <discovery_dir>/rank_input.jsonl --out <discovery_dir>/deep_review_input.jsonl` and declare that worklist pair authoritative and exhaustive for every worker - do not create or require `rank_output.jsonl`; Deep Security Scan does not use ranked truncation in this version - every worker must consume those shared standard-path worklists as parent-provided inputs while writing its own worker-local ledgers, candidates, coverage ledger, and discovery report Do not let individual discovery workers reinterpret or widen the scan target, but do let them independently generate their own target-specific threat models at worker-specific paths before discovery begins. ## Deep Discovery Loop Run discovery in synchronous rounds: - `6` independent discovery workers per round - maximum `10` rounds total - stop after the first full round that adds no new canonical merged discovery candidates of any kind For an app workspace scan with a `scanId` and the Codex Security progress tool available, record the one-based `deepReviewPass` at the start of each round, reset completed review items to zero, and update them as that round's file-review receipts close. Always run at least one round. After each round: 1. collect that round's discovery outputs 2. confirm every completed discovery worker from that round is idle after its artifacts and summary have been collected 3. merge the completed round's outputs with every prior round's discovery outputs 4. update the canonical candidate inventory 5. compare the canonical inventory against the previous round's canonical inventory 6. stop if no new canonical candidate clusters of any kind were added Do not reuse completed discovery workers across rounds. Later rounds should consume only the preserved artifacts, not prior worker state. Before spawning any later round, confirm that every worker from the prior round has completed and become idle; do not interrupt an already completed worker. While a discovery round is active, keep the coordinator neutral. It may perform orchestration bookkeeping and artifact-health checks, but it must not run its own target-specific discovery lane, form candidate hypotheses, queue likely finding families, or do repository-grounded validation preparation before the round closes. This stop rule measures discovery saturation only. It does not claim that validated findings or final reportable findings have saturated; validation, canonical JSON completion, and report projection still happen once after the discovery loop completes. If the first round finds no plausible candidates, write the appropriate canonical no-findings discovery artifact and continue directly to the final Codex Security no-findings assembly path. ### Required Round-Transition Checklist Execute this checklist in order for every completed round. Do not skip steps. 1. confirm the round has exactly six usable completed discovery workers 2. confirm every worker artifact needed for this scan type has been collected under its worker-specific path 3. confirm all six completed workers from the round are idle 4. confirm no worker from that round remains running 5. merge the round's preserved artifacts with prior preserved artifacts into Codex Security's standard discovery-report shape 6. write the merge record, the round-specific candidate inventory, and the canonical merged `finding_discovery_report.md` 7. compute novelty against the prior canonical candidate inventory 8. choose exactly one next action: - stop, only if the completed round added zero new canonical clusters of any kind - spawn the next six-worker round, only after every prior checklist step is complete ## Worker Isolation Each discovery worker must be independent: - same resolved scan target - its own worker-local Codex goal when the worker runtime exposes `/goal` or goal tools - its own independently generated threat model for the resolved target written to its worker-specific artifact path - same Codex Security discovery rules - same canonical worker brief except for mechanical substitutions such as target metadata, round id, worker id, and output paths - the same parent-provided authoritative `<discovery_dir>/rank_input.jsonl` and exhaustive `<discovery_dir>/deep_review_input.jsonl` inputs - no access to prior workers' findings or merge outputs - no top-level `$codex-security:validation`, no top-level `$codex-security:attack-path-analysis`, and no canonical finalization - no file edits The goal is not shallow parallelism; the goal is independent high-quality discovery diversity from repeated same-brief stochastic passes. ## Discovery Worker Brief Use this canonical brief for every discovery worker. Do not prepend or append extra coordinator prose, skill-path boilerplate, themed emphasis, candidate-family hints, prior-round novelty hints, or coordinator-invented specialty lanes. Only substitute the resolved target details, round id, worker id, and worker-specific output paths required for the run. ```text You are a discovery worker, not the top-level scan coordinator. Follow this self-contained worker-specific assignment as your task. If you cannot complete it, report the problem to the coordinator rather than taking over or terminating the overall scan. Run the Codex Security threat-model phase and then the finding-discovery phase only. Before substantive worker work, create or adopt one worker-local Codex goal if your runtime exposes `/goal` or goal tools. Use this objective: `Run Deep Security Scan discovery worker <round id>/<worker id> for <resolved repository target>; do not stop until the worker-specific threat model and discovery artifact set are written, every assigned shared worklist row has a worker-local completion receipt or explicit deferred closure, and the worker summary is returned to the coordinator.` If a compatible active goal already exists in this worker thread, continue under it instead of creating a duplicate. If goal tools are unavailable, state the same objective in your first visible update and continue. Do not mark the worker-local goal complete until the threat model, finding discovery report, repository-wide ledgers, candidate ledgers, and coordinator-facing summary for your assigned artifact paths are saved or returned. Use the provided resolved scan target exactly as given. First generate your own threat model for that resolved target using the ordinary `$codex-security:threat-model` rules, but write it only to your worker-specific threat-model output path. Do not read, reuse, overwrite, or infer a shared coordinator threat model. Then run `$codex-security:finding-discovery` using your own worker-specific target threat model as the threat-model source of truth. Do not reinterpret the target, run the top-level `$codex-security:validation` phase, run the top-level `$codex-security:attack-path-analysis` phase, author canonical final artifacts, or edit repository files. Your task is to enumerate technically plausible, distinct security finding candidates as comprehensively as possible for this scope. Apply the ordinary `$codex-security:finding-discovery` rules in full: - stay grounded in the code and your worker-specific threat model - preserve separate root causes rather than cosmetic variants - keep independently reachable instances separate - preserve concrete source, closest-control, sink, impact, and affected-location evidence - consume the parent-provided authoritative `<discovery_dir>/rank_input.jsonl` and exhaustive `<discovery_dir>/deep_review_input.jsonl` exactly as supplied; do not regenerate, rerank, overwrite, or reinterpret them - treat those standard-path worklists as shared inputs while writing every worker output only to the explicit worker-specific artifact paths supplied for this discovery pass - for repository-wide and scoped-path scans, perform the normal Codex Security exhaustive deep-review, seed-research, work-ledger, raw-candidate, candidate-ledger, dedupe, repository-coverage-ledger, and frontier-pass work required by finding discovery - for repository-wide and scoped-path scans, preserve any candidate-local validation evidence and candidate-local attack-path facts that the current Codex Security discovery workflow requires before dedupe; those receipts are discovery support artifacts, not permission to run the later centralized top-level phases - for repository-wide and scoped-path worker candidate JSONL, use one canonical machine-readable affected-location shape only: - `affected_locations` must be an array of objects - every object must contain `label`, `path`, and `lines` - `detail` may be included when it materially helps later merge or validation - use `lines` as a string even for one line, such as `"154"` - do not emit string-only locations such as `"src/file.py:154"`, alternate `file` or `line` keys, or separate-only `source_locations` / `root_locations` / `sink_locations` fields without also materializing the unified `affected_locations` array Return your worker-specific threat model plus the normal discovery artifact set for your worker-specific artifact paths, with enough detail for later centralized semantic merging and validation. ``` ## Worker Artifact Layout Keep the canonical Codex Security scan paths for the final merged pipeline. Put repeated discovery worker artifacts under the canonical `artifacts_dir` without overwriting one another: ```text <artifacts_dir>/ 02_discovery/ rank_input.jsonl deep_review_input.jsonl deep_discovery/ round-01/ worker-01/ threat_model.md finding_discovery_report.md seed_research.md work_ledger.jsonl raw_candidates.jsonl dedupe_report.md deduped_candidates.jsonl repository_coverage_ledger.md findings/ <candidate_id>/ candidate_ledger.jsonl worker-02/ ... round-02/ ... ``` Workers write their worker-local exhaustive discovery artifact set to their assigned paths while sharing only the standard-path `<discovery_dir>/rank_input.jsonl` and exhaustive `<discovery_dir>/deep_review_input.jsonl`. Give each worker explicit worker-specific output paths so the discovery reports and exhaustive-scan ledgers do not overwrite one another. For repository-wide and scoped-path workers, the machine-readable candidate streams must use this canonical affected-location contract in both `raw_candidates.jsonl` and `deduped_candidates.jsonl`: ```json { "affected_locations": [ { "label": "root_control", "path": "src/example.py", "lines": "154",