# How to Add Platform-Specific Bootstrap Scripts for a New OS Distribution

> Learn to add platform-specific bootstrap scripts for new OS distributions in the reverse-skill repository. Customize scripts, define capabilities, update platforms, and add tests for seamless integration.

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

---

**To add platform-specific bootstrap scripts for a new OS distribution in the reverse-skill repository, create a customized shell script under `alpine/scripts/` (or your OS directory), define a [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) listing all capabilities, update the platform matrix in [`docs/PLATFORMS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/PLATFORMS.md), and add validation tests under `skills/scripts/`.**

The reverse-skill repository automates security tool installation through modular bootstrap scripts that detect missing dependencies and install them on demand. When extending support to a new OS distribution—such as Alpine Linux, Fedora, or a custom corporate image—you must implement a platform-specific bootstrap script that interfaces with the native package manager while conforming to the repository's established three-file pattern. This guide explains how to add platform-specific bootstrap scripts for a new OS distribution using the existing Windows, generic Linux, and Kali Linux implementations as reference templates.

## Understanding the Bootstrap Architecture

Each supported platform in reverse-skill follows a consistent three-file architecture located in a dedicated directory (e.g., `skills/scripts/` for generic platforms, `kali/scripts/` for Kali Linux).

The architecture consists of:

- **Bootstrap script**: The entry point that parses arguments and installs tools (e.g., [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh)).
- **Manifest JSON**: A declarative list of capabilities, download sources, and checksums (e.g., [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json)).
- **Refresh-index script**: A utility that detects already-installed tools and updates the local index (e.g., [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)).

For Windows, the repository uses PowerShell equivalents: `bootstrap-reverse.ps1` and `refresh-tool-index.ps1`.

## Creating the Platform-Specific Bootstrap Script

Start by copying the generic Linux bootstrap script as a template. In the reverse-skill source code, [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) provides the baseline Bash implementation used for Debian-based distros.

```bash

# Create the directory structure for Alpine Linux

mkdir -p alpine/scripts
cp skills/scripts/bootstrap-reverse.sh alpine/scripts/bootstrap-reverse.sh
chmod +x alpine/scripts/bootstrap-reverse.sh

```

Adapt the script to the new platform's package manager. Replace `apt` calls with the native manager—such as `apk` for Alpine, `dnf` for Fedora, or `zypper` for openSUSE—and adjust the `--list` output to reflect supported capabilities.

```bash

# -------------------------- helper for Alpine -------------------------

install_apk_package() {
  local pkg="$1"
  log_info "apk add $pkg ..."
  sudo apk add --no-progress "$pkg"
}

```

The script must handle three standard flags:

- `--list` (or `-l`): Outputs space-separated capability names and exits.
- `--start-services`: Indicates background services should be started after installation.
- `--skip-refresh`: Skips the tool index refresh step.

The script sources shared utilities from [`lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/lib/tool-discovery.sh) relative to its location:

```bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/lib/tool-discovery.sh"

```

## Configuring the Bootstrap Manifest

Create [`alpine/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/alpine/scripts/bootstrap-manifest.json) to declare which tools the bootstrap script can install. While you can reuse the generic [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) if the same GitHub releases apply, a dedicated manifest allows OS-specific package entries (e.g., `apk-package` bootstrap kind).

The manifest contains two top-level keys:

- `bootstrapDependencies`: Maps capability names to their source definitions.
- `capabilities`: Lists all installable capabilities with their `bootstrapKind`.

```json
{
  "bootstrapDependencies": {
    "jadx": {
      "bootstrapKind": "github-release-zip",
      "repo": "skylot/jadx",
      "assetRegex": "^jadx-.*\\.zip$",
      "installDir": "$HOME/tools/jadx",
      "releaseTag": "latest",
      "assetSha256": "sha256:<checksum>"
    }
  },
  "capabilities": [
    {
      "name": "jadx",
      "bootstrapKind": "github-release-zip"
    },
    {
      "name": "apktool",
      "bootstrapKind": "apk-package"
    }
  ]
}

```

Reference the existing manifests for syntax details:

- Generic platforms: [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json)
- Kali Linux: [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-manifest.json)

## Integrating Documentation and Discovery

Update the platform matrix so users can discover the new OS. Edit [`docs/PLATFORMS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/PLATFORMS.md) to add a row linking to the new documentation and script path.

