diff --git a/.github/release-notes/v2.3.0.md b/.github/release-notes/v2.3.0.md new file mode 100644 index 0000000..9d84153 --- /dev/null +++ b/.github/release-notes/v2.3.0.md @@ -0,0 +1,27 @@ +# BadBuilderLinux v2.3.0 + +Feature release adding **XeUnshackle Max** as a separate, optional bootstrap. + +## Highlights + +- Add XeUnshackle Max alongside the existing XeUnshackle and FreeMyXe bootstrap choices. +- Pin the official [klofi/XeUnshackle-Max v1.0.0](https://github.com/klofi/XeUnshackle-Max/releases/tag/v1.0.0) ZIP to its exact release tag, filename and upstream-published SHA-256. +- Install its `BadUpdatePayload` overlay and `launch.ini` using the existing safe preflight mechanism. +- Do **not** automatically copy the archive's JRPC2/Xbdm remote-access plugins onto the USB. +- Allow default homebrew auto-launch configuration using either XeUnshackle variant. +- Add regression tests for catalog pinning, bootstrap capabilities and installation-plan overlay behavior. +- Preserve the original XeUnshackle and FreeMyXe implementations, Linux disk safety checks, and Windows UAC handling. + +## Features of XeUnshackle Max + +XeUnshackle Max supports configurable auto-start, hiding CPU/DVD keys on-screen, boot-video customization and volume controls. It is still described by its developer as **beta** software. + +Read the upstream usage notes before use. Do not flash a modified NAND or overwrite the console's flash boot animation. This USB builder erases the selected target disk. + +## Downloads + +- `BadBuilder-linux-x64` — self-contained Linux x64 binary +- `BadBuilder-win-x64.exe` — self-contained Windows x64 binary +- `SHA256SUMS` — checksums for both builds + +Automated Linux and Windows tests do not replace physical Xbox 360 compatibility testing. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8c3687b..14b311b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,6 +38,9 @@ jobs: - name: Audit dependencies run: dotnet list BadBuilder/BadBuilder.csproj package --vulnerable --include-transitive + - name: Verify pinned XeUnshackle Max release ZIP + if: runner.os == 'Linux' + run: python3 scripts/verify_xeunshackle_max_release.py - name: Warning-free build run: dotnet build BadBuilder.Tests/BadBuilder.Tests.csproj -c Release --no-restore diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dfca785..844b2be 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -72,6 +72,9 @@ jobs: run: dotnet restore BadBuilder.Tests/BadBuilder.Tests.csproj - name: Audit dependencies run: dotnet list BadBuilder/BadBuilder.csproj package --vulnerable --include-transitive + - name: Verify pinned XeUnshackle Max release ZIP + if: runner.os == 'Linux' + run: python3 scripts/verify_xeunshackle_max_release.py - name: Build with warnings as errors run: dotnet build BadBuilder.Tests/BadBuilder.Tests.csproj -c Release --no-restore - name: Run unit tests diff --git a/BadBuilder.Tests/GitHubAndDownloadTests.cs b/BadBuilder.Tests/GitHubAndDownloadTests.cs index 7a301b0..3885443 100644 --- a/BadBuilder.Tests/GitHubAndDownloadTests.cs +++ b/BadBuilder.Tests/GitHubAndDownloadTests.cs @@ -47,6 +47,36 @@ public void Catalog_ABadAvatar13Beta_IsPinnedToExpectedReleaseAndDigest() Assert.Contains("Content", artifact.Layout?.RequiredPaths ?? []); } + [Fact] + public void Catalog_XeUnshackleMax_PinsReleaseAndOmitsRemoteAccessPlugins() + { + ArtifactDefinition artifact = ArtifactCatalog.Bootstraps[BootstrapOption.XeUnshackleMax]; + GitHubReleaseSource source = Assert.IsType(artifact.Source); + + Assert.Equal("XeUnshackle Max", artifact.DisplayName); + Assert.Equal("klofi", source.Owner); + Assert.Equal("XeUnshackle-Max", source.Repo); + Assert.Equal("XeUnshackle-Max-v1.0.0.zip", source.AssetPattern); + Assert.Equal(ReleaseSelectionPolicy.ExactTag, source.ReleasePolicy); + Assert.Equal("v1.0.0", source.ReleaseTag); + Assert.Equal("838CF16450790601158265C22C84D90C1F9FFFF7BA07854B9781722DBA2328E4", source.PinnedSHA256); + Assert.True(artifact.Layout?.RequireSingleTopLevelDirectory); + Assert.Equal(2, artifact.Operations?.Count); + Assert.Equal("BadUpdatePayload", artifact.Operations![0].DestinationPath); + Assert.Equal("/BadUpdatePayload", artifact.Operations[0].SourcePath); + Assert.Contains("BadUpdatePayload/default.xex", artifact.Operations[0].AllowedOverwritePaths ?? []); + Assert.Equal("launch.ini", artifact.Operations[1].DestinationPath); + Assert.Equal("/launch.ini", artifact.Operations[1].SourcePath); + } + + [Fact] + public void XeUnshackleVariantsSupportDefaultHomebrewLaunch() + { + Assert.True(BootstrapCapabilities.SupportsDefaultHomebrewLaunch(BootstrapOption.XeUnshackle)); + Assert.True(BootstrapCapabilities.SupportsDefaultHomebrewLaunch(BootstrapOption.XeUnshackleMax)); + Assert.False(BootstrapCapabilities.SupportsDefaultHomebrewLaunch(BootstrapOption.FreeMyXe)); + } + [Fact] public void AssetSelection_RequiresExactlyOneGlobMatch() { diff --git a/BadBuilder.Tests/InstallAndFormattingTests.cs b/BadBuilder.Tests/InstallAndFormattingTests.cs index 0252d65..b941262 100644 --- a/BadBuilder.Tests/InstallAndFormattingTests.cs +++ b/BadBuilder.Tests/InstallAndFormattingTests.cs @@ -150,6 +150,40 @@ [new InstallOperation( [(firstArtifact, first), (missingExpected, second)], [], 128L * 1024 * 1024)); } + [Fact] + public async Task XeUnshackleMax_OverlaysOnlyPayloadAndLaunchConfig() + { + using TemporaryDirectory temporary = new(); + string exploitRoot = Path.Combine(temporary.Path, "exploit"); + string maxRoot = Path.Combine(temporary.Path, "max"); + string maxFolder = Path.Combine(maxRoot, "XeUnshackle-Max-v1.0.0"); + string target = Path.Combine(temporary.Path, "target"); + Directory.CreateDirectory(Path.Combine(exploitRoot, "BadUpdatePayload")); + Directory.CreateDirectory(Path.Combine(maxFolder, "BadUpdatePayload")); + Directory.CreateDirectory(target); + + await File.WriteAllTextAsync(Path.Combine(exploitRoot, "BadUpdatePayload", "default.xex"), "exploit"); + await File.WriteAllTextAsync(Path.Combine(maxFolder, "BadUpdatePayload", "default.xex"), "max"); + await File.WriteAllTextAsync(Path.Combine(maxFolder, "BadUpdatePayload", "BadStorage.xex.dll"), "storage"); + await File.WriteAllTextAsync(Path.Combine(maxFolder, "launch.ini"), "[Paths]"); + await File.WriteAllTextAsync(Path.Combine(maxFolder, "JRPC2.xex"), "remote access"); + await File.WriteAllTextAsync(Path.Combine(maxFolder, "Xbdm.xex"), "remote access"); + + ArtifactDefinition exploit = new( + "exploit", "Exploit", "Test", string.Empty, null, + [new InstallOperation(InstallOperationKind.CopyDirectory, ".", ".")]); + ArtifactDefinition max = ArtifactCatalog.Bootstraps[BootstrapOption.XeUnshackleMax]; + InstallPlan plan = InstallService.BuildPlan( + [(exploit, exploitRoot), (max, maxRoot)], [], 128L * 1024 * 1024); + await InstallService.ExecuteAsync(plan, target, CancellationToken.None); + + Assert.Equal("max", await File.ReadAllTextAsync(Path.Combine(target, "BadUpdatePayload", "default.xex"))); + Assert.Equal("storage", await File.ReadAllTextAsync(Path.Combine(target, "BadUpdatePayload", "BadStorage.xex.dll"))); + Assert.True(File.Exists(Path.Combine(target, "launch.ini"))); + Assert.False(File.Exists(Path.Combine(target, "JRPC2.xex"))); + Assert.False(File.Exists(Path.Combine(target, "Xbdm.xex"))); + } + [Fact] public void FormatterSizePolicy_StaysWithinGuaranteedFat32Range() { diff --git a/BadBuilder/Application/BuilderApp.Configuration.cs b/BadBuilder/Application/BuilderApp.Configuration.cs index 8a46f2c..deb28b7 100644 --- a/BadBuilder/Application/BuilderApp.Configuration.cs +++ b/BadBuilder/Application/BuilderApp.Configuration.cs @@ -74,10 +74,10 @@ private static void ConfigureBootstrap() Config.SelectedBootstrap = selected.Value; - if (selected.Value != BootstrapOption.XeUnshackle && Config.LaunchHomebrew is not null) + if (!BootstrapCapabilities.SupportsDefaultHomebrewLaunch(selected.Value) && Config.LaunchHomebrew is not null) { Config.LaunchHomebrew = null; - Controls.WriteWarning("The default homebrew launch selection was cleared because automatic launching requires XeUnshackle."); + Controls.WriteWarning("The default homebrew launch selection was cleared because automatic launching requires XeUnshackle or XeUnshackle Max."); Controls.Pause(); } } diff --git a/BadBuilder/Application/BuilderApp.Homebrew.cs b/BadBuilder/Application/BuilderApp.Homebrew.cs index 56a702f..9dbdc40 100644 --- a/BadBuilder/Application/BuilderApp.Homebrew.cs +++ b/BadBuilder/Application/BuilderApp.Homebrew.cs @@ -167,9 +167,9 @@ private static void RemoveCustomHomebrew() private static void ConfigureLaunchHomebrew() { - if (Config.SelectedBootstrap != BootstrapOption.XeUnshackle) + if (!BootstrapCapabilities.SupportsDefaultHomebrewLaunch(Config.SelectedBootstrap)) { - Controls.WriteWarning("Automatic homebrew launch requires the XeUnshackle bootstrap."); + Controls.WriteWarning("Automatic homebrew launch requires XeUnshackle or XeUnshackle Max."); Controls.Pause(); return; } diff --git a/BadBuilder/Application/BuilderApp.cs b/BadBuilder/Application/BuilderApp.cs index 41660c5..b996e32 100644 --- a/BadBuilder/Application/BuilderApp.cs +++ b/BadBuilder/Application/BuilderApp.cs @@ -262,8 +262,8 @@ private static void ValidateConfiguration() if (Config.LaunchHomebrew is null) return; - if (Config.SelectedBootstrap != BootstrapOption.XeUnshackle) - throw new InvalidOperationException("Automatic homebrew launch requires the XeUnshackle bootstrap."); + if (!BootstrapCapabilities.SupportsDefaultHomebrewLaunch(Config.SelectedBootstrap)) + throw new InvalidOperationException("Automatic homebrew launch requires XeUnshackle or XeUnshackle Max."); if (string.IsNullOrWhiteSpace(Config.LaunchHomebrew.EntryPointRelativePath)) throw new InvalidOperationException("The selected default homebrew has no valid entry point."); } diff --git a/BadBuilder/BadBuilder.csproj b/BadBuilder/BadBuilder.csproj index c5ecdae..f2f30d6 100644 --- a/BadBuilder/BadBuilder.csproj +++ b/BadBuilder/BadBuilder.csproj @@ -12,7 +12,7 @@ all low latest-recommended - 2.2.1 + 2.3.0 win-x64;linux-x64 true true diff --git a/BadBuilder/Configuration/ArtifactCatalog.cs b/BadBuilder/Configuration/ArtifactCatalog.cs index 9425ded..2ba3c8a 100644 --- a/BadBuilder/Configuration/ArtifactCatalog.cs +++ b/BadBuilder/Configuration/ArtifactCatalog.cs @@ -68,6 +68,34 @@ internal static class ArtifactCatalog ArtifactPriority.Bootstrap, Layout: new ArchiveLayout(RequireSingleTopLevelDirectory: true) ), + [BootstrapOption.XeUnshackleMax] = new + ( + "bootstrap-xeunshackle-max", + "XeUnshackle Max", + "XeUnshackle fork with auto-start, key masking and configurable boot video (beta)", + "bootstrap", + new GitHubReleaseSource( + "klofi", + "XeUnshackle-Max", + "XeUnshackle-Max-v1.0.0.zip", + ReleaseSelectionPolicy.ExactTag, + "v1.0.0", + "838CF16450790601158265C22C84D90C1F9FFFF7BA07854B9781722DBA2328E4"), + [ + // Network-access plugins included in the ZIP are not installed automatically. + new InstallOperation( + InstallOperationKind.CopyDirectory, + "BadUpdatePayload", + "/BadUpdatePayload", + AllowedOverwritePaths: ["BadUpdatePayload/default.xex"]), + new InstallOperation( + InstallOperationKind.CopyFile, + "launch.ini", + "/launch.ini") + ], + ArtifactPriority.Bootstrap, + Layout: new ArchiveLayout(RequireSingleTopLevelDirectory: true) + ), [BootstrapOption.FreeMyXe] = new ( "bootstrap-freemyxe", diff --git a/BadBuilder/Configuration/Models.cs b/BadBuilder/Configuration/Models.cs index cf9e7f7..fac7954 100644 --- a/BadBuilder/Configuration/Models.cs +++ b/BadBuilder/Configuration/Models.cs @@ -10,10 +10,17 @@ internal enum ExploitOption internal enum BootstrapOption { XeUnshackle, + XeUnshackleMax, FreeMyXe, } +internal static class BootstrapCapabilities +{ + internal static bool SupportsDefaultHomebrewLaunch(BootstrapOption option) => + option is BootstrapOption.XeUnshackle or BootstrapOption.XeUnshackleMax; +} + internal enum ReleaseSelectionPolicy { LatestStable, diff --git a/README.md b/README.md index 2b2b6ae..274e23e 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Do not run `sudo ./BadBuilder`. Interactive root launches are refused. ## Using BadBuilder 1. Open **Target drive** and choose the USB device. Fixed and protected disks are not shown. -2. Select BadUpdate, ABadAvatar Public Beta, or the pinned ABadAvatar 1.3 Beta build, then choose a post-exploit bootstrap and any desired homebrew. Dashboard Update is a separate install mode for official `2.0.17559.0` update files. +2. Select BadUpdate, ABadAvatar Public Beta, or the pinned ABadAvatar 1.3 Beta build, then choose XeUnshackle, XeUnshackle Max, or FreeMyXe as a post-exploit bootstrap and any desired homebrew. Dashboard Update is a separate install mode for official `2.0.17559.0` update files. 3. Choose **Install**. BadBuilder resolves releases, verifies or explicitly approves hashes, extracts into a unique temporary run directory, validates layouts, and builds the complete copy plan. 4. Review the displayed path, model, byte size, and serial/WWN. Type the exact device path to authorize formatting. 5. Wait for the success message. Linux automatically flushes and unmounts the USB. Windows leaves its assigned drive letter in place for normal eject. @@ -44,6 +44,16 @@ Expected disk, network, cache, and archive errors are shown as actionable messag > [!WARNING] > ABadAvatar 1.3 Beta is still a prerelease. Disconnect the Xbox 360 from both Ethernet and Wi-Fi before triggering it. Its release notes also warn that a connected Kinect can significantly reduce the exploit success rate. +## XeUnshackle Max + +XeUnshackle Max is an additional post-exploit bootstrap choice alongside the original XeUnshackle and FreeMyXe. Its pinned source is [klofi/XeUnshackle-Max v1.0.0](https://github.com/klofi/XeUnshackle-Max/releases/tag/v1.0.0), an independent **beta** fork of Byrom90's XeUnshackle. + +The fork adds optional automatic startup, CPU/DVD-key masking, boot-video skipping and volume control, and custom boot-video playback. On the Xbox 360, pressing Start can create a XeUnshackleConfig.txt next to BadUpdatePayload/default.xex. See the [upstream configuration documentation](https://github.com/klofi/XeUnshackle-Max#features). Both XeUnshackle variants support default homebrew launching through launch.ini. + +BadBuilderLinux pins the exact v1.0.0 ZIP and its upstream-published SHA-256. It copies the BadUpdatePayload directory and launch.ini, intentionally **not** installing the bundled JRPC2/Xbdm remote-access binaries automatically. You can add those plugins manually after reviewing the security implications. The upstream launch.ini may reference plugins that are not present on the freshly formatted USB. + +The existing preflight and disk-identity checks remain mandatory. XeUnshackle Max is not a permanent softmod. Do not flash modified NAND images or overwrite files in the console's flash. Read the upstream warnings before use. + ## Storage locations Persistent downloads and their manifests live in the user cache: @@ -96,6 +106,7 @@ If release metadata is unavailable and no valid cache exists, BadBuilder asks fo - Bibarub — [ABadAvatar 1.3 Beta](https://github.com/bibarub/Xbox360BadUpdate/releases/tag/avatar-v1.3-beta) - FreeMyXe Team / InvoxiPlayGames — [FreeMyXe](https://github.com/FreeMyXe/FreeMyXe) - Byrom90 — [XeUnshackle](https://github.com/Byrom90/XeUnshackle) +- klofi — [XeUnshackle Max](https://github.com/klofi/XeUnshackle-Max) - Swizzy — Simple 360 NAND Flasher - Team XeDEV — XeXMenu - Phoenix — Aurora Dashboard diff --git a/scripts/verify_xeunshackle_max_release.py b/scripts/verify_xeunshackle_max_release.py new file mode 100644 index 0000000..25a61a9 --- /dev/null +++ b/scripts/verify_xeunshackle_max_release.py @@ -0,0 +1,44 @@ +#!/usr/bin/env python3 +"""Verify the exact upstream XeUnshackle Max ZIP without extracting or flashing it.""" + +from hashlib import sha256 +from io import BytesIO +from urllib.request import Request, urlopen +from zipfile import ZipFile + +URL = ( + "https://github.com/klofi/XeUnshackle-Max/releases/download/v1.0.0/" + "XeUnshackle-Max-v1.0.0.zip" +) +EXPECTED_SHA256 = "838cf16450790601158265c22c84d90c1f9ffff7ba07854b9781722dba2328e4" +EXPECTED_SIZE_LIMIT = 32 * 1024 * 1024 + +with urlopen(Request(URL, headers={"User-Agent": "BadBuilderLinux-CI"}), timeout=60) as reply: + payload = reply.read(EXPECTED_SIZE_LIMIT + 1) + +if len(payload) > EXPECTED_SIZE_LIMIT: + raise SystemExit("XeUnshackle Max archive exceeds the expected download-size limit") + +digest = sha256(payload).hexdigest() +if digest != EXPECTED_SHA256: + raise SystemExit(f"Checksum mismatch: expected {EXPECTED_SHA256}, found {digest}") + +with ZipFile(BytesIO(payload)) as archive: + entries = [name.replace("\\", "/").rstrip("/") for name in archive.namelist()] + entries = [name for name in entries if name] + top_level = {name.split("/", 1)[0] for name in entries} + if len(top_level) != 1: + raise SystemExit(f"Expected exactly one top-level directory: {sorted(top_level)}") + prefix = next(iter(top_level)) + "/" + required = { + prefix + "BadUpdatePayload/default.xex", + prefix + "launch.ini", + } + actual = set(entries) + missing = required - actual + if missing: + raise SystemExit(f"XeUnshackle Max archive is missing required files: {sorted(missing)}") + if archive.testzip() is not None: + raise SystemExit("XeUnshackle Max archive contains corrupt ZIP data") + +print(f"XeUnshackle Max v1.0.0 verified: SHA256={digest}, {len(entries)} ZIP entries")