fix(doctor): expose read-only build and Wi-Fi diagnostics

This commit is contained in:
2026-10-30 11:08:20 -03:00
parent 4d2c3d6d7d
commit 8240669504
6 changed files with 165 additions and 21 deletions
+16 -3
View File
@@ -447,8 +447,19 @@ You need a user password or the FileVault recovery key. If neither is available,
### "Not a macOS Data volume"
Unleash checks for `/private/var/db/dslocal/nodes/Default` on the mounted volume. If it's missing, you mounted the wrong disk. Run `diskutil list` to find the correct one.
### macOS 27 (or future version)
Unleash should work on any macOS version that uses the same MDM enrollment mechanism. If a new macOS changes the enrollment daemons or DEP markers, open an issue.
### macOS 27 and later
macOS 27 has no recorded passing hardware validation in this project yet.
Compatibility is tracked in [#22](https://github.com/mateussiqueira/unleash/issues/22).
For a compatibility or Wi-Fi report, collect the build and interface state:
```bash
./unleash doctor --network
```
This reads the macOS build, Wi-Fi interface, power, and link status. Include
the script commit, hardware model, and external SSD/hub connection when
reporting an external-volume problem. It does not certify compatibility.
### Monitor won't start
Check if it's already running (`monitor-status`). Check permissions — it needs root. Check logs at `/var/log/unleash-monitor.log`.
@@ -456,7 +467,9 @@ Check if it's already running (`monitor-status`). Check permissions — it needs
## FAQ
**What macOS versions are supported?**
12.x (Monterey) through 15.x (Sequoia), 26.x (Tahoe), and 27.x. Tested on Intel T2, M1, M2, M3, M4, M5.
The existing targets are macOS 12–15 and 26. Validation depends on the command,
OS build, and hardware; macOS 27 remains unverified. Shell regression tests
do not replace testing Recovery, FileVault, and networking on the target Mac.
**Do I need to disable SIP?**
No. All writes target the Data volume.
+1
View File
@@ -9,6 +9,7 @@ cat > "$OUT" << HEADER
#!/bin/bash
set -euo pipefail
VERSION="$VERSION"
STANDALONE_BUILD=true
SCRIPT_DIR="\$(cd "\$(dirname "\$0")" && pwd)"
SCRIPT_PATH="\$SCRIPT_DIR/\$(basename "\$0")"
HEADER
+43 -8
View File
@@ -1,22 +1,59 @@
_network_diagnostics() {
header "Network Diagnostics"
local version=unavailable build=unavailable
if command -v sw_vers &>/dev/null; then
version=$(sw_vers -productVersion 2>/dev/null) || version=unavailable
build=$(sw_vers -buildVersion 2>/dev/null) || build=unavailable
fi
printf 'macOS: %s (build %s)\n' "$version" "$build"
case "$version" in 27.*) warn "macOS 27 hardware compatibility remains unverified (issue #22)." ;; esac
local interface
interface=$(networksetup -listallhardwareports 2>/dev/null | awk '
/Hardware Port:/ { wifi=($0 ~ /: (Wi-Fi|AirPort)$/); next }
wifi && /^[[:space:]]*Device:/ { print $2; exit }
' || true)
if [ -z "$interface" ]; then
info "No Wi-Fi hardware port reported."
return 0
fi
local power status
power=$(networksetup -getairportpower "$interface" 2>/dev/null || true)
case "$power" in *': On') power=on ;; *': Off') power=off ;; *) power=unavailable ;; esac
status=$(ifconfig "$interface" 2>/dev/null | awk '/^[[:space:]]*status:/ {print $2; exit}' || true)
printf 'Wi-Fi interface: %s\nWi-Fi power: %s\nLink status: %s\n' "$interface" "$power" "${status:-unavailable}"
}
run_doctor() {
if [ "${1:-}" = --network ]; then _network_diagnostics; return; fi
header "Unleash Doctor — Pre-Flight Check"
local errors=0 warnings=0
begin "Script location"
if [ -n "$SCRIPT_DIR" ] && [ -d "$SCRIPT_DIR" ]; then
end_ok; echo " $SCRIPT_DIR"
local script_dir="${SCRIPT_DIR:-}"
if [ -n "$script_dir" ] && [ -d "$script_dir" ]; then
end_ok; echo " $script_dir"
else
end_fail; errors=$((errors + 1))
fi
begin "Library files"
local missing=0
for _lib in colors detect validate dscl suppress backup status heal firewall harden whitelist check monitor history; do
[ -f "$LIB_DIR/$_lib.sh" ] || missing=$((missing + 1))
done
if [ "${STANDALONE_BUILD:-false}" = true ]; then
local core
for core in log resolve_data_volume validate_username create_admin_user suppress_enrollment backup_state deep_status _launchd_script_path heal_suppress install_pf_mdm_block harden_live_os install_selective_block run_preformat_check monitor_mdm show_history; do
declare -F "$core" >/dev/null || missing=$((missing + 1))
done
else
local lib_dir="${LIB_DIR:-}"
for _lib in colors detect validate dscl suppress backup status launchd heal firewall harden whitelist check monitor history; do
[ -n "$lib_dir" ] && [ -f "$lib_dir/$_lib.sh" ] || missing=$((missing + 1))
done
fi
if [ "$missing" -eq 0 ]; then
end_ok; echo " 13/13 modules loaded"
end_ok
if [ "${STANDALONE_BUILD:-false}" = true ]; then echo " Embedded core modules loaded";
else echo " Core library files available"; fi
else
end_fail; echo " $missing module(s) missing"; errors=$((errors + 1))
fi
@@ -38,8 +75,6 @@ run_doctor() {
fi
begin "Disk space (Data volume)"
local mount_pt
mount_pt=$(df / 2>/dev/null | awk 'NR>1 {print $NF; exit}')
local avail
avail=$(df / 2>/dev/null | awk 'NR>1 {print $4; exit}')
if [ -n "$avail" ] && [ "$avail" -gt 1048576 ]; then
+56
View File
@@ -18,3 +18,59 @@ setup() {
LIB_DIR="$old_dir"
echo "$output" | grep -qi "missing\|error"
}
@test "network doctor reports build power and link using only read commands" {
local entrypoint
for entrypoint in unleash unleash-standalone.sh; do
local script="$BATS_TEST_DIRNAME/../$entrypoint"
local definitions="$BATS_TEST_TMPDIR/$entrypoint.functions"
local calls="$BATS_TEST_TMPDIR/$entrypoint.calls"
sed '/^main "\$@"$/d' "$script" > "$definitions"
run "${UNLEASH_TEST_SHELL:-bash}" -u -c '
source "$1"
calls="$2"
load_config() { :; }
sw_vers() {
echo "sw_vers $*" >> "$calls"
case "$1" in -productVersion) echo 27.0 ;; -buildVersion) echo TESTBUILD ;; *) return 97 ;; esac
}
networksetup() {
echo "networksetup $*" >> "$calls"
case "$*" in
-listallhardwareports) printf "Hardware Port: Ethernet\nDevice: en0\nHardware Port: Wi-Fi\nDevice: en7\nEthernet Address: PRIVATE-MAC\n" ;;
"-getairportpower en7") echo "Wi-Fi Power (en7): On" ;;
*) return 97 ;;
esac
}
ifconfig() {
echo "ifconfig $*" >> "$calls"
[ "$*" = en7 ] || return 97
printf "en7: flags\n ether PRIVATE-MAC\n status: inactive\n"
}
main doctor --network
' "$script" "$definitions" "$calls"
[ "$status" -eq 0 ]
[[ "$output" == *"27.0 (build TESTBUILD)"* ]]
[[ "$output" == *"Wi-Fi interface: en7"* ]]
[[ "$output" == *"Wi-Fi power: on"* ]]
[[ "$output" == *"Link status: inactive"* ]]
[[ "$output" != *"PRIVATE-MAC"* ]]
run grep -vE '^(sw_vers -(productVersion|buildVersion)|networksetup -listallhardwareports|networksetup -getairportpower en7|ifconfig en7)$' "$calls"
[ "$status" -eq 1 ]
done
}
@test "standalone doctor verifies embedded modules without a lib directory" {
local script="$BATS_TEST_DIRNAME/../unleash-standalone.sh"
local definitions="$BATS_TEST_TMPDIR/standalone.functions"
sed '/^main "\$@"$/d' "$script" > "$definitions"
run "${UNLEASH_TEST_SHELL:-bash}" -u -c '
unset LIB_DIR
source "$1"
load_config() { :; }
main doctor
' "$script" "$definitions"
[ "$status" -eq 0 ]
[[ "$output" == *"Embedded core modules loaded"* ]]
[[ "$output" != *"unbound variable"* ]]
}
+3 -1
View File
@@ -2,6 +2,7 @@
set -euo pipefail
VERSION="2.0.0"
STANDALONE_BUILD=false
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SCRIPT_PATH="$SCRIPT_DIR/$(basename "$0")"
@@ -41,7 +42,7 @@ show_cmd_help() {
monitor-uninstall) echo "Remove monitor LaunchDaemon." ;;
monitor-stop) echo "Stop the monitor daemon." ;;
monitor-status) echo "Check if monitor is running." ;;
doctor) echo "Run pre-flight diagnostics." ;;
doctor) echo "Run pre-flight diagnostics; --network reports the build and Wi-Fi state." ;;
init) echo "Interactive setup wizard." ;;
suggest) echo "Risk-based recommendations." ;;
remediate) echo "Per-org MDM cleanup." ;;
@@ -593,6 +594,7 @@ main() {
monitor-uninstall|mn-uninstall) uninstall_monitor_launchdaemon "" ;;
monitor-stop|mn-stop) cmd_monitor_stop ;;
monitor-status|mn-st) cmd_monitor_status ;;
doctor) run_doctor "${2:-}" ;;
version|-v|--version) cmd_version ;;
init) cmd_init ;;
suggest) cmd_suggest ;;
+46 -9
View File
@@ -1,6 +1,7 @@
#!/bin/bash
set -euo pipefail
VERSION="2.0.0"
STANDALONE_BUILD=true
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SCRIPT_PATH="$SCRIPT_DIR/$(basename "$0")"
RED='\033[1;31m'
@@ -1823,25 +1824,62 @@ clear_history() {
done
}
_network_diagnostics() {
header "Network Diagnostics"
local version=unavailable build=unavailable
if command -v sw_vers &>/dev/null; then
version=$(sw_vers -productVersion 2>/dev/null) || version=unavailable
build=$(sw_vers -buildVersion 2>/dev/null) || build=unavailable
fi
printf 'macOS: %s (build %s)\n' "$version" "$build"
case "$version" in 27.*) warn "macOS 27 hardware compatibility remains unverified (issue #22)." ;; esac
local interface
interface=$(networksetup -listallhardwareports 2>/dev/null | awk '
/Hardware Port:/ { wifi=($0 ~ /: (Wi-Fi|AirPort)$/); next }
wifi && /^[[:space:]]*Device:/ { print $2; exit }
' || true)
if [ -z "$interface" ]; then
info "No Wi-Fi hardware port reported."
return 0
fi
local power status
power=$(networksetup -getairportpower "$interface" 2>/dev/null || true)
case "$power" in *': On') power=on ;; *': Off') power=off ;; *) power=unavailable ;; esac
status=$(ifconfig "$interface" 2>/dev/null | awk '/^[[:space:]]*status:/ {print $2; exit}' || true)
printf 'Wi-Fi interface: %s\nWi-Fi power: %s\nLink status: %s\n' "$interface" "$power" "${status:-unavailable}"
}
run_doctor() {
if [ "${1:-}" = --network ]; then _network_diagnostics; return; fi
header "Unleash Doctor — Pre-Flight Check"
local errors=0 warnings=0
begin "Script location"
if [ -n "$SCRIPT_DIR" ] && [ -d "$SCRIPT_DIR" ]; then
end_ok; echo " $SCRIPT_DIR"
local script_dir="${SCRIPT_DIR:-}"
if [ -n "$script_dir" ] && [ -d "$script_dir" ]; then
end_ok; echo " $script_dir"
else
end_fail; errors=$((errors + 1))
fi
begin "Library files"
local missing=0
for _lib in colors detect validate dscl suppress backup status heal firewall harden whitelist check monitor history; do
[ -f "$LIB_DIR/$_lib.sh" ] || missing=$((missing + 1))
done
if [ "${STANDALONE_BUILD:-false}" = true ]; then
local core
for core in log resolve_data_volume validate_username create_admin_user suppress_enrollment backup_state deep_status _launchd_script_path heal_suppress install_pf_mdm_block harden_live_os install_selective_block run_preformat_check monitor_mdm show_history; do
declare -F "$core" >/dev/null || missing=$((missing + 1))
done
else
local lib_dir="${LIB_DIR:-}"
for _lib in colors detect validate dscl suppress backup status launchd heal firewall harden whitelist check monitor history; do
[ -n "$lib_dir" ] && [ -f "$lib_dir/$_lib.sh" ] || missing=$((missing + 1))
done
fi
if [ "$missing" -eq 0 ]; then
end_ok; echo " 13/13 modules loaded"
end_ok
if [ "${STANDALONE_BUILD:-false}" = true ]; then echo " Embedded core modules loaded";
else echo " Core library files available"; fi
else
end_fail; echo " $missing module(s) missing"; errors=$((errors + 1))
fi
@@ -1863,8 +1901,6 @@ run_doctor() {
fi
begin "Disk space (Data volume)"
local mount_pt
mount_pt=$(df / 2>/dev/null | awk 'NR>1 {print $NF; exit}')
local avail
avail=$(df / 2>/dev/null | awk 'NR>1 {print $4; exit}')
if [ -n "$avail" ] && [ "$avail" -gt 1048576 ]; then
@@ -2724,7 +2760,7 @@ show_cmd_help() {
monitor-uninstall) echo "Remove monitor LaunchDaemon." ;;
monitor-stop) echo "Stop the monitor daemon." ;;
monitor-status) echo "Check if monitor is running." ;;
doctor) echo "Run pre-flight diagnostics." ;;
doctor) echo "Run pre-flight diagnostics; --network reports the build and Wi-Fi state." ;;
init) echo "Interactive setup wizard." ;;
suggest) echo "Risk-based recommendations." ;;
remediate) echo "Per-org MDM cleanup." ;;
@@ -3276,6 +3312,7 @@ main() {
monitor-uninstall|mn-uninstall) uninstall_monitor_launchdaemon "" ;;
monitor-stop|mn-stop) cmd_monitor_stop ;;
monitor-status|mn-st) cmd_monitor_status ;;
doctor) run_doctor "${2:-}" ;;
version|-v|--version) cmd_version ;;
init) cmd_init ;;
suggest) cmd_suggest ;;