deep-security-scan

Deep Security Scan

The host runs Standard audits and merges their findings. Workers in the same scan can exchange investigation leads and verify each other’s evidence. Later passes receive the titles and locations already reported. The host stops when consecutive audits add nothing new or the configured scan or time limit is reached. Its final report includes every accepted audit.

1. Resolve the authorized target and scope. For a scoped directory use that directory as targetPath and scope: ".". For a continuation, call get_codex_security_scan_context with its scanId and supplied handoffClaimToken. Use its saved identity and scope. If its mode is Standard or diff, continue with the corresponding scan skill. Follow ../../references/scan-prologue.md for source access and context updates.
2. For a new target, call inspect_codex_security_setup({ targetPath, scope: ".", mode: "deep", projectConfigPath? }). Show the effective settings and their sources. max_discovery_runs caps the total number of Standard scans, including when several run together. Pass a project file only when the user selected it. Existing scans use their saved configuration.
3. For a newly launched native scan with a supplied scan ID, inspect otherRunningDeepScans in the result of get_codex_security_scan_context once. Target-based setup previews have no scan ID. If another Deep scan is active, show its target, phase and human-friendly start time. Explain the additional CPU, memory and token use. Offer Cancel (Recommended) and Continue using request_user_input, then request_codex_security_user_input or plain chat if unavailable. Wait for an explicit choice. A dismissed dialog is not a cancellation. Cancel only the new scan if requested.
4. Follow ../../references/access-advisory.md, then call start_codex_security_deep_scan({ scanId, handoffClaimToken? }) for an existing scan or start_codex_security_deep_scan({ targetPath, scope: ".", userContext?, projectConfigPath? }) for a new target. Reuse the project file selected at setup. Await the tool. If the tool runner returns a running cell ID, wait on that cell until it returns the scan result. If the connection closes, rejoin with the same arguments. Report a terminal failure with its saved results. For a policy refusal, identify the worker from its saved error when available. On explicit cancellation call cancel_codex_security_scan({ scanId }) from the owning thread.
5. For an SDK-owned scan, return the host's scan ID and manifest path so the SDK can finalize it. When the tool returns completion, link its generated report.md and canonical artifacts. Use completion.scan.usage and any separate cost estimate to report usage per ../../references/final-report.md. Distinguish a completed audit with zero findings from a deadline reached before any audit completed.