What Happens When a Tool Fails to Install or Bootstrap Multiple Times in Reverse-Skill

When a tool fails to install during the reverse-skill bootstrap process, the script logs the error via log_err, marks the capability as failed, and exits with code 1. Repeated executions retry the same installation steps without automatic back-off or circuit-breaking, requiring users to manually resolve underlying issues before the bootstrap can succeed.

The reverse-skill repository uses the Kali-specific bootstrap script bootstrap-reverse.sh to automate the installation of reverse engineering capabilities. Understanding how this script handles failures is critical for maintaining a reliable tooling environment, as multiple consecutive failures will persist until the root cause—such as missing dependencies or network issues—is corrected.

How the Bootstrap Script Handles Installation Failures

The Core Installation Loop

The script processes capabilities through the ensure_capability function defined in kali/scripts/bootstrap-reverse.sh (source). This function first verifies whether the command already exists using command -v. If the tool is absent, it attempts installation via helper functions such as install_apt_package, install_pip_package, or install_git_commit.

Error Detection and Logging

When any installation helper returns a non-zero exit status, the script immediately:

• Prints an error message through log_err (prefixed with a red "ERR" label).
• Returns status 1 from ensure_capability to the main loop.

The calling code in the main loop captures this failure:

if ensure_capability "$cap"; then
    RESULTS+=("{\"name\":\"$cap\",\"status\":\"ready\"}")
else
    RESULTS+=("{\"name\":\"$cap\",\"status\":\"failed\"}")
    FAILED=true
fi

(source)

Final Exit Code Determination

At script termination, the bootstrap logic evaluates three distinct exit conditions:

• 0 – All capabilities installed successfully.
• 1 – At least one capability failed (FAILED=true).
• 2 – A capability requires manual installation (MANUAL_REQUIRED=true).

if [[ "$FAILED" == "true" ]]; then
    final_exit_code=1
elif [[ "$MANUAL_REQUIRED" == "true" ]]; then
    final_exit_code=2
fi
exit "$final_exit_code"

(source)

Re-running the Script After Multiple Failures

No Built-in Retry Logic

The bootstrap-reverse.sh script does not implement automatic retries or exponential back-off. Each invocation independently executes the same installation sequence, meaning that if a tool fails due to transient network errors or repository unavailability, consecutive runs will produce identical failures until the external condition resolves.

Handling Partial or Broken Installations

If a previous installation attempt left a tool in a partially installed or broken state, the script does not perform cleanup or rollback. Instead, it re-attempts the full installation routine, which may overwrite existing files or fail if the environment is corrupted. For Git-based installations specifically, install_git_commit will abort with an error if it detects an existing checkout pointing to a different commit or containing local modifications (source).

When Manual Intervention Is Required

Certain proprietary tools (such as JEB Pro or BurpSuite-MCP) cannot be installed automatically. When ensure_capability detects these entries, it sets MANUAL_REQUIRED=true and records the status as manual-required. In this scenario, the script exits with code 2, signaling that automated bootstrap cannot complete the installation and human intervention is necessary.

Practical Examples of Bootstrap Failure Handling

Successful Installation Run

$ bash bootstrap-reverse.sh jadx apktool frida --skip-refresh
[INFO] apt install jadx ...
[OK] jadx installed
[INFO] apt install apktool ...
[OK] apktool installed
[INFO] pip3 install frida-tools==14.10.4 ...
[OK] frida installed
$ echo $?
0

Tool Installation Failure

$ bash bootstrap-reverse.sh nmap
[ERR] apt install nmap failed
✗ nmap (failed)
$ echo $?
1

Manual Installation Requirement

$ bash bootstrap-reverse.sh jeb-pro
[WARN] MANUAL_INSTALL_REQUIRED: jeb-pro
! jeb-pro (manual install required)
$ echo $?
2

Recovery After Fixing the Issue

$ sudo apt-get update && sudo apt-get install -f
$ bash bootstrap-reverse.sh nmap
[INFO] apt install nmap ...
[OK] nmap installed
✓ nmap
$ echo $?
0

Summary

• Immediate failure detection: The ensure_capability function checks exit statuses and sets FAILED=true upon any installation error, ensuring the script exits with code 1.
• No automatic retries: The script repeats identical installation steps on each invocation; it does not back off or skip previously failed tools.
• Git repository protection: Existing Git checkouts with divergent commits or local changes prevent re-installation to avoid data loss.
• Manual install gateway: Tools requiring manual setup trigger exit code 2 via the MANUAL_REQUIRED flag, distinguishing them from automated installation failures.
• Recovery requirement: Users must inspect error output, resolve underlying system issues (dependencies, permissions, network), and re-run bootstrap-reverse.sh to achieve a clean exit code 0.

Frequently Asked Questions

What happens if a tool fails to install multiple times in reverse-skill?

Each failed attempt returns exit code 1 and logs the specific error via log_err. The script does not implement retry logic, so consecutive runs will continue failing until you resolve the underlying cause, such as fixing package manager issues or restoring network connectivity.

How do I know which tool caused the bootstrap to fail?

The script outputs structured JSON-like results showing each capability name and its status (ready, failed, or manual-required). Additionally, the log_err function prints red "ERR" prefixed messages indicating the specific tool and installation method that failed.

Does the script automatically retry failed installations?

No. The bootstrap-reverse.sh script executes the same installation sequence on every run without exponential back-off or circuit-breaking logic. It relies on the user to manually correct the environment before re-execution.

What is the difference between exit code 1 and exit code 2 in bootstrap-reverse.sh?

Exit code 1 indicates that one or more tools failed to install automatically (FAILED=true), while exit code 2 signifies that at least one capability requires manual installation (MANUAL_REQUIRED=true), such as commercial tools that cannot be downloaded via automated package managers.

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