What Is the Purpose of scope.md in Reverse‑Skill Case Management

The scope.md file serves as the central contract and mandatory authorization gate that defines boundaries, assets, and execution parameters for every pentest or reverse‑engineering case, preventing any active operations until explicitly granted.

In the zhaoxuya520/reverse-skill framework, case management relies on a file‑based governance model rather than traditional database permissions. The scope.md file acts as the single source of truth stored in work/<case>/scope.md that determines what operations are permitted, which assets are in scope, and when the framework may proceed with active testing.

Core Functions of scope.md in Case Management

The scope.md file operates as a "hard gate" that replaces database‑driven permissions with a version‑controlled Markdown contract. It enforces six critical aspects of case management:

Authorization Gate Control

The auth.status field records whether authorization is granted, pending, or denied. According to the contractual requirements defined in skills/ops/scope-contract.md, the framework must not proceed with any ACT (active operations such as scanning, hooking, or exploiting) until this status equals granted. The skills/scripts/case-guard.ps1 and skills/scripts/case-init.ps1 scripts validate this field before allowing further actions.

In‑Scope and Out‑of‑Scope Asset Definition

The file explicitly lists all permitted interaction targets—including hosts, domains, binaries, and URLs—under the in_scope section. Conversely, it enumerates prohibited activities and assets (such as denial‑of‑service attacks or phishing real users) in the out_of_scope section. Guard scripts continuously validate that no operation touches out‑of‑scope assets.

Network Profile Enforcement

scope.md declares the allowed network mode via the network_profile field, which supports values such as offline, lab_only, authorized_target_only, and unrestricted_lab. This profile restricts network traffic to match the authorization level. Changing this mode is only permitted after auth.status is set to granted. The case-init.ps1 script derives the default network profile from the provided assets and authorization status.

Deliverables and Operational Constraints

The file specifies required outputs such as reports, field journals, and diagrams under deliverables sections. It also records operational constraints including timebox limitations, stealth levels, and data handling requirements. Downstream skills like skills/docs-generator parse these fields to auto‑populate final reports.

Sign‑Off Checklist

Before setting ready_for_act = true, scope.md enforces a final checklist ensuring that authorization is granted, assets are populated, and a network profile is selected. The case-guard script reads this flag to determine if the primary skill can be safely launched.

Technical Implementation and Enforcement

The enforcement mechanism relies on three key components within the repository:

• skills/ops/scope-contract.md: Defines the "MUST" rule that a case cannot perform any ACT without a populated scope.md file present in the case directory.
• skills/scripts/case-init.ps1: Generates the work/<case>/scope.md file by copying the template from skills/pentest-tools/templates/scope.md and populating mandatory fields based on command‑line arguments.
• skills/scripts/case-guard.ps1: Validates the contents of scope.md before allowing any target‑facing activity to proceed.

Practical Examples for Creating and Reading scope.md

To initialize a new case with a ready‑to‑act scope, execute the case‑initialization script with the appropriate authorization flags:

# Initialise a case named “web‑pentest‑01”

powershell -NoProfile -ExecutionPolicy Bypass `
    -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" `
    -CaseName "web-pentest-01" `
    -AuthGranted `
    -TargetUrl "https://test.example.com" `
    -NetworkProfile authorized_target_only

This command writes work/web-pentest-01/scope.md with a structure similar to:

# Case Scope

## meta

- case_id: 20230801-web-pentest-01
- created: 2023-08-01T12:34:56Z
- operator: local
- primary_skill: reverse-engineering
- primary_id: R0
- lead_role: lead
- specialist_roles: []

## auth

- status: granted
- basis: own_system
- evidence_of_auth: cli-flag AuthGranted or AuthStatus=granted
- MUST NOT proceed if status != granted

## in_scope

- assets:
  - https://test.example.com/

To programmatically verify authorization status in custom scripts:

$caseRoot = "work\web-pentest-01"
$scopePath = Join-Path $caseRoot "scope.md"
$scope = Get-Content $scopePath -Raw

# Extract the auth status

if ($scope -match 'status:\s*(\w+)') {
    $authStatus = $Matches[1]
    Write-Host "Auth status: $authStatus"
}

Summary

• Central Contract: scope.md acts as the single source of truth for case boundaries and permissions in the reverse‑skill framework.
• Mandatory Gate: Located in work/<case>/scope.md, it must exist and show auth.status: granted before any ACT operations are permitted.
• Asset Control: Explicitly defines in‑scope targets and out‑of‑scope prohibitions to prevent unauthorized testing.
• Network Restrictions: Enforces network profiles (offline, lab_only, etc.) that limit traffic based on authorization levels.
• Automation Support: Parsed by case-guard.ps1 and case-init.ps1 to automate validation and report generation.

Frequently Asked Questions

What happens if scope.md is missing from the work directory?

The framework will refuse to execute any ACT operations. The skills/scripts/case-guard.ps1 script explicitly checks for the existence and validity of work/<case>/scope.md and halts execution if the file is absent or if auth.status is not set to granted.

How does scope.md prevent unauthorized operations without a database?

By using a version‑controlled Markdown file stored directly in the case directory, scope.md creates an auditable, signed contract. The case-guard.ps1 script parses this file before every operation, creating a "hard gate" that is enforced at the script level rather than requiring external database connectivity.

Can the network profile be changed after initial case creation?

Yes, but only after auth.status is set to granted. The case-init.ps1 script derives the initial network_profile from command‑line arguments, but modifications to this field require explicit authorization to prevent accidental exposure of operations to unauthorized networks.

Where is the template for scope.md located?

The baseline template is stored at skills/pentest-tools/templates/scope.md. When case-init.ps1 creates a new case, it copies this template to work/<case>/scope.md and populates the mandatory fields including metadata, authorization details, and asset lists based on the initialization parameters provided.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}