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

> Discover how reverse-skill's bootstrap script handles missing tools by automatically installing them or marking them as manually required, providing a detailed status report.

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

---

**The [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

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

```

Platform detection occurs at `line 34-39`:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# 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`):

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

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) (`line 86-88`) to update the local manifest. This ensures the tool index reflects any newly installed binaries.

```bash

# Skip refresh example

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

```

## Practical Usage Examples

### Installing Multiple Tools Automatically

```bash

# 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
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) | Main bootstrap logic with detection, installation, and reporting |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Manifest regeneration post-installation |
| [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) | Tool metadata (repos, asset regexes, SHA-256 hashes) |
| [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.