How the `bootstrap-reverse.sh` Script Handles Missing Tools in reverse-skill

The bootstrap-reverse.sh script treats missing tools as capabilities to be satisfied through automatic installation first, then falls back to a "manual-required" status when automation is impossible, while generating a detailed JSON status report for the entire process.

The bootstrap-reverse.sh script in the zhaoxuya520/reverse-skill repository is a generic Linux/macOS bootstrapper designed to prepare a reverse-engineering environment with minimal friction. Understanding how it handles missing tools is essential for both automated deployments and interactive troubleshooting. This article breaks down its six-step strategy, key implementation patterns, and practical usage examples.

Platform Detection and Command Availability Checking

The script begins by determining the host platform and checking whether required commands already exist.

At line 70-71, has_cmd provides a cross-platform command check:

has_cmd() {
  command -v "$1" >/dev/null 2>&1
}

Platform detection occurs at line 34-39:

UNAME_S="$(uname -s 2>/dev/null || echo unknown)"
case "$UNAME_S" in
  Darwin) PLATFORM="macos" ;;
  Linux)  PLATFORM="linux" ;;
  *)      PLATFORM="unknown" ;;
esac

This dual detection—platform plus command availability—drives all subsequent installation decisions.

Runtime Prerequisites: Ensuring Foundations First

Before any tool can function, the script guarantees that required runtimes are present. This prevents cascading failures where a tool downloads but cannot execute.

Runtime	Function	Location
Python 3	ensure_python_interpreter	line 63-70
Node.js	ensure_node_runtime	line 74-81
Java	ensure_java_runtime	line 83-90

These ensure_* functions follow a consistent pattern: check with has_cmd, install if missing, then verify success.

Automatic Installation Methods for Missing Tools

When a tool is absent, bootstrap-reverse.sh selects from multiple installation strategies based on the platform and tool type.

Package Manager Installers

• install_apt (line 20-25): Debian/Ubuntu package installation
• install_brew (line 27-35): macOS Homebrew integration

GitHub Release Downloads

The install_github_release function (line 100-121) handles tools distributed as release assets:

# Example: jadx installation (lines 68-79)

if has_cmd jadx; then log_ok "jadx ready"; return 0; fi
ensure_java_runtime
repo=$(manifest_field jadx repo) && re=$(manifest_field jadx assetRegex) && ...
case "$PLATFORM" in
  macos) install_brew jadx || install_github_release "$repo" "$re" "$TOOLS_ROOT/jadx" "$tag" "$sha" ;;
  linux) install_github_release "$repo" "$re" "$TOOLS_ROOT/jadx" "$tag" "$sha" ;;
esac

Language-Specific Package Managers

• pipx for Python tools like Frida (ensure_frida_tools, line 109-115)
• npm/pnpm for Node-based utilities

Each method includes SHA-256 verification after download (install_github_release, line 100-121).

Manual-Required Fallback for Unscriptable Tools

When automatic installation is impossible—due to commercial licensing, platform restrictions, or unavailable binaries—the script calls manual_required (line 44-49):

manual_required() {
  local cap="$1"
  local msg="${2:-Manual installation required for $cap}"
  log_warn "MANUAL_INSTALL_REQUIRED: $cap — $msg"
  MANUAL_REQUIRED=true
  status_json_line "$cap" "manual-required" "$msg"
}

This pattern appears in several ensure_* functions:

• ensure_jeb_pro (line 56-63): Commercial software requiring license purchase
• ensure_r2 (line 226-228): Radare2 when apt installation fails
• ensure_adb (line 236-237): Android SDK components requiring manual SDK setup
• ensure_proxycat (line 88-92): Tools with complex build dependencies

# JEB Pro example (lines 56-63)

if has_cmd jeb_wincon || has_cmd jeb; then
  log_ok "JEB Pro ready"
else
  manual_required jeb-pro "JEB Pro is commercial software. Purchase and install from https://www.pnfsoftware.com/"
fi

JSON Status Reporting and Result Aggregation

Every capability processed generates a structured status entry through status_json_line (line 86-94):

Status	Meaning	Typical Cause
ready	Tool available and functional	Pre-installed or successfully auto-installed
manual-required	User intervention needed	Commercial software, unsupported platform
registration-required	Account/license registration needed	API keys, SaaS tools
failed	Installation attempt failed	Network error, bad checksum, missing dependencies

The main loop (line 71-84) collects these into a temporary file, later aggregated into pretty-printed JSON for human and machine consumption.

Tool Index Refresh and Skip Option

Unless --skip-refresh is supplied, the script invokes refresh-tool-index.sh (line 86-88) to update the local manifest. This ensures the tool index reflects any newly installed binaries.

# Skip refresh example

bash skills/scripts/bootstrap-reverse.sh --skip-refresh jadx

Practical Usage Examples

Installing Multiple Tools Automatically

# Install jadx, apktool and frida on Linux/macOS

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

Result: Each tool is checked; missing ones are auto-installed via optimal method; final JSON summary shows all as "status":"ready".

Handling a Manual-Required Tool

bash skills/scripts/bootstrap-reverse.sh jeb-pro

Result:

[WARN] MANUAL_INSTALL_REQUIRED: jeb-pro — JEB Pro is commercial...

Final JSON includes: {"capability":"jeb-pro","status":"manual-required","message":"..."}

Key Source Files

File	Purpose
skills/scripts/bootstrap-reverse.sh	Main bootstrap logic with detection, installation, and reporting
skills/scripts/refresh-tool-index.sh	Manifest regeneration post-installation
skills/scripts/bootstrap-manifest.json	Tool metadata (repos, asset regexes, SHA-256 hashes)
kali/scripts/bootstrap-reverse.sh	Kali Linux-specific variant with reduced capabilities

Summary

• Detection first: has_cmd checks existing availability before any action
• Runtime prerequisites: Python, Node, Java are ensured before dependent tools
• Multi-channel installation: apt, brew, GitHub releases, pipx, and npm cover diverse distribution methods
• Graceful degradation: manual_required preserves workflow continuity when automation fails
• Structured reporting: JSON status lines enable programmatic consumption and audit trails
• Idempotent design: Repeated runs converge to the same state without redundant work

Frequently Asked Questions

What happens if bootstrap-reverse.sh cannot install a tool automatically?

The script calls manual_required, logs a descriptive warning, sets MANUAL_REQUIRED=true, records "status":"manual-required" in the JSON output, and continues with remaining capabilities. The overall script exit remains successful (0) so that partial automation is still valuable.

How does the script choose between apt and brew for installation?

Platform detection (uname -s) determines the package manager: apt for Linux, brew for macOS. Some tools attempt brew first on macOS with GitHub release as fallback, while Linux may skip directly to GitHub releases if no apt package exists.

Can I run the bootstrap script without updating the tool index?

Yes. Pass the --skip-refresh flag to prevent execution of refresh-tool-index.sh. This is useful for offline environments or when the index is already current.

Where does the script install tools that come from GitHub releases?

The install_github_release function extracts archives to $TOOLS_ROOT/<toolname> (defaulting to a tools/ subdirectory of the repository) and adds the binary location to $PATH for the current session.

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