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

> Understand the work/<case>/scope.md structure in reverse-skill. This Markdown file defines authorization, in-scope assets, network rules, and sign-off for your security cases.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: architecture
- Published: 2026-08-16

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```markdown

# 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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) files.

### Initialization via case-init.ps1

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

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/sample-case/scope.md) with all required keys pre-populated:

```markdown

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | Official specification and full template reference |
| `skills/scripts/case-init.ps1` | Generates initial [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) for new cases |
| `skills/scripts/case-guard.ps1` | Runtime enforcement before ACT execution |
| [`skills/scripts/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-review/scripts/review_case.py) | Deep validation of all schema fields |
| [`examples/ctf-demo/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) in the reverse-skill repository. This file documents every valid key, acceptable values, and formatting rules for the schema.