/pentest-scope

name: pentest-scope
description: Define or update engagement scope — saves scope to disk without launching a pentest. Can be run before or during an engagement. If a pentest is active and the target changes drastically, warns the operator and suggests a new engagement.
disable-model-invocation: true
allowed-tools:
  - AskUserQuestion
  - Read
  - Write

Output the following banner verbatim:

============================================================
[SCOPE DEFINITION]
============================================================

Step 1 — Detect Existing Scope

Try to Read `.pentest-scope.json`.

If the file exists and is valid JSON, extract these fields and store them:

• `existing_target` — the saved target value
• `existing_engagement` — the saved engagement name
• `existing_out_of_scope` — the saved out-of-scope value
• `existing_auth` — the saved auth value
• `existing_timing` — the saved time budget / quota (for backward compatibility: if `timing` is absent but a legacy `window` field exists, use `window`)
• `existing_thoroughness` — the saved thoroughness level (light, medium, deep, or full)
• `existing_output_formats` — the saved deliverable formats array (default `[]` if absent)
• `existing_status` — either `"pending"` (not yet launched) or `"active"` (pentest in progress)

Set `has_existing_scope = true`.

If the file does not exist or cannot be parsed, set `has_existing_scope = false`.

Step 2 — Show Existing Scope (if present)

If `has_existing_scope = true`, output this block with real values substituted in:

============================================================
EXISTING SCOPE FOUND
============================================================
Target:       {existing_target}
Engagement:   {existing_engagement}
Out-of-scope: {existing_out_of_scope}
Auth:         {existing_auth}
Time budget:  {existing_timing}
Thoroughness: {existing_thoroughness}
Deliverables: report.md + pentest-report.json{, plus existing_output_formats if any}
Status:       {existing_status}
============================================================

Then use AskUserQuestion to ask:

"What would you like to do with the existing scope?"

Present exactly these options:

• "Update scope — define a new scope (replaces the existing one)"
• "Cancel — keep the existing scope as-is"

If the user selects "Cancel — keep the existing scope as-is", output:

Scope unchanged. Existing scope is still active.

Then stop — do not proceed to Step 3.

If the user selects "Update scope", continue to Step 3.

Step 3 — Scope Collection

**Free-text fields — ask each as a plain prompt, NOT via AskUserQuestion.** Real targets are rarely `localhost`, so canned options don't fit — output the question and wait for the user's typed reply. Ask one at a time, in order:

1. **Target** — "Target URL / IP range — what is the target? (e.g., https://example.com, 10.0.0.81:3000, 192.168.1.0/24)" → `new_target` 2. **Engagement name** — "Engagement name — what should this engagement be called? (used as the outputs/{name}/ folder, e.g., example-com-2026-06)" → `new_engagement` 3. **Scope restrictions** — "Out-of-scope — any paths, subdomains, or services to exclude? (e.g., /admin, staging.example.com — or 'none')" → `new_out_of_scope` 4. **Time budget** — "Time budget — how long should active testing run? This is the QUOTA the engagement will spend (not just a ceiling), excluding report generation. (e.g., 30min, 2h, 8h, until 2026-06-20, or 'unlimited')" → `new_timing` 5. **Authentication** — "Authentication — are credentials available for authenticated testing? (no — or provide username:password / token)" → `new_auth`

> The single Time-budget question replaces the previous redundant "testing window" + "max execution time" pair — there is one time concept now: the quota.

Then use AskUserQuestion (genuine multiple choice) to ask thoroughness:

"Thoroughness — How deep should testing go? This affects which attack vectors are tested and how many payloads are attempted per category. (If it exceeds the time budget, the engagement runs breadth-first and reports the effective level.)"

Present exactly these options:

• "Light — surface-level scanning, automated tools only, fast coverage"
• "Medium — standard coverage, common attack paths, mix of automated and manual (Recommended)"
• "Deep — thorough manual testing, complex attack chains, edge cases explored"
• "Full — exhaustive testing, all payloads and vectors, maximum coverage (slowest)"

Store this answer as `new_thoroughness`.

Then use AskUserQuestion with **multiSelect: true** to ask deliverable formats:

"Deliverable formats — which report artifacts should be produced? `report.md` and `pentest-report.json` are ALWAYS produced; select any extras."

Present exactly these options (multi-select):

• "Executive summary — 1-page non-technical summary (exec-summary.md)"
• "Remediation plan — actionable ticket-style fix list (remediation-plan.md)"
• "CSV findings table — findings.csv for tracking"
• "PDF render — report.pdf (requires pandoc; degrades to markdown with a warning if unavailable)"
• "DOCX render — report.docx (requires pandoc; degrades to markdown with a warning if unavailable)"

Store the selected labels as the `new_output_formats` array (empty array if none selected).

Store all answers as `new_target`, `new_engagement`, `new_out_of_scope`, `new_auth`, `new_timing`, `new_thoroughness`, `new_output_formats`.

Step 4 — Change Impact Assessment

This step only applies when `has_existing_scope = true` AND `existing_status = "active"`.

If `has_existing_scope = false` OR `existing_status = "pending"`, skip to Step 5.

Compare `new_target` to `existing_target`:

**Drastic change** — the primary domain or IP subnet is different. Examples:

• `https://example.com` → `https://other.com` (different domain)
• `192.168.1.0/24` → `10.0.0.0/8` (different IP range)
• A URL target changed to an IP target or vice versa

**Minor change** — same primary ta