Security Deep Scan

Deep Security Scan

If you know another deep scan is already running over the same scope, ask the user whether to continue or stop before doing substantive work.

Overview

Deep Security Scan is a higher-recall wrapper around the repository-wide and scoped-path exhaustive-scan machinery in references/repository-wide-scan.md. It preserves the ordinary security-scan 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 the exhaustive-scan semantics in references/repository-wide-scan.md
2. run repeated independent discovery workers, each of which generates its own target-specific threat model before following references/phase-finding-discovery.md
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. follow references/phase-validation.md, references/phase-attack-path-analysis.md, canonical JSON completion, and generated report finalization once

Do not replace the established scan rules with custom shortcuts.

Required Capabilities

Read references/config-preflight.md and dispatch and await the preflight execution described there with the security_deep_scan capability profile before evaluating the workflow-specific requirements below and before any substantive scan work. Follow the returned block/warn/suggest/ready results. On blocked or incomplete, present the exact reasons and any advisory guidance and config delta, ask the user whether to apply the remediation, and stop for the answer before substantive work; do not auto-fail. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet.

The phase references (references/phase-threat-model.md, references/phase-finding-discovery.md, references/phase-validation.md, references/phase-attack-path-analysis.md) and the repository-wide and scoped-path exhaustive-scan machinery (references/repository-wide-scan.md) are bundled with this skill and always available, so no plugin-availability check is required before starting substantive scan phases.

This workflow does require 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 security scan as the fallback path.

When delegated discovery workers are spawned from the current scan, use the host's default subagent type, model, and reasoning effort. The canonical worker brief below is self-contained; spawn each discovery worker with a fresh context (no inherited coordinator history) when your host supports it.

Cost Gate

Deep Security Scan is the highest-volume workflow in this set, by design: it re-runs discovery with six workers per round, repeating rounds until discovery is saturated or capped, so its discovery work is roughly an ordinary security scan's discovery × six × the number of rounds, plus the centralized validation and attack-path tail.

After the capability preflight returns ready and the target is resolved, and before goal setup or the first discovery round:

1. Size one single-pass review volume with the cheap deterministic inventory ( /scripts/generate_rank_input.py make-repo-rank-input --repo --scope --out /rank_input.jsonl): about files × planned top-percent / 100 file-review passes.

You may also give a rough input-token count for one pass as the total in-scope file size in characters divided by about 4. Then state the deep multiplier: × six workers × the number of rounds. Report token counts, not money; a dollar cost depends on token pricing, model, and input/output/cache ratios that change.

1. Present the scope plainly, noting this is the high-volume option intended for high-assurance moments (pre-release, post-incident, compliance).

Then stop and wait for the user's explicit approval before creating shared worklists or goals or spawning the first discovery round. This is a binary go/no-go on deep scan as scoped — do not propose narrowing the scope or switching to a lighter scan. Proceed without waiting only if the user's request already explicitly approved this scope.

Goal Setup

After the capability preflight returns ready, if your host has goal/todo/task-tracking tools, create the coordinator goal capturing the objective; otherwise state the same objective in your first visible update and track it yourself. 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 Deep Security Scan for ; 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.

Every delegated discovery worker must also create the worker-local discovery goal before substantive worker discovery if the worker runtime has goal/todo/task-tracking tools; otherwise the worker states the same objective in its first visible update and tracks it itself. Use objective wording shaped like:

Run Deep Security Scan discovery worker / for ; 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.

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

Do not enter Goal Setup until the capability preflight has returned ready and the Cost Gate has been approved by the user.

User-Facing Contract

• The final answer should feel like an ordinary security-scan 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 the standard canonical JSON and generated-report 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 /rank_input.jsonl plus one exhaustive shared /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 the 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_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 the security_deep_scan capability preflight has returned ready.

1. Read references/repository-wide-scan.md 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 an ordinary security scan. Never silently widen a scoped-path target to the repository root.

1. Create or adopt the coordinator scan goal described in Goal Setup for that active scan context.
2. Resolve the ordinary 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

1. Do not generate a shared pre-discovery threat model in the coordinator.
2. Reserve the standard per-scan /threat_model.md path for the later canonical validation threat model that will be synthesized only after the discovery loop reaches a terminal state.
3. Create the fixed parent-provided coverage scope before any discovery worker starts:

• generate /rank_input.jsonl once using the ordinary deterministic exhaustive-scan worklist helper: /scripts/generate_rank_input.py make-repo-rank-input --repo --scope --out /rank_input.jsonl
• use the repository root as `` 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 /scripts/generate_rank_input.py copy-deep-review-input --rank-input /rank_input.jsonl --out /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

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 candid

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahgraber
• Source: ahgraber/skills
• License: CC0-1.0

Install and usage instructions live in the source repository linked above.