# How the `case-init` Scripts Manage Work Directory Structure and `scope.md` in Reverse-Skill

> Learn how reverse-skill case-init scripts build work directories and generate scope.md contracts for authentication, network, and asset management, streamlining your reverse engineering tasks.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-09-01

---

**The `case-init` scripts automatically create a standardized work directory under `work/<case>/` with evidence, notes, and report subfolders, then generate a YAML-style [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract that records authentication status, network profile, in-scope assets, and a `ready_for_act` flag for downstream enforcement.**

The `case-init` utilities—[`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) for Linux/macOS/Kali and `skills/scripts/case-init.ps1` for Windows—are the entry point for every reverse engineering engagement in the [zhaoxuya520/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) framework. These scripts enforce consistent directory structure and scope documentation before any skill module executes.

## Resolving Repository Roots and Project Context

The scripts first establish three critical path variables to anchor all subsequent operations:

- `SKILLS_ROOT` – the directory containing the scripts themselves
- `PACKAGE_ROOT` – resolved as `SKILLS_ROOT/..` (two levels above the script location)
- `PROJECT_ROOT` – defaults to the current working directory, overridable via `--project-root` or `--package-root`

These calculations appear in [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) at lines 47-58, ensuring the framework can locate skill modules and write case data to the correct location regardless of where the user invokes the script.

## Determining and Validating the Case Name

If the user omits `--case-name`, the script constructs a slug from the `--hint` value, truncates it to prevent filesystem issues, and prefixes it with an ISO-style timestamp (lines 99-103). The validation logic (lines 104-114) enforces strict rules:

- 1-80 characters maximum
- Alphanumeric characters only
- No special characters, spaces, or control characters

This prevents path traversal vulnerabilities and ensures cross-platform compatibility.

## Processing Presets and Building the Asset Inventory

The `case-init` scripts support **preset profiles** that configure multiple parameters simultaneously (lines 69-97):

| Preset | Use Case | Auth Status | Network Profile |
|--------|----------|-------------|-----------------|
| `offline-sample` | Local malware/samples | `granted` | `offline` |
| `ctf-public` | Public CTF challenges | `granted` | `authorized_target_only` |
| `own-system` | User-owned hardware | `granted` | `air_gap` or `isolated_vlan` |

Assets are collected into an `ASSETS` array from three sources (lines 47-55):
- `--target-url` for remote hosts
- `--sample` for local files
- `--in-scope-asset` for explicit additions

If no assets are provided but the hint contains a URL, the host is extracted and added automatically (lines 56-58).

## Deriving Network Constraints

The final `network_mode` is determined through a priority cascade (lines 60-79):
1. Explicit `--network-profile` if provided
2. Preset-derived profile based on authentication status
3. Default safe mode if assets exist but auth is pending

This ensures network isolation requirements are never accidentally relaxed.

## Creating the Work Directory Structure

Upon successful validation, the script creates the canonical directory layout at `<PROJECT_ROOT>/work/<CASE_NAME>/` (line 26):

```text
work/<timestamp>-<case-name>/
├─ evidence/          # Malware samples, memory dumps, disk images

├─ notes/             # Analysis notebooks and scratch files

├─ report/            # Final deliverables and findings

├─ scope.md           # Authorization contract and constraints

├─ timeline.md        # Audit trail starting with initialization

├─ workitems.md       # Task tracking table

└─ README.md          # Human-readable case status and next steps

```

## Generating the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) Contract

The [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file is the centerpiece of the `case-init` scripts' output. Built between lines 30-94 of [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh), it contains a YAML-style header with these sections:

- **meta** – case name, timestamp, primary skill, analyst identification
- **auth** – `status` (`granted`, `pending`, `denied`), `basis` (legal document reference), and `evidence_of_auth` (file paths or ticket IDs)
- **in_scope_assets** – enumerated list of URLs, file hashes, IP ranges
- **out_of_scope_assets** – explicitly excluded systems
- **network_profile** – operational network constraints
- **deliverables** – expected output formats and deadlines
- **constraints** – time windows, no-fly zones, special handling requirements
- **checklist** – verification that auth, assets, and network profile are satisfied
- **ready_for_act** – boolean flag computed by validating checklist completion

The `ready_for_act` flag (lines 8-15, 17-22) implements critical safety logic: it returns `false` if authentication status is not `granted` or if the network profile conflicts with the asset types present.

## Creating Ancillary Documentation Files

Three additional files support case workflow:

### [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)

Records the initialization event with ready status and links back to [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) (lines 96-108). This forms the audit trail required for incident response and legal proceedings.

### [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)

Provides a starter Markdown table for tracking analysis tasks (lines 110-128):

```markdown
| ID | Task | Skill | Status | Owner | Due |
|----|------|-------|--------|-------|-----|
| 1  | Static analysis of sample | reverse-apk | todo | | |

```

### [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md)

Conditionally generated based on `ready_for_act` (lines 31-43):
- If `false`: Instructions to complete [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) and obtain proper authorization
- If `true`: Confirmation that downstream skills can be invoked

## Example: Initializing an Offline Sample Case

```bash
bash skills/scripts/case-init.sh \
  --hint "apk reverse" \
  --case-name demo \
  --preset offline-sample \
  --sample ./app.apk

```

This creates `work/20231120-123456-apk-reverse-demo/` with:
- `auth.status: granted` (preset)
- `network_profile: offline`
- `assets` containing the APK file path
- `ready_for_act: true`

## Example: Initializing a CTF Public Challenge

```bash
bash skills/scripts/case-init.sh \
  --hint "ctf web" \
  --preset ctf-public \
  --target-url https://challenge.example

```

Resulting [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contains:
- `auth.status: granted` (CTF challenges are pre-authorized)
- `network_profile: authorized_target_only`
- Target URL in the assets list with host extraction

## Integration with Downstream Enforcement

The [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract is not merely documentation—it is machine-readable. According to the reverse-skill source code, [`case-guard.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-guard.sh) validates this file before any skill execution, checking that:
- The `ready_for_act` flag is `true`
- The current network mode matches the declared profile
- Assets referenced in skill commands appear in the in-scope list

Similarly, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) (invoked during initialization) reads [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) to determine the appropriate primary skill based on asset types and network constraints.

