/security-scan

name: security-scan
description: "Use when the user asks for a repository-wide or scoped-path security scan."
metadata:
  short-description: Run security scan

Security Scan

Used when a user wants to audit an entire repository or a user-specified path, package, folder, or submodule-like scope for security vulnerabilities. Keep the scan phases separate and produce final HTML and markdown reports.

Phase Sequence

Keep these phases distinct and run them in linear order:

1. `$threat-model` 2. `$finding-discovery` 3. `$validation` 4. `$attack-path-analysis` 5. Generate final output

Treat this skill as the top-level orchestrator for the four skills plus the final report assembly step. Do not collapse the phases together.

For each phase: 1. Read that phase's skill. 2. Load only the inputs required for that phase. 3. Complete that phase's workflow and checklist. 4. Only then read the next phase's skill.

Do not read ahead into later-phase skills until the current phase has completed. Do not amortize effort across phases: complete each phase to the full depth expected by that phase before moving on. If user requests a repo-side scan or a scoped scan, stop and ask for authorization for subagents now before setting up the goal.

Goal Setup

Before substantive scan work, create a Codex goal for the scan if the runtime exposes goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the resolved files in scope have been covered and the required coverage artifacts prove that closure.

Use objective wording shaped like:

`Run the Codex Security repository/scoped-path scan for <resolved target>; do not stop until every in-scope file/worklist row has a completion receipt or explicit deferred closure, every candidate has required ledger receipts, and the final report is written.`

If a compatible active goal already exists, 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.

Do not mark the goal complete until:

• every file or worklist row in the resolved scope has a completion receipt, or an explicit `deferred`, `not_applicable`, or `suppressed` closure with exact reason
• every candidate that reached discovery has the required discovery, validation, and attack-path ledger receipts, or an explicit deferred reason for the missing proof
• the final markdown and HTML reports have been written to the resolved scan paths

Artifact Resolution

The path references in this skill are the default locations for this phase. If the user explicitly provides a different path for a required input or output, use the user-provided path instead of the corresponding default path referenced in this skill. If a required input is still missing, stop and ask the user for it before continuing. Use the shared scan artifact path conventions in `../../references/scan-artifacts.md`.

Execution Plan

Follow this plan in order. Do not skip ahead to a later phase until the current phase has produced its intended output.

1. Resolve the scan target, `repo_name`, `security_scans_dir`, `scan_id`, `scan_dir`, and `artifacts_dir` using `../../references/scan-artifacts.md`. 2. Create or adopt the scan goal described in `Goal Setup`. 3. Run `$threat-model` first.

• Copy the repository-scoped threat model to the per-scan threat model path without alteration for auditability.
• Treat the per-scan threat model path as the source of truth threat model for later phases.

4. Run `$finding-discovery` as the second step, against the resolved repository or scoped path and using the per-scan threat model as context.

• Stop at discovery only when the ranked runtime-surface worklist exists and the coverage ledger has closed every applicable high-impact and seeded root-control row as `suppressed`, `not_applicable`, or `deferred` with exact reasons. Open, reportable, or unresolved seeded rows continue to validation even when they are not yet numbered as findings.

5. Run `$validation` as the third step, for each candidate that came out of discovery and each open, reportable, or deferred seeded/root-control ledger row that still needs closure.

• Pass the resolved scan scope, discovery notes, and candidate inventory to validation. Validation should preserve or suppress the provided instances; it should not independently broaden or narrow the requested repository or scoped-path scan.
• Each candidate finding's candidate-ledger path from `../../references/scan-artifacts.md` is part of the validation input for every scan scope. Every candidate finding that came out of discovery must have a discovery receipt before validation starts and a validation receipt before the scan can proceed to final reporting.
• For repository-wide and scoped-path scans, the discovery worklists, work ledger, raw candidates, per-finding candidate ledgers, deduped candidates, and discovery coverage ledger from `../../references/scan-artifacts.md` are part of the validation input; the ledger is a coverage artifact, not just a findings tracker. Raw candidates should already include the discovering file-review subagent's or parent agent's candidate-local validation evidence and attack-path facts before dedupe, and each per-finding candidate ledger should prove that its raw candidate finding received both checks or has an explicit deferred reason. Validation should preserve checked surfaces with not_applicable, suppressed, deferred, and reportable dispositions, reconcile cross-file proof gaps, and continue the ledger's high-impact sibling checks when needed rather than narrowing to one representative finding.
• When multiple candidates or coverage-ledger rows need validation and subagents are available and approved, divide validation across validation subagents by candidate, deduped candidate, or ledger row. Each validation subagent must receive the candidate or row, discovery evide