diff --git a/README.md b/README.md index 4ef0896..3c9705c 100644 --- a/README.md +++ b/README.md @@ -27,59 +27,86 @@ The target app's process is completely untouched (with kmod + lsposed) — no Xp ## Which modules do I need? -You always need **lsposed** (Java API layer) plus one native module: +You always need the **VPN Hide app** (`vpnhide-lsposed.apk`) plus one native module. The app's **Dashboard** will detect your device and recommend the right one: -- **`kmod` + `lsposed`** (recommended) — fully out-of-process, invisible to anti-tamper. Requires a supported GKI kernel (see below). -- **`zygisk` + `lsposed`** — use this if your device's GKI generation isn't covered by the kmod builds, or if you can't install kernel modules. +- **`kmod`** (recommended) — fully out-of-process, invisible to anti-tamper. Requires a supported GKI kernel. +- **`zygisk`** — use this if your kernel isn't supported by kmod. + +See [Install](#install) for step-by-step instructions. ## Install Download the latest release from [Releases](https://github.com/okhsunrog/vpnhide/releases). -### kmod + lsposed (recommended) +### Step 1 — VPN Hide app + LSPosed -1. Install `vpnhide-kmod-.zip` via KernelSU-Next manager → Modules → Install from storage -2. Install `vpnhide-lsposed.apk` as a regular app -3. In LSPosed manager, enable the vpnhide module and add **"System Framework"** to its scope -4. Reboot (required — LSPosed hooks are injected into `system_server` at boot, so the module must be active before `system_server` starts) -5. Open the VPN Hide app, grant it root access (Magisk will prompt automatically; on KernelSU-Next, grant permission manually in the manager), and select target apps +1. Install `vpnhide-lsposed.apk` as a regular app +2. In LSPosed manager, enable the VPN Hide module and add **"System Framework"** to its scope +3. Reboot (required — LSPosed hooks are injected into `system_server` at boot, so the module must be active before `system_server` starts) +4. Open the VPN Hide app and grant it root access (Magisk will prompt automatically; on KernelSU-Next, grant permission manually in the manager) -**How to find your GKI generation:** +### Step 2 — Native module + +Open the VPN Hide app. The **Dashboard** tab will detect your device and kernel, and tell you exactly which native module to install: + +- If your kernel is supported, it will recommend a specific kmod file (e.g. `vpnhide-kmod-android14-6.1.zip`) +- If not, it will recommend the zygisk module (`vpnhide-zygisk.zip`) + +Install the recommended module: +- **kmod:** via KernelSU-Next manager → Modules → Install from storage +- **zygisk:** via KernelSU-Next or Magisk manager → Modules + +Reboot after installing the native module. + +### Step 3 — Select target apps + +Open the VPN Hide app → **Apps** tab. Use the **L** / **K** / **Z** toggles to control which protection layers apply to each app (LSPosed, Kernel module, Zygisk), or tap the row to toggle all layers at once. Tap Save. + +After changing targets, force-stop and restart the affected apps — hooks take effect on the next app launch. + +> **Note:** some apps detect Zygisk hooks. For those apps, keep **Z** disabled and rely on kmod + LSPosed. + +
+Shell configuration (advanced) + +Edit `/data/adb/vpnhide_kmod/targets.txt`, `/data/adb/vpnhide_zygisk/targets.txt`, or `/data/adb/vpnhide_lsposed/targets.txt` directly (one package name per line). Force-stop and restart affected apps for changes to take effect. + +
+ +
+Manual GKI lookup (if you want to pick the kmod file yourself) 1. On your phone, go to **Settings → About phone** and find the **Kernel version** line. It looks something like `6.1.75-android14-11-g...` 2. You need two parts from this string: the kernel version (`6.1`) and the android generation (`android14`). Together they form your GKI generation: `android14-6.1` 3. Download the matching file from the release: `vpnhide-kmod-android14-6.1.zip` -Alternatively, if you have ADB set up, run `adb shell uname -r` to see the same kernel version string. +Alternatively, run `adb shell uname -r` to see the kernel version string. -> **Important:** the `android14` in the kernel string is NOT your Android version — it's the kernel generation. For example, Pixels from 6 to 9a all use the `android14-6.1` kernel regardless of whether they run Android 14 or 15. Pixel 10 series uses `android16-6.12`. +> **Important:** `android14` in the kernel string is NOT your Android version — it's the kernel generation. For example, Pixels from 6 to 9a all use the `android14-6.1` kernel regardless of whether they run Android 14 or 15. -### zygisk + lsposed - -1. Install `vpnhide-zygisk.zip` via KernelSU-Next or Magisk manager → Modules -2. Install `vpnhide-lsposed.apk` as a regular app -3. In LSPosed manager, enable the vpnhide module and add **"System Framework"** to its scope -4. Reboot (required — LSPosed hooks are injected into `system_server` at boot) -5. Open the VPN Hide app, grant it root access (Magisk will prompt automatically; on KernelSU-Next, grant permission manually in the manager), and select target apps - -## Configuration - -**VPN Hide app (recommended):** open the VPN Hide app (installed as `vpnhide-lsposed.apk`) and grant it root access (Magisk prompts automatically; on KernelSU-Next, grant permission in the manager). It shows all installed apps with icons, names, and search. Check the apps you want to hide VPN from, tap Save. Works with both kmod and zygisk — writes to all target locations automatically via `su`. - -**Shell:** edit `/data/adb/vpnhide_kmod/targets.txt` or `/data/adb/vpnhide_zygisk/targets.txt` directly (one package name per line). Reboot for changes to take effect. - -After changing targets, force-stop and restart the affected apps — hooks take effect on the next app launch. +
## Verify -Open the VPN Hide app, switch to the Diagnostics tab, and run all checks with VPN active. The app auto-adds itself to the target list. All 26 checks should show PASS. +The app has a built-in diagnostics system that catches most setup problems automatically. + +**Dashboard** (runs on every app launch): +- Module status for all three layers (installed, active, version, target count) +- LSPosed configuration validation — reads the LSPosed database to verify that VPN Hide is enabled, System Framework is in scope, and no extra apps are scoped (a common misconfiguration) +- Version mismatch detection — compares installed module versions with the running app version and tells you exactly what to update +- Native module recommendation — detects your kernel and maps it to the right kmod artifact, or recommends zygisk if unsupported +- Live protection check (when VPN is active) — runs 16 native checks and 5 Java API checks to verify that VPN is actually hidden + +Any issues found are shown as actionable cards with specific instructions. + +**Diagnostics** tab — detailed per-check breakdown with individual PASS/FAIL results for all 26 detection vectors. Useful for troubleshooting when the Dashboard shows partial protection. ## Components | Directory | What | How | |---|---|---| | **[kmod/](kmod/)** | Kernel module (C) | `kretprobe` hooks in kernel space. Zero footprint in the target app's process. ([details](kmod/README.md)) | -| **[lsposed/](lsposed/)** | LSPosed module + app (Kotlin + Rust) | Hooks `writeToParcel` in `system_server` for per-UID Binder filtering. The APK serves as target picker, diagnostics (26 checks), and module management UI. ([details](lsposed/README.md)) | +| **[lsposed/](lsposed/)** | LSPosed module + app (Kotlin + Rust) | Hooks `writeToParcel` in `system_server` for per-UID Binder filtering. The APK provides a dashboard (module status, version checks, LSPosed config validation, install recommendations), per-app layer toggles, and diagnostics. ([details](lsposed/README.md)) | | **[zygisk/](zygisk/)** | Zygisk module (Rust) | Inline-hooks `libc.so` in the target app's process. Alternative to kmod. ([details](zygisk/README.md)) | ## Detection coverage diff --git a/README.ru.md b/README.ru.md index 348b661..9da5417 100644 --- a/README.ru.md +++ b/README.ru.md @@ -25,59 +25,86 @@ vpnhide решает обе проблемы двухуровневой архи ## Какие модули нужны? -Всегда нужен **lsposed** (уровень Java API) плюс один нативный модуль: +Всегда нужно **приложение VPN Hide** (`vpnhide-lsposed.apk`) плюс один нативный модуль. Вкладка **«Обзор»** в приложении определит ваше устройство и порекомендует нужный: -- **`kmod` + `lsposed`** (рекомендуется) — полностью out-of-process, невидим для anti-tamper. Требуется поддерживаемое GKI-ядро (см. ниже). -- **`zygisk` + `lsposed`** — используйте, если ваше устройство не поддерживается сборками kmod или если нет возможности установить модуль ядра. +- **`kmod`** (рекомендуется) — полностью out-of-process, невидим для anti-tamper. Требуется поддерживаемое GKI-ядро. +- **`zygisk`** — используйте, если ваше ядро не поддерживается kmod. + +См. [Установка](#установка) для пошаговой инструкции. ## Установка Скачайте последний релиз из [Releases](https://github.com/okhsunrog/vpnhide/releases). -### kmod + lsposed (рекомендуется) +### Шаг 1 — Приложение VPN Hide + LSPosed -1. Установите `vpnhide-kmod-<ваш-gki>.zip` через менеджер KernelSU-Next → Модули → Установить из хранилища -2. Установите `vpnhide-lsposed.apk` как обычное приложение -3. В менеджере LSPosed включите модуль vpnhide и добавьте **«System Framework»** в его область действия -4. Перезагрузите устройство (обязательно — хуки LSPosed внедряются в `system_server` при загрузке, поэтому модуль должен быть активен до запуска `system_server`) -5. Откройте приложение VPN Hide, предоставьте ему root-доступ (Magisk запросит автоматически; на KernelSU-Next выдайте разрешение вручную в менеджере) и выберите целевые приложения +1. Установите `vpnhide-lsposed.apk` как обычное приложение +2. В менеджере LSPosed включите модуль VPN Hide и добавьте **«System Framework»** в его область действия +3. Перезагрузите устройство (обязательно — хуки LSPosed внедряются в `system_server` при загрузке, поэтому модуль должен быть активен до запуска `system_server`) +4. Откройте приложение VPN Hide и предоставьте ему root-доступ (Magisk запросит автоматически; на KernelSU-Next выдайте разрешение вручную в менеджере) -**Как узнать поколение GKI:** +### Шаг 2 — Нативный модуль + +Откройте приложение VPN Hide. На вкладке **«Обзор»** приложение определит ваше устройство и ядро и покажет, какой именно нативный модуль нужно установить: + +- Если ядро поддерживается — будет рекомендован конкретный файл kmod (например, `vpnhide-kmod-android14-6.1.zip`) +- Если нет — будет рекомендован модуль zygisk (`vpnhide-zygisk.zip`) + +Установите рекомендованный модуль: +- **kmod:** через менеджер KernelSU-Next → Модули → Установить из хранилища +- **zygisk:** через менеджер KernelSU-Next или Magisk → Модули + +Перезагрузите устройство после установки нативного модуля. + +### Шаг 3 — Выбор целевых приложений + +Откройте приложение VPN Hide → вкладка **«Приложения»**. Используйте переключатели **L** / **K** / **Z** для управления уровнями защиты каждого приложения (LSPosed, модуль ядра, Zygisk), или нажмите на строку, чтобы переключить все уровни сразу. Нажмите «Сохранить». + +После изменения списка принудительно остановите и перезапустите затронутые приложения — хуки вступают в силу при следующем запуске. + +> **Примечание:** некоторые приложения обнаруживают хуки Zygisk. Для таких приложений оставьте **Z** выключенным и используйте kmod + LSPosed. + +
+Настройка через командную строку (для продвинутых) + +Редактируйте `/data/adb/vpnhide_kmod/targets.txt`, `/data/adb/vpnhide_zygisk/targets.txt` или `/data/adb/vpnhide_lsposed/targets.txt` напрямую (одно имя пакета на строку). Принудительно остановите и перезапустите затронутые приложения для применения изменений. + +
+ +
+Ручной подбор GKI (если хотите выбрать файл kmod самостоятельно) 1. На телефоне откройте **Настройки → О телефоне** и найдите строку **Версия ядра**. Она выглядит примерно так: `6.1.75-android14-11-g...` 2. Вам нужны две части из этой строки: версия ядра (`6.1`) и поколение android (`android14`). Вместе они образуют ваше поколение GKI: `android14-6.1` 3. Скачайте соответствующий файл из релиза: `vpnhide-kmod-android14-6.1.zip` -Также можно выполнить `adb shell uname -r` через ADB, чтобы увидеть ту же строку версии ядра. +Также можно выполнить `adb shell uname -r` через ADB, чтобы увидеть строку версии ядра. -> **Важно:** `android14` в строке ядра — это НЕ версия Android, а поколение ядра. Например, все Pixel с 6 по 9a используют ядро `android14-6.1` вне зависимости от того, стоит ли на них Android 14 или 15. Серия Pixel 10 использует `android16-6.12`. +> **Важно:** `android14` в строке ядра — это НЕ версия Android, а поколение ядра. Например, все Pixel с 6 по 9a используют ядро `android14-6.1` вне зависимости от того, стоит ли на них Android 14 или 15. -### zygisk + lsposed - -1. Установите `vpnhide-zygisk.zip` через менеджер KernelSU-Next или Magisk → Модули -2. Установите `vpnhide-lsposed.apk` как обычное приложение -3. В менеджере LSPosed включите модуль vpnhide и добавьте **«System Framework»** в его область действия -4. Перезагрузите устройство (обязательно — хуки LSPosed внедряются в `system_server` при загрузке) -5. Откройте приложение VPN Hide, предоставьте ему root-доступ (Magisk запросит автоматически; на KernelSU-Next выдайте разрешение вручную в менеджере) и выберите целевые приложения - -## Настройка - -**Приложение VPN Hide (рекомендуется):** откройте приложение VPN Hide (устанавливается как `vpnhide-lsposed.apk`) и предоставьте ему root-доступ (Magisk запрашивает автоматически; на KernelSU-Next выдайте разрешение в менеджере). Приложение показывает все установленные приложения с иконками, названиями и поиском. Отметьте приложения, от которых нужно скрыть VPN, нажмите «Сохранить». Работает и с kmod, и с zygisk — автоматически записывает во все нужные файлы через `su`. - -**Командная строка:** редактируйте `/data/adb/vpnhide_kmod/targets.txt` или `/data/adb/vpnhide_zygisk/targets.txt` напрямую (одно имя пакета на строку). Для применения изменений требуется перезагрузка. - -После изменения целей принудительно остановите и перезапустите затронутые приложения — хуки вступают в силу при следующем запуске приложения. +
## Проверка -Откройте приложение VPN Hide, перейдите на вкладку «Диагностика» и запустите все проверки при активном VPN. Приложение автоматически добавит себя в список целевых. Все 26 проверок должны показать PASS. +В приложении есть встроенная система диагностики, которая автоматически обнаруживает большинство проблем с настройкой. + +**Обзор** (запускается при каждом открытии приложения): +- Статус модулей для всех трёх уровней (установлен, активен, версия, количество целей) +- Валидация конфигурации LSPosed — читает базу данных LSPosed и проверяет, что VPN Hide включён, System Framework в scope, и нет лишних приложений в scope (частая ошибка при настройке) +- Обнаружение несоответствия версий — сравнивает версии установленных модулей с версией приложения и подсказывает, что именно нужно обновить +- Рекомендация нативного модуля — определяет ядро устройства и подбирает нужный файл kmod, или рекомендует zygisk, если ядро не поддерживается +- Проверка защиты в реальном времени (при активном VPN) — выполняет 16 нативных и 5 Java API проверок, чтобы убедиться, что VPN действительно скрыт + +Все обнаруженные проблемы показываются в виде карточек с конкретными инструкциями по исправлению. + +**Диагностика** — детальная разбивка по каждой проверке с индивидуальными результатами PASS/FAIL для всех 26 векторов обнаружения. Полезна для отладки, когда «Обзор» показывает частичную защиту. ## Компоненты | Директория | Что | Как | |---|---|---| | **[kmod/](kmod/)** | Модуль ядра (C) | Хуки `kretprobe` в пространстве ядра. Нулевой след в процессе приложения. ([подробнее](kmod/README.md)) | -| **[lsposed/](lsposed/)** | LSPosed-модуль + приложение (Kotlin + Rust) | Хуки `writeToParcel` в `system_server` для per-UID фильтрации Binder. APK служит для выбора целей, диагностики (26 проверок) и управления модулями. ([подробнее](lsposed/README.md)) | +| **[lsposed/](lsposed/)** | LSPosed-модуль + приложение (Kotlin + Rust) | Хуки `writeToParcel` в `system_server` для per-UID фильтрации Binder. APK предоставляет обзорную панель (статус модулей, проверка версий, валидация конфигурации LSPosed, рекомендации по установке), поуровневое управление приложениями и диагностику. ([подробнее](lsposed/README.md)) | | **[zygisk/](zygisk/)** | Zygisk-модуль (Rust) | Inline-хуки `libc.so` в процессе приложения. Альтернатива kmod. ([подробнее](zygisk/README.md)) | ## Покрытие обнаружения diff --git a/lsposed/app/build.gradle.kts b/lsposed/app/build.gradle.kts index eff4fd2..f4a9289 100644 --- a/lsposed/app/build.gradle.kts +++ b/lsposed/app/build.gradle.kts @@ -26,14 +26,14 @@ android { signingConfigs { create("release") { val keystorePropertiesFile = rootProject.file("keystore.properties") - val keystoreProperties = Properties() if (keystorePropertiesFile.exists()) { + val keystoreProperties = Properties() keystoreProperties.load(FileInputStream(keystorePropertiesFile)) + keyAlias = keystoreProperties["keyAlias"] as String + keyPassword = keystoreProperties["password"] as String + storeFile = file(keystoreProperties["storeFile"] as String) + storePassword = keystoreProperties["password"] as String } - keyAlias = keystoreProperties["keyAlias"] as String - keyPassword = keystoreProperties["password"] as String - storeFile = file(keystoreProperties["storeFile"] as String) - storePassword = keystoreProperties["password"] as String } }