/scan-site

name: scan-site
description: >-
  Runs a security scan on a deployed Power Pages site, fetches the latest
  scan report, and produces a plain-language summary. Scans the live site's
  public surface for vulnerabilities and surfaces issues by severity. Use
  when the user wants to scan, check, test, audit, or assess a published
  site, find vulnerabilities on production, view the latest scan report,
  see previous scan results, run a security audit, or asks "how safe is
  my live site?", "is my site vulnerable?", "audit my production site" —
  even if they say "find issues" or "check for problems" without mentioning
  "scan" or "security".
user-invocable: true
argument-hint: "[optional: --review <out-dir>]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Scan Site

Run a security scan on a deployed Power Pages site, fetch the latest scan report, and surface findings in a plain-language summary. The scan runs server-side; duration depends on site size — small sites finish in minutes, large sites can take hours.

This skill scans the live deployed site, not local source code.

**Initial request:** $ARGUMENTS

Gotchas

• **Website record id vs portal id.** `.powerpages-site/website.yml` stores the website record id, not the portal id. Every script takes `--portalId`. Resolve once via `website.js --websiteId` during prerequisites.
• **Never resolve by name.** Site names can duplicate inside an environment; only the website record id is safe.
• **`null` from the resolver** means the site is not deployed, or the authenticated profile points at a different environment.
• **Scans are long-running.** Duration depends on site size — small sites finish in minutes, large sites can take hours. Poll in the background and increase `--timeoutMinutes` for large sites.
• **Only one scan per site at a time.** A start while a scan is running returns `Z003` — `start-deep-scan.js` reports it as `{ "status": "already-running" }` (exit 0).
• **Rate limits may apply.** The service may throttle repeated scans on the same site. When throttled, wait and retry later.
• **No completed scan yet.** A fresh site or a site mid-scan has no completed report — `get-latest-report.js` returns `{ "status": "empty" }`.

Workflow

1. **Prerequisites** — Locate project, confirm sign-in, identify site 2. **Check scan state** — Detect whether a scan is currently running 3. **Choose an action** — Context-aware recommendation (run new scan / show latest) 4. **Run the scan** — Start and poll for completion 5. **Fetch and summarize** — Get the report, present findings 6. **Walk through follow-ups** — Route issues to the right downstream skill (only if the report contains issues)

Task Tracking

Create tasks in four groups. Mark each `in_progress` when starting, `completed` when done.

| Group | When to create | Tasks | |-------|----------------|-------| | 1 | At start | Check prerequisites | | 2 | After prerequisites pass | Check scan state · Choose an action (skip in review mode) | | 3 | After user confirms an action (or in review mode) | Run the scan (skip only if the user chose to view latest results in interactive mode) · Fetch and summarize (always) | | 4 | After fetch and summarize | Walk through follow-ups (only if the report contains issues AND not in review mode) |

---

1. Prerequisites

1.1 Locate the project, detect review mode

Use `Glob` to find `**/powerpages.config.json`. If `$ARGUMENTS` contains `--review <out-dir>`, remember the output directory — Step 3 (choose an action) is skipped, Step 4 (run scan) executes automatically (start a fresh scan or attach to a running one), Step 5 writes JSON only, and Step 6 (follow-ups) is skipped.

1.2 Resolve site identifiers

Read `.powerpages-site/website.yml` → extract `id` field → that is `<WEBSITE_ID>`.

If missing, the site has not been deployed. Tell the user and recommend `/deploy-site`. Stop. Do **not** resolve by name or URL.

Resolve to portalId:

node "${PLUGIN_ROOT}/scripts/website.js" --websiteId "<WEBSITE_ID>"

Capture `Id` (portalId), `Type`, `Name`, `WebsiteUrl`. If exit code `2` → sign-in required (`pac auth create` or `az login`). If `null` → site not found in this environment. Stop in either case.

---

2. Check scan state

node "${PLUGIN_ROOT}/skills/scan-site/scripts/poll-deep-scan.js" --portalId "<PORTAL_ID>" --once

`--once` does a single status check, exits 0, and prints:

• `{ "status": "ongoing" }` → a scan is currently running.
• `{ "status": "idle" }` → no scan running.

Then call `get-latest-report.js` to know whether a completed report exists:

node "${PLUGIN_ROOT}/skills/scan-site/scripts/get-latest-report.js" --portalId "<PORTAL_ID>"

`{ "status": "ok" }` means a report is available. `{ "status": "empty" }` means no completed scan exists.

---

3. Choose an action

Skip in **review mode** — go straight to Step 4 (which always runs in review mode).

MUST use plain language only. Never use words like CSP, CORS, OWASP, hardening, or scan profile.

Default approach

<!-- gate: scan-site:3.action-choice | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · scan-site:3.action-choice):** Recommend an action based on the site's scan state (running, idle, has report, no report), then ask the user to accept or choose differently. Starting a new scan triggers a multi-minute backend run; using an existing report is free. > > **Trigger:** Phase 3 entry (interactive mode only — review mode bypasses to step 4). > **Why we ask:** Auto-starting a new scan wastes minutes if a recent report already answers the question; auto-using a stale report misses recent findings. > **Cancel leaves:** Nothing — no scan triggered, no report consumed.

Analyze the site's current state and **recommend