Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions .github/release-notes/v2.3.0.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 30 additions & 0 deletions BadBuilder.Tests/GitHubAndDownloadTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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<GitHubReleaseSource>(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("<SUBFOLDER>/BadUpdatePayload", artifact.Operations[0].SourcePath);
Assert.Contains("BadUpdatePayload/default.xex", artifact.Operations[0].AllowedOverwritePaths ?? []);
Assert.Equal("launch.ini", artifact.Operations[1].DestinationPath);
Assert.Equal("<SUBFOLDER>/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()
{
Expand Down
34 changes: 34 additions & 0 deletions BadBuilder.Tests/InstallAndFormattingTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
{
Expand Down
4 changes: 2 additions & 2 deletions BadBuilder/Application/BuilderApp.Configuration.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
}
Expand Down
4 changes: 2 additions & 2 deletions BadBuilder/Application/BuilderApp.Homebrew.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down
4 changes: 2 additions & 2 deletions BadBuilder/Application/BuilderApp.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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.");
}
Expand Down
2 changes: 1 addition & 1 deletion BadBuilder/BadBuilder.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<NuGetAuditMode>all</NuGetAuditMode>
<NuGetAuditLevel>low</NuGetAuditLevel>
<AnalysisLevel>latest-recommended</AnalysisLevel>
<VersionPrefix>2.2.1</VersionPrefix>
<VersionPrefix>2.3.0</VersionPrefix>
<RuntimeIdentifiers>win-x64;linux-x64</RuntimeIdentifiers>
<PublishSingleFile Condition="'$(RuntimeIdentifier)' != ''">true</PublishSingleFile>
<SelfContained Condition="'$(RuntimeIdentifier)' != ''">true</SelfContained>
Expand Down
28 changes: 28 additions & 0 deletions BadBuilder/Configuration/ArtifactCatalog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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",
"<SUBFOLDER>/BadUpdatePayload",
AllowedOverwritePaths: ["BadUpdatePayload/default.xex"]),
new InstallOperation(
InstallOperationKind.CopyFile,
"launch.ini",
"<SUBFOLDER>/launch.ini")
],
ArtifactPriority.Bootstrap,
Layout: new ArchiveLayout(RequireSingleTopLevelDirectory: true)
),
[BootstrapOption.FreeMyXe] = new
(
"bootstrap-freemyxe",
Expand Down
7 changes: 7 additions & 0 deletions BadBuilder/Configuration/Models.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
13 changes: 12 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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
44 changes: 44 additions & 0 deletions scripts/verify_xeunshackle_max_release.py
Original file line number Diff line number Diff line change
@@ -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")
Loading