What Information Is Stored in a Reverse-Skill Case Directory?

A reverse-skill case directory stores structured engagement metadata, authorization scope, chronological timelines, work-item trackers, and evidence containers required to audit and execute penetration-testing or reverse-engineering engagements.

The zhaoxuya520/reverse-skill repository provides a PowerShell-based framework for managing security assessments. When an analyst initializes a new engagement using skills/scripts/case-init.ps1, the script creates a reverse-skill case directory under work\<case-name> that serves as the single source of truth for the entire operation.

Core Directory Structure

The foundation of every case is a standard folder hierarchy created by the initialization script.

Sub-Folders for Artifacts

Three directories are generated in a loop at skills/scripts/case-init.ps1 lines 35-40 to organize physical evidence:

• evidence/ – Stores raw artifacts such as screenshots, packet captures, and exported data.
• notes/ – Contains analyst observations, scratchpad thoughts, and intermediate findings.
• report/ – Holds the final deliverable documentation.

# Directory creation logic from case-init.ps1

foreach ($d in $dirs) {
    $path = Join-Path $caseRoot $d
    New-Item -ItemType Directory -Path $path -Force | Out-Null
}

Mandatory Markdown Files

Beyond folders, the reverse-skill case directory contains four standardized Markdown files that enforce documentation discipline and drive workflow gates.

scope.md – The Engagement Contract

scope.md acts as the central configuration file and authorization gate. According to skills/scripts/case-init.ps1 lines 49-52, this file captures:

• Meta data – Case name, creation date, and analyst identification.
• Authentication status – Whether authorization has been granted (auth_granted: true/false).
• In-scope assets – Target URLs, IP ranges, or offline systems under assessment.
• Network profile – Operating mode (airgapped, authorized_target_only, unrestricted).
• Deliverables – Expected output formats (report, raw evidence, etc.).
• Constraints – Time limits, testing windows, and blackout periods.
• Sign-off – Digital or physical authorization references.
• Checklist – Prerequisites that must be satisfied before active testing.

This file is parsed by case-guard.ps1 to determine if the engagement is ready for active testing (ACT).

timeline.md – The Audit Trail

Written immediately after scope.md in the same code block (case-init.ps1 lines 49-52), timeline.md functions as an append-only log. Each entry records:

• Date and timestamp of action.
• Role performing the action (analyst, lead, client).
• Description of the activity.
• Reference to commands or evidence IDs.
• Next step indicators.

This creates a forensic-quality chronology of the engagement from initialization through reporting.

workitems.md – Task Tracking

Also generated at case-init.ps1 lines 49-52, this file maintains a table of work-items (prefixed WI-*) that track:

• Scope establishment and authorization verification.
• Coverage checks for target assets.
• Evidence collection milestones.
• Report generation status.

The work-items serve as a lightweight project management layer within the case directory.

README.md – Analyst Guidance

Generated at the end of the initialization process (case-init.ps1 lines 74-80), README.md provides human-readable context and next-step instructions. It dynamically adjusts content based on readiness:

• Pending state – Instructs the analyst to edit scope.md and obtain authorization.
• Ready state – Directs the analyst to open the primary skill and begin ACT.

The Case Guard Validation System

Before any active testing command executes, skills/scripts/case-guard.ps1 validates the reverse-skill case directory contents. The script enforces four critical checks:

1. Authorization (line 33) – Verifies auth_granted: true exists in scope.md.
2. Network Profile (lines 40-48) – Ensures network_profile.mode is defined.
3. Asset Definition (lines 51-66) – Confirms in-scope assets are listed unless operating in offline mode.
4. Readiness Gate (lines 69-72) – Checks for ready_for_act: true.

If any validation fails, the guard exits with code 2, preventing accidental unauthorized testing. The -Force parameter can override this for sandbox environments.

Creating and Populating a Case Directory

The following PowerShell commands demonstrate the complete lifecycle of a reverse-skill case directory:

# Initialize a new authorized case

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

# Verify the generated scope metadata

Get-Content work\demo-case\scope.md

# Validate readiness before testing

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

# Append evidence to the case

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work\demo-case `
    -Id E-001 `
    -Title "Found admin panel" `
    -ReproCommand "curl https://target.example/admin"

# Manual timeline update and re-validation

notepad.exe work\demo-case\timeline.md
powershell -File skills/scripts/case-guard.ps1 -CaseRoot work\demo-case -Force

Summary

A reverse-skill case directory contains the complete administrative and operational record of a security engagement:

• Three sub-folders (evidence/, notes/, report/) for physical artifact organization.
• scope.md defining authorization boundaries, assets, constraints, and readiness gates.
• timeline.md providing an immutable audit trail of analyst actions.
• workitems.md tracking task completion and coverage requirements.
• README.md offering contextual guidance based on engagement state.
• case-guard.ps1 enforcing validation logic to prevent unauthorized testing.

Together, these components create a reproducible, version-controllable structure that satisfies both operational workflow and compliance auditing requirements.

Frequently Asked Questions

What happens if scope.md is missing required fields?

If scope.md lacks auth_granted: true, defined assets (when not offline), or ready_for_act: true, case-guard.ps1 exits with code 2 and blocks ACT execution. The script performs explicit null-checks and string validations at lines 33-72 to ensure all gates are satisfied before permitting active testing.

Can I manually edit files in the case directory?

Yes. While case-init.ps1 generates the initial templates, analysts are expected to manually update timeline.md and modify scope.md as engagement parameters change. However, case-guard.ps1 will re-validate these files before allowing any automated testing scripts to run against the targets.

How does the network profile affect case requirements?

The network_profile.mode setting in scope.md determines whether asset lists are mandatory. According to case-guard.ps1 lines 51-66, if the mode is offline, the script skips asset validation. For authorized_target_only or unrestricted modes, the guard requires at least one defined in-scope asset to prevent misconfigured testing scopes.

Where is the case directory physically located?

By default, case-init.ps1 creates the reverse-skill case directory under work\<case-name> relative to the repository root. The script uses Join-Path to construct these paths dynamically based on the -CaseName parameter provided during initialization.

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