Scan Site

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.

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 the single most relevant action via AskUserQuestion:

• Scan running, no completed report → recommend waiting for the running scan to finish.
• Scan running, report exists → recommend showing the latest results while the new scan continues.
• Idle, no completed report → recommend running a new scan.
• Idle, recent report exists → ask whether to use the existing report or run a fresh scan.

If the site's state does not warrant a specific recommendation, do not force one — ask what the user wants to do.

Option rules

<!-- not-a-gate: meta-documentation describing how to structure `AskUserQuestion` options in this skill — not a literal call site. The actual prompt ("use existing report / run a fresh scan") fires dynamically in §3 Default approach. See approval-gates.md §6.24a + §6.27. -->

When presenting options via AskUserQuestion:

• Keep label to 1–5 words. Include description on every option.
• For options that trigger a new scan, surface the relevant caveats inside that option's description so the user has them at decision time. Do not ask a separate confirmation question after the user picks the option.
• Include preview only when the option represents a concrete change (starting a new scan). Do not add preview to "show latest" or informational choices.
• Only show options that are actionable given the current state. If a scan is already running, do not offer "Start a new scan".
• Mark "(Recommended)" only when the site's state justifies it.