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

> Quickly set up the zhaoxuya520/reverse-skill development environment on Ubuntu, macOS, or Kali Linux. Clone the repo, install dependencies, and run the bootstrap script to get started.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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)](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)](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.

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

```

Verify the directory structure:

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

```bash
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

```bash
/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
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)](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
bash skills/scripts/bootstrap-reverse.sh --list

```

### Install Specific Tools

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

```

### Refresh the Tool Index After Manual Installs

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

```

Or use the legacy entry point:

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

```

Both commands produce two artifacts:

- [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) – human-readable summary of detected tools
- [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) – machine-readable data for the router

## Step 4: Validate Your Environment

Run verification commands to confirm tool detection:

```bash
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
bash skills/scripts/case-init.ps1 --case MyFirstSample
cd work/MyFirstSample

```

The scaffold includes:

- [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) – engagement boundaries and targets
- [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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)](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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) → [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) → [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) → [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) |

The routing layer reads [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) lacks a tool entry, the routing layer in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) by scanning PATH and standard installation directories. The router reads these files at runtime to determine available capabilities.