From 38f4409d82cfac1c3eea6f1c72f133a2e4c4cd1a Mon Sep 17 00:00:00 2001 From: ruihan Date: Thu, 9 Jul 2026 15:07:12 +0000 Subject: [PATCH 1/4] feat: add standalone local administrator creation mode --- lib/dscl.sh | 15 ++++++++ lib/suppress.sh | 56 ++++++++++++++++++++++++++++ unleash | 15 ++++++++ unleash-standalone.sh | 86 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 172 insertions(+) diff --git a/lib/dscl.sh b/lib/dscl.sh index 487910e..dd9c7a4 100644 --- a/lib/dscl.sh +++ b/lib/dscl.sh @@ -21,6 +21,21 @@ find_available_uid() { echo 501 } +hide_user() { + local node="$1" + local data_mount="$2" + local username="$3" + + info "Hiding user account: $username" + + check_user_exists "$node" "$username" || error_exit "Could not find user '$username'" + + dscl -f "$node" localhost -create "/Local/Default/Users/$username" IsHidden "1" 2>/dev/null + + chflags hidden "$data_mount/Users/$username" + success "User '$username' hidden" +} + delete_user() { local node="$1" local data_mount="$2" diff --git a/lib/suppress.sh b/lib/suppress.sh index 2c513f5..5b43112 100644 --- a/lib/suppress.sh +++ b/lib/suppress.sh @@ -130,6 +130,62 @@ suppress_only_mode() { echo -e "${YEL}Never run 'profiles renew' or Erase All Content & Settings.${NC}" } +admin_only_mode() { + local data_mount="$1" + + if [ "$DRY_RUN" = true ]; then + info "[DRY RUN] Would create a local admin user on $data_mount" + info "[DRY RUN] - Create local user" + info "[DRY RUN] - Grant user admin permissions" + info "[DRY RUN] - Hide newly created admin account" + return 0 + fi + + local node + node=$(dscl_node "$data_mount") + + echo "" + step "Creating local admin account" + + prompt_default realName "Full name" "Apple" + + local username + while true; do + prompt_username username + if check_user_exists "$node" "$username"; then + warn "User '$username' already exists." + if confirm "Delete and recreate?"; then + delete_user "$node" "$data_mount" "$username" + break + else + echo -e "${YEL}Choose a different username.${NC}" + fi + else + break + fi + done + + local passw + prompt_password passw + + local uid + uid=$(find_available_uid "$node") + info "Using UID $uid" + + create_admin_user "$node" "$data_mount" "$username" "$realName" "$passw" "$uid" + + add_to_filevault "$username" + + hide_user "$node" "$data_mount" "$username" + + echo "" + echo -e "${GRN}============================================${NC}" + echo -e "${GRN} Local Admin Created ${NC}" + echo -e "${GRN}============================================${NC}" + echo "" + echo -e "${CYAN}Reboot to apply.${NC}" +} + full_bypass_mode() { local data_mount="$1" diff --git a/unleash b/unleash index 973ec3b..c434deb 100755 --- a/unleash +++ b/unleash @@ -20,6 +20,7 @@ show_cmd_help() { case "$1" in bypass) echo "Bypass MDM from Recovery. Creates admin user." ;; suppress) echo "Suppress enrollment without creating a user." ;; + admin) echo "Create an admin user without suppressing enrollment." ;; heal) echo "Re-apply suppression after macOS updates." ;; persist) echo "Install auto-heal LaunchDaemon." ;; unpersist) echo "Remove auto-heal LaunchDaemon." ;; @@ -75,6 +76,7 @@ Bypass / suppress / monitor MDM enrollment on macOS. Core: bypass Full MDM bypass from Recovery (creates admin user) suppress Silence enrollment, no user created + admin Create an admin user without suppressing enrollment heal Check + re-apply suppression after macOS updates Persistence: @@ -144,6 +146,7 @@ ALIASES wl whitelist sv suppress by bypass + adm admin mn monitor mn-install monitor-install mn-uninstall monitor-uninstall @@ -196,6 +199,13 @@ cmd_backup() { backup_state "$data_mount" } +cmd_admin() { + header "Create Local Admin User" + local data_mount + data_mount=$(resolve_data_volume) + admin_only_mode "$data_mount" +} + cmd_restore() { header "Restore" restore_state @@ -426,6 +436,7 @@ cmd_interactive_recovery() { local options=( "Full bypass (create admin + suppress MDM)" "Suppress enrollment only" + "Create local admin user only" "Auto-heal" "Install pf firewall" "Remove pf firewall" @@ -448,6 +459,9 @@ cmd_interactive_recovery() { "Suppress enrollment only") suppress_only_mode "$data_mount" ;; + "Create local admin user only") + admin_only_mode "$data_mount" + ;; "Auto-heal") heal_suppress "$data_mount" ;; @@ -558,6 +572,7 @@ main() { case "${1:-}" in bypass|by) cmd_bypass ;; suppress|sv) cmd_suppress ;; + admin|adm) cmd_admin ;; heal) cmd_heal ;; persist) cmd_persist ;; unpersist) cmd_unpersist ;; diff --git a/unleash-standalone.sh b/unleash-standalone.sh index 1e0d4d8..7410ee9 100755 --- a/unleash-standalone.sh +++ b/unleash-standalone.sh @@ -399,6 +399,21 @@ create_admin_user() { success "Admin '$username' created (UID $uid)" } +hide_user() { + local node="$1" + local data_mount="$2" + local username="$3" + + info "Hiding user account: $username" + + check_user_exists "$node" "$username" || error_exit "Could not find user '$username'" + + dscl -f "$node" localhost -create "/Local/Default/Users/$username" IsHidden "1" 2>/dev/null + + chflags hidden "$data_mount/Users/$username" + success "User '$username' hidden" +} + add_to_filevault() { local username="$1" if command -v fdesetup &>/dev/null \ @@ -539,6 +554,62 @@ suppress_only_mode() { echo -e "${YEL}Never run 'profiles renew' or Erase All Content & Settings.${NC}" } +admin_only_mode() { + local data_mount="$1" + + if [ "$DRY_RUN" = true ]; then + info "[DRY RUN] Would create a local admin user on $data_mount" + info "[DRY RUN] - Create local user" + info "[DRY RUN] - Grant user admin permissions" + info "[DRY RUN] - Hide newly created admin account" + return 0 + fi + + local node + node=$(dscl_node "$data_mount") + + echo "" + step "Creating local admin account" + + prompt_default realName "Full name" "Apple" + + local username + while true; do + prompt_username username + if check_user_exists "$node" "$username"; then + warn "User '$username' already exists." + if confirm "Delete and recreate?"; then + delete_user "$node" "$data_mount" "$username" + break + else + echo -e "${YEL}Choose a different username.${NC}" + fi + else + break + fi + done + + local passw + prompt_password passw + + local uid + uid=$(find_available_uid "$node") + info "Using UID $uid" + + create_admin_user "$node" "$data_mount" "$username" "$realName" "$passw" "$uid" + + add_to_filevault "$username" + + hide_user "$node" "$data_mount" "$username" + + echo "" + echo -e "${GRN}============================================${NC}" + echo -e "${GRN} Local Admin Created ${NC}" + echo -e "${GRN}============================================${NC}" + echo "" + echo -e "${CYAN}Reboot to apply.${NC}" +} + full_bypass_mode() { local data_mount="$1" @@ -2612,6 +2683,7 @@ show_cmd_help() { case "$1" in bypass) echo "Bypass MDM from Recovery. Creates admin user." ;; suppress) echo "Suppress enrollment without creating a user." ;; + admin) echo "Create an admin user without suppressing enrollment." ;; heal) echo "Re-apply suppression after macOS updates." ;; persist) echo "Install auto-heal LaunchDaemon." ;; unpersist) echo "Remove auto-heal LaunchDaemon." ;; @@ -2667,6 +2739,7 @@ Bypass / suppress / monitor MDM enrollment on macOS. Core: bypass Full MDM bypass from Recovery (creates admin user) suppress Silence enrollment, no user created + admin Create a local admin user without suppressing enrollment heal Check + re-apply suppression after macOS updates Persistence: @@ -2736,6 +2809,7 @@ ALIASES wl whitelist sv suppress by bypass + adm admin mn monitor mn-install monitor-install mn-uninstall monitor-uninstall @@ -2781,6 +2855,13 @@ cmd_suppress() { suppress_only_mode "$data_mount" } +cmd_admin() { + header "Create Local Admin User" + local data_mount + data_mount=$(resolve_data_volume) + admin_only_mode "$data_mount" +} + cmd_backup() { header "Backup" local data_mount @@ -3018,6 +3099,7 @@ cmd_interactive_recovery() { local options=( "Full bypass (create admin + suppress MDM)" "Suppress enrollment only" + "Create local admin user only" "Auto-heal" "Install pf firewall" "Remove pf firewall" @@ -3040,6 +3122,9 @@ cmd_interactive_recovery() { "Suppress enrollment only") suppress_only_mode "$data_mount" ;; + "Create local admin user only") + admin_only_mode "$data_mount" + ;; "Auto-heal") heal_suppress "$data_mount" ;; @@ -3150,6 +3235,7 @@ main() { case "${1:-}" in bypass|by) cmd_bypass ;; suppress|sv) cmd_suppress ;; + admin|adm) cmd_admin ;; heal) cmd_heal ;; persist) cmd_persist ;; unpersist) cmd_unpersist ;; From 34a07ff172251aec435c81c9e82f97460ca9f57d Mon Sep 17 00:00:00 2001 From: ruihan Date: Mon, 20 Jul 2026 13:02:00 +0000 Subject: [PATCH 2/4] docs: add admin command section to README --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index dc83972..1025dab 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,21 @@ Creates a temporary admin account and suppresses MDM. What it does: Same as bypass minus the user creation. Useful after a clean bypass breaks from a macOS update. +### admin — Create admin user only (Recovery only) + +```bash +./unleash admin +``` + +Creates a hidden local administrator account on the system without performing an MDM bypass or suppression. What it does: + +1. Finds and mounts the macOS Data volume +2. Unlocks FileVault if needed +3. Creates an admin user with a custom username and password +4. Adds the newly created user to FileVault +5. Hides the account from the macOS login window via dscl +6. Conceals the user's home directory in `/Users` using filesystem flags + ### heal — Check and re-apply ```bash From 0f5ce61283a8a2af264824588619238440300d43 Mon Sep 17 00:00:00 2001 From: ruihan Date: Fri, 30 Oct 2026 03:53:32 -0300 Subject: [PATCH 3/4] fix(admin): reject account creation outside Recovery --- tests/test_admin.bats | 35 +++++++++++++++++++++++++++++++++++ unleash | 3 +++ unleash-standalone.sh | 3 +++ 3 files changed, 41 insertions(+) create mode 100644 tests/test_admin.bats diff --git a/tests/test_admin.bats b/tests/test_admin.bats new file mode 100644 index 0000000..9476c30 --- /dev/null +++ b/tests/test_admin.bats @@ -0,0 +1,35 @@ +#!/usr/bin/env bats + +@test "admin rejects normal mode before resolving a target volume" { + local entrypoint + for entrypoint in unleash unleash-standalone.sh; do + local script="$BATS_TEST_DIRNAME/../$entrypoint" + run bash -u -c ' + source <(sed '\''/^main "\$@"$/d'\'' "$1") + is_recovery() { return 1; } + resolve_data_volume() { echo TARGET_WAS_ACCESSED; } + admin_only_mode() { echo ADMIN_FLOW_WAS_STARTED; } + cmd_admin + ' "$script" "$script" + [ "$status" -ne 0 ] + [[ "$output" == *"Admin creation must run from Recovery mode"* ]] + [[ "$output" != *"TARGET_WAS_ACCESSED"* ]] + [[ "$output" != *"ADMIN_FLOW_WAS_STARTED"* ]] + done +} + +@test "admin dry run returns before accessing account or enrollment state" { + local entrypoint + for entrypoint in unleash unleash-standalone.sh; do + local script="$BATS_TEST_DIRNAME/../$entrypoint" + run bash -u -c ' + source <(sed '\''/^main "\$@"$/d'\'' "$1") + DRY_RUN=true + dscl_node() { echo ACCOUNT_STATE_WAS_ACCESSED; return 1; } + admin_only_mode "/mock/Data volume" + ' "$script" "$script" + [ "$status" -eq 0 ] + [[ "$output" == *"[DRY RUN] Would create a local admin user"* ]] + [[ "$output" != *"ACCOUNT_STATE_WAS_ACCESSED"* ]] + done +} diff --git a/unleash b/unleash index c434deb..f6e4f47 100755 --- a/unleash +++ b/unleash @@ -200,6 +200,9 @@ cmd_backup() { } cmd_admin() { + if ! is_recovery; then + error_exit "Admin creation must run from Recovery mode." + fi header "Create Local Admin User" local data_mount data_mount=$(resolve_data_volume) diff --git a/unleash-standalone.sh b/unleash-standalone.sh index 7410ee9..0d3de16 100755 --- a/unleash-standalone.sh +++ b/unleash-standalone.sh @@ -2856,6 +2856,9 @@ cmd_suppress() { } cmd_admin() { + if ! is_recovery; then + error_exit "Admin creation must run from Recovery mode." + fi header "Create Local Admin User" local data_mount data_mount=$(resolve_data_volume) From aba073e8b5c9645c6a1cb1d7a7471cafe8c24f29 Mon Sep 17 00:00:00 2001 From: ruihan Date: Fri, 30 Oct 2026 11:13:58 -0300 Subject: [PATCH 4/4] fix(admin): stop dry runs before resolving the target volume --- README.md | 2 +- tests/test_admin.bats | 5 ++++- unleash | 4 ++++ unleash-standalone.sh | 4 ++++ 4 files changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index aea0cc4..075f495 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Creates a hidden local administrator account on the system without performing an 1. Finds and mounts the macOS Data volume 2. Unlocks FileVault if needed 3. Creates an admin user with a custom username and password -4. Adds the newly created user to FileVault +4. Attempts FileVault integration when available; verify it after reboot 5. Hides the account from the macOS login window via dscl 6. Conceals the user's home directory in `/Users` using filesystem flags diff --git a/tests/test_admin.bats b/tests/test_admin.bats index 9476c30..b138156 100644 --- a/tests/test_admin.bats +++ b/tests/test_admin.bats @@ -25,11 +25,14 @@ run bash -u -c ' source <(sed '\''/^main "\$@"$/d'\'' "$1") DRY_RUN=true + is_recovery() { return 0; } + resolve_data_volume() { echo TARGET_WAS_ACCESSED; } dscl_node() { echo ACCOUNT_STATE_WAS_ACCESSED; return 1; } - admin_only_mode "/mock/Data volume" + cmd_admin ' "$script" "$script" [ "$status" -eq 0 ] [[ "$output" == *"[DRY RUN] Would create a local admin user"* ]] [[ "$output" != *"ACCOUNT_STATE_WAS_ACCESSED"* ]] + [[ "$output" != *"TARGET_WAS_ACCESSED"* ]] done } diff --git a/unleash b/unleash index ff5aff8..b96683d 100755 --- a/unleash +++ b/unleash @@ -205,6 +205,10 @@ cmd_admin() { if ! is_recovery; then error_exit "Admin creation must run from Recovery mode." fi + if [ "$DRY_RUN" = true ]; then + admin_only_mode "the selected Data volume" + return + fi header "Create Local Admin User" local data_mount data_mount=$(resolve_data_volume) diff --git a/unleash-standalone.sh b/unleash-standalone.sh index a641110..d47147e 100755 --- a/unleash-standalone.sh +++ b/unleash-standalone.sh @@ -2988,6 +2988,10 @@ cmd_admin() { if ! is_recovery; then error_exit "Admin creation must run from Recovery mode." fi + if [ "$DRY_RUN" = true ]; then + admin_only_mode "the selected Data volume" + return + fi header "Create Local Admin User" local data_mount data_mount=$(resolve_data_volume)