/security-review

name: security-review
description: >-
  Runs a guided, end-to-end security review of a Power Pages site and
  consolidates every finding into one HTML report covering source code
  and dependencies, the live site, browser headers, firewall,
  authentication, and role-based permissions. Use when the user wants a
  full security review, a release-readiness check before publishing, a
  code-and-config check during development, live site monitoring, or
  asks open-ended questions like "review my site security", "is my site
  safe to ship", "do a security check", "monitor my site" — even if they
  do not name the individual checks.
user-invocable: true
argument-hint: "[optional natural-language hint about the goal]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Skill, Agent
model: opus

> **Plugin check**: Run `node "${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 `code-config` goal, the deploy check is not required: source code, dependencies, authentication, web roles, and table permissions are read from local files 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 (`code-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 | |-------|-------------| | Code & config | Check source code, dependencies, 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 | |-------|---------|------------| | Code & config | `code-config` | scan-code, audit-permissions, setup-auth (read-only) | | Release readiness | `release` | scan-code, 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 `code-config`