security-review

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

# Review Security

Guide the user through a full security review of their Power Pages site. Runs the matching focused skills and assembles every finding into a single HTML report.

The skill never asks the user technical questions. The conversation stays in plain language.

**Initial request:** $ARGUMENTS

## Workflow

The skill has six phases. Phases 2–5 each map to one conversation beat with the user; phases 1 and 6 are silent setup and cleanup. See `references/flow.md` for the rationale behind each beat.

| Phase | What happens | User-facing beat |
|-------|--------------|------------------|
| 1 — Prerequisites | Locate project, set up working folders | (silent setup) |
| 2 — Scope | Capture goal — one question, three answers, plain language | Ask the goal |
| 3 — Skills | Run the matching skills, surface progress | Scan in progress |
| 4 — Report | Build the consolidated report — totals + per-section findings | Results summary + Findings |
| 5 — Present | Present results, offer remediation follow-ups | Next steps and guidance |
| 6 — Cleanup | Remove temporary files | (silent cleanup) |

## Task Tracking

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

**Group 1 — create at the start of prerequisites:**

| Task subject | activeForm |
|--------------|------------|
| Check prerequisites | Checking prerequisites |

Only this one task. Do not create any other tasks until prerequisites complete.

**Group 2 — create after prerequisites complete:**

| Task subject | activeForm |
|--------------|------------|
| Capture goal | Capturing goal |

**Group 3 — create after the goal is captured:**

| Task subject | activeForm |
|--------------|------------|
| Run skills | Running checks |
| Build the report | Building the report |
| Present findings | Presenting findings |
| Clean up | Cleaning up |

---

## 1. Prerequisites

### 1.1 Locate the project

Use `Glob` to find `**/powerpages.config.json`. If none is found, tell the user the site needs to be created first with `/create-site`, then stop.

For the `monitor` and `release` goals (any goal that delegates to `scan-site` or `manage-firewall`), also confirm that `.powerpages-site/website.yml` exists. If it does not, the site has not been deployed yet — tell the user (in plain language) the site needs to be deployed once before a live security review can run, recommend `/deploy-site`, then stop. Do **not** try to identify the site by name or URL — different sites can share the same name.

For the `access-config` goal, the deploy check is not required: authentication, web roles, and table permissions are read from local YAML alone.

### 1.2 Prepare a temporary working folder

Create a fresh working directory: `<SYSTEM_TEMP>/security-review/`. The folder holds JSON data files emitted by each skill in **review mode**. The folder is removed in the cleanup step.

If the folder already exists from a previous interrupted run, delete its contents (not the folder itself) before continuing.

### 1.3 Determine the docs output path

The final HTML always lives at `<PROJECT_ROOT>/docs/security-review-<YYYY-MM-DD-HHMMSS>.html` using the local timestamp at the start of the run (e.g. `security-review-2026-05-14-053805.html`). Always include the timestamp — do not use a bare `security-review.html` name. This keeps each run's report distinct.

---

## 2. Capture goal

### 2.1 Ask the goal

<!-- gate: security-review:2.1.goal | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · security-review:2.1.goal):** Capture the review goal — choice branches into one of three sub-skill sets (`access-config` / `release` / `monitor`).
>
> **Trigger:** Phase 2.1 entry, unless `$ARGUMENTS` already answers it.
> **Why we ask:** Auto-picking `release` runs ALL sub-skills (slow; possibly hits scan/firewall endpoints unnecessarily); auto-picking the wrong goal mis-scopes the review.
> **Cancel leaves:** Nothing — no sub-skills invoked yet.

Ask the user with a single `AskUserQuestion` call. If the user's initial request already answers it, skip and continue.

**Question — What to review?**

| Label | Description |
|-------|-------------|
| Access & config | Check authentication, web roles, and table permissions. Works on local files only. |
| Release readiness | Full review before publishing — checks everything. (Recommended) |
| Deployed site | Check the live site for issues. Requires deployment. |

Goal mapping (internal):

| Label | Goal id | Skills |
|-------|---------|------------|
| Access & config | `access-config` | audit-permissions, setup-auth (read-only) |
| Release readiness | `release` | scan-site, manage-headers, manage-firewall, audit-permissions, setup-auth (read-only) |
| Deployed site | `monitor` | scan-site |

### 2.2 Capture the chosen skill set

Build a `selectedSkills` list based on the answer. Always include the read-only check of `setup-auth` for the `access-config` and `release` goals (it consists of reading existing YAML, not running the skill itself — see § 3.2 below). This is the **Access & Data Security Validation** component.

---

## 3. Run the matching skills

Spawn each selected skill as a background subagent via the `Agent` tool. Each subagent invokes its skill with the argument `--review <SYSTEM_TEMP>/security-review/`. Each skill handles its own authentication, error reporting, and progress.

### 3.1 Skill invocation via subagents

Skills run as **parallel subagents** using the `Agent` tool.

**Default — launch every Agent-eligible skill in one parallel batch.** Spawn all selected subagents in a single message with multiple `Agent` tool calls so they start concurrently. Each subagent runs with `run_in_background: true`. The Agent-eligible set is `scan-site`, `manage-headers`, `manage-firewall` — these all support `--review` mode. `scan-site` is t