{"id":50792905,"url":"https://github.com/cryptojones/hydra","last_synced_at":"2026-06-12T12:02:27.684Z","repository":{"id":358162966,"uuid":"1239641961","full_name":"CryptoJones/Hydra","owner":"CryptoJones","description":"Multi-OS bootable USB builder (Ventoy + Ubuntu LTS + Kali Live) with QEMU boot-test","archived":false,"fork":false,"pushed_at":"2026-06-06T04:50:16.000Z","size":100,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T06:18:07.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CryptoJones.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T09:43:17.000Z","updated_at":"2026-06-06T04:49:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CryptoJones/Hydra","commit_stats":null,"previous_names":["cryptojones/hydra"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CryptoJones/Hydra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FHydra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FHydra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FHydra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FHydra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CryptoJones","download_url":"https://codeload.github.com/CryptoJones/Hydra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FHydra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T12:01:47.704Z","updated_at":"2026-06-12T12:02:27.531Z","avatar_url":"https://github.com/CryptoJones.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hydra — Multi-OS Bootable USB Builder + VM Tester\n\n[![Tests](https://github.com/CryptoJones/Hydra/actions/workflows/test.yml/badge.svg)](https://github.com/CryptoJones/Hydra/actions/workflows/test.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nBuild a [Ventoy](https://github.com/ventoy/Ventoy)-based multi-boot USB stick\nthat carries Ubuntu LTS + Kali Linux Live (and any other ISOs you drop on\nit), then sanity-check the stick by booting a local QEMU VM directly from\nthe physical USB — no actual reboot required to verify it works.\n\nNamed for the mythological creature: one stick, many heads.\n\n---\n\n## What it does\n\n1. **Downloads** Ventoy, the latest Ubuntu LTS desktop ISO, and Kali Linux\n   Live (via torrent — Kali's Live image is torrent-only on cdimage.kali.org).\n2. **Installs Ventoy** to your USB stick (with safety checks so it refuses to\n   touch internal disks or non-removable devices).\n3. **Copies the ISOs** to the Ventoy data partition.\n4. **Spins up a QEMU VM** that boots from the physical USB so you can verify\n   the stick actually boots before staking a real reboot on it.\n\n---\n\n## Quick start\n\n```bash\nchmod +x hydra.sh\n\n# See what's installed, what's missing, and which USB candidates are visible\n./hydra.sh check\n\n# One-time tool install (apt / dnf / pacman; needs sudo)\n# Installs: aria2, qemu-system-x86, qemu-utils, ovmf, parted, gdisk, wget, curl, tar\n./hydra.sh deps\n\n# Download Ventoy + Ubuntu + Kali (idempotent — re-runs skip already-fetched files)\n./hydra.sh download\n\n# Install Ventoy onto your USB (DESTRUCTIVE — pass the exact device path).\n# The script refuses to write to non-removable or rootfs-backing devices.\n./hydra.sh usb /dev/sdX\n\n# USB-attached SSD/NVMe enclosure? The kernel reports RM=0 even though the\n# enclosure is hot-pluggable. Pass --allow-non-removable to bypass that\n# check. (The rootfs guard and the type-the-device confirmation still fire.)\n./hydra.sh usb /dev/sdX --allow-non-removable\n\n# Want a GPT partition table instead of Ventoy's MBR default? (Recommended\n# for \u003e2 TB drives and modern UEFI-only systems.)\n./hydra.sh usb /dev/sdX --gpt\n\n# Copy the ISOs to the Ventoy data partition.\n# Set HYDRA_WINDOWS_ISO to also drop a Windows installer ISO alongside\n# Ubuntu + Kali (Microsoft doesn't offer a stable direct URL, so BYO).\n./hydra.sh copy /dev/sdX\nHYDRA_WINDOWS_ISO=~/Downloads/Win11_25H2_x64.iso ./hydra.sh copy /dev/sdX\n\n# Optional: add LUKS-encrypted persistence file(s). Default = Kali fills\n# the remaining free space. Pass --kali / --ubuntu to override per-OS.\n# Prompts for each passphrase (no recovery if lost).\n./hydra.sh persistence /dev/sdX                          # Kali, fill remaining\n./hydra.sh persistence /dev/sdX --kali 8G                # Kali fixed 8 GiB\n./hydra.sh persistence /dev/sdX --kali 8G --ubuntu max   # Kali fixed, Ubuntu absorbs rest\n./hydra.sh persistence /dev/sdX --kali 4G --ubuntu 4G    # Both fixed\n\n# Verify the stick boots — opens a QEMU window with your USB as the boot drive\n./hydra.sh test /dev/sdX\n```\n\nOr, all in one shot:\n\n```bash\n./hydra.sh all /dev/sdX                       # full flow: deps -\u003e download -\u003e usb -\u003e copy -\u003e test\n./hydra.sh all /dev/sdX --skip-downloads      # ISOs already in place; skip the download step\n./hydra.sh all /dev/sdX --skip-deps           # deps already installed; skip apt/dnf/pacman\n./hydra.sh all /dev/sdX --skip-downloads --skip-deps   # straight to the destructive write\n```\n\n---\n\n## Dependencies\n\n`./hydra.sh deps` installs everything below via your distro's package manager\n(`apt`, `dnf`, or `pacman` — detected automatically). All of these are\nmainstream and freely available.\n\n| Tool | Purpose |\n|---|---|\n| **[aria2](https://aria2.github.io/)** | **Required for Kali Live download.** Kali distributes Live ISOs only via BitTorrent on cdimage.kali.org. `aria2c` speaks both HTTP and BitTorrent, so the `download` step fetches the `.torrent` file via HTTP and then pulls the actual ISO from peers. The script will refuse to download Kali without `aria2c` on `PATH`. |\n| **qemu-system-x86 / qemu-utils** | Boot-test step. `hydra test` launches a QEMU/KVM VM that boots from your physical USB stick. |\n| **ovmf / edk2-ovmf** | UEFI firmware for QEMU. Lets the VM emulate a modern UEFI machine instead of legacy BIOS. |\n| **parted / gdisk** | Used internally by Ventoy when partitioning the USB. |\n| **cryptsetup** | LUKS-encrypted Kali persistence (`./hydra.sh persistence`). |\n| **jq** | Persistence step writes/merges `ventoy/ventoy.json` via jq. |\n| **wget / curl / tar** | Fetch Ventoy + Ubuntu, extract the Ventoy archive. |\n\nIf you can't (or don't want to) install dependencies via `./hydra.sh deps` —\ne.g. you're on a hardened system — install just `aria2` manually for the Kali\nstep, and skip the `test` subcommand to avoid needing QEMU.\n\n---\n\n## Configuration\n\nAll paths and versions are env-overridable. Defaults:\n\n| Variable | Default | Notes |\n|---|---|---|\n| `HYDRA_ISO_DIR` | `~/Downloads/iso` | Where ISOs + Ventoy tarball live |\n| `HYDRA_VENTOY_VERSION` | `1.1.12` | [Ventoy releases](https://github.com/ventoy/Ventoy/releases) |\n| `HYDRA_UBUNTU_VERSION` | `26.04` | LTS; set to `24.04` for prior LTS |\n| `HYDRA_KALI_VERSION` | `2026.1` | https://www.kali.org/get-kali/ |\n| `HYDRA_VM_MEMORY` | `4096` (MB) | QEMU RAM for boot test |\n| `HYDRA_VM_VCPUS` | `2` | QEMU vCPU count |\n| `HYDRA_PERSISTENCE_KALI` | unset | Default for `--kali` (e.g. `2G`, `max`) |\n| `HYDRA_PERSISTENCE_UBUNTU` | unset | Default for `--ubuntu` (e.g. `2G`, `max`) |\n| `HYDRA_PERSISTENCE_SIZE` | (deprecated) | Back-compat alias for `HYDRA_PERSISTENCE_KALI` |\n| `HYDRA_REPO_URL` | `https://github.com/CryptoJones/Hydra` | URL written to `Hydra.url` on the stick |\n| `HYDRA_WINDOWS_ISO` | unset | Absolute path to a Windows ISO. When set, `copy` drops it on the Ventoy partition alongside Ubuntu + Kali. |\n\nExample:\n\n```bash\nHYDRA_UBUNTU_VERSION=24.04 HYDRA_VM_MEMORY=8192 ./hydra.sh all /dev/sdc\nHYDRA_WINDOWS_ISO=~/Downloads/Win11_25H2_x64.iso ./hydra.sh copy /dev/sdc\n```\n\n---\n\n## Adding a Windows installer (BYO ISO)\n\nMicrosoft does not publish a stable direct URL for Windows ISOs (the\ndownload page rotates short-lived links and gates them behind a JS-driven\nflow), so Hydra can't fetch one automatically. Instead, point\n`HYDRA_WINDOWS_ISO` at a local file you've already downloaded:\n\n```bash\nHYDRA_WINDOWS_ISO=/path/to/Win11_25H2_English_x64_v2.iso \\\n  ./hydra.sh copy /dev/sdX\n```\n\n`copy` drops it onto the Ventoy partition under its original filename so\nVentoy's menu lists it next to Ubuntu and Kali. `./hydra.sh check` shows\nwhether the env var is set and the ISO is present. No persistence\nconfiguration is involved — Windows installers don't use Ventoy\npersistence.\n\n---\n\n## Safety\n\nThe `usb` and `all` subcommands write to a block device. Before writing, the\nscript:\n\n1. Refuses if the target isn't a block device.\n2. Refuses if the device's `RM` flag (removable) is 0 — i.e. internal disk.\n   Pass `--allow-non-removable` to bypass this for USB-attached SSD/NVMe\n   enclosures, which report `RM=0` even though they're hot-pluggable.\n3. Refuses if the device is smaller than 4 GB or larger than 2 TB.\n4. Refuses if the device backs the host root filesystem.\n   (This guard fires regardless of `--allow-non-removable`.)\n5. Prompts you to type the device path again as confirmation before writing.\n\nAdding a USB? Run `./hydra.sh check` first to see your removable-disk candidates.\n\n---\n\n## Encrypted persistence\n\n`./hydra.sh persistence /dev/sdX` adds LUKS-encrypted persistence\nfile(s) to the Ventoy partition so the changes you make in a Live\nsession survive reboots.\n\n### Choosing the layout\n\nEach enabled OS gets its own `persistence-\u003cos\u003e.dat` file (separate LUKS\nvolume, separate passphrase). Pick how to divide the free space:\n\n| Command | Layout |\n|---|---|\n| `./hydra.sh persistence /dev/sdX` | Kali absorbs all free space. Backwards-compatible default. |\n| `./hydra.sh persistence /dev/sdX --kali 8G` | Kali fixed at 8 GiB, the rest stays as free Ventoy space. |\n| `./hydra.sh persistence /dev/sdX --kali 8G --ubuntu max` | Kali fixed at 8 GiB, Ubuntu absorbs the remainder. |\n| `./hydra.sh persistence /dev/sdX --kali 4G --ubuntu 4G` | Two fixed 4 GiB images, anything left over is free Ventoy space. |\n| `./hydra.sh persistence /dev/sdX --ubuntu 6G` | Ubuntu only, no Kali persistence. |\n\nSize accepts iec values (`500M`, `2G`, `8G`, etc.) or the literal `max`.\nOnly one OS can be `max` per run. Each image must be at least 256 MiB.\n\nEnv vars `HYDRA_PERSISTENCE_KALI` / `HYDRA_PERSISTENCE_UBUNTU` set the\ndefaults that flags override. The older `HYDRA_PERSISTENCE_SIZE` env var\nis honoured as a Kali-only alias for back-compat.\n\n### Under the hood\n\nFor each enabled OS:\n\n1. Allocate a `persistence-\u003cos\u003e.dat` file at the requested size (FAT32\n   capped at 4 GiB - 1 byte; exFAT or newer Ventoy partitions don't cap).\n2. `cryptsetup luksFormat` (LUKS2) — prompts twice for the passphrase.\n   **There is no recovery if you forget it.**\n3. Open the LUKS container, format ext4, label it for the OS that boots it:\n   - Kali: label `persistence`, conf file `/persistence.conf`\n   - Ubuntu: label `writable`, conf file `/writable.conf`\n4. Write `/ union` into the conf file, close LUKS.\n5. Add (or update) a per-ISO entry in `ventoy/ventoy.json`'s persistence\n   plugin pointing the ISO at the `.dat` backing file.\n\n### Booting with persistence\n\n- **Kali**: at the boot menu, pick **Live USB Encrypted Persistence** and\n  enter the Kali passphrase.\n- **Ubuntu**: pick the persistent live entry. Note that Ubuntu's newer\n  Subiquity-based installer ISOs may not honour persistence in all\n  releases — test before relying on it.\n\nThe same step also drops a `Hydra.url` shortcut at the partition root\npointing back at this repo, so anyone who plugs the stick into a\nWindows host has a single click back to the source.\n\n---\n\n## Why torrent for Kali?\n\nKali Linux distributes their **Live** ISO only via BitTorrent on\ncdimage.kali.org (only their installer ISOs are direct HTTP). `hydra deps`\ninstalls `aria2`, which speaks both HTTP and BitTorrent. The\n`hydra.sh download` step grabs the `.torrent` file via HTTP, then uses aria2c\nto fetch the actual ISO from peers.\n\nIf you want the **installer** ISO instead of Live, edit the URLs near the\ntop of `hydra.sh`.\n\n---\n\n## Why QEMU instead of VirtualBox / VMware?\n\nQEMU/KVM is kernel-native on Linux, has zero proprietary dependencies, and\ncan boot directly from a raw block device with one flag\n(`-drive file=/dev/sdX,format=raw,if=virtio,readonly=on`). VirtualBox can do\nthis too via `vboxmanage internalcommands createrawvmdk`, but it's a more\ninvolved setup and requires the proprietary extension pack for some features.\n\n---\n\n## Testing\n\n### Unit tests (bats)\n\n```bash\nsudo apt install bats   # (or dnf / pacman; also installed by ./hydra.sh deps)\nbats tests/\n```\n\nThe suite covers CLI dispatch, error paths on the destructive subcommands,\nURL constant substitution from `HYDRA_*_VERSION` env overrides, the\n`run_ventoy_installer` cwd / arg / stdin contract, the `mkexfatfs` alias\nhelper, the `.url` writer, and the script-structure invariants (shebang,\nSPDX header, sourcing guard). No sudo, no real block devices, no\nnetwork — safe to run on any host.\n\nSee `tests/README.md` for the full inventory and how to add tests for new\nfunctionality.\n\n### Manual integration test (real USB + QEMU)\n\nEnd-to-end verification that the stick you just built actually boots.\nRun this after any non-trivial change to `cmd_usb`, `cmd_copy`, `cmd_persistence`,\nor the Ventoy version pin.\n\n**Prerequisites:** a 4–32 GB USB stick you don't mind wiping, plus a host\nwith KVM (`/dev/kvm` accessible to your user — group `kvm` membership is\nthe usual fix).\n\n**1. Build the stick.** Both subcommands need sudo; both write to the device.\n\n```bash\n# Wipe + reinstall Ventoy. The post-install probe will refuse to claim\n# success unless a Ventoy-labelled partition actually appears.\n./hydra.sh usb --force /dev/sdX\n\n# Copy Ubuntu + Kali ISOs to the Ventoy data partition. Also writes\n# Hydra.url to the partition root for Windows-host discoverability.\n./hydra.sh copy /dev/sdX\n```\n\n**2. (Optional) Add encrypted persistence.** Skip if you only want a\nfresh boot test.\n\n```bash\n./hydra.sh persistence /dev/sdX\n# Default: Kali absorbs the remaining free space, LUKS-encrypted.\n# Prompts twice for the passphrase. No recovery if you forget it.\n```\n\n**3. Install QEMU + UEFI firmware.** Only needed for the boot test;\n`./hydra.sh deps` covers it, or install manually for a lighter touch:\n\n```bash\nsudo apt install qemu-system-x86 qemu-utils ovmf\n```\n\n**4. Boot the stick in QEMU.**\n\nTwo modes:\n\n```bash\n./hydra.sh test /dev/sdX                    # read-only — safe but persistence won't activate\n./hydra.sh test /dev/sdX --writable-scratch # writable scratch copy — full persistence verification\n```\n\n**Plain `./hydra.sh test`** mounts the physical stick read-only as a\nvirtio drive. Fast (no copy) and the real stick is untouched, but\nVentoy's initramfs persistence-loading hook doesn't fire reliably\nunder this configuration — meaning persistence verification fails\ninside QEMU even when the build is correct on real hardware.\n\n**`--writable-scratch`** first `dd`'s the stick into a temp image\nunder `$HYDRA_SCRATCH_DIR` (default `/var/tmp`), then boots QEMU\nagainst the scratch image with writes enabled. Persistence works\n(writes go to the scratch image, not the real stick), and the\nscratch is deleted on QEMU exit. The dd step takes a few minutes\non a USB 3.0 stick.\n\nEither way, a QEMU window opens with Ventoy's menu listing Ubuntu +\nKali. Pick either; verify it boots all the way to a desktop. Close\nthe QEMU window when satisfied.\n\n**What \"pass\" looks like:**\n\n- [ ] `lsblk /dev/sdX` shows two partitions: a large `Ventoy`-labelled\n      one and a small `VTOYEFI` one.\n- [ ] `/dev/sdX1` mounted on the host shows `Hydra.url`,\n      `ubuntu-*.iso`, `kali-*.iso`, and (if persistence was added)\n      `persistence-kali.dat` + `ventoy/ventoy.json`.\n- [ ] QEMU boot reaches the Ventoy menu without complaint.\n- [ ] Picking Ubuntu boots to the GNOME desktop.\n- [ ] **With `--writable-scratch`**, picking Kali → **Live USB Encrypted\n      Persistence** prompts for the passphrase, then boots Kali with `/`\n      writable. Create a file in `/home/kali`, reboot via QEMU, re-enter\n      the passphrase, confirm the file is still there.\n- [ ] Without `--writable-scratch`, persistence is expected NOT to\n      activate (Ventoy hook limitation under read-only virtio).\n      Validate persistence on real hardware instead, or rerun with\n      `--writable-scratch`.\n\n**If any step fails:**\n\n- `usb` step prints \"Some tools can not run\" — re-run `./hydra.sh deps`\n  to refresh the `mkexfatfs` symlink, then retry.\n- `usb` claims success but `lsblk` shows only the manufacturer FAT32 —\n  the post-install probe should have caught this; if it didn't, file an\n  issue with the contents of `~/Downloads/iso/ventoy-1.1.12/log.txt`.\n- QEMU window is black for \u003e30s with no menu — `dmesg` on the host\n  often points at a missing `ovmf` or KVM permission issue.\n\n---\n\n## Upstream projects\n\nHydra is a thin orchestrator on top of several excellent tools — please\nsupport and credit them:\n\n- **[Ventoy](https://github.com/ventoy/Ventoy)** — the multi-boot magic.\n  Drop ISOs on a Ventoy USB and it boots them with no per-ISO setup.\n  GPLv3, by [longpanda](https://github.com/longpanda).\n- **[Ubuntu](https://ubuntu.com/)** — Canonical's Linux distribution.\n- **[Kali Linux](https://www.kali.org/)** — Offensive Security's pentest distro.\n- **[QEMU](https://www.qemu.org/)** + **KVM** — open-source virtualization\n  used for the boot-test step.\n- **[aria2](https://aria2.github.io/)** — multi-protocol downloader, used\n  to fetch Kali's torrent-only Live image.\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n\nNote: Hydra's code is Apache 2.0, but the *tools it orchestrates* carry their\nown licenses (Ventoy is GPLv3, etc.). Hydra does not redistribute them; it\ndownloads them from their official sources at runtime.\n\nProudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fhydra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptojones%2Fhydra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fhydra/lists"}