Auth Gate Implementation and scope.md Generation Workflow in reverse-skill

The reverse-skill repository enforces a mandatory authentication gate through a two-stage PowerShell workflow: case-init.ps1 generates the scope.md authorization document, and case-guard.ps1 validates it before any ACT operation proceeds.

This workflow ensures that no offensive security actions execute against a target without explicit written authorization, proper network profiling, and defined asset scope. Below is the complete technical breakdown of how the auth gate functions, including exact file paths, parameter behaviors, and validation logic from the source code.

---

Overview of the Auth Gate Architecture

The auth gate in reverse-skill is implemented as a state machine that progresses from "pending" to "granted" status. The gate consists of two core scripts located in skills/scripts/:

• case-init.ps1 — Generates the case workspace and the scope.md authorization contract
• case-guard.ps1 — Performs pre-flight validation before any skill execution

Both scripts operate on a YAML-formatted scope.md file that serves as the single source of truth for authorization status, network constraints, and in-scope targets.

---

Step 1: Initialize the Case with case-init.ps1

The workflow begins by running skills/scripts/case-init.ps1, which creates the case directory structure and populates scope.md with templated authorization fields.

Key Operations in case-init.ps1

The script performs four critical functions (lines 70–242):

1. Resolves authentication status (lines 70–78): Determines authStatusResolved based on the -AuthGranted switch parameter
2. Builds the asset list (lines 91–99): Processes -TargetUrl inputs into structured in-scope assets
3. Decides network mode (lines 103–119): Validates authorized_target_only, offline, or other network profiles
4. Writes the markdown template (lines 183–242): Generates the complete scope.md with sections for meta, auth, in_scope, network_profile, and signoff

Code Example: Creating a Case

# Initialize with pending authentication (default)

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" -CaseName my-case

# Initialize with auth pre-granted and target specified

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" -CaseName my-case `
    -AuthGranted -TargetUrl "https://app.example/" `
    -NetworkProfile authorized_target_only

The -AuthGranted flag forces authStatusResolved = 'granted' at line 71, bypassing the default "pending" state. When this flag is omitted, the generated scope.md contains placeholder values requiring manual completion.

---

Step 2: Authorize via scope.md Editing

After initialization, scope.md resides at work/<case>/scope.md with a templated structure created at lines 197–205 of case-init.ps1. The file uses YAML frontmatter with markdown sections.

Required Fields to Complete

Section	Field	Purpose
auth	status	Must change from pending to granted
auth	granted_by	Identifier of authorizing party
in_scope	assets	List of authorized target URLs/IPs
network_profile	mode	Network constraints for engagement
signoff	checklist	Verification items (lines 331–336)

The checklist under signoff displays completion status using markdown checkboxes ([ ] → [x]). The case is considered ready for ACT only when all mandatory checkboxes are marked complete.

---

Step 3: Re-initialization (Optional Alternative to Manual Edit)

Rather than manually editing scope.md, you can re-run case-init.ps1 with authorization parameters to update the file programmatically. This approach is documented in the comment block at lines 5–6 of case-init.ps1.

This method is preferred when:

• The initial case was created without -AuthGranted
• Additional targets must be added to the asset list
• Network profile requirements have changed

---

Step 4: Enforce the Gate with case-guard.ps1

Before any ACT operation executes, skills/scripts/case-guard.ps1 performs mandatory validation. The script returns specific exit codes that control workflow continuation:

Exit Code	Meaning	Behavior
0	Gate passed	Proceed with primary skill execution
1	Error	Fatal configuration or parsing error
2	Not ready	Auth gate conditions not satisfied

Validation Logic (lines 51–87)

case-guard.ps1 parses scope.md and enforces four sequential checks:

1. Authentication status (lines 52–53): Verifies auth.status equals granted
2. Network profile validity (lines 56–67): Confirms network_profile.mode is valid; if offline, checks for offline-sample cue existence
3. Asset presence (lines 71–82): Validates at least one in-scope asset unless operating in offline mode
4. ACT readiness flag (line 85): Confirms ready_for_act: true

Exit Handling (lines 88–102)

Any check failure triggers immediate termination with the appropriate exit code. The -Force parameter modifies this behavior to emit warnings only and return exit 0—not recommended for production engagements.

Code Example: Running the Guard

# Standard gate verification

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

# Force continuation despite warnings (use with caution)

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

---

Step 5: Execute the Primary Skill

Upon successful guard validation (exit 0), the workflow extracts the primary_skill from the scope.md header (populated at lines 186–193 of case-init.ps1) and executes the designated skill against the authorized assets within the defined network constraints.

---

Supporting Files and Contracts

File	Path	Purpose
case-init.ps1	skills/scripts/case-init.ps1	Case initialization and scope.md generation
case-guard.ps1	skills/scripts/case-guard.ps1	Pre-ACT authorization validation
verify-routing-coherence.ps1	skills/scripts/verify-routing-coherence.ps1	CI validation of auth.status consistency across routing tests
scope-contract.md	skills/ops/scope-contract.md	Formal specification of required scope.md fields
evidence-finding-path.md	skills/ops/evidence-finding-path.md	Guidance for linking evidence to auth gate

---

Summary

• case-init.ps1 creates the authorization contract (scope.md) with configurable auth status, network profile, and asset scope
• Manual editing or re-initialization updates scope.md from "pending" to "granted" state with completed checklists
• case-guard.ps1 enforces hard gates on auth status, network validity, asset presence, and readiness flag before any ACT
• Exit codes 0/1/2 provide deterministic workflow control for CI/CD and manual operations
• The -Force parameter bypasses gate failures with warnings only—avoid in production

---

Frequently Asked Questions

What happens if auth.status remains pending in scope.md?

case-guard.ps1 will detect the non-granted status at lines 52–53 and exit with code 2 (not ready), preventing any ACT operations. The workflow must pause until authorization is explicitly recorded.

Can I use case-init.ps1 to update an existing case without recreating it?

Yes. Re-running case-init.ps1 with the same -CaseName and new parameters (such as -AuthGranted or additional -TargetUrl values) will regenerate scope.md with updated values while preserving the existing case directory.

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

Exit code 1 indicates a fatal error such as file parsing failure or missing scope.md. Exit code 2 indicates the gate conditions are not yet satisfied—the file is valid but authorization is incomplete. This distinction allows automation to differentiate between retryable and non-retryable failures.

Is the -Force parameter safe to use in automated pipelines?

No. The -Force parameter (lines 88–102) causes case-guard.ps1 to emit warnings and return exit 0 regardless of gate status, effectively disabling the auth gate. It should be restricted to local development or testing scenarios with synthetic data.

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