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

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:

#Requires -Version 5.1

Linux/macOS Bash scripts use the .sh extension with a standard shebang. The skills/scripts/master-route.sh file specifies:

#!/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:

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

Users invoke the script with named parameters:

.\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 script iterates through flags like --hint and --out-dir, supporting both dashed and double-dashed variants:

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 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:

$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 launches a heredoc-embedded Python program:

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 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 output, the Windows script explicitly uses UTF-8-BOM encoding for Notepad compatibility:

$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:

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:

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

The Linux/macOS counterpart kali/scripts/refresh-tool-index.sh sources lib/tool-discovery.sh and iterates over a predefined TOOL_CATALOG array:

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 mirrors this workflow using shell-native constructs, including regex validation and mkdir -p, while calling master-route.sh to extract the primary skill for the case:

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 script embeds Python to parse 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 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 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 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 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.

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