ZapretKVN-android/README.md

Zapret KVN

VPN, который пропускает только необходимое

Zapret KVN — быстрый и бережный Android-клиент для sing-box-extended. Это не ещё одна оболочка над VPN-ядром, а цельная архитектура, в которой приложения, маршруты, DNS и подключение работают как одна система.

По умолчанию выбранные приложения используют режим «Россия напрямую»: российские домены и IP, а также LAN идут через прямую сеть Android, остальное — через VPN. Так VPN-сервер не тратит ресурсы на доступные без обхода сайты.

Сейчас проект находится на стадии pre-release. Целевой ориентир — подтверждённое подключение за 1–2 секунды на реальных устройствах. Это цель финального performance-gate, а не обещание для текущих тестовых сборок.

Скачать тестовую сборку · Посмотреть архитектуру · Изучить маршрутизацию

Минимализм в чистом виде

• Только нужные приложения. Невыбранные приложения вообще не попадают в TUN: их не видят ни VPN-ядро, ни DNS приложения, ни VPN-сервер.
• Россия напрямую по умолчанию. Российские домены и IP, а также LAN сразу идут напрямую. Они не занимают канал и ресурсы VPN-сервера и не получают зарубежный IP без необходимости.
• Только нужные сайты. Для каждого направления можно выбрать действие: через VPN, напрямую или блокировать.
• Без лишних запросов. Нет периодических health-check, бесконечного reconnect, фоновой синхронизации и одновременных запросов к основному и резервному DNS.
• Без тяжёлого фона. Приложение не держит WakeLock, не запускает alarm/job/WorkManager, а статистику обновляет только пока открыт главный экран.
• Rootless hardening. Localhost proxy/API закрываются до запуска ядра; защита не создаёт scanner, timer или отдельный процесс.
• Нативный интерфейс. Компактный Material 3 на стандартных компонентах и анимациях, без тяжёлого dashboard.

Трафик идёт кратчайшим путём

Трафик	Что с ним происходит
Невыбранное приложение	Android сразу отправляет его напрямую; Zapret KVN его не обрабатывает
Выбранный трафик с правилом direct	Проходит локальное правило, но не обращается к VPN-серверу
Выбранный трафик с правилом proxy	Уходит через выбранный VPN-профиль
Заблокированный трафик	Отклоняется локально

Так сервер обрабатывает только тот трафик, ради которого он действительно нужен. Можно направить через VPN отдельные приложения или сайты, оставить Россию напрямую, отправить через VPN только российские ресурсы либо собрать собственные правила.

WireGuard и WARP — с настоящим роутингом

Zapret KVN импортирует WireGuard и AmneziaWG .conf, включая совместимые конфигурации WARP. WireGuard здесь не означает режим «всё устройство целиком через один сервер»: профиль становится полноценным outbound и участвует в тех же правилах direct / proxy / reject.

Это позволяет, например, отправить через WARP только выбранные сайты, остальные открыть напрямую, а другой набор трафика направить через отдельный proxy-outbound в составе конфигурации. Из-за ограничений Android выбранные приложения используют один системный TUN, но решение о маршруте остаётся раздельным для каждого назначения.

У WireGuard два независимых MTU: внешний Android TUN и внутренний userspace endpoint. MTU TUN по умолчанию остаётся 1500, а для WireGuard/AmneziaWG без собственного MTU применяется Android-совместимый внутренний MTU 1280, как в официальном клиенте Amnezia. Явное значение из .conf или JSON всегда имеет приоритет.

Android AAR также применяет один открытый воспроизводимый patch поверх pinned commit: как официальный AmneziaWG backend, он запрещает WireGuard менять peer endpoint после аутентифицированных пакетов на Android. Upstream commit и отдельный SHA-256 patchset публикуются в диагностике и release metadata.

Скрытие VPN без root

В «Настройки → Скрытие VPN» находятся меры, которые реально доступны обычному Android-приложению: запрет дополнительных localhost inbounds, удаление внешних Clash/V2Ray control API, нейтральное имя VPN-сессии и MTU TUN 1500 по умолчанию. Постоянная защита включена по умолчанию, работает только при сборке runtime JSON и не добавляет фоновой нагрузки. Сохранённый профиль не переписывается.

Android всё равно показывает системный VpnService, TRANSPORT_VPN, TUN-интерфейс и VPN indicator. Zapret KVN не называет rootless-режим полной невидимостью и не пытается подменять API других приложений. Точные границы и release-gate описаны в VPN Hiding ADR.

Быстрый и лёгкий — по архитектуре

Внутри приложения один Android VPN service, один TUN и один экземпляр ядра. Здесь нет второго туннеля, дублирующих таблиц правил и постоянного опроса состояния. Конфигурация проверяется до запуска, а при ошибке соединение полностью закрывается вместо бесконечных повторов в фоне.

