deep-security-scan

What this skill does

# Deep Security Scan

## Overview

Deep Security Scan is a higher-recall repository-wide wrapper around Codex Security. 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 the full-repository scan target once using Codex Security repository-wide semantics
2. run repeated independent discovery workers, each of which generates its own repository-level 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`, and final report assembly once

Do not replace Codex Security's established scan rules with custom shortcuts.

## Required Capabilities

Before starting, 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 fanout 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, inherit the parent worker configuration. Do not override `agent_type`, model, or reasoning effort on a full-history fork; use the host's inherited defaults so the spawn call does not fail before discovery begins.

## 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 final-report contract and review-directive behavior 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 repository-level threat model
- the coordinator must create one shared authoritative `<discovery_dir>/rank_input.csv` plus one exhaustive shared `<discovery_dir>/deep_review_input.csv` 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
- close every completed worker from the round before any later round is spawned
- merge only preserved artifacts from closed 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 been closed, 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 closure, 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

1. Read `$codex-security:security-scan` first and follow its repository-wide scan semantics exactly.
2. Resolve the full-repository target once. Deep Security Scan v0 does not support PR diffs, commits, branch diffs, working-tree diffs, or scoped paths. If the user requested a scoped path, stop this workflow and direct them to ordinary `$codex-security:security-scan`; if the user requested a PR, commit, branch diff, or working-tree diff, direct them to ordinary `$codex-security:security-diff-scan`. Do not silently widen the scope.
3. 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`
4. Do not generate a shared pre-discovery threat model in the coordinator.
5. 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.
6. Create the fixed parent-provided coverage scope before any discovery worker starts:
   - generate `<discovery_dir>/rank_input.csv` once using Codex Security's ordinary deterministic repository-wide worklist helper for the resolved repository
   - treat Deep Security Scan as exhaustive for this version: copy every `rank_input.csv` row into `<discovery_dir>/deep_review_input.csv` and declare that worklist pair authoritative and exhaustive for every worker
   - do not create or require `rank_output.csv`; repo-wide Deep Security Scan does not use ranked truncation in this version
   - every worker must consume tho