# Windows vs Linux/macOS Scripts in reverse-skill: Architectural Differences Explained

> Discover the architectural differences between Windows and Linux/macOS scripts in reverse-skill. Learn how each platform handles parsing and .NET integration.

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

---

**The reverse-skill repository maintains functional parity between platforms through parallel PowerShell and Bash implementations that share a single JSON routing configuration, but Windows scripts leverage native .NET objects and `ConvertFrom-Json` while Linux/macOS scripts delegate complex parsing to embedded Python interpreters.**

The reverse-skill toolkit automates reverse engineering workflows across operating systems. While the Windows and Linux/macOS scripts perform identical logical operations—routing traffic, generating tool indexes, and initializing case directories—they achieve this through platform-native scripting paradigms that reflect each ecosystem's strengths. Understanding these architectural differences helps users debug issues and extend the toolkit effectively.

## Script Interpreters and Execution Requirements

The repository ships with distinct file extensions and interpreter declarations that enforce platform compatibility.

**Windows PowerShell** scripts use the `.ps1` extension and declare minimum version requirements. In `skills/scripts/master-route.ps1`, the header enforces PowerShell 5.1 or later:

```powershell
#Requires -Version 5.1

```

**Linux/macOS Bash** scripts use the `.sh` extension with a standard shebang. The [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) file specifies:

```bash
#!/usr/bin/env bash

```

Both implementations immediately enable strict error handling, though with platform-specific syntax. PowerShell sets `$ErrorActionPreference = 'Stop'` to terminate on exceptions, while Bash uses `set -euo pipefail` to achieve equivalent fail-fast semantics with undefined variable checks and pipeline error propagation.

## Argument Parsing: Typed Parameters vs Manual Loops

The divergence in parameter handling illustrates the fundamental difference between PowerShell's object-oriented approach and Bash's text-stream paradigm.

**PowerShell** utilizes typed parameter blocks. In `skills/scripts/master-route.ps1`, arguments are declared with type accelerators and default values:

```powershell
param(
    [string] $Hint,
    [string] $OutDir = "routes",
    [string] $ProjectRoot = "."
)

```

Users invoke the script with named parameters:

```powershell
.\skills\scripts\master-route.ps1 -Hint "apk reverse" -OutDir "C:\tmp\route"

```

**Bash** implements manual argument parsing through `while … case` loops. The [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) script iterates through flags like `--hint` and `--out-dir`, supporting both dashed and double-dashed variants:

```bash
while [[ $# -gt 0 ]]; do

  case $1 in
    -Hint|-hint|--hint)
      HINT="$2"
      shift 2
      ;;
    -OutDir|-out-dir|--out-dir)
      OUT_DIR="$2"
      shift 2
      ;;
  esac
done

```

Positional arguments are accepted only when the `$HINT` variable remains empty, providing flexibility while maintaining backward compatibility.

## JSON Configuration Loading: Native Objects vs Embedded Python

The most significant architectural difference lies in how each platform parses the shared [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file, which serves as the single source of truth for routing logic.

**Windows** leverages PowerShell's native `ConvertFrom-Json` cmdlet. The `master-route.ps1` script loads the configuration with:

```powershell
$config = Get-Content -Raw -Encoding UTF8 $configPath | ConvertFrom-Json

```

This produces native .NET objects that PowerShell pipelines can manipulate directly, using structures like `System.Collections.Generic.List[string]` and ordered hashtables to accumulate scores and priorities.

**Linux/macOS** delegates JSON parsing to an embedded Python block within the Bash script. After verifying Python 3 exists, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) launches a heredoc-embedded Python program:

```bash
python3 - "$config_path" << 'EOF'
import json, pathlib, sys
config = json.loads(pathlib.Path(sys.argv[1]).read_text(encoding="utf-8"))
scores = {}
priority = []

# Processing logic populates Python data structures

EOF

```

The Python block uses native dictionaries and lists, then returns data to Bash for post-processing. This design avoids dependencies on external JSON parsers like `jq` for core functionality, though `jq` appears in [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) for optional JSON output formatting.

## Path Handling and File Encoding

Platform-specific path separators and encoding requirements necessitate different file operation strategies.

**PowerShell** uses the `Join-Path` cmdlet and `[IO.Path]::DirectorySeparatorChar` to construct platform-agnostic paths. When writing the final [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) output, the Windows script explicitly uses UTF-8-BOM encoding for Notepad compatibility:

```powershell
$outPath = Join-Path $OutDir "route-scope.md"
[System.IO.File]::WriteAllText($outPath, $content, [System.Text.Encoding]::UTF8)

```

**Bash** constructs paths using variable expansion and `cd … && pwd` patterns to establish `SCRIPT_DIR`, `SKILLS_ROOT`, and `PACKAGE_ROOT`. For cross-platform path manipulation within the embedded Python blocks, it relies on `pathlib.Path`. Output writes use standard UTF-8 encoding:

```python
Path(output_path).write_text(content, encoding="utf-8")

```

## Tool Index Generation and Case Initialization

The dual implementation strategy extends to helper utilities and workflow initialization.

**Tool Discovery:** Windows scripts in `skills/scripts/refresh-tool-index.ps1` load PowerShell libraries from `lib/ToolDiscovery.ps1` and use the custom cmdlet `Get-ReverseToolReport` to assemble markdown and JSON tables:

```powershell
.\skills\scripts\refresh-tool-index.ps1 -OutputMarkdown "tools.md" -OutputJson "tools.json"

```

The Linux/macOS counterpart [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) sources [`lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/lib/tool-discovery.sh) and iterates over a predefined `TOOL_CATALOG` array:

```bash
bash kali/scripts/refresh-tool-index.sh tools.md tools.json

```

**Case Initialization:** The `case-init.ps1` script uses `CmdletBinding`, typed parameters, and PowerShell functions like `Test-ReverseIsWindows` and `Ensure-WingetPackage` to handle preset logic and privilege checks. The Bash version [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) mirrors this workflow using shell-native constructs, including regex validation and `mkdir -p`, while calling [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) to extract the primary skill for the case:

```bash
bash skills/scripts/case-init.sh --hint "android hooking" --case-name android-demo

```

## Summary

The reverse-skill repository achieves cross-platform compatibility through idiomatic implementations rather than abstraction layers:

- **File Extensions:** `.ps1` files require PowerShell 5.1+; `.sh` files use standard Bash shebangs
- **Error Handling:** PowerShell uses `$ErrorActionPreference = 'Stop'`; Bash uses `set -euo pipefail`
- **JSON Processing:** PowerShell leverages native `ConvertFrom-Json`; Bash delegates to embedded Python with `json.loads`
- **Data Structures:** PowerShell uses .NET `List` and hashtable objects; Bash/Python uses native dictionaries and arrays
- **Path Operations:** PowerShell uses `Join-Path` and .NET path classes; Bash uses `pathlib.Path` within Python blocks
- **Output Encoding:** Windows writes UTF-8-BOM for Notepad compatibility; Linux/macOS uses standard UTF-8

## Frequently Asked Questions

### Why does the Linux version use Python instead of jq for JSON parsing?

The [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) script embeds Python to parse [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) primarily to avoid external dependencies beyond the Python 3 interpreter, which is ubiquitous on modern Linux and macOS systems. While [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) optionally uses `jq` for its specific JSON output needs, the core routing logic relies on Python's standard library to ensure consistent behavior across distributions without requiring additional package installations.

### Can I run the PowerShell scripts on Linux or the Bash scripts on Windows?

The PowerShell scripts require Windows PowerShell 5.1 or later and utilize Windows-specific paths and encoding (UTF-8-BOM). While PowerShell Core (`pwsh`) exists on Linux, the scripts expect Windows-specific helper modules in `lib/WorkRoot.ps1` and `lib/ToolDiscovery.ps1`. Conversely, the Bash scripts require a POSIX-compatible shell and specifically look for Python 3 in Unix-like paths. Users should employ the script set designed for their target platform.

### How do the scripts handle the shared routing configuration differently?

Both implementations read from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as the single source of truth. However, `master-route.ps1` converts the JSON directly into PowerShell objects using `ConvertFrom-Json`, allowing pipeline-based manipulation of scores and priorities. The [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) script passes the file path to an embedded Python block that processes the JSON using standard Python dictionaries, then returns processed data to Bash for final file generation.

### What are the exact parameter differences between case-init.ps1 and case-init.sh?

The `case-init.ps1` script accepts typed parameters like `-Hint` and `-CaseName` through a formal `param()` block, supporting tab completion and validation attributes. The [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) script accepts equivalent long-form flags `--hint` and `--case-name` through a manual parsing loop, also supporting short variants like `-Hint` for compatibility. Both scripts subsequently call their respective platform's master routing script to determine the primary skill for the case directory structure.