Автоматизированные проверки уже подтвердили:

• 85/85 JVM-тестов и 67/67 instrumented-тестов на Android API 36;
• полные матрицы на API 26 и 29;
• 100 циклов connect/stop и 50 переходов Wi-Fi ↔ cellular на API 29/36;
• отсутствие собственного периодического сетевого трафика в idle-сценариях;
• обход TUN невыбранным трафиком: в тесте 5 × 8 MiB дали 0 UID RX+TX приложения и медиану 0 TUN bytes.

Физические проверки энергии, OEM-поведения, DNS/NAT64 и финальной скорости подключения ещё входят в release-gate. Подробные результаты и границы измерений опубликованы в GATE8_RESULTS.md.

Профиль добавляется так, как удобно

Можно импортировать JSON, WireGuard/AWG .conf, VLESS, VMess, Trojan, Shadowsocks, Hysteria2 и TUIC из ссылки, подписки, QR-кода, буфера обмена или файла. Перед сохранением приложение показывает preview и проверяет конфигурацию встроенным ядром.

Настоящий sing-box JSON остаётся единственным источником сетевой конфигурации: Zapret KVN не создаёт скрытую копию правил и не теряет незнакомые extended-поля.

Тестовые сборки

Ручные debug-сборки публикуются в GitHub Releases как pre-release. Они используют package io.github.zapretkvn.android.debug и Android debug key, поэтому могут стоять рядом с будущей production-версией.

При ошибке главная сразу показывает стабильный код вида DNS-101 или NET-102 и понятное описание. В «Настройки → Диагностика» видны этот же код, безопасная техническая причина, длительности этапов, bounded-логи и последний Kotlin/Java crash. Кнопка «Экспортировать диагностику» вверху экрана формирует redacted-отчёт без профиля и credentials.

Известные ограничения MVP

• Android 8+; release APK разделены на arm64-v8a, armeabi-v7a и x86_64, интерфейс рассчитан на телефоны.
• Always-on/Lockdown и shared UID не поддерживаются как гарантированный per-app режим.
• Rootless hardening не скрывает системный TRANSPORT_VPN, TUN и установленный APK от другого приложения.
• Managed DNS перехватывает TCP/UDP 53, но не встроенный DoH, DoT или mDNS; FakeIP выключен.
• Domain-only block не является firewall: для гарантии нужен IP/CIDR rule-set.
• Clash YAML и Hysteria v1 URI пока не импортируются; raw JSON остаётся ответственностью пользователя.
• APK проверяется один раз при запуске по выбранному каналу и вручную из настроек; найденное обновление показывает release notes. Загрузка выполняется после подтверждения, установка — только штатным Android installer; silent install недоступен. Подписки не обновляются в фоне, core обновляется только вместе с APK.
• При неработающем proxy/DNS VPN закрывается без бесконечного retry и plaintext DNS fallback.

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

• Архитектура продукта
• Маршрутизация
• DNS и Android VPN
• Скрытие VPN и rootless hardening
• Поддерживаемые форматы импорта
• План реализации
• Результаты Gate 8
• Подпись и восстановление ключа

Сборка для разработчиков

Toolchain

• JDK 17;
• Android Gradle Plugin 9.2.1 и Gradle 9.4.1;
• compile/target SDK 36, min SDK 26;
• Compose BOM 2026.06.00;
• закреплённый sing-box-extended v1.13.14-extended-2.5.2, commit ff11f007ec798136a5de258f947a4f34011a37ea;
• отдельные APK для arm64-v8a, armeabi-v7a и x86_64, без чужих native-библиотек внутри.

Укажите путь к Android SDK в local.properties или ANDROID_HOME, затем запустите локальный аналог CI:

scripts/ci-build.sh

Скрипт собирает закреплённые CLI/AAR, проверяет fixtures и rule-set, запускает Go/Kotlin tests и lint, собирает x86_64 debug APK и три release APK, затем проверяет ABI, stripping, R8 mapping, native symbols и security-инварианты.

Для debug APK другой архитектуры используйте, например:

./gradlew assembleDebug -PzapretAbi=arm64-v8a

Универсальный APK намеренно не создаётся. Сборка также останавливается, если app/libs/libbox.aar отсутствует: динамическая загрузка ядра приложением запрещена.

Полная Android-матрица запускается командой ./gradlew :app:connectedDebugAndroidTest. Дополнительные device/release-проверки описаны в плане реализации и протоколе Gate 8.

Лицензия

Zapret KVN распространяется по лицензии GPL-3.0-or-later. Условия сторонних компонентов перечислены в THIRD_PARTY_NOTICES.md.