## Summary

- **Root resolution**: [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) calculates `PACKAGE_ROOT` and `PROJECT_ROOT` to anchor all file operations
- **Safe naming**: Timestamps and slugified hints produce valid, unique directory names
- **Preset system**: Common engagement types pre-configure auth status and network isolation
- **Asset collection**: URLs, samples, and explicit assets merge into a validated inventory
- **Directory layout**: `work/<case>/` with `evidence/`, `notes/`, `report/` subfolders
- **Contract generation**: [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) encodes authorization, constraints, and `ready_for_act` status
- **Safety gates**: Downstream scripts like [`case-guard.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-guard.sh) enforce scope compliance before skill execution

## Frequently Asked Questions

### What happens if I don't provide a `--case-name`?

The script generates one automatically by combining a timestamp with a slugified version of your `--hint` value, truncated to 80 characters (lines 99-103). For example, `--hint "analyze banking trojan"` might produce `20231120-143022-analyze-banking-tro`.

### Can I override the default project root directory?

Yes. Use `--project-root /path/to/cases` or `--package-root` to bind `PROJECT_ROOT` to the package installation directory. This is useful when running [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) from arbitrary locations while keeping case data organized (lines 47-58).

### Why does [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) use YAML-style frontmatter?

The format allows both human readability and automated parsing by downstream scripts. [`case-guard.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-guard.sh) and skill modules extract specific fields like `auth.status` and `network_profile` without requiring a full Markdown parser, while analysts can edit the file in any text editor.

### What prevents me from running skills against assets I haven't authorized?

The `ready_for_act` flag must be `true`, which requires `auth.status: granted` and compatible asset/network combinations. [`case-guard.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-guard.sh) validates this before skill execution. Additionally, the checklist in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) documents which authorization elements have been satisfied, creating an audit trail for compliance review.