skills/security-scan/references/desktop-scan.md

# Codex Desktop Standard Scan

Read this reference only after the host explicitly identifies itself as the Codex desktop app. Listed tools alone do not establish a desktop host.

## Resolve The Authoritative Scan

Resolve the target, requested scope, and user-provided security context before starting the scan.

- If the request already includes a `scanId`, call `get_codex_security_scan_context`, passing `handoffClaimToken` when provided, and continue that existing scan.
- Otherwise call `start_codex_security_prompt_only_scan` once with `mode: "standard"`, `targetPath`, `scope`, and any exact `userContext`. Require its authoritative `scan.scanId` and `scan.scanDir`; preserve its handoff token when provided.
- If the direct start fails or returns malformed context, surface that error. Do not invent scan ownership, start a replacement scan, open setup, or switch to a terminal workflow.

Use the returned `scanId`, `scanDir`, scope, and exact `userContext` throughout the parent workflow. Read `../../../references/desktop-config-preflight.md` and run capability preflight only after this authoritative context exists.

## Publish Live Progress

Call `update_codex_security_scan_progress({ scanId, handoffClaimToken, phase })` when entering each real phase. After publishing a ready preflight result, set `phase: "threat_model"` before mapping security boundaries. Set `discovery` before dispatching investigation packets, `validation` before parent validation, `attack_path` before assessing reachability, and `reporting` before assembling the final report inputs. Preserve the current phase when work overlaps; never move backward or repeat completed work. Use the returned `scan.userContext` for the new phase and its workers.

Publish meaningful completed-review batches through the same tool. Increase the investigator total before dispatching each newly discovered assignment; the concurrently running baseline is independent and does not inflate that total. Capture each completed, source-backed investigation as a real coverage surface before advancing its `review_receipts` progress count. Do not create separate receipt files. Advance later phase counts only after the corresponding finding or report artifact exists, and never invent counts, phase workers, or coverage. Model-only checkpoints preserve the current phase. Checkpoints containing findings or reviewed surfaces advance a Standard scan to at least `discovery`, and the final draft advances it to `reporting`; publish earlier phase transitions as they happen instead of waiting for a checkpoint.

## Complete The Same Scan

Save the first `complete: false` checkpoint as soon as architecture mapping produces the threat model, with `findings: []` and honest partial coverage when no findings exist yet. The host retains the canonical model and generates `threatmodel.md`. Continue saving checkpoints as results arrive and validation decisions are made. Preserve pending candidates with their original evidence in `coverage.deferred`; they are not validated findings. When the audit finishes, record the final semantic scan draft once with `record_codex_security_scan_draft({ scanId, complete: true, handoffClaimToken?, scope?, threatModel?, findings, coverage })`. Supply the actual findings, source-backed coverage, and preserved threat model; let the workbench write the unsealed canonical artifacts and derive authoritative target, scope, coverage metadata, finding identities, and fingerprints.

Honor desktop handoff requirements for any per-finding write-ups before completion. After the semantic draft succeeds and all three canonical JSON files exist, call `complete_codex_security_scan` exactly once with the same authoritative scan ID and handoff token. Return only after completion succeeds and `report.md` exists, linking the generated report and canonical artifacts; retrieve the complete findings only when the user explicitly requests them. Include measured token usage when available and explicitly label partial or unavailable measurement.

For each reported finding, emit one `::code-comment{title="[<priority-label>] <title>" body="<explanation>" file="<absolute path>" start=<line> end=<line> priority=<priority-number> confidence=<0-to-1>}` review directive at its tightest `root_control` location, or the most relevant affected source location when no root control is identifiable. Map `critical`, `high`, `medium`, and `low` to `P0/0`, `P1/1`, `P2/2`, and `P3/3` respectively; keep its title and explanation consistent with the generated report.

If finalization fails, surface the exact error and preserve the durable scan for later continuation; do not retry completion in the same response, generate a replacement report, or claim success.