# Understanding the Scope Contract: How case-guard.ps1 Validates Authorization

> Learn about the scope contract in penetration testing and how case-guard.ps1 validates authorization by checking critical conditions before script execution.

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

---

**The scope contract is a formal markdown document that defines penetration-testing engagement boundaries including targets, authorized accounts, and prohibited actions, and `case-guard.ps1` validates this contract by checking four mandatory conditions—authorization status, network profile mode, in-scope assets, and readiness flags—before permitting any ACT script execution.**

In the `zhaoxuya520/reverse-skill` repository, security engagements rely on a strictly enforced scope contract to prevent unauthorized testing. The `case-guard.ps1` script serves as a mandatory pre-execution gate that validates this contract's presence and correctness, ensuring that all penetration testing activities remain within explicitly defined boundaries.

## What Is the Scope Contract?

The **scope contract** is a formal definition of what a penetration-testing engagement is allowed to cover, captured in a [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file that follows a specific template located at [`skills/pentest-tools/templates/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/templates/scope.md). This markdown document structures the engagement parameters into four critical sections:

- **目标 (Targets)**: Lists the domains, IPs, applications, or APIs that are explicitly in-scope.
- **授权账号 (Authorized Accounts)**: Enumerates the roles and usernames that may be used during testing.
- **明确禁止 (Explicit Prohibitions)**: Check-boxes defining disallowed targets, actions, time windows, or rate limits.
- **授权证明 (Authorization Proof)**: Records the authorizer, date, and textual description of the authorized scope.

## How case-guard.ps1 Validates Authorization

Located at `skills/scripts/case-guard.ps1`, this lightweight gate runs **before any ACT (action) script** to verify that the contract at `work\<my-case>\scope.md` satisfies minimal safety conditions. The script performs four specific validation checks implemented between lines 33 and 72.

### Authorization Status Validation

The contract must explicitly declare `status: granted` (or `- status: granted`). If this declaration is missing, the script records the issue *"auth.status is not granted"* at lines 33-37 and flags the contract as invalid.

### Network Profile Mode Verification

The contract must specify a `mode:` value (e.g., `online` or `offline`). For `offline` mode, the script requires an additional cue indicating a sample is present (keywords like "sample", ".apk", or ".exe"). Implemented at lines 39-49, this check raises the issue *"network_profile.mode is offline without offline sample cue"* if the requirement is not met.

### In-Scope Assets Check

Under the markdown heading `## in_scope`, the script looks for a `- assets:` list containing at least one non-empty entry, unless the network mode is `offline`. Lines 51-67 implement this validation, adding the issue *"in_scope.assets appears empty"* when the asset list is missing or empty.

### Readiness Flag Confirmation

The final gate at lines 69-72 requires `ready_for_act: true` in the contract. If omitted, the script records *"ready_for_act is not true"* and prevents execution.

## Exit Codes and Execution Control

The script uses specific exit codes to communicate validation results to downstream automation:

- **Exit code `0`**: All validations passed. The script prints "CASE‑GUARD OK" and permits ACT script execution.
- **Exit code `2`**: Validation issues detected. Execution stops unless the user supplies the `-Force` switch, which forces exit code `0` while displaying warnings.
- **Exit code `1`**: Usage or fatal error (e.g., missing case directory).

## Practical Usage Examples

Run the guard on a case directory to validate the scope contract before execution:

```powershell

# Normal run – stops if scope is not ready

powershell -File skills/scripts/case-guard.ps1 -CaseRoot work\my-case

# Force execution with warnings only – useful for debugging

powershell -File skills/scripts/case-guard.ps1 -CaseRoot work\my-case -Force

```

A valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) that satisfies all validation checks:

```markdown

# 授权范围 (Scope)

## 目标

| 类型 | 目标 | 备注 |
|------|------|------|
| 域名 | example.com | |

## 授权账号

| 角色 | 用户名 | 备注 |
|------|--------|------|
| admin | tester | |

## 明确禁止

- [ ] 不得测试的目标：

## 授权证明

- 授权人：Alice
- 授权日期：2026‑08‑01
- 授权范围描述：完整渗透测试

## in_scope

- assets:
  - /var/www/html
  - /opt/app/config.yaml

- status: granted
- network_profile:
    mode: online
- ready_for_act: true

```

## Summary

- The **scope contract** in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) defines engagement boundaries including targets, authorized accounts, and explicit prohibitions based on the template at [`skills/pentest-tools/templates/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/templates/scope.md).
- `case-guard.ps1` at `skills/scripts/case-guard.ps1` validates four mandatory conditions before ACT script execution: authorization status (lines 33-37), network profile mode (lines 39-49), in-scope assets (lines 51-67), and readiness flags (lines 69-72).
- Exit code `2` blocks execution unless the `-Force` switch is specified, ensuring strict adherence to the scope contract and preventing unauthorized testing activities.

## Frequently Asked Questions

### What happens if scope.md is missing the status: granted line?

`case-guard.ps1` records the validation issue *"auth.status is not granted"* and exits with code `2`, preventing ACT script execution unless the `-Force` switch is used to override the block.

### Can I run penetration tests in offline mode without providing a sample file?

No. According to lines 39-49 of `case-guard.ps1`, offline mode requires a sample cue (such as "sample", ".apk", or ".exe") in the contract; otherwise validation fails with the error *"network_profile.mode is offline without offline sample cue"*.

### Where does case-guard.ps1 look for the scope.md file?

The script reads [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) from the specified case directory (e.g., `work\<my-case>\scope.md`) passed via the `-CaseRoot` parameter, as implemented in the file path resolution logic at `skills/scripts/case-guard.ps1`.

### What is the difference between exit code 1 and exit code 2 in case-guard.ps1?

Exit code `2` indicates validation issues with the scope contract (such as missing required fields like `status: granted` or `ready_for_act`), while exit code `1` indicates usage errors or fatal conditions such as a missing case directory or invalid parameters.