What Is the Structure of `work/<case>/scope.md` in the reverse-skill Repository?

The work/<case>/scope.md file is a mandatory Markdown contract that defines authorization, in-scope assets, network rules, and sign-off status for every security or reverse-engineering case in the reverse-skill repository.

This file follows a strict schema so that automated guard scripts can parse it reliably. Every case directory under work/ must contain this file before any authorized controlled testing (ACT) can proceed. The structure is enforced by skills/scripts/case-guard.ps1 and validated by skills/scripts/case-review/scripts/review_case.py.

Required Sections of the scope.md Schema

The file uses Markdown headings with YAML-style key/value pairs nested underneath. This hybrid format remains human-readable while being machine-parseable.

Header Section

The first line is an H1 title identifying the case:

# Scope for <case-name>

This serves as a human-readable identifier and matches the directory name under work/<case>/.

Auth Section

Records the authorization status that must be granted before any ACT is permitted:

auth:
  status: granted
  granted_by: <user>
  granted_at: 2026-08-16T12:34:00Z

The case-review script specifically validates auth.status and will raise auth_invalid if missing or malformed.

In Scope Section

Lists the assets and targets permitted for investigation:

in_scope:
  assets:
    - https://target.example.com
    - 10.0.0.5

For network cases, this list must be non-empty. The guard scripts enforce this requirement before allowing any network interaction.

Network Profile Section

Defines the allowed network interaction mode:

network_profile:
  mode: authorized_target_only

Valid modes restrict outbound connections to explicitly authorized targets only. The case-review script checks network_profile.mode and raises network_invalid for unrecognized values.

Sign-off Section

Indicates whether the case is ready for actual ACT:

signoff:
  ready_for_act: true

The review script validates signoff.ready_for_act and raises ready_invalid if this boolean is missing or false when attempting to proceed.

Optional Metadata Section

Additional notes, references, or evidence links:

notes:
  - See work/<case>/evidence/
  - Reference: internal ticket #12345

File Validation and Enforcement

The reverse-skill repository implements a multi-layer validation system for scope.md files.

Initialization via case-init.ps1

The skills/scripts/case-init.ps1 script generates a minimal valid template:

# Generate a fresh scope for a new case called "sample-case"

powershell -File skills/scripts/case-init.ps1 -Hint "sample task" -CaseName sample-case -AuthGranted

This produces work/sample-case/scope.md with all required keys pre-populated:

# Scope for sample-case

auth:
  status: granted
  granted_by: alice
  granted_at: 2026-08-16T12:00:00Z

in_scope:
  assets:
    - https://target.example.com

network_profile:
  mode: authorized_target_only

signoff:
  ready_for_act: false

Runtime Enforcement via case-guard.ps1

Before any ACT executes, skills/scripts/case-guard.ps1 verifies:

• The file exists at work/<case>/scope.md
• All required YAML keys are present and parseable
• auth.status equals granted

Failure aborts with explicit error messages:

ERROR: scope.md missing under work/sample-case
ERROR: auth.status is missing

Formal Review via review_case.py

The Python validator at skills/scripts/case-review/scripts/review_case.py performs deep validation:

• auth.status → raises auth_invalid on failure
• network_profile.mode → raises network_invalid on failure
• signoff.ready_for_act → raises ready_invalid on failure
• in_scope.assets → validates non-empty for network cases

Complete Example: ctf-demo/scope.md

The repository includes a concrete reference at examples/ctf-demo/scope.md demonstrating a fully populated contract. This example shows proper formatting for complex multi-asset engagements with time-bounded authorization.

Key Files Controlling scope.md Structure

File	Role
skills/ops/scope-contract.md	Official specification and full template reference
skills/scripts/case-init.ps1	Generates initial scope.md for new cases
skills/scripts/case-guard.ps1	Runtime enforcement before ACT execution
skills/scripts/case-review/scripts/review_case.py	Deep validation of all schema fields
examples/ctf-demo/scope.md	Working example of a populated scope contract

Summary

• Purpose: work/<case>/scope.md is the legal and technical contract governing every reverse-skill engagement
• Format: Markdown with YAML-style nested key/value pairs
• Required sections: Header, auth, in_scope, network_profile, signoff
• Enforcement: Three-layer validation through initialization, runtime guards, and formal review
• Automation: Scripts in skills/scripts/ handle generation, guarding, and validation without manual intervention

Frequently Asked Questions

What happens if scope.md is missing or malformed?

The case-guard.ps1 script aborts execution with a clear error message such as ERROR: scope.md missing under work/<case> or ERROR: auth.status is missing. No ACT can proceed until the file is present and valid.

Can I edit scope.md manually after case creation?

Yes. The file is plain Markdown with YAML content. You can manually add assets, update authorization timestamps, or modify the ready_for_act flag. Run case-review.ps1 after edits to validate changes before execution.

How does reverse-skill prevent scope creep during an engagement?

The network_profile.mode field restricts outbound connections to authorized_target_only. The guard scripts parse this value and enforce network isolation accordingly. Any attempt to interact with non-listed assets triggers enforcement mechanisms.

Where is the authoritative template for scope.md?

The full specification resides in skills/ops/scope-contract.md in the reverse-skill repository. This file documents every valid key, acceptable values, and formatting rules for the schema.

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