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

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 listing all capabilities, update the platform matrix in 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).
• Manifest JSON: A declarative list of capabilities, download sources, and checksums (e.g., bootstrap-manifest.json).
• Refresh-index script: A utility that detects already-installed tools and updates the local index (e.g., 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 provides the baseline Bash implementation used for Debian-based distros.

# 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.

# -------------------------- 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 relative to its location:

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 to declare which tools the bootstrap script can install. While you can reuse the generic 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.

{
  "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
• Kali Linux: kali/scripts/bootstrap-manifest.json

Integrating Documentation and Discovery

Update the platform matrix so users can discover the new OS. Edit 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 that explains manual prerequisites, package-manager differences, and the command to list capabilities:

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

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

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 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 and adapting it to the target package manager (e.g., apk, dnf).
• Define a bootstrap-manifest.json that maps capabilities to their bootstrapKind (GitHub releases, native packages, etc.).
• Update docs/PLATFORMS.md and docs/platforms/<os>.md to document the new support.
• Implement a 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 (or .ps1), scripts/bootstrap-manifest.json, and optionally 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 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). 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.

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