What Information Is Included in a Scope Contract File? A Complete Guide to the reverse-skill Format

A scope contract file (scope.md) contains nine mandatory sections—meta, auth, in_scope, out_of_scope, network_profile, deliverables, constraints, signoff, and ops_refs—that enforce authorization, define boundaries, and gate-keep all offensive security work.

The reverse-skill repository implements a rigorous workflow where every analysis case must have a signed scope contract before any "ACT" phase work (scanning, exploitation, etc.) can begin. This plain-Markdown document serves as a hard contractual boundary between planning and execution.

The Nine Sections of a Scope Contract File

According to the source code in zhaoxuya520/reverse-skill, each scope.md follows a standardized template defined in skills/ops/scope-contract.md. The concrete implementation in examples/ctf-demo/scope.md demonstrates how these sections work in practice.

meta: Case Identification and Assignment

The meta section captures administrative metadata that links the contract to a specific engagement.

• case_id: Unique identifier for the analysis case
• created: ISO 8601 timestamp
• operator: Primary analyst assigned
• primary_skill: Core competency required
• lead and specialist: Role assignments from skills/ops/role-map.md

In examples/ctf-demo/scope.md, this appears as:

meta:
  case_id: ctf-demo
  created: 2026-08-02T00:00:00+08:00
  operator: reverse-ops
  primary_skill: reverse
  lead: reverse-lead
  specialist: null

auth: Authorization Gate

The auth section is the critical security control. The contract forbids proceeding if status != granted.

Field	Purpose
status	Must be granted for any ACT work
basis	Legal or policy foundation for permission
evidence_of_auth	Documentary proof of authorization

From the CTF demo: basis: ctf_lab with evidence_of_auth: 平台授权条款（靶场挑战自带授权）.

in_scope: Permitted Targets and Activities

The in_scope section defines what can be touched and how:

• assets: Specific URLs, IPs, or systems (e.g., https://ctf.example.com/challenges/pwn1)
• surfaces: Attack vectors allowed (binary download, remote service)
• activities: Techniques permitted (static analysis, exploit development, remote verification)

out_of_scope: Explicit Prohibitions

The out_of_scope section lists forbidden assets and activities. In the CTF example:

out_of_scope:
  assets: [其他挑战、平台基础设施]
  activities: [dos, phishing_real_users, unrestricted_exfil]

This creates a deny-list that complements the in_scope allow-list.

network_profile: Connectivity Rules

The network_profile restricts network access through enumerated modes:

• offline: No network connectivity
• lab_only: Isolated lab environment only
• authorized_target_only: Direct connections to in-scope targets only
• unrestricted_lab: Full lab access without external constraints

The notes field allows free-form documentation of network topology or VPN requirements.

deliverables: Required Outputs

The deliverables section defines mandatory artifacts:

deliverables:
  report: true
  field_journal: true
  diagrams: true
  timeline: true

These booleans drive automated checklist validation in the signoff phase.

constraints: Operational Limits

The constraints section imposes time, stealth, and data-handling boundaries:

• timebox: Maximum duration (e.g., {2h})
• stealth: Required stealth level (low, medium, high, critical)
• data_handling: Retention rules (anonymize, encrypt_at_rest, shred_after_report)

signoff: Pre-ACT Checklist

The signoff section contains a mandatory checklist that must pass before ACT phase entry. In examples/ctf-demo/scope.md:

signoff:
  ready_for_act: true
  checklist:
    - auth_verified: true
    - in_scope_assets_confirmed: true
    - network_profile_selected: true
    - out_of_scope_reviewed: true
    - roles_assigned: true

This is the final gate enforced by automation.

ops_refs: Documentation Links

The ops_refs section provides traceability to governing documents:

ops_refs:
  - skills/ops/scope-contract.md
  - skills/ops/evidence-finding-path.md
  - skills/ops/report-template.md

Validating Scope Contracts Programmatically

The structured format enables automated validation. Below are two approaches extracted from the repository's operational patterns.

Python Validation Script

This script extracts YAML-like front matter and enforces mandatory fields:

import yaml
import re
import pathlib

def load_scope(md_path: pathlib.Path) -> dict:
    """Extract the YAML-like front-matter from a scope.md file."""
    text = md_path.read_text()
    # Grab everything between section headers

    sections = re.split(r'\n## ', text)

    data = {}
    for sec in sections[1:]:
        name, *body = sec.split('\n', 1)
        data[name.strip()] = yaml.safe_load(body[0] if body else '')
    return data

scope = load_scope(pathlib.Path('examples/ctf-demo/scope.md'))

assert scope['auth']['status'] == 'granted', "Auth not granted!"
assert scope['in_scope']['assets'], "No in-scope assets defined!"
assert scope['signoff']['ready_for_act'], "Sign-off not completed!"
print("Scope contract validated – ready for ACT.")

Bash Validation with yq

For shell-based pipelines, use yq for quick checks:

#!/usr/bin/env bash
FILE=examples/ctf-demo/scope.md

# Verify authorization status

auth_status=$(yq '.auth.status' "$FILE")
if [[ "$auth_status" != "granted" ]]; then
  echo "ERROR: auth.status is not granted"
  exit 1
fi

# Confirm in-scope assets exist

asset_count=$(yq '.in_scope.assets | length' "$FILE")
if (( asset_count == 0 )); then
  echo "ERROR: No in-scope assets defined"
  exit 1
fi

echo "Scope contract passes basic validation."

Key Files in the Scope Contract System

File	Purpose	Location
skills/ops/scope-contract.md	Canonical template with field definitions and recommended values	skills/ops/scope-contract.md#L36-L92
examples/ctf-demo/scope.md	Working example of a completed contract	examples/ctf-demo/scope.md
skills/scripts/case-init.sh / case-init.ps1	Generates fresh scope.md from template	skills/scripts/
skills/ops/role-map.md	Defines roles referenced in meta and signoff	skills/ops/role-map.md

The template in scope-contract.md specifies that all field names remain in English to simplify script validation, even when used in Chinese-language operational environments.

Summary

• A scope contract file (scope.md) contains nine mandatory sections that collectively define authorization, boundaries, and readiness for offensive security work.
• The auth section acts as a hard gate: status: granted is required before any ACT phase activity.
• in_scope and out_of_scope create explicit allow-lists and deny-lists for assets and activities.
• The signoff section provides a final checklist that must pass automated validation.
• All field names are English-only for parsing consistency, with the canonical template at skills/ops/scope-contract.md.

Frequently Asked Questions

What happens if a scope contract has auth.status set to anything other than "granted"?

The workflow blocks all ACT phase work. According to the scope-contract.md template, this field is a hard gate—tools and operators must not proceed with scanning, exploitation, or any active engagement until authorization is explicitly granted and documented.

Can I add custom fields to a scope contract file?

While the template defines standard fields, the YAML-like structure accommodates extensions. However, automated validation scripts may fail on unrecognized fields unless explicitly updated. The repository recommends staying within the defined schema for interoperability.

How do I create a new scope contract for a case?

Use the initialization scripts: skills/scripts/case-init.sh (Linux/macOS) or case-init.ps1 (Windows). These generate a fresh scope.md pre-populated with the template structure, ready for case-specific values. The scripts ensure consistent formatting and mandatory section presence.

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