How to Set Up the zhaoxuya520/reverse-skill Development Environment on Ubuntu, macOS, and Kali Linux

Clone the repository, install Java 17, Node 22+, and Python 3, then run bash skills/scripts/bootstrap-reverse.sh to detect and install the reverse-engineering tools needed for the modular skill router.

The reverse-skill repository is a modular skill router that orchestrates reverse-engineering, pentesting, and CTF workflows through a three-layer architecture. Setting up the development environment requires cloning the codebase with its CTF-Sandbox submodule, installing prerequisite runtimes, and running platform-specific bootstrap scripts that populate the tool index and scaffold case directories.

Prerequisites and System Requirements

The reverse-skill system depends on three core runtimes and an optional container engine:

• Java 17 (OpenJDK) – for Ghidra, jadx, and other JVM-based tools
• Node.js 22+ – for the routing layer and MCP server integration
• Python 3 with pipx – for script automation and tool installation
• Docker (optional) – for sandboxed analysis environments

Platform-specific package lists are maintained in [docs/platforms/linux.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) for Ubuntu/Debian derivatives and [kali/README-kali.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) for Kali Linux.

Step 1: Clone the Repository and Initialize Submodules

The repository contains a thin wrapper at the root; all heavy logic resides in skills/ and CTF-Sandbox-Orchestrator/. The CTF-Sandbox submodule is a large GPL-v3 component that must be initialized separately.

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
git submodule update --init --recursive

Verify the directory structure:

ls -la skills/ CTF-Sandbox-Orchestrator/

Step 2: Install System Dependencies

Ubuntu and Debian-Based Systems

Install core runtimes and common security tools from the standard repositories:

sudo apt update
sudo apt install -y git curl wget ca-certificates unzip tar jq \
    python3 python3-venv python3-pip pipx \
    openjdk-17-jdk nodejs npm \
    graphviz plantuml nmap sqlmap ffuf hashcat binwalk

python3 -m pipx ensurepath

Additional tools like radare2, jadx, and Ghidra require manual installation or can be handled by the bootstrap script in the next step.

macOS with Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git curl wget openjdk@17 node python3 jq
pipx ensurepath

The bootstrap scripts detect macOS automatically and adjust installation methods accordingly.

Kali Linux

Kali ships most offensive tools pre-installed. Use the dedicated refresh script:

bash kali/scripts/refresh-tool-index.sh

Refer to [kali/README-kali.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) for the complete pre-installed utility list.

Step 3: Bootstrap the Skill Router

The bootstrap-reverse.sh script in skills/scripts/ performs three critical functions:

1. Detects installed tools across the system PATH
2. Installs missing open-source tools via GitHub releases, pipx, go install, or package managers
3. Generates the tool-index files consumed by the routing layer

Preview Available Capabilities

bash skills/scripts/bootstrap-reverse.sh --list

Install Specific Tools

bash skills/scripts/bootstrap-reverse.sh jadx apktool frida

Refresh the Tool Index After Manual Installs

bash skills/scripts/bootstrap-reverse.sh

Or use the legacy entry point:

bash skills/scripts/refresh-tool-index.sh

Both commands produce two artifacts:

• skills/tool-index.md – human-readable summary of detected tools
• skills/tool-index.json – machine-readable data for the router

Step 4: Validate Your Environment

Run verification commands to confirm tool detection:

java -version
python3 --version
node -v
npm -v

# Optional tools (may return non-zero if not installed)

jadx --version || true
apktool --version || true
frida --version || true
r2 -v || true
ghidraRun 2>/dev/null || true

# Verify index generation

cat skills/tool-index.md

All required commands should print version strings. Optional tools may fail silently without breaking the router.

Step 5: Create Your First Analysis Case

The case-init.ps1 script in skills/scripts/ generates a sandboxed work/ directory structure for each investigation:

bash skills/scripts/case-init.ps1 --case MyFirstSample
cd work/MyFirstSample

The scaffold includes:

• scope.md – engagement boundaries and targets
• timeline.md – chronological activity log
• evidence/ – collected artifacts
• artefacts/ – generated outputs

This case directory is automatically wired to the router via [RULES.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), enabling AI-driven dispatch to the appropriate skill module.

Complete Setup Commands

Copy and execute this consolidated sequence:

# Clone and initialize

git clone https://github.com/zhaoxuya520/reverse-skill.git && cd reverse-skill
git submodule update --init --recursive

# Install Ubuntu prerequisites (adjust for your platform)

sudo apt update && sudo apt install -y \
  git curl wget unzip tar jq python3 python3-venv python3-pip pipx \
  openjdk-17-jdk nodejs npm graphviz plantuml nmap sqlmap ffuf hashcat binwalk
python3 -m pipx ensurepath

# Bootstrap capabilities

bash skills/scripts/bootstrap-reverse.sh jadx apktool frida
bash skills/scripts/refresh-tool-index.sh

# Verify and initialize case

cat skills/tool-index.md
bash skills/scripts/case-init.ps1 --case Sample01
cd work/Sample01

Architecture Overview

Understanding the three-layer structure helps troubleshoot setup issues:

Layer	Purpose	Key Files
Routing Core	Determines which skill handles each request	RULES.md → skills/MASTER-ROUTING.md → skills/routing.md
Case Management	Sandboxed directories per investigation	skills/scripts/case-init.ps1
Tool-Index & Bootstrap	Detects and registers available capabilities	skills/scripts/refresh-tool-index.sh → skills/tool-index.md

The routing layer reads skills/tool-index.json to determine which MCP servers can be launched for a given request.

Summary

• Clone the repository with git submodule update --init --recursive to fetch the CTF-Sandbox component
• Install Java 17, Node 22+, Python 3, and pipx using your platform's package manager
• Bootstrap with bash skills/scripts/bootstrap-reverse.sh to detect tools and populate indices
• Validate by checking version outputs and reviewing skills/tool-index.md
• Initialize cases using bash skills/scripts/case-init.ps1 --case <name> for sandboxed investigations

Frequently Asked Questions

Do I need Docker to run reverse-skill?

No. Docker is optional and only required for specific sandboxed analysis environments. The core routing and case management functions operate entirely with Java, Node, and Python. Container support can be added post-installation without rebuilding the environment.

What happens if a tool is missing after bootstrap?

The router gracefully degrades. When skills/tool-index.json lacks a tool entry, the routing layer in skills/routing.md skips skills requiring that capability and may fall back to alternative approaches or prompt for manual installation. Re-run bash skills/scripts/bootstrap-reverse.sh <toolname> to add missing components.

Why does case-init use a PowerShell filename on Linux?

The case-init.ps1 script is cross-platform PowerShell Core (pwsh). On Linux and macOS, it executes via the PowerShell interpreter if installed, or falls back to bash compatibility mode. The .ps1 extension is preserved for Windows-native environments in heterogeneous teams.

How do I update the tool index after installing tools manually?

Execute bash skills/scripts/refresh-tool-index.sh or bash skills/scripts/bootstrap-reverse.sh with no arguments. Both regenerate skills/tool-index.md and skills/tool-index.json by scanning PATH and standard installation directories. The router reads these files at runtime to determine available capabilities.

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