Create a platform-specific guide at [`docs/platforms/alpine.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/alpine.md) that explains manual prerequisites, package-manager differences, and the command to list capabilities:

```markdown

```bash
bash alpine/scripts/bootstrap-reverse.sh --list

```

```

Finally, add the path to the top-level [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) (or [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md)) under the "Supported Platforms" section to ensure visibility.

## Adding the Refresh-Index Utility

Duplicate an existing refresh script to handle tool detection for the new OS. If the new distribution requires custom detection logic—such as using `apk info` instead of `dpkg -l`—copy [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) to [`alpine/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/alpine/scripts/refresh-tool-index.sh) and modify the detection routines.

Users invoke this script to update the local tool index before running the bootstrap:

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

```

## Testing and Validation

Platform support requires automated validation to maintain CI integrity.

### Write Platform-Specific Tests

Create a test file under `skills/scripts/` following the naming convention `test-bootstrap-<platform>.sh` (or `.ps1` for Windows). This script should invoke the bootstrap with a known capability and assert on exit codes and output.

```bash

# Example: skills/scripts/test-bootstrap-alpine.sh

bash alpine/scripts/bootstrap-reverse.sh --list | grep -q "jadx" || exit 1
bash alpine/scripts/bootstrap-reverse.sh apktool

```

### Run CI Checks

Execute the supply-chain validation and list command to ensure the implementation is sound:

```bash
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-bootstrap-supply-chain.ps1
bash alpine/scripts/bootstrap-reverse.sh --list

```

The CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml) automatically triggers on pull requests. Ensure that `scripts/test-routing.ps1` and `scripts/smoke.ps1` remain aware of the new platform by including it in their test matrices if applicable.

## Summary

- **Create** a platform-specific bootstrap script by copying [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) and adapting it to the target package manager (e.g., `apk`, `dnf`).
- **Define** a [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) that maps capabilities to their `bootstrapKind` (GitHub releases, native packages, etc.).
- **Update** [`docs/PLATFORMS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/PLATFORMS.md) and `docs/platforms/<os>.md` to document the new support.
- **Implement** a [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) variant if the OS requires custom tool detection logic.
- **Add** tests under `skills/scripts/` and verify them with `test-bootstrap-supply-chain.ps1` before submitting a PR.

## Frequently Asked Questions

### What file structure is required for a new OS distribution?

You must create a directory structure containing three core files: [`scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-reverse.sh) (or `.ps1`), [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json), and optionally [`scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/refresh-tool-index.sh). Place these under a top-level directory named after the OS (e.g., `alpine/` or `fedora/`) to keep the repository organized alongside `skills/` and `kali/`.

### How do I adapt the bootstrap script for a different package manager?

Copy the generic [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) as a template, then replace the `apt` commands with the target package manager (e.g., `apk add`, `dnf install`, or `zypper install`). Add helper functions like `install_apk_package()` to encapsulate OS-specific logic, and ensure the script still handles the `--list`, `--start-services`, and `--skip-refresh` flags as implemented in the source.

### What is the purpose of the bootstrap-manifest.json file?

The manifest acts as a declarative registry of installable capabilities. It separates tool metadata—such as source repositories, checksums, and install directories—from the procedural logic in the bootstrap script, allowing the script to query JSON fields via `bootstrapKind` to determine how to fetch and install each tool.

### How does the CI pipeline validate new platform support?

The pipeline runs `skills/scripts/test-bootstrap-supply-chain.ps1` to verify checksums and sources, along with any platform-specific tests (e.g., [`test-bootstrap-alpine.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-bootstrap-alpine.sh)). All tests must pass, and the new bootstrap script must successfully execute `--list` without errors, as coordinated by the workflows defined in [`.github/workflows/ci.yml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml).