WhiteListChecker

Android-приложение для проверки мобильной сети и обнаружения признаков режима белых списков.

Приложение проверяет именно мобильную сеть через ConnectivityManager + Network.openConnection(), даже если активная сеть телефона — Wi-Fi.

Текущая dev-версия: 0.8.15

Последний релиз: v0.7.1-hotfix · GitHub Releases

Статус проекта

Проект находится на стадии MVP/beta.

Приложение уже можно использовать для ручной проверки и тестовой автопроверки, но возможны ложные срабатывания и особенности работы на разных прошивках Android.

WhiteListChecker определяет признаки сетевого режима, а не внутренние правила оператора.

Уже реализовано:

• ручная проверка мобильной сети;
• классификация признаков белых списков;
• локальные уведомления;
• Telegram через пользовательский Cloudflare Worker;
• очередь Telegram;
• автопроверка через WorkManager;
• политики уведомлений для автопроверки;
• активный мониторинг через foreground service с постоянным уведомлением;
• команды Telegram-бота /status, /check, /help во время активного мониторинга;
• центральный Cloudflare-сервис с публичным Telegram-ботом для агрегированных данных;
• добровольная отправка обезличенных результатов в общий сервис;
• фиксированный URL центрального сервиса из BuildConfig, без пользовательского поля URL;
• автоматическое и ручное определение региона, города и мобильного оператора для public reports;
• привязка Telegram-чата к устройству для удалённой проверки во время активного мониторинга;
• диагностика;
• редактируемые сайты.

Android permissions

Приложение использует:

• INTERNET — сетевые проверки;
• ACCESS_NETWORK_STATE — чтение активной сети и состояния подключений;
• CHANGE_NETWORK_STATE — требуется для ConnectivityManager.requestNetwork(), чтобы явно запросить мобильную сеть при активном Wi-Fi;
• ACCESS_COARSE_LOCATION — разовое приблизительное местоположение по явному нажатию пользователя для определения региона и города;
• FOREGROUND_SERVICE — запуск активного мониторинга с постоянным уведомлением;
• FOREGROUND_SERVICE_DATA_SYNC — тип foreground service для сетевой синхронизации на Android 14+;
• POST_NOTIFICATIONS — локальные уведомления на Android 13+;
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS — переход в настройки энергосбережения для автопроверки.

Безопасность

Не публикуйте:

• BOT_TOKEN;
• RELAY_SECRET;
• local.properties;
• release keystore;
• реальные логи с секретами.

BOT_TOKEN должен храниться только в Cloudflare Worker secrets.

Подробнее: SECURITY.md

Возможности

• ручная проверка мобильной сети;
• группы FOREIGN / LOCAL сайтов;
• классификация:
  • белые списки не обнаружены;
  • похоже на включённые белые списки;
  • мобильного интернета нет;
  • проблема DNS в мобильной сети;
  • частичная проблема сети;
  • мобильная сеть недоступна;
• подтверждение смены состояния через 2 проверки подряд;
• локальные Android-уведомления только при смене статуса;
• Telegram-уведомления через пользовательский Cloudflare Worker relay;
• несколько Telegram-получателей;
• очередь неотправленных Telegram-сообщений (Room);
• публичный Telegram-бот центрального сервиса без требования установить приложение;
• отдельные согласия на отправку обезличенных reports и удалённые проверки;
• автоопределение региона/города через платформенный LocationManager + Geocoder с ручным fallback;
• автоопределение оператора по active/default data subscription с ручным override;
• автопроверка через WorkManager;
• редактируемый список сайтов;
• диагностика и подробный отчёт.

Стек

• Kotlin
• Android native
• Jetpack Compose
• Material 3
• MVVM + UseCase
• Coroutines / Flow
• DataStore Preferences
• Room
• WorkManager
• OkHttp (только HTTPS к Cloudflare Worker relay)

minSdk 26 · compileSdk / targetSdk 35

Документация

• Текущий MVP
• Стек технологий
• Cloudflare Worker relay
• Центральный публичный сервис
• Cloudflare Public Service
• Public report contract
• Remote command flow
• Public data sharing privacy
• Mobile routing, VPN и Private DNS
• Telegram bot buttons and distributed reports
• Changelog
• Release v0.7.1 Hotfix
• Contributing
• Security
• Инструкции для агента
• Версии: v0.1 … v0.6
• Legacy: архив

Требования

• JDK 17+
• Android SDK (ANDROID_HOME или local.properties → sdk.dir)
• Platform android-35, Build-Tools 35.x
• Git

Скопируй local.properties.example → local.properties и укажи путь к SDK локально.

Сборка

.\gradlew.bat assembleDebug

APK: app/build/outputs/apk/debug/app-debug.apk

Установка на устройство

adb devices
adb install -r -d app\build\outputs\apk\debug\app-debug.apk

Telegram через Cloudflare Worker

WhiteListChecker не хранит BOT_TOKEN в Android.

Каждый пользователь сам создаёт:

1. Telegram-бота через BotFather;
2. Cloudflare Worker;
3. Worker secrets:
   • BOT_TOKEN
   • RELAY_SECRET.

В приложении вводятся:

• Worker URL;
• Relay Secret;
• Telegram-получатели / chat_id.

Подробная инструкция: docs/cloudflare-worker/README.md

Схема:

Android → user's Cloudflare Worker → Telegram Bot API

Центральный публичный сервис

Начиная с dev-версии 0.8.14 проект содержит отдельный Cloudflare Worker MVP для центрального публичного сервиса:

Android-приложения пользователей → центральный Cloudflare Worker → D1 → публичный Telegram-бот

Это не замена личного Telegram relay.

Начиная с dev-версии 0.8.15 URL центрального сервиса встроен в сборку через BuildConfig.PUBLIC_SERVICE_BASE_URL:

• пользователь не вводит и не редактирует URL общего сервиса;
• debug/release URL задаются в Gradle и не являются секретом;
• пользовательский Worker URL личного Telegram relay остаётся отдельной настройкой.

Сценарии разделены:

• Статус по данным пользователей — доступен любому пользователю публичного бота, приложение не требуется; бот показывает сохранённые агрегированные данные.
• Проверить на моём устройстве — доступно только связанному Telegram-чату и только пока в Android работает активный мониторинг.

В Android согласия независимы и выключены по умолчанию:

• отправлять обезличенные результаты в общий сервис;
• разрешить удалённые проверки из Telegram.

Для public reports пользователь выбирает или подтверждает:

• регион;
• необязательный город;
• мобильного оператора.

Автоопределение местоположения запускается только по нажатию, использует приблизительное location permission, не сохраняет и не отправляет координаты. Оператор определяется по текущей/default SIM мобильных данных; ручной выбор не перезаписывается автоматикой.

Подробно: docs/architecture/central-public-service.md

Дорожная карта

Версия	Содержание
v0.1	Ручная проверка мобильной сети
v0.2	Группы FOREIGN / LOCAL
v0.3	Подтверждение смены состояния
v0.3.5	Локальные уведомления
v0.4.2	Telegram через Cloudflare Worker relay
v0.5	Очередь Telegram
v0.6	WorkManager автопроверка
v0.7	UI cleanup, редактируемые сайты, диагностика
v0.8.14	Центральный public service MVP
v0.8.15	Fixed public service URL, auto/manual area and operator selection

Лицензия

Проект распространяется под лицензией MIT. См. LICENSE.