Pixel Guard Deploy

Portable ADB installer for Pixel Guard Device Owner deployment.

Pixel Guard is a no-VPN-slot Android Device Owner guard for Pixel devices. It blocks risky carrier/device-lock/config packages on metered Wi‑Fi through Android DevicePolicyManager and manages Wi‑Fi as metered suggestions.

Описание

Pixel Guard Deploy — это переносимый установщик для развёртывания Pixel Guard на телефоне через ADB. Основной сценарий: дать обычному пользователю архив/папку, он подключает телефон по USB и запускает установщик. На Windows не нужен установленный ADB и не нужен PowerShell: используется PixelGuardDeploy.cmd / PixelGuardDeploy.exe с встроенным ADB.

Pixel Guard — это Android-приложение, которое становится Device Owner и применяет политики Android Enterprise. Цель — не занять VPN-слот и не создавать tun0, а заблокировать интернет для опасных системных компонентов carrier/device-lock/config на уровне штатных политик Android.

Ключевая идея: обычный интернет для пользователя остаётся, но пакеты из списка риска получают METERED_ADMIN_DISABLED на metered-сетях. Wi‑Fi сети добавляются не через обычные Settings, а через Pixel Guard как metered Wi‑Fi suggestions.

Как работает само приложение Pixel Guard

После установки скрипт назначает компонент com.pixel.guard/.AdminReceiver владельцем устройства (Device Owner). Только после этого приложение получает право применять нужные политики.

Что делает Pixel Guard на телефоне:

1. Блокирует сетевой доступ опасным пакетам на metered-сетях. Приложение вызывает DevicePolicyManager.setMeteredDataDisabledPackages() для carrier/device-lock/config пакетов, например com.google.android.apps.work.oobconfig, com.android.devicelockcontroller, carrier setup/eUICC/config updater компонентов и т.п. На рабочей metered Wi‑Fi сети Android показывает для их UID состояние вроде METERED_ADMIN_DISABLED.

2. Не использует VPN. В приложении нет VpnService, не включается Always-on VPN, не создаётся tun0. VPN-слот остаётся свободным для обычного VPN пользователя.

3. Запрещает обычное добавление Wi‑Fi сетей через Settings. Включается DISALLOW_ADD_WIFI_CONFIG, чтобы пользователь или системный UI не создали обычную saved Wi‑Fi network вне контроля Pixel Guard. При этом DISALLOW_CONFIG_WIFI специально не держится активным для user 0, чтобы Wi‑Fi экран не был полностью заблокирован.

4. Добавляет разрешённые Wi‑Fi сети как metered suggestions. Пользователь открывает Pixel Guard, нажимает поиск Wi‑Fi, выбирает SSID, вводит пароль, и приложение создаёт WifiNetworkSuggestion с setIsMetered(true). Это принципиально: DPM-блокировка опасных пакетов работает именно на metered network.

5. Ведёт allowlist SSID через Device Owner policy. Для разрешённых сетей применяется WifiSsidPolicy, чтобы Android не подключался к произвольным SSID вне списка.

6. Хранит registry управляемых Wi‑Fi сетей. SSID, режим WPA2/WPA3 и passphrase сохраняются в app-private device-protected storage. Это нужно, чтобы после перезагрузки или переустановки приложения восстановить managed suggestions, если Android Wi‑Fi suggestion store потерял или отключил их.

7. Восстанавливает Wi‑Fi suggestions после reboot/package replace. BootReceiver на BOOT_COMPLETED и MY_PACKAGE_REPLACED заново применяет guard policies и вызывает repair для managed Wi‑Fi networks.

8. Переключает управляемые сети внутри Pixel Guard. Кнопка Make active: <SSID> пересобирает suggestions так, чтобы выбранная сеть была единственным autojoin-кандидатом, а остальные managed сети временно не участвовали в autojoin. Это надёжнее, чем пытаться переключаться через обычные Android Settings.

9. Показывает диагностический статус. В UI видны admin, deviceOwner, allowedSsids, managedSsids, текущие suggestions и результаты операций. Установщик дополнительно проверяет Device Owner, VPN slot, metered state и наличие METERED_ADMIN_DISABLED.

Что приложение не делает:

• не разблокирует уже заблокированную SIM или устройство;
• не прошивает телефон;
• не требует root;
• не меняет bootloader;
• не занимает VPN;
• не создаёт обычные saved Wi‑Fi networks.

Как работает установщик

Установщик — это host-side wrapper над ADB:

1. Находит встроенный или системный adb.
2. Проверяет, что подключено ровно одно авторизованное устройство.
3. Устанавливает app/pixel-guard.apk.
4. Выполняет dpm set-active-admin --user 0 com.pixel.guard/.AdminReceiver.
5. Выполняет dpm set-device-owner --user 0 com.pixel.guard/.AdminReceiver.
6. Открывает Pixel Guard на телефоне.
7. Запускает verify checks.

На Windows основной путь — PixelGuardDeploy.cmd / PixelGuardDeploy.exe. Внутри есть меню: активировать защиту, проверить состояние, открыть приложение, попытаться вернуть stock-like состояние, показать ADB devices.

Пункт Restore stock-like state пытается выполнить dpm remove-active-admin и удалить приложение. Это работает только если Android разрешает снятие Device Owner для данной testOnly-сборки. Если Android отказывает, это не обходится скриптом; raw dpm output является источником истины.

Critical limitation: already locked SIM/device

Pixel Guard is preventive. It blocks the carrier/device-lock/config path from getting usable network access after Pixel Guard has been deployed.

It does not unlock a SIM or device that has already been locked.

If the SIM/device is already locked, the practical recovery/deployment flow is:

1. Remove Google accounts from the phone first, if Android UI still allows it. This avoids Factory Reset Protection surprises.
2. Factory reset the phone.
3. During initial setup, keep the phone offline: no SIM data, no Wi‑Fi, no Internet.
4. Enable Developer options and USB debugging.
5. Run this deploy tool from the computer.
6. Only after Pixel Guard is Device Owner, enroll Wi‑Fi networks inside Pixel Guard.

If Android refuses dpm set-device-owner, the raw Android error is the source of truth. ADB Device Owner provisioning is state-dependent; many already-set-up devices require factory reset or QR/MDM provisioning.

What this installer does

1. Uses bundled adb when available.
2. Installs app/pixel-guard.apk.
3. Sets com.pixel.guard/.AdminReceiver as Device Owner.
4. Opens Pixel Guard.
5. Runs verification checks.

Bundled ADB

Included now:

• tools/adb/darwin-universal/adb — macOS universal binary, works on Apple Silicon and Intel Macs.
• tools/adb/windows-x64/platform-tools/adb.exe — Windows x64 ADB from official Android SDK Platform-Tools, with required DLLs.

Supported by scripts if you add binaries later:

• tools/adb/linux-x64/adb

Bundled Windows Platform-Tools files include Google NOTICE.txt and source.properties under tools/adb/windows-x64/platform-tools/.

You can always override ADB explicitly:

PIXEL_GUARD_ADB=/absolute/path/to/adb ./install.sh

PowerShell:

$env:PIXEL_GUARD_ADB="C:\path\to\adb.exe"
.\install.ps1

Requirements

• Exactly one Android device connected over USB.
• Developer options enabled.
• USB debugging enabled and authorized.
• Device state must allow ADB Device Owner provisioning.
• No other Device Owner already configured.

Android permits only one Device Owner. If dpm set-device-owner fails, the raw Android error is authoritative; many already-set-up devices require factory reset or QR/MDM provisioning for Device Owner enrollment.

Windows portable install: recommended for normal users

Do not use PowerShell as the primary path. Windows often blocks .ps1 by default.

Use the portable launcher instead:

1. Download/extract the full repository/bundle.
2. Double-click PixelGuardDeploy.cmd, or run PixelGuardDeploy.exe directly.
3. Choose:
   • [1] Activate protections + install app
   • [2] Verify current state
   • [3] Open Pixel Guard on phone
   • [4] Restore stock-like state

The Windows launcher uses bundled ADB from:

tools\adb\windows-x64\platform-tools\adb.exe

No system-wide ADB install and no PowerShell execution-policy change is required.

macOS / Linux install

chmod +x install.sh verify.sh scripts/adb.sh tools/adb/darwin-universal/adb
./install.sh

Windows PowerShell install: optional legacy path

From PowerShell:

.\install.ps1

Prefer PixelGuardDeploy.exe / PixelGuardDeploy.cmd. PowerShell may be blocked by default Windows execution policy.

After install

On the phone:

1. Open Pixel Guard.
2. Enroll allowed Wi‑Fi networks inside Pixel Guard.
3. Do not add Wi‑Fi networks from Android Settings.
4. Use Pixel Guard Make active buttons to switch between managed networks.

Verify later

./verify.sh

Expected properties:

• com.pixel.guard is Device Owner.
• always_on_vpn_app=null.
• always_on_vpn_lockdown=0.
• Connected Wi‑Fi is metered from netpolicy perspective.
• Risky package UIDs show METERED_ADMIN_DISABLED when present.
• Saved Wi‑Fi networks remain empty; Pixel Guard uses metered suggestions.

Repository layout

app/pixel-guard.apk                 Prebuilt APK installed by scripts
pixel-guard-poc/                    Source snapshot used to build APK
scripts/adb.sh                      Shared POSIX ADB selection/preflight
install.sh                          macOS/Linux installer
verify.sh                           macOS/Linux verification
install.ps1                         Windows PowerShell installer
PixelGuardDeploy.exe                Windows portable menu app
PixelGuardDeploy.cmd                Double-click Windows launcher
windows-deployer/                   Go source for Windows portable menu app
tools/adb/darwin-universal/adb      Bundled macOS ADB
tools/adb/windows-x64/platform-tools Bundled Windows ADB + DLLs + notices

Security notes

• The GitHub token used to publish this repository is not stored here.
• Pixel Guard does not occupy Android's VPN slot.
• Pixel Guard does not create saved Wi‑Fi networks; it uses metered Wi‑Fi suggestions.
• Removing a Device Owner is intentionally not a normal app uninstall path; plan deployment accordingly.