Настройте оптимальный уровень защиты для надёжной безопасности мобильного приложения.
# Введение в ГостПротектор
## 1. Что такое ГостПротектор?
ГостПротектор – это комплексное автономное решение для обеспечения защиты мобильных приложений и библиотек на платформах `Android` и `iOS`.
ГостПротектор осуществляет анализ, защиту и подпись вашего приложения или библиотеки или SDK. После развертывания приложения ГостПротектор начинает его мониторинг и защиту во время выполнения (RASP). Имеется возможность автоматической передачи данных о рисках, угрозах и атаках в вашу учетную запись в системе телеметрии атак и аналитики угроз Элис.
Механизмы защиты ГостПротектор включают:
* **Защиту кода и ресурсов** посредством обфускации и шифрования для предотвращения статического анализа и реверс-инжиниринга.
* **Runtime Application Self-Protection (RASP)** – защиту приложений в процессе выполнения, обеспечивающая непрерывный мониторинг операционной среды и сетевых коммуникаций для предотвращения динамического анализа и атак типа "человек посередине".
* **Проверки целостности** для предотвращения модификации кода и клонирования приложений.
* **Выделенный КриптоМодуль**, обеспечивающий изолированное хранение и обработку криптографических данных в доверенной среде исполнения (Trusted Execution Environment), для предотвращения компрометации криптографических ключей и несанкционированных вычислений.
ГостПротектор работает непосредственно с скомпилированными пакетами (`APKs`, `AABs`, `AARs`, `IPAs`, `xcarchives` и `iOS Frameworks`), не требуя внесения изменений в исходный код. Для начала работы необходимо загрузить ГостПротектор, указать целевой пакет, задать параметры конфигурации и запустить процесс защиты.
## 2. Схема работы ГостПротектор
1. **Загрузите** `APK`/`AAB`/`AAR`/`IPA`/`xcarchive`/`iOS Framework` файл в ГостПротектор.
2. **Выберите** параметры защиты, используя `файл конфигурации` ГостПротектор или интерфейс "Настройка параметров защиты" в `ГостПротектор Студии`.
3. ГостПротектор **проанализирует** структуру пакета, выявляя элементы, подлежащие защите.
4. ГостПротектор **применит** механизмы защиты на уровне байт-кода и нативном уровне к классам, методам, строкам и ресурсам, автоматически интегрируя средства защиты приложений во время выполнения (Runtime Application Self-Protection).
5. ГостПротектор **сформирует** защищенный `APK`/`AAB`/`AAR`/`IPA`/`iOS Framework` файл, подписанный в соответствии с указанной конфигурацией и готовый к тестированию или публикации.
6. После развертывания приложения, ГостПротектор **начнет** мониторинг его безопасности, при необходимости передавая данные о рисках, угрозах и инцидентах в реальном времени в вашу учетную запись в системе телеметрии атак и аналитики угроз.
## 3. ГостПротектор Студия
`ГостПротектор Студия` – это настольное приложение, поставляемое в комплекте с каждой лицензией ГостПротектор. Студия предоставляет графический интерфейс для управления всеми аспектами процесса защиты ГостПротектор, позволяя:
* Активировать лицензию ГостПротектор.
* Визуализировать результаты анализа входного файла.
* Настраивать параметры защиты проекта.
* Создавать профили защиты.
* Наглядно представлять применение механизмов защиты ГостПротектор к коду и ресурсам.
* Управлять интеграцией с системой телеметрии атак и аналитики угроз.
## 4. Элис - Система телеметрии атак и аналитики угроз
После развертывания приложения, ГостПротектор начинает мониторинг его безопасности в любой точке мира, передавая данные (при условии активации данной системы) о рисках, угрозах и инцидентах в реальном времени в вашу учетную запись в системе телеметрии атак и аналитики угроз.
Элис предоставляет удобную панель управления для отслеживания ключевых инцидентов, включая аномалии, связанные с HTTP Public Key Pinning, несанкционированную модификацию, сбои и обнаружение зловредного программного обеспечения на устройстве. Данные об инцидентах могут быть отфильтрованы по времени и географическому положению. Предусмотрена возможность настройки формата выходных данных в соответствии с требованиями к отчетности.
ГостПротектор и Элис могут быть интегрированы с существующими системами анализа рисков, обеспечивая получение информации о состоянии безопасности в наиболее удобном для организации формате.
---
*Для получения дополнительной информации, запроса пробной или коммерческой лицензии ГостПротектор, пожалуйста, напишите на gostprotector@licel.ru*
# ГостПротектор для Android
## Обзор
`ГостПротектор` обеспечивает защиту Android-приложений и библиотек от статического и динамического анализа, несанкционированного вмешательства, реверс-инжиниринга и атак типа "человек посередине".
`ГостПротектор` работает с уже скомпилированными пакетами **любого размера** на завершающем этапе процесса сборки, интегрируя механизмы защиты как на уровне байт-кода, так и на нативном уровне.
ГостПротектор легко интегрируется в **любой цикл разработки**, обеспечивая поддержку как нативных, так и кроссплатформенных приложений, а также инструментов сборки, таких как Gradle, и платформ CI/CD, таких как Bitrise, Jenkins, Azure Pipelines и Bitbucket Pipelines.
## Ключевые особенности ГостПротектор для Android:
**Защита кода**
* Шифрование строк
* Шифрование классов
* Сокрытие доступа к вызовам методов и полям
* Обфускация нативного кода
* Шифрование нативного кода
* Защита от отладки нативного кода
* Шифрование аннотаций
**Защита ресурсов**
* Шифрование ресурсов
* Шифрование кода HTML, JS и CSS
* Поддержка внешнего доступа к зашифрованным ресурсам
* Шифрование папки `res` и файла `strings.xml`
* Маскирование `AndroidManifest`
* Шифрование ресурсов в каталоге `root`
* Шифрование криптографических материалов
**Контроль целостности**
* Проверки сертификатов
* Проверки целостности кода
* Проверки целостности ресурсов
**Защита сетевых подключений**
* Мониторинг статуса сетевой безопасности
* Закрепление открытых ключей (Public Key Pinning)
* Прозрачность сертификатов (Certificate Transparency)
**Runtime Application Self-Protection (RASP)** – Защита приложений во время выполнения
* Механизмы защиты от отладки
* Механизмы защиты пользовательского интерфейса
* Проверки окружения (обнаружение и информирование о рутованных устройствах, эмуляторах, отладчиках, перехвате вызовов, несанкционированном вмешательстве и т.д.)
# Начало работы
## 1. Загрузка
Загрузка и активация `ГостПротектор`. После запроса пробной версии или приобретения полной лицензии, вы получите электронное письмо, содержащее ссылку для загрузки и уникальный одноразовый код активации.
Перейдите по ссылке, чтобы загрузить ZIP-архив с дистрибутивом. Извлеките содержимое архива в целевой каталог.
### Содержимое дистрибутивного пакета
* Исполняемый JAR-файл — `protector.jar`
* Библиотека аннотаций — `protector-annotations.jar`
* Maven-плагин — `protector-maven-plugin.jar`
* Gradle-плагин — `protector-gradle-plugin.jar`
* Файл конфигурации — `protector.xml`
* Файл настроек Ant — `custom_rules.xml`
* Тексты лицензий — `NOTICE`, `LICENSE`
> ⚠️ В электронном письме с дистрибутивом также будет содержаться ссылка на ГостПротектор Студию.
## 2. Активация
Вы можете активировать ГостПротектор через интерфейс командной строки или через ГостПротектор Студию; активация возможна как в режиме онлайн, так и в режиме оффлайн.
> ⚠️ Коды активации являются одноразовыми. В случае утери исходного файла лицензии или изменения аппаратной или программной конфигурации, вам потребуется обратиться в службу поддержки для получения нового кода.
### Активация через CLI (онлайн)
Чтобы активировать ГостПротектор онлайн через командную строку, выполните следующую команду и следуйте инструкциям:
```bash
java -jar protector.jar -activate
```
После успешной активации в домашней папке пользователя будет создан файл лицензии protector.licel.
Чтобы использовать файл лицензии, расположенный в каталоге отличным от домашнего каталога пользователя, укажите путь к файлу лицензии с помощью специальной опции, предоставляемой в CLI.
### Активация через CLI (оффлайн)
Чтобы активировать ГостПротектор оффлайн через командную строку, выполните следующую команду:
```bash
java -jar protector.jar -activationRequest
```
Введите код активации поcле запроса. После ввода актуального кода активации будет сгенерирован код запроса. Отправьте этот код в нашу службу поддержки по электронной почте gostprotector@licel.ru.
Вы получите код ответа не позднее, чем в течение 1 рабочего дня.
После получения кода ответа выполните следующую команду и введите код ответа после запроса:
```bash
java -jar protector.jar -activationResponse
```
После успешной активации в домашней папке пользователя будет создан файл лицензии protector.licel.
Чтобы использовать файл лицензии, расположенный не в домашней папке, необходимо указать путь к файлу лицензии.
### Активация через ГостПротектор Студию (онлайн)
1. Нажмите «Информация о лицензии» справа от панели в нижней части окна.
2. Нажмите «Активировать лицензию» и следуйте инструкциям в новом окне. Чтобы активировать лицензию и получить файл лицензии **онлайн**, просто введите уникальный одноразовый код активации, указанный в электронном письме со ссылками для загрузки.
3. После успешной активации в домашнем каталоге пользователя будет создан файл лицензии `protector.licel`.
### Активация через ГостПротектор Студию (оффлайн)
1. Нажмите «Информация о лицензии» справа от панели в нижней части окна.
2. Нажмите «Активировать лицензию» и следуйте инструкциям в новом окне. Если у вас нет активного подключения к Интернету или вы предпочитаете автономную активацию, введите уникальный одноразовый код активации, указанный в электронном письме со ссылками для загрузки, и нажмите «Создать запрос активации».
3. После ввода действительного кода активации будет сгенерирован код запроса. Отправьте этот код запроса в нашу службу поддержки по электронной почте gostprotector@licel.ru. Вы получите код ответа в течение 1 рабочего дня.
4. После получения кода ответа вернитесь в то же окно «Активировать лицензию» и нажмите «У меня уже есть код ответа активации». В следующем окне введите полученный код ответа и нажмите «Активировать», чтобы завершить процедуру активации лицензии.
5. После успешной активации в домашнем каталоге пользователя будет создан файл лицензии `dprotector.licel`.
## 3. После активации
После успешной активации ГостПротектор вы можете начать процесс защиты своего приложения. Первым шагом является указание того, что вы хотите защитить и как именно вы хотите это сделать, путем настройки параметров защиты.
# Настройка ГостПротектор
## Введение в настройку ГостПротектор
`ГостПротектор` наиболее эффективен при индивидуальной настройке под ваше приложение.
Настройка осуществляется с помощью единого XML-файла, который можно редактировать непосредственно или через интерфейс ГостПротектор Студии. Файл конфигурации по умолчанию (`protector.xml`) находится в корневом каталоге дистрибутивного пакета, но каждое приложение (или библиотека) имеет разные требования. Поэтому настоятельно рекомендуется создать собственную индивидуальную конфигурацию, чтобы правильно определить код и ресурсы, подлежащие защите.
Вы можете использовать файл конфигурации для управления процессом ГостПротектор в соответствии с вашими задачами. Файл конфигурации позволяет указать следующие параметры:
* Параметры сборки и ведения журнала для процесса ГостПротектор
* Методы подписи
* Механизмы защиты и фильтры для включения/исключения кода и ресурсов из защиты
* Проверки окружения для обнаружения рутованных устройств, отладчиков, эмуляторов и средств перехвата вызовов (RASP)
* Параметры защиты сетевых подключений, включая мониторинг сертификатов для механизмов Certificate Transparency и Public Key Pinning
* Интеграция с системой мониторинга об угрозах и телеметрии атак.
### Рекомендации по защите
Рекомендуется использовать все предоставляемые функции безопасности, поскольку каждый элемент защиты повышает уровень безопасности и устойчивость к вредоносному ПО, реверс-инжинирингу, несанкционированному вмешательству и атакам типа "человек посередине".
> **Примечание:** Для некоторых функций требуется лицензия ГостПротектор Enterprise. Для получения дополнительной информации обратитесь в нашу службу поддержки по электронной почте gostprotector@licel.ru
## Обзор файла конфигурации
<pre><code class="language-xml"><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<protector>
<!-- Параметры сборки и ведения журнала для процесса ГостПротектор -->
<verbose>false</verbose>
<optimize>false</optimize>
<securityAssessment>
<signingCertificateCompromised mode="error"/>
<signingCertificateWeakKey mode="error"/>
<dependencyCheck mode="warning" />
</securityAssessment>
<proguardMapFile>no_default</proguardMapFile>
<!-- Методы подписи -->
<signMode>debug</signMode>
<keystore>no_default</keystore>
<storepass>no_default</storepass>
<alias>no_default</alias>
<keypass>no_default</keypass>
<certificate>no_default</certificate>
<sha256CertificateFingerprint>no_default</sha256CertificateFingerprint>
<legacySha256CertificateFingerprint>no_default</legacySha256CertificateFingerprint>
<!-- Удаление небезопасных вызовов -->
<stripLogging>no_default</stripLogging>
<stripMethodCalls>
<filters>
<filter>no_default</filter>
</filters>
</stripMethodCalls>
<!-- Механизмы защиты кода -->
<stringEncryption/>
<annotationEncryption/>
<jniObfuscation/>
<hideAccess/>
<classEncryption/>
<nativeLibraryEncryption/>
<!-- Механизмы защиты ресурсов -->
<resourceEncryption>
<assets>
<filters>
<filter>no_default</filter>
</filters>
</assets>
<res>
<filters>
<filter>no_default</filter>
</filters>
</res>
<strings>
<filters>
<filter>no_default</filter>
</filters>
</strings>
<nameObfuscation>
<filters>
<filter>no_default</filter>
</filters>
</nameObfuscation>
<androidManifestMangling/>
<xamarinAssemblies/>
</resourceEncryption>
<!-- RASP - Проверки окружения для обнаружения рутованных устройств,
отладчиков, эмуляторов и средств перехвата вызовов -->
<antiDebug>true</antiDebug>
<antiEmulator>true</antiEmulator>
<antiManualInstall>true</antiManualInstall>
<antiMalware>true</antiMalware>
<runtimeChecks/>
<!-- Параметры защиты сетевых подключений -->
<publicKeyPinning src="no_default">
<trace>0</trace>
<actions>block, report</actions>
<network-security-config>
<domain-config>
<domain includeSubdomains="false">...</domain>
<pin-set expiration="no_default">
<pin digest="no_default"></pin>
</pin-set>
</domain-config>
</network-security-config>
</publicKeyPinning>
<certificateTransparency>
<trace>0</trace>
<domain includeSubdomains="false">no_default</domain>
<!-- <logFile>no_default</logFile> -->
</certificateTransparency>
<!-- Защита пользовательского интерфейса -->
<uiProtection/>
<!-- Интеграция с системой мониторинга об угрозах и телеметрии атак -->
<reportMonitoring>
<apiKey>no_default</apiKey>
<!-- <customFieldsUpdate>no_default</customFieldsUpdate> -->
<trace>0</trace>
</reportMonitoring>
<!-- Параметры защиты библиотек (AAR) -->
<aar autoInit="on" autoInitAuthorities="${applicationId}">
<!-- <initMethod>...</initMethod> -->
<!-- <initClass>...</initClass> -->
<!-- <kotlinSupport>...</kotlinSupport> -->
<!-- <nativeClassEncryption>...</nativeClassEncryption> -->
<!-- <nativeHideAccess>...</nativeHideAccess> -->
</aar>
</protector>
</code></pre>
## Описание параметров конфигурации
*(Примечание: В следующих разделах подробно описываются элементы, представленные выше. Для форматирования используются заголовки для категорий и подзаголовки для отдельных элементов.)*
### Параметры сборки
**Подробное ведение журнала** (`boolean`)
* **Элемент:** `<verbose>`
* **Описание:** Включает/отключает подробное ведение журнала для процесса ГостПротектор.
* **Допустимые значения:** `true`; `false`.
* **Значение по умолчанию:** `false`
```xml
<verbose>false</verbose>
```
**Оптимизация кода** (`boolean`)
* **Элемент:** `<optimize>`
* **Описание:** Удаляет из кода избыточные метаданные, которые могут негативно повлиять на производительность и/или использоваться злоумышленниками.
* **Допустимые значения:** `true`; `false`.
* **Значение по умолчанию:** `false`
```xml
<optimize>false</optimize>
```
**Оценка безопасности**
* **Элемент:** `<securityAssessment>`
* **Описание:** Если оценка безопасности включена, процесс ГостПротектор завершится с ошибкой, если будет обнаружено, что сертификат подписи скомпрометирован или признан слабее рекомендованного.
* **Допустимые значения:** `true`; `false`.
* **Значение по умолчанию:** `false`
* **Вложенные элементы:** (`<signingCertificateCompromised>`, `<signingCertificateWeakKey>`, `<dependencyCheck>`)
* **Элемент (вложенный):** `<signingCertificateCompromised>`
* **Описание:** Если сертификат подписи скомпрометирован, процесс ГостПротектор выдаст ошибку, и сборка завершится неудачей.
* **Допустимые значения:** `warning`; `error`; `off`.
* **Значение по умолчанию:** `error`
* **Элемент (вложенный):** `<signingCertificateWeakKey>`
* **Описание:** Если ключ подписи является слабым (например, RSA-ключ длиной менее 2048 бит), процесс ГостПротектор выдаст ошибку, и сборка завершится неудачей.
* **Допустимые значения:** `warning`; `error`; `off`.
* **Значение по умолчанию:** `error`
* **Элемент (вложенный):** `<dependencyCheck>`
* **Описание:** Проверяет зависимости приложения на наличие известных уязвимостей.
* **Допустимые значения:** `warning`; `error`; `off`.
* **Значение по умолчанию:** `warning`
<pre><code class="language-xml"><securityAssessment>
<signingCertificateCompromised mode="error"/>
<signingCertificateWeakKey mode="error"/>
<dependencyCheck mode="warning" />
</securityAssessment>
</code></pre>
**Файл соответствий ProGuard** (`string`)
* **Элемент:** `<proguardMapFile>`
* **Описание:** Указывает абсолютный путь к файлу соответствий ProGuard. Если вы используете ProGuard для обфускации имен, необходимо указать путь к файлу соответствий ProGuard, чтобы ГостПротектор мог найти классы для защиты по их оригинальному имени.
* **Значение по умолчанию:** отсутствует.
* **Примечание:** При использовании Gradle-плагина ГостПротектор значение `proguardMapFile` (при необходимости) устанавливается автоматически.
```xml
<proguardMapFile>/path/to/mapping.txt</proguardMapFile>
```
### Подпись
**Режим подписи** (`string`)
* **Элемент:** `<signMode>`
* **Описание:** Определяет параметры для подписи приложения.
* **Допустимые значения:**
* `debug` — подпись выполняется с использованием ключа отладки, полученного из `${USER_HOME}/.android/debug.keystore`
* `release` — подпись выполняется с использованием ключа разработчика
* `google` — режим подписи, используемый с подписью приложений Google Play (см. Подпись приложений Google Play)
* `amazon` — режим подписи, используемый для Amazon Appstore (см. Подпись приложений Amazon)
* `none` — ключ подписи отсутствует. Это целесообразно только в тех случаях, когда подпись будет выполняться на более позднем этапе, например, с помощью ключа производителя или платформы для системных приложений.
```xml
<signMode>google</signMode>
```
**Информация о хранилище ключей** (для `signMode == release`; `signMode == google`; `signMode == amazon`)
* **Элемент:** `<keystore>`
* **Описание:** Указывает путь к хранилищу ключей, содержащему соответствующий ключ подписи.
* **Значение по умолчанию:** отсутствует. **Примечание:** С помощью Gradle-плагина ГостПротектор путь указывается автоматически.
* **Элемент:** `<storepass>`
* **Описание:** Указывает пароль к хранилищу ключей, содержащему соответствующий ключ подписи.
* **Значение по умолчанию:** отсутствует. **Примечание:** С помощью Gradle-плагина ГостПротектор путь указывается автоматически.
* **Элемент:** `<alias>`
* **Описание:** Указывает строку псевдонима для соответствующего ключа подписи в вашем хранилище ключей.
* **Значение по умолчанию:** отсутствует. **Примечание:** С помощью Gradle-плагина ГостПротектор путь указывается автоматически.
* **Элемент:** `<keypass>`
* **Описание:** Указывает пароль для ключа подписи.
* **Значение по умолчанию:** отсутствует. **Примечание:** С помощью Gradle-плагина ГостПротектор путь указывается автоматически.
<pre><code class="language-xml"><keystore>/home/developer/example.keystore</keystore>
<storepass>examplestorepass</storepass>
<alias>examplealias</alias>
<keypass>examplekeypass</keypass>
</code></pre>
**Информация о хранилище ключей** (для `signMode == google`)
* **Элемент:** `<sha256CertificateFingerprint>`
* **Описание:** Указывает отпечаток сертификата SHA-256, соответствующий ключу подписи приложения Google Play, используемому при подписи приложения Play.
* **Значение по умолчанию:** отсутствует. **Примечание:** С помощью Gradle-плагина ГостПротектор значение определяется автоматически.
* **Элемент:** `<legacySha256CertificateFingerprint>`
* **Описание:** Если вы публикуете свое приложение в Google Play, вы можете обновить ключ подписи для своего опубликованного приложения через Play Console — ваш новый ключ используется для подписи новых установок и обновлений приложений, а ваш старый ключ подписи приложений используется для подписи обновлений для пользователей, которые установили ваше приложение до обновления ключа. Если вы обновили ключ подписи для своего опубликованного приложения и используете ГостПротектор для обновления, вы должны указать как отпечаток сертификата SHA-256, соответствующий новому ключу, так и устаревший отпечаток сертификата SHA-256, соответствующий исходному ключу.
* **Значение по умолчанию:** отсутствует.
<pre><code class="language-xml"><signMode>google</signMode>
<keystore>/home/developer/upload.keystore</keystore>
<storepass>upload_password</storepass>
<alias>upload_alias</alias>
<keypass>upload_key_password</keypass>
<sha256CertificateFingerprint>AB:CD:EF:...</sha256CertificateFingerprint>
<!-- <legacySha256CertificateFingerprint>12:34:56:...</legacySha256CertificateFingerprint> -->
</code></pre>
### Удаление небезопасных вызовов
**Удаление вызовов ведения журнала**
* **Элемент:** `<stripLogging>`
* **Описание:** Предотвращает нежелательные выводы журнала, блокируя вызов методов с `android.util.Log`. Уровни детализации (от наименьшей к наибольшей) — WTF, ERROR, WARNING, INFO, DEBUG, VERBOSE.
* **Допустимые значения:** `wtf` [удалить `android.util.Log.wtf(...)`]; `error` [удалить `android.util.Log.e(...)`]; `warning` [удалить `android.util.Log.w(...)`]; `info` [удалить `android.util.Log.i(...)`]; `debug` [удалить `android.util.Log.d(...)`]; `verbose` [удалить `android.util.Log.v(...)`]; `all` [удалить все вышеперечисленное]
```xml
<stripLogging>all</stripLogging>
```
**Удаление вызовов методов**
* **Элемент:** `<stripMethodCalls>`
* **Описание:** Удаляет вызов указанных методов (например, вызовы методов сторонних библиотек ведения журнала).
* **Элемент (вложенный):** `filters` (только если mode != off):
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><stripMethodCalls>
<filters>
<filter>glob:com/example/debug/Logger.**</filter>
</filters>
</stripMethodCalls>
</code></pre>
### Защита кода
**Шифрование строк**
* **Элемент:** `<stringEncryption>`
* **Описание:** Включает механизм шифрования строк ГостПротектор. **Примечание:** Мы рекомендуем шифровать как можно больше строк, но особенно те, которые содержат конфиденциальные данные (логины, пароли, учетные данные API, ключи и т. д.). С другой стороны, нет необходимости шифровать какие-либо строки, содержащиеся в общедоступных сторонних библиотеках, и файл конфигурации ГостПротектор по умолчанию содержит определенные примеры фильтров для исключения таких библиотек из процесса шифрования строк.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><stringEncryption>
<filters>
<filter>glob:!com/google/**</filter>
<filter>glob:com/mycompany/sensitive/**</filter>
</filters>
</stringEncryption>
</code></pre>
**Шифрование аннотаций**
* **Элемент:** `<annotationEncryption>`
* **Описание:** Шифрует аннотации Kotlin для защиты конфиденциальных метаданных. **Важно:** Фильтры для шифрования аннотаций работают иначе, чем для других механизмов. Фильтры должны быть указаны на классы, в которых определены аннотации, а не на классы, в которых аннотации используются. Затем ГостПротектор найдет все использования аннотаций согласно фильтру и зашифрует их.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><annotationEncryption>
<filters>
<filter>glob:kotlin/Metadata.class</filter> <!-- Example: Encrypt standard Kotlin metadata -->
<filter>glob:com/mycompany/annotations/SecretAnnotation.class</filter>
</filters>
</annotationEncryption>
</code></pre>
**Обфускация JNI**
* **Элемент:** `<jniObfuscation>`
* **Описание:** Включает обфускацию имен методов JNI (Java Native Interface) в нативных библиотеках и классах в соответствии с указанными фильтрами. **Примечание:** При установке фильтров для обфускации JNI вам нужно указать только классы, содержащие методы JNI. Затем ГостПротектор автоматически обработает нативные библиотеки, содержащие методы JNI из этих классов.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><jniObfuscation>
<filters>
<filter>glob:com/mycompany/nativeinterface/Bridge.class</filter>
</filters>
</jniObfuscation>
</code></pre>
**Сокрытие доступа**
* **Элемент:** `<hideAccess>`
* **Описание:** Механизм сокрытия доступа скрывает вызовы методов и обращения к полям в пакетах и классах, указанных в фильтрах, разрывая связь между местом вызова и вызываемой функцией.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><hideAccess>
<filters>
<filter>glob:!com/google/**</filter>
<filter>glob:com/mycompany/internal/**</filter>
</filters>
</hideAccess>
</code></pre>
**Шифрование классов**
* **Элемент:** `<classEncryption>`
* **Описание:** ГостПротектор шифрует все классы.dex, включая Application, Activities, ContentProviders и Receivers, в соответствии с указанными фильтрами. **Примечание:** ГостПротектор будет шифровать все классы по умолчанию, не влияя на производительность приложения. Однако важно исключить любые классы, которые должны оставаться доступными для вызова из стороннего кода, например, классы, которые являются частью открытого API.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует (шифрует все, если элемент присутствует без фильтров)
<pre><code class="language-xml"><classEncryption>
<filters>
<filter>glob:!com/mycompany/publicapi/**</filter>
</filters>
</classEncryption>
</code></pre>
**Шифрование нативных библиотек**
* **Элемент:** `<nativeLibraryEncryption>`
* **Описание:** ГостПротектор шифрует нативные библиотеки (файлы .so) в целевом пакете в соответствии с выбранными фильтрами.
* **Элемент (вложенный):** `filters`
* **Формат:** string (используя синтаксис фильтров)
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><nativeLibraryEncryption>
<filters>
<filter>glob:lib/armeabi-v7a/libsecret.so</filter>
</filters>
</nativeLibraryEncryption>
</code></pre>
### Защита ресурсов
**Шифрование ресурсов**
* **Элемент:** `<resourceEncryption>`
* **Описание:** Шифрование ресурсов защищает от злонамеренного копирования, модификации и раскрытия информации путем шифрования внутренних ресурсов приложения, имен ресурсов и, для кроссплатформенных приложений, кода HTML, JS и CSS. Фильтры могут быть указаны на каталоги assets и res, а также на ресурсы в корневом каталоге и отдельные строковые ресурсы.
* **Вложенные элементы:** (`<assets>`, `<res>`, `<strings>`, `<nameObfuscation>`, `<root>`, `<androidManifestMangling>`, `<xamarinAssemblies>`)
* **Элемент (вложенный):** `assets`
* **Описание:** Шифрует файлы в `assets/`. Файлы можно выбирать по шаблону файла (т. е. `*.png` обозначает все файлы формата PNG), шаблону имени (т. е. `File1*` обозначает все файлы, имена которых начинаются со строки "File1"), по определенному имени файла (например, `File2.json`) или по пути (например, `TestDir/File3.txt`). **Примечание 1.** Если в файле конфигурации в разделе `resourceEncryption` нет элементов `assets`/`res`, шифрование каталога активов будет выполняться в соответствии с настройками ГостПротектор по умолчанию. **Примечание 2.** Активы, к которым операционная система обращается напрямую, не должны быть зашифрованы.
* **Формат:** содержит вложенные элементы `filters`.
* **Элемент (вложенный):** `res`
* **Описание:** Шифрует файлы в `res/`. Файлы можно выбирать по шаблону файла (т. е. `*.png`), шаблону имени (т. е. `File1*`), определенному имени файла (например, `File2.json`) или по пути (например, `TestDir/File3.txt`). **Примечание 1.** Если нет элементов `assets`/`res`... применяются настройки по умолчанию. **Примечание 2.** Ресурсы, к которым Android обращается напрямую, не должны быть зашифрованы.
* **Формат:** содержит вложенные элементы `filters`.
* **Элемент (вложенный):** `strings`
* **Описание:** Шифрует строки и массивы строк в `resources.arsc`. **Примечание.** Если нет элемента 'strings'... применяются настройки по умолчанию.
* **Формат:** содержит вложенные элементы `filters`.
* **Элемент (вложенный):** `nameObfuscation`
* **Описание:** Если включена обфускация имен ресурсов, ГостПротектор будет обфусцировать имена файлов в `res/`. Можно установить фильтры для обфускации имен ресурсов независимо от фильтров, указанных для шифрования каталога res. Дополнительную информацию см. в руководстве по фильтрам для шифрования ресурсов.
* **Формат:** содержит вложенные элементы `filters`.
* **Элемент (вложенный):** `root`
* **Описание:** Шифрует файлы в `root/`. Файлы можно выбирать по шаблону файла (т. е. `*.png`), шаблону имени (т. е. `File1*`), определенному имени файла (например, `File2.json`) или по пути (например, `TestDir/File3.txt`).
* **Формат:** содержит вложенные элементы `filters`.
* **Элемент (вложенный):** `androidManifestMangling`
* **Описание:** Параметры маскировки для `AndroidManifest.xml`. Если элемент `androidManifestMangling` включен в файл конфигурации, ГостПротектор будет маскировать сущности в файле `AndroidManifest.xml`.
* **Элемент (вложенный):** `xamarinAssemblies`
* **Описание:** Шифрует сборки Xamarin.
* **Атрибут:** `dir`
* **Описание:** Если сборки находятся не в каталоге по умолчанию (`assets/assemblies`), вы можете установить путь к ним, используя атрибут `dir`. Путь должен начинаться с корня APK, например: `assets/xxx/assemblies`
* **Формат:** string
* **Значение по умолчанию:** отсутствует
<pre><code class="language-xml"><resourceEncryption nameObfuscation="on">
<assets>
<filters><filter>glob:data/**</filter></filters>
</assets>
<res>
<filters><filter>glob:raw/**</filter></filters>
</res>
<strings>
<filters><filter>my_secret_string_key</filter></filters>
</strings>
<nameObfuscation>
<filters><filter>layout/secret_layout</filter></filters>
</nameObfuscation>
<root>
<filters><filter>important_config.dat</filter></filters>
</root>
<androidManifestMangling/>
<xamarinAssemblies dir="assets/assemblies"/>
</resourceEncryption>
</code></pre>
### RASP (Runtime Application Self-Protection) - Проверки окружения во время выполнения
**Защита от отладки**
* **Элемент:** `<antiDebug>`
* **Описание:** Если этот параметр включен, ГостПротектор Runtime Engine немедленно прекратит выполнение приложения, если обнаружит подключенный отладчик.
* **Допустимые значения:** `true`, `false`
* **Значение по умолчанию:** `true`
**Защита от эмулятора**
* **Элемент:** `<antiEmulator>`
* **Описание:** Если этот параметр включен, ГостПротектор Runtime Engine предотвратит запуск приложения в эмуляторе. **Примечание:** Клиентский API и параметры обратного вызова доступны в качестве альтернативы закрытию приложения. Более подробная информация о конфигурации и реализации доступна по запросу
* **Допустимые значения:** `true`, `false`
* **Значение по умолчанию:** `true`
**Защита от ручной установки**
* **Элемент:** `<antiManualInstall>`
* **Описание:** Если этот параметр включен, ГостПротектор Runtime Engine предотвратит запуск приложения, если оно было загружено не из официальных источников (т.е. магазина приложений). **Примечание:** Клиентский API и параметры обратного вызова доступны в качестве альтернативы закрытию приложения. Более подробная информация о конфигурации и реализации доступна по запросу.
* **Допустимые значения:** `true`, `false`
* **Значение по умолчанию:** `true`
**Защита от вредоносного ПО**
* **Элемент:** `<antiMalware>`
* **Описание:** Если этот параметр включен, ГостПротектор Runtime Engine будет передавать информацию о вредоносном ПО и потенциально опасных приложениях, обнаруженных на устройстве, в систему телеметрии Элис. **Примечание:** Должен быть включен `<reportMonitoring>`. Также доступны клиентский API и параметры обратного вызова. Более подробная информация о конфигурации и реализации доступна по запросу.
* **Допустимые значения:** `true`, `false`
* **Значение по умолчанию:** `true`
**Проверки времени выполнения**
* **Элемент:** `<runtimeChecks>`
* **Описание:** Если этот параметр включен, ГостПротектор Runtime Engine предотвратит запуск приложения на пользовательских прошивках и рутоованных устройствах.
* **Допустимые значения:** (Включение элемента включает его)
* **Значение по умолчанию:** Включено, если присутствует
### Защита сетевых подключений
**Закрепление открытых ключей (Public Key Pinning)**
* **Элемент:** `<publicKeyPinning>`
* **Описание:** Параметры для закрепления открытых ключей SSL/HTTP. Их можно указать **либо** через файл конфигурации безопасности в `res/xml` (в соответствии со спецификацией для Android N), либо через вложенный элемент `network-security-config`. Если у вас есть отдельный файл конфигурации безопасности, вы должны установить путь к нему в атрибуте `src`.
* **Атрибут:** `src`
* **Допустимые значения:** Путь к файлу конфигурации безопасности.
* **Значение по умолчанию:** отсутствует
* **Примечание:** если файл существует, **все** параметры закрепления открытых ключей берутся из файла. С другой стороны, если атрибут `src` **не установлен** и есть тег `network-security-config`, все параметры берутся из конфигурации, определенной внутри тега, и будет создан файл `res/xml/networksecurityconfig.xml`. Он будет содержать параметры из тега `network-security-config`, а также следующая информация будет добавлена в `AndroidManifest.xml`:
```xml
<application ...> <meta-data android:name="android.security.net.config"
android:resource="@xml/networksecurityconfig" />
...
</application>
```
* **Формат:** содержит вложенные элементы (`<actions>`, `<reportUri>`, `<reportMethod>`, `<network-security-config>`)
* **Элемент (вложенный):** `actions`
* **Описание:** Указывает действия, которые необходимо выполнить при обнаружении ошибок или аномалий во время проверок закрепления открытых ключей.
* **Формат:** список с разделителем `,`
* **Допустимые значения:** `block` - блокировать соединение; `report` - отправить отчет о соединении
* **Значение по умолчанию:** `block, report`
* **Элемент (вложенный):** `reportUri`
* **Описание:** Указывает адрес, который будет использоваться для отправки отчетов JSON о любых ошибках или аномалиях, обнаруженных во время проверок закрепления открытых ключей.
* **Формат:** string (URL)
* **Элемент (вложенный):** `reportMethod`
* **Описание:** Указывает метод (в формате `ClassName.methodName`), в который передаются отчеты JSON в случае каких-либо ошибок или аномалий, обнаруженных во время проверок закрепления открытых ключей. Эти методы должны иметь модификатор `public static` и сигнатуру `(String jsonStr)`.
* **Формат:** string
* **Элемент (вложенный):** `cacheTTL`
* **Описание:** Время жизни результата проверки цепочки SSL-сертификата сервера для каждого домена.
* **Формат:** int (секунды)
* **Значение по умолчанию:** 180
* **Элемент (вложенный):** `network-security-config`
* **Описание:** Встроенный файл конфигурации безопасности. См. документацию Android для получения формата.
* **Пример №1 (встроенный):**
<pre><code class="language-xml"><publicKeyPinning>
<network-security-config>
<domain-config>
<domain includeSubdomains="true">example.com</domain>
<pin-set expiration="2025-01-01">
<pin digest="SHA-256">...</pin>
</pin-set>
</domain-config>
</network-security-config>
</publicKeyPinning>
</code></pre>
* **Пример №2 (внешний файл):**
```xml
<publicKeyPinning src="@xml/my_network_security_config"/>
```
**Прозрачность сертификатов (Certificate Transparency)**
* **Элемент:** `<certificateTransparency>`
* **Описание:** Параметры для мониторинга сертификатов открытых ключей в соответствии со стандартом прозрачности сертификатов. ГостПротектор использует список серверов журналов, который находится в дистрибутивном пакете. Этот список основан на: [список журналов chromium](https://source.chromium.org/chromium/chromium/src/+/master:components/certificate_transparency/data/log_list.json). Альтернативно, список авторизованных серверов журналов можно указать вручную, введя путь к файлу, содержащему этот список.
* **Формат:** содержит вложенные элементы (`<trace>`, `<logFile>`)
* **Элемент (вложенный):** `trace`
* **Формат:** string (integer)
* **Описание:** Для целей отладки установите для трассировки значение `1000`.
* **Значение по умолчанию:** отсутствует (фактически 0)
* **Элемент (вложенный):** `logFile`
* **Формат:** string (путь)
* **Описание:** Путь к файлу, содержащему ваш собственный список авторизованных серверов журналов.
* **Значение по умолчанию:** отсутствует (использует внутренний список)
<pre><code class="language-xml"><certificateTransparency>
<trace>0</trace>
<!-- <domain includeSubdomains="false">example.com</domain> -->
<!-- <logFile>/path/to/custom_log_list.json</logFile> -->
</certificateTransparency>
</code></pre>
### Защита пользовательского интерфейса
**Защита пользовательского интерфейса**
* **Элемент:** `<uiProtection>`
* **Описание:** ГостПротектор блокирует захват экрана и предотвращает
перехват активности.
Блокировка захвата экрана защищает ваше приложение от снимков экрана,
записи экрана и трансляции экрана. Предотвращение перехвата защищает
приложение от вредоносного ПО, которое берет под контроль приложение
и заменяет оригинальные окна зловредными.
* **Допустимые значения:** (Включение элемента включает его)
* **Значение по умолчанию:** Включено, если присутствует
### Мониторинг угроз и телеметрия - Интеграция с `Элис`
**Мониторинг угроз**
* **Элемент:** `<reportMonitoring>`
* **Описание:** Настраивает службу телеметрии атак и аналитики угроз
`Элис` в реальном времени.
* **Формат:** содержит вложенные элементы (`<apiKey>`, `<customFieldsUpdate>`, `<trace>`)
* **Элемент (вложенный):** `apiKey`
* **Формат:** string
* **Значение по умолчанию:** отсутствует
* **Элемент (вложенный):** `customFieldsUpdate`
* **Формат:** string (полное имя класса)
* **Описание:** Указывает метод (если он реализован в коде пакета)
для настройки типов данных, сообщаемых в `Элис` системой мониторинга
(например, IP-адрес пользователя, серийный номер устройства и т. д.).
Указанный метод должен иметь следующий формат:
<pre><code class="language-java">// Example structure
package com.example;
import java.util.Map;
public class AliceCustomData {
public static void updateFields(Map<String, String> values) {
values.put("custom_field_1", "some_value");
values.put("custom_field_2", getDynamicValue());
}
private static String getDynamicValue() {
return "dynamic";
}
}
</code></pre>
* **Значение по умолчанию:** отсутствует, но поле должно
иметь следующую структуру, если используется:
<pre><code class="language-xml"><customFieldsUpdate><![CDATA[com.example.AliceCustomData]]></customFieldsUpdate>
</code></pre>
* **Элемент (вложенный):** `trace`
* **Формат:** string (integer, обычно 0 или 1000)
* **Описание:** Уровень ведения журнала сообщений ГостПротектор
на конечном устройстве. Для целей отладки установите значение `1000`.
В противном случае установите значение `0` или исключите узел `<trace>`.
* **Значение по умолчанию:** отсутствует (фактически 0)
<pre><code class="language-xml"><reportMonitoring>
<apiKey>YOUR_ALICE_API_KEY</apiKey>
<customFieldsUpdate><![CDATA[
com.example.AliceCustomData
]]></customFieldsUpdate>
<trace>0</trace>
</reportMonitoring>
</code></pre>
### Параметры AAR
**AAR**
* **Элемент:** `<aar>`
* **Описание:** Включает DexProtection для библиотек Android (AAR). Поскольку механизм среды выполнения ГостПротектор должен запускаться до первого доступа к AAR, необходимо настроить процесс инициализации и/или оставить включенным механизм автоматической инициализации ГостПротектор.
* **Атрибут:** `autoInit`
* **Допустимые значения:** `on` - включить механизм автоматической инициализации ГостПротектор; `off` - отключить механизм автоматической инициализации ГостПротектор. Если `autoInit="off"`, необходимо указать либо `initMethod(s)`, либо `initClass(es)`.
* **Значение по умолчанию:** `on`
* **Атрибут:** `autoInitAuthorities`
* **Описание:** Чтобы гарантировать, что механизм среды выполнения ГостПротектор инициализируется при необходимости, механизм `autoInit` использует подход Content Provider и определяет компонент Content Provider в `AndroidManifest.xml`. Поэтому, если `autoInit="on"`, мы **настоятельно рекомендуем** указать `autoInitAuthorities="${applicationId}"`, дополнительно указав уникальный идентификатор для каждого AAR, где это необходимо, чтобы избежать риска конфликта, при котором в `android:authorities` указано несколько Content Provider с одним и тем же именем.
* **Значение по умолчанию:** `${applicationId}`
* **Атрибут:** `kotlinSupport`
* **Допустимые значения:** `on` - включить поддержку библиотек, содержащих код Kotlin; `off` - отключить поддержку библиотек, содержащих код Kotlin
* **Значение по умолчанию:** `off`
* **Атрибут:** `nativeClassEncryption`
* **Допустимые значения:** `on` - включить шифрование нативных классов в библиотеке; `off` - отключить шифрование нативных классов в библиотеке
* **Значение по умолчанию:** `on`
* **Атрибут:** `nativeHideAccess`
* **Допустимые значения:** `on` - включить механизм скрытия доступа для нативных классов в библиотеке; `off` - отключить механизм скрытия доступа для нативных классов в библиотеке
* **Значение по умолчанию:** `off`
* **Пример (Автоматическая инициализация — рекомендуется):**
```xml
<aar autoInit="on" autoInitAuthorities="${applicationId}.myLibId" kotlinSupport="on"/>
```
* **Пример (Ручная инициализация):**
```xml
<aar autoInit="off" kotlinSupport="on"> <initMethod>com.example.library.Initializer.initializeDexPro</initMethod> <initClass>com.example.library.MyReceiver</initClass> </aar>
```
## Фильтры: руководство по настройке
`ГостПротектор` предоставляет гибкий механизм для установки пользовательских фильтров для каждого из своих механизмов защиты кода, защиты ресурсов и удаления кода.
Если механизмы защиты включены, но фильтры не указаны, ГостПротектор автоматически защищает все строки во всех классах (шифрование строк), все методы, поля и обращения к полям во всех классах (шифрование классов, сокрытие доступа), а также шифрует ресурсы (шифрование ресурсов). Это обеспечивает максимальную защиту и рекомендуется включить на этапе тестирования, но иногда может привести к неэффективной работе приложения. Это особенно относится к механизму сокрытия доступа для кода выполняющего объемные вычисления с использованием циклов. Поэтому рекомендуется использовать фильтры для точной настройки защиты там, где это необходимо.
Для применения защиты в соответствии с указанными шаблонами имен можно использовать режимы синтаксиса `'glob'` или `'regex'`.
Чтобы установить фильтр для **включения** данного пакета или класса в процесс защиты, просто укажите режим синтаксиса и шаблон имени в формате: `'syntax:pattern'`, где `:` обозначает само себя.
Чтобы **исключить** данный пакет или класс из защиты, используйте восклицательный знак (`!`) перед шаблоном имени в формате: `'syntax:!pattern'`
Ниже приведены руководства по фильтрам, настроенным для **включения**, **исключения** и **обоих**, с использованием режима синтаксиса `glob`.
### Включение
**Защита каждого класса в указанном пакете**
Допустим, необходимо настроить фильтр, чтобы указать, какие классы ГостПротектор должен включать в свой процесс шифрования классов. В `classes.dex` имеется следующая структура пакетов:
```
android/support/...
com/google/..
com/facebook/..
com/mycompany/..
com/mycompany/ui/..
com/mycompany/core/..
```
В этом случае необходимо, чтобы ГостПротектор зашифровал все классы, содержащиеся в пакете `com/mycompany`. Поэтому необходимо установить следующий фильтр в конфигурации:
```xml
<filter>glob:com/mycompany/**</filter>
```
**Защита одного класса**
Чтобы защитить один класс — например, `com/mycompany/core/InternalEngine.class` — необходимо следующий формат фильтра:
```xml
<filter>glob:com/mycompany/core/InternalEngine.class</filter>
```
### Исключение
**Исключение каждого класса в указанном пакете из защиты**
Фильтры исключения устанавливаются путем добавления восклицательного знака (`!`) перед шаблоном имени класса или пакета:
```xml
<filter>glob:!android/support/**</filter> <filter>glob:!com/google/**</filter> <filter>glob:!com/facebook/**</filter>
```
**Исключение одного класса из защиты**
Фильтры исключения для классов выполняются таким же образом, путем добавления восклицательного знака (`!`) перед путем к классу:
```xml
<filter>glob:!com/mycompany/core/BumpGenerator.class</filter>
```
### Смешанные фильтры: объединение включения и исключения
Один из возможных (и рекомендуемых) подходов для шифрования строк и сокрытия доступа — сначала установить глобальный фильтр исключения, чтобы исключить каждый класс из защиты, а затем выбрать конкретные классы для включения. Для шифрования классов не должно возникнуть никаких проблем при шифровании каждого класса в пакете, за исключением тех, которые должны оставаться доступными для третьих сторон, например, классы, которые являются частью открытого API.
Ниже приведен простой пример конфигурации для шифрования строк, шифрования классов и сокрытия доступа:
<pre><code class="language-xml"><dexprotector>
***
<stringEncryption mode="filters">
<filters>
<filter>glob:!**/**</filter> <!-- Исключить все глобально -->
<filter>glob:com/test/**</filter> <!-- Включить конкретный пакет -->
</filters>
</stringEncryption>
<classEncryption/> <!-- ГостПротектор будет шифровать все классы по умолчанию -->
<!-- Добавьте фильтры здесь, только если необходимо ИСКЛЮЧИТЬ общедоступные API -->
<!-- <filters><filter>glob:!com/mycompany/publicapi/**</filter></filters> -->
<hideAccess mode="filters">
<filters>
<filter>glob:!**/**</filter> <!-- Исключить все глобально -->
<filter>glob:com/test/**</filter> <!-- Включить конкретный пакет -->
</filters>
</hideAccess>
***
</dexprotector>
</code></pre>
### Подробная информация о синтаксисе фильтров
Фильтры определяются режимом синтаксиса и шаблоном и имеют вид: `'syntax_mode:pattern'`, где `:` обозначает само себя. Значение компонента синтаксиса не чувствительно к регистру.
Когда режим синтаксиса — `'glob'`, строковое представление шаблона сопоставляется с путями с использованием ограниченного языка шаблонов, который напоминает регулярные выражения, но с более простым синтаксисом.
Например:
* `*.java` — Соответствует именам файлов, заканчивающимся на `.java`
* `foo.?` — Соответствует именам файлов, начинающимся с `foo.` и односимвольным расширением.
* `com//` — Соответствует пакету `/com/test/a`.
* `com/**` — Соответствует всем пакетам и классам внутри пакета `com`.
**Символы синтаксиса Glob:**
* Символ `*` соответствует нулю или более символам компонента имени, **не** пересекая границы каталогов.
* Символы `**` соответствуют нулю или более символам, **пересекая** границы каталогов.
* Символ `?` соответствует ровно одному символу компонента имени.
* Обратная косая черта (`\`) используется для предотвращения интерпретации символов как специальных символов. Например, выражение `\\` соответствует одной обратной косой черте, а `\{` соответствует левой фигурной скобке.
* Символы `[...]` составляют выражение в скобках, которое соответствует одному символу компонента имени из набора символов. Например, `[abc]` соответствует "a", "b" или "c". Дефис (`-`) можно использовать для указания диапазона, поэтому `[a-z]` указывает диапазон, соответствующий символам от "a" до "z" (включительно). Эти формы можно смешивать, поэтому `[abce-g]` соответствует "a", "b", "c", "e", "f" или "g". Если символ после `[` является `!`, то он используется для отрицания, т. е. `[!a-c]` соответствует любому символу, кроме "a", "b" или "c". Внутри выражения в скобках символы `*`, `?` и `\` соответствуют сами себе и, следовательно, в этом контексте не имеют эффектов сопоставления с шаблоном, описанных выше. Символ `-` соответствует самому себе, если он является либо первым символом внутри скобок, либо первым символом после `!`, когда `!` используется для отрицания.
* Символы `{}` представляют собой группу подшаблонов, где группа соответствует, если какой-либо подшаблон в группе соответствует. Символ `,` используется для разделения подшаблонов. Группы не могут быть вложенными.
* Начальные точки/точки (`.`) в имени файла рассматриваются как обычные символы в операциях сопоставления шаблонов. Например, шаблон glob `*` соответствует имени файла ".login".
* Размещение символа `!` в начале компонента шаблона отрицает шаблон.
---
## Дополнительные примечания о фильтрах: шифрование ресурсов и шифрование аннотаций
### Фильтры для шифрования ресурсов
В целом, для шифрования ресурсов применяются те же принципы, что и для других механизмов защиты, но файлы также можно выбирать по **шаблону файла** (т. е. `*.png` обозначает все файлы формата PNG; ГостПротектор найдет и зашифрует все файлы этого типа в каталоге), **шаблону имени** (т. е. `File1*` обозначает все файлы, имена которых начинаются со строки "File1"), по **определенному имени файла** (например, `File2.json`) или по **пути** (например, `TestDir/File3.txt`). Ниже приведен пример конфигурации специально для каталога `assets`:
<pre><code class="language-xml"><resourceEncryption>
<assets>
<filters>
<filter>*.png</filter>
<filter>File1*</filter>
<filter>File2.json</filter>
<filter>TestDir/File3.txt</filter>
</filters>
</assets>
</resourceEncryption>
</code></pre>
Далее представлен другой пример, с более широкими фильтрами, нацеленными на каталоги assets и res, а также на строки и массивы строк, указанные в `strings.xml` в `resources.arsc`.
<pre><code class="language-xml"><resourceEncryption nameObfuscation="on">
<assets>
<filters>
<filter>glob:cert/**</filter>
</filters>
</assets>
<res>
<filters>
<filter>glob:raw/**</filter>
</filters>
</res>
<strings>
<filters>
<filter>my_api_key</filter>
<filter>glob:mobile_token*</filter>
<filter>glob:payments_**</filter>
<filter>glob:sensitive_string</filter>
</filters>
</strings>
</resourceEncryption>
</code></pre>
### Обфускация имен ресурсов
При желании можно разделить фильтры для шифрования ресурсов и фильтры для обфускации имен ресурсов. Это можно настроить следующим образом:
<pre><code class="language-xml"><resourceEncryption nameObfuscation="on"> <!-- or "off" -->
<res>
<filters>
<filter>res-filter-pattern-01</filter>
<filter>res-filter-pattern-02</filter>
</filters>
</res>
<nameObfuscation>
<filters>
<filter>res-name-01</filter>
<filter>res-name-02</filter>
</filters>
</nameObfuscation>
</resourceEncryption>
</code></pre>
И ниже приведены перестановки для элемента `<nameObfuscation>`:
| атрибут / фильтр → | Пустой фильтр | Указаны фильтры | Фильтры не указаны |
| :------------------- | :-------------------- | :-------------------- | :------------------- |
| **on** | Обфусцировать все имена | В соответствии с фильтром | Обфусцировать все имена |
| **off** | Нет обфускации имен | Нет обфускации имен | Нет обфускации имен |
| **Атрибут не указан** | Обфусцировать все имена | В соответствии с фильтром | Нет обфускации имен |
### Фильтры для шифрования аннотаций
Фильтры для шифрования аннотаций работают иначе, чем для других механизмов. Фильтры должны быть указаны на классы, **в которых определены аннотации**, а не на классы, в которых аннотации используются. Затем ГостПротектор найдет все экземпляры аннотаций и зашифрует их. Например:
<pre><code class="language-xml"><annotationEncryption>
<filters>
<filter>glob:kotlin/Metadata.class</filter>
<filter>glob:your/own/secret/AnnotationDefinition.class</filter>
<filter>glob:other/framework/secret/AnnotationDef.class</filter>
</filters>
</annotationEncryption>
</code></pre>
## Настройка ГостПротектор для приложений (APK и AAB)
Механизмы защиты ГостПротектор одинаково работают с APK и AAB, и каждый элемент Android, перечисленный в Обзоре файла конфигурации, за исключением элементов внутри тега `<aar>`, может быть применен как к APK, так и к AAB. Однако существуют некоторые важные различия между DexProtection для APK и DexProtection для AAB.
1. Для защиты AAB требуется использовать Android Studio 3.2 (или выше) и (если используется Gradle) Android Gradle Plugin 3.2.0 (или выше).
2. Согласно требованиям Google Play к пакетам приложений, необходимо использовать подпись приложений Google Play для AAB, предназначенных для выпуска через Google Play. Это означает, что в конфигурации ГостПротектор для `<signMode>` должно быть установлено значение `google`. Если вы выберете режим подписи `google`, вам также потребуется ввести информацию о хранилище ключей загрузки и отпечаток SHA-256 целевого сертификата. Вы можете найти отпечаток сертификата на странице подписи приложений Google Play Console: Подпись приложений → Сертификат подписи приложений → Отпечаток сертификата SHA-256.
> ⚠️ **Важно отметить, что если ваше приложение защищено с включенным режимом подписи приложений Google Play `google`, ваше приложение *должно* быть загружено и скачано непосредственно из Google Play (включая открытое, закрытое или внутреннее тестирование), чтобы работать.** Если в конфигурации ГостПротектор выбран режим подписи Google Play, и приложение тестируется локально до обработки через Google Play, приложение будет неработоспособно и аварийно завершится при запуске. Если вы не хотите использовать подпись приложений Google Play, но хотите опубликовать свое приложение в Google Play Store, вам следует использовать режим подписи `release` в ГостПротектор. Для этого см. раздел о локальной подписи для APK и AAB. С августа 2021 года любое новое приложение, опубликованное в Google Play Store, должно быть в формате пакета приложений (AAB) и должно быть подписано через подпись приложений Play.
### Пример конфигурации для приложений (APK и AAB)
<pre><code class="language-xml"><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<protector>
<!-- Параметры сборки и ведения журнала для процесса ГостПротектор -->
<verbose>true</verbose>
<optimize>false</optimize>
<securityAssessment>
<signingCertificateCompromised mode="error"/>
<signingCertificateWeakKey mode="error"/>
<dependencyCheck mode="warning" />
</securityAssessment>
<proguardMapFile>/Users/developer/project/app/build/outputs/mapping/release/mapping.txt</proguardMapFile>
<!-- Методы подписи -->
<signMode>google</signMode>
<keystore>/home/developer/example.keystore</keystore>
<storepass>examplestorepass</storepass>
<alias>examplealias</alias>
<keypass>examplekeypass</keypass>
<sha256CertificateFingerprint>1B:5F:8B:D...</sha256CertificateFingerprint>
<!-- Удаление небезопасных вызовов -->
<stripLogging>all</stripLogging>
<stripMethodCalls>
<filters>
<filter>android.util.Log.println</filter>
</filters>
</stripMethodCalls>
<!-- Механизмы защиты кода -->
<stringEncryption/>
<classEncryption/>
<hideAccess/>
<annotationEncryption/>
<nativeLibraryEncryption/>
<jniObfuscation/>
<!-- Механизмы защиты ресурсов -->
<resourceEncryption nameObfuscation="on">
<assets>
<filters>
<filter>glob:cert/**</filter>
</filters>
</assets>
<res>
<filters>
<filter>glob:raw/**</filter>
</filters>
</res>
<strings>
<filters>
<filter>my_api_key</filter>
<filter>glob:mobile_token*</filter>
<filter>glob:payments_**</filter>
<filter>glob:sensitive_string</filter>
</filters>
</strings>
<androidManifestMangling/>
</resourceEncryption>
<!-- RASP - Проверки окружения -->
<runtimeChecks/>
<!-- Параметры защиты сетевых подключений -->
<publicKeyPinning>
<trace>0</trace>
<actions> block<!--, report--></actions>
<network-security-config>
<domain-config>
<domain includeSubdomains="true">yourdomain.com</domain>
<pin-set expiration="2022-10-30">
<pin digest="SHA-256">h/sha256hashbase64==</pin>
</pin-set>
</domain-config>
</network-security-config>
</publicKeyPinning>
<certificateTransparency>
<trace>0</trace>
<domain includeSubdomains="false">yourdomain.com</domain>
<!-- <logFile>path_to_custom_log_list.json</logFile> -->
</certificateTransparency>
<!-- Интеграция с системой мониторинга -->
<reportMonitoring>
<apiKey>137feb09-f390-4f00-b43f-ebcc...</apiKey>
<!-- <customFieldsUpdate>com.dexprotector.demo.AliceReporter</customFieldsUpdate> -->
<trace>0</trace>
</reportMonitoring>
</protector>
</code></pre>
## Настройка ГостПротектор для библиотек (AAR)
Большинство механизмов защиты ГостПротектор можно применять к библиотекам Android (AAR), но есть некоторые различия, и определенные функции необходимо настраивать иначе, чем для APK и AAB.
Наиболее важные различия между настройкой защиты приложения и AAR касаются:
* Инициализации
* Kotlin
* Защиты общедоступных API
### Инициализация
Поскольку механизм среды выполнения ГостПротектор должен запускаться до первого доступа к AAR, необходимо настроить процесс инициализации и/или оставить включенным механизм автоматической инициализации ГостПротектор.
Чтобы гарантировать, что механизм среды выполнения ГостПротектор инициализируется при необходимости, механизм `autoInit` использует подход Content Provider и определяет компонент Content Provider в `AndroidManifest.xml`. Поэтому, если `autoInit="on"`, мы **настоятельно рекомендуем** указать `autoInitAuthorities="${applicationId}.yourUniqueLibId"`, дополнительно указав уникальный идентификатор для каждого AAR, где это необходимо, чтобы избежать риска конфликта, при котором в `android:authorities` указано несколько Content Provider с одним и тем же именем.
```xml
<aar autoInit="on" autoInitAuthorities="${applicationId}.yourUniqueLibId"/>
```
Мы настоятельно рекомендуем оставить `autoInit="on"`, но если вы предпочитаете установить `autoInit="off"`, необходимо указать либо `initMethod(s)`, либо `initClass(es)`. Например:
<pre><code class="language-xml"><aar autoInit="off">
<initMethod>com.sample.Lib.initMethod</initMethod>
<initClass>com.sample.MyReceiver</initClass>
</aar>
</code></pre>
### Kotlin
Если ваш AAR содержит классы Kotlin, это необходимо указать в файле конфигурации (чего не требуется для APK). Причина в том, что AAR компилируются в байт-код Java, а не в байт-код Dalvik, поэтому должны обрабатываться нативными движками ГостПротектор по-разному. Просто укажите атрибут `kotlinSupport` внутри элемента `<aar>`, как показано ниже:
```xml
<aar kotlinSupport="on" />
```
### Защита общедоступных API
При защите AAR крайне важно указать фильтры для шифрования классов таким образом, чтобы классы общедоступного API не шифровались.
### Пример конфигурации для библиотек и SDK (AAR)
<pre><code class="language-xml"><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<protector>
<!-- Параметры сборки и ведения журнала для процесса ГостПротектор -->
<verbose>false</verbose>
<optimize>false</optimize>
<proguardMapFile>/Users/developer/project/library/build/outputs/mapping/release/mapping.txt</proguardMapFile>
<!-- Параметры защиты библиотек (AAR) -->
<aar autoInit="on" autoInitAuthorities="${applicationId}.myLibraryId" kotlinSupport="on"/>
<!-- Удаление небезопасных вызовов -->
<stripLogging>all</stripLogging>
<stripMethodCalls>
<filters>
<filter>android.util.Log.println</filter>
</filters>
</stripMethodCalls>
<!-- Механизмы защиты кода -->
<stringEncryption>
<filters>
<filter>glob:!**/**</filter> <!-- Исключить все -->
<filter>glob:com/test/**</filter> <!-- Включить конкретный внутренний пакет -->
</filters>
</stringEncryption>
<classEncryption>
<filters>
<filter>glob:!com/mycompany/library/public/**</filter> <!-- Исключить общедоступный API -->
</filters>
</classEncryption>
<hideAccess>
<filters>
<filter>glob:!**/**</filter> <!-- Исключить все -->
<filter>glob:com/test/**</filter> <!-- Включить конкретный внутренний пакет -->
</filters>
</hideAccess>
<nativeLibraryEncryption>
<filters>
<filter>libsome.so</filter>
</filters>
</nativeLibraryEncryption>
<jniObfuscation>
<filters>
<filter>glob:com/sample/NativeLibInterface</filter>
</filters>
</jniObfuscation>
<!-- Механизмы защиты ресурсов -->
<resourceEncryption>
<assets>
<filters>
<filter>glob:cert/**</filter>
</filters>
</assets>
</resourceEncryption>
<!-- RASP - Проверки окружения для обнаружения рутованных устройств, отладчиков,
эмуляторов и средств перехвата вызовов -->
<runtimeChecks/>
<!-- Параметры защиты сетевых подключений -->
<publicKeyPinning>
<trace>0</trace>
<actions> block<!--, report--></actions>
<network-security-config>
<domain-config>
<domain includeSubdomains="true">librarydomain.com</domain>
<pin-set expiration="2022-10-30">
<pin digest="SHA-256">h/sha256hashbase64==</pin>
</pin-set>
</domain-config>
</network-security-config>
</publicKeyPinning>
<certificateTransparency>
<trace>0</trace>
<domain includeSubdomains="false">librarydomain.com</domain>
<!-- <logFile>path_to_custom_log_list.json</logFile> -->
</certificateTransparency>
<!-- Параметры защиты библиотек (AAR) -->
<reportMonitoring>
<apiKey>137feb09-f390-4f00-b43f-ebcc...</apiKey>
<!-- <customFieldsUpdate>com.dexprotector.demo.AliceReporter</customFieldsUpdate> -->
<trace>0</trace>
</reportMonitoring>
</protector>
</code></pre>
## Подпись приложений
Подпись вашего приложения — обязательная часть обеспечения его защиты от несанкционированного вмешательства и клонирования. Для максимально возможной защиты от несанкционированного вмешательства и контроля целостности ГостПротектор использует **ряд параметров для построения криптографической цепочки доверия**, и информация о сертификате подписи приложения является важным звеном в этой цепочке.
В результате, если злоумышленник попытается повторно подписать защищенное приложение, криптографическая цепочка доверия будет нарушена, и приложение просто перестанет работать. Поэтому каждую новую версию вашего приложения необходимо повторно защищать с помощью ГостПротектор и повторно подписывать перед выпуском.
ГостПротектор проверяет надежность и целостность сертификата подписи как часть оценки безопасности; настоятельно рекомендуется использовать сертификат подписи с длиной ключа не менее 2048 бит, и ГостПротектор по умолчанию настроен таким образом, что приложение со слабым или скомпрометированным сертификатом подписи не будет обработано, что приведет к сообщению об ошибке.
Выбор режима подписи будет зависеть от этапа цикла сборки и от того, защищается APK, AAB или AAR. Поэтому ГостПротектор поддерживает различные режимы подписи, включая подпись приложений Google Play и подпись Amazon Appstore, любой из которых можно ввести в качестве `signMode` в файле конфигурации ГостПротектор или выбрать через ГостПротектор Студию. Значение `signMode` можно установить как `google`, `amazon`, `debug`, `release` или `none`. См. ниже руководства по каждому режиму подписи.
### Облачная подпись (подпись приложений Google Play; Amazon Appstore)
#### Подпись приложений Google Play
Вам необходимо использовать режим подписи `google`, если ваше приложение опубликовано или будет опубликовано в Google Play Store и вы используете подпись приложений Google Play, при этом Google управляет вашим ключом подписи приложения и использует его для подписи ваших APK при их распространении.
Если вы выберете режим подписи `google`, вам также потребуется ввести свой ключ загрузки и отпечаток SHA-256 целевого сертификата. Вы можете найти отпечаток сертификата на странице подписи приложений Google Play Console: Подпись приложений -> Сертификат подписи приложений -> Отпечаток сертификата SHA-256.
> ⚠️ **Важно отметить, что при использовании подписи приложений Google Play вы *должны* использовать режим подписи `google` в ГостПротектор, и после того, как приложение было защищено с использованием режима подписи `google`, оно станет *только* функциональным, когда оно будет *загружено и скачано непосредственно из Google Play*.** Это связано с тем, что приложение должно быть подписано на серверах Google с ожидаемым ключом подписи приложения, соответствующим отпечатку сертификата SHA-256, указанному в конфигурации ГостПротектор. Если вы попытаетесь запустить приложение локально или с помощью службы тестирования *без* предварительной загрузки и скачивания из Google Play, оно аварийно завершится. Если вы хотите протестировать приложение, которое было DexProtected с режимом подписи `google`, вы должны сделать это через Play Console.
Чтобы настроить режим подписи `google`, выполните следующие действия:
1. В файле конфигурации (`protector.xml`) укажите `google` в качестве значения `signMode`:
```xml
<signMode>google</signMode>
```
2. Добавьте отпечаток сертификата SHA-256 для ключа подписи приложения, который вы ранее сгенерировали для этого приложения через Google Play:
```xml
<sha256CertificateFingerprint>ВВЕДИТЕ_СВОЕ_ЗНАЧЕНИЕ_ЗДЕСЬ</sha256CertificateFingerprint>
```
3. Укажите информацию, связанную с хранилищем ключей, для вашего **ключа загрузки** в файл конфигурации (если вы используете плагин ГостПротектор Gradle, эта информация будет взята автоматически из `signingConfig`):
* `keystore` - путь к хранилищу ключей, содержащему ключ загрузки, используемый для создания ключа подписи приложения.
* `storepass` - пароль для хранилища ключей
* `alias` - псевдоним ключа
* `keypass` - пароль для ключа
Например:
```xml
<protector>
...
<signMode>google</signMode> <keystore>/Users/developer/keys/upload.keystore</keystore> <storepass>android</storepass> <alias>android</alias> <keypass>android</keypass> <sha256CertificateFingerprint>AB:CD:EF:...</sha256CertificateFingerprint>
...
</protector>
```
И если вы используете Gradle, обязательно добавьте новый `buildType`/`productFlavor` специально для публикации в Google Play, так как он не будет работать для других магазинов или для прямого распространения.
#### Подпись приложений Amazon Appstore
Вам необходимо использовать режим подписи `amazon`, если ваше приложение опубликовано или будет [опубликовано в Amazon Appstore](link-to-amazon-appstore).
Когда вы отправляете свое приложение, Amazon удаляет подпись, которую вы использовали для подписи своего приложения, и повторно подписывает его подписью Amazon, которая является уникальной для вас, не изменяется и одинакова для всех приложений в вашей учетной записи.
Поэтому, если вы выберете режим подписи `amazon`, вам также потребуется ввести отпечаток SHA-256 целевого сертификата. Этот хэш можно найти в разделе **Хэши сертификатов Appstore** консоли разработчика Amazon.
> ⚠️ **Важно отметить, что при использовании подписи приложений Amazon Appstore вы *должны* использовать режим подписи `amazon` в ГостПротектор, и после того, как приложение было защищено с использованием режима подписи `amazon`, оно станет *только* функциональным, когда оно будет *загружено и скачано непосредственно из Amazon Appstore*.** Это связано с тем, что приложение должно быть подписано на серверах Amazon с ожидаемой подписью Amazon, соответствующей отпечатку сертификата SHA-256, указанному в конфигурации ГостПротектор. Если вы попытаетесь запустить приложение локально или с помощью службы тестирования *без* предварительной загрузки и скачивания из Amazon Appstore, оно аварийно завершится.
Чтобы настроить режим подписи `amazon`, выполните следующие действия:
1. В файле конфигурации (`protector.xml`) введите `amazon` в качестве значения `signMode`:
```xml
<signMode>amazon</signMode>
```
2. Добавьте отпечаток сертификата SHA-256 для подписи Amazon:
```xml
<sha256CertificateFingerprint>ВВЕДИТЕ_СВОЙ_ХЭШ_AMAZON_ЗДЕСЬ</sha256CertificateFingerprint>
```
Например:
```xml
<dexprotector>
...
<signMode>amazon</signMode> <sha256CertificateFingerprint>12:34:56:
...</sha256CertificateFingerprint>
...
</dexprotector>
```
И если вы используете Gradle, обязательно добавьте новый `buildType`/`productFlavor` специально для публикации в Amazon, так как он не будет работать для других магазинов или для прямого распространения.
### Подпись для системных и предустановленных приложений
Для системных и предустановленных приложений, для которых подпись приложений управляется платформой или поставщиком, режим подписи зависит от того, есть ли у вас доступ к ключу подписи платформы.
* **Если у вас есть доступ к ключу**, установите для `<signMode>release</signMode>` и заполните все другие теги, связанные с подписью, как если бы вы использовали свой собственный закрытый ключ:
<pre><code class="language-xml"><signMode>release</signMode>
<keystore>/Users/developer/keystores/platform.keystore</keystore>
<storepass>android</storepass>
<alias>android</alias>
<keypass>android</keypass>
</code></pre>
* **Если у вас нет доступа к ключу**, установите для `<signMode>none</signMode>`, и, запросив файл сертификата подписи у поставщика платформы, добавьте путь к сертификату, используя тег `<certificate>`, следующим образом:
<pre><code class="language-xml"><signMode>none</signMode>
<certificate>/home/developer/vendor/platform.x509.pem</certificate>
</code></pre>
### Локальная подпись для APK
Если вы хотите подписать APK локально (либо потому, что он предназначен для прямого распространения, либо потому, что это обновление для старого приложения), и, следовательно, **не** используете подпись приложений Google Play и **не** отправляете приложение в Amazon Appstore, просто выберите `<signMode>release</signMode>`, а также укажите хранилище ключей, пароль хранилища ключей, псевдоним ключа и пароль ключа:
<pre><code class="language-xml"><signMode>release</signMode>
<keystore>/Users/developer/keystores/release.keystore</keystore>
<storepass>android</storepass>
<alias>android</alias>
<keypass>android</keypass>
</code></pre>
# Интеграция
## Gradle-плагин ГостПротектор
Gradle-плагин `ГостПротектор` входит в каждый дистрибутив и может использоваться для защиты APK, AAB и AAR.
Шаги по внедрению ГостПротектор в процесс сборки:
1. Установите путь к ГостПротектор в `buildscript.repositories` (основной `build.gradle` вашего проекта), например:
```groovy
buildscript {
repositories {
google()
mavenCentral()
flatDir { dirs '/Users/developer/protector/lib' } // Путь к каталогу
lib ГостПротектор
}
// ...
}
```
2. Добавьте следующие зависимости:
```groovy
buildscript {
dependencies {
classpath ':protector-gradle-plugin:' // Gradle-плагин ГостПротектор
classpath ':protector:' // ГостПротектор
// ... other classpath dependencies
}
}
```
3. Примените Gradle-плагин ГостПротектор в файле `build.gradle` вашего приложения/библиотеки, в строке сразу после `apply plugin: 'com.android.application'` или `apply plugin: 'com.android.library'`:
```groovy
apply plugin: 'com.android.application' // или com.android.library
apply plugin: 'protector'
```
4. Необходимо указать соответствующий файл конфигурации ГостПротектор в `buildType`, следующим образом:
```groovy
android {
// ...
buildTypes {
release {
// ... other release settings
ext.set("protector.configFile", "${project.rootDir}/protector-release.xml")
}
debug {
// ... other debug settings
ext.set("protector.configFile", "${project.rootDir}/protector-debug.xml")
}
}
// ...
}
```
5. Чтобы указать файл конфигурации для конкретной разновидности продукта, применяется тот же принцип:
```groovy
android {
// ...
productFlavors {
flavor1 {
// ... flavor1 settings
ext.set("protector.configFile", "${project.rootDir}/protector-flavor1.xml")
}
flavor2 {
// ... flavor2 settings
ext.set("protector.configFile", "${project.rootDir}/protector-flavor2.xml")
}
}
// ...
}
```
Таким образом, можно управлять файлами конфигурации ГостПротектор для соответствующих вариантов сборки, используя параметры разновидностей, разновидности продуктов и типы сборки, например, следующим образом:
```groovy
android {
flavorDimensions "version", "target" // Пример параметров
productFlavors {
free {
dimension "version"
// ...
}
paid {
dimension "version"
// ...
}
googlePlay {
dimension "target"
// ...
}
amazonStore {
dimension "target"
// ...
}
}
buildTypes {
release {
// ...
// Установите конфигурацию на основе комбинации разновидностей
для сборок выпуска
productFlavors.free.googlePlay.ext.set("protector.configFile",
"${project.rootDir}/protector-free-google-release.xml")
productFlavors.paid.googlePlay.ext.set("protector.configFile",
"${project.rootDir}/protector-paid-google-release.xml")
productFlavors.free.amazonStore.ext.set("protector.configFile",
"${project.rootDir}/protector-free-amazon-release.xml")
productFlavors.paid.amazonStore.ext.set("protector.configFile",
"${project.rootDir}/protector-paid-amazon-release.xml")
}
debug {
// ...
// Установите конфигурацию на основе комбинации разновидностей
для отладочных сборок (необязательно)
productFlavors.free.googlePlay.ext.set("protector.configFile",
"${project.rootDir}/dexprotector-free-google-debug.xml")
// ... и т.д.
}
}
}
```
## Защита гибридных и кроссплатформенных приложений (React Native, Ionic, NativeScript, Cordova, Xamarin, Flutter)
### Гибридные и кроссплатформенные приложения на основе JavaScript и HTML
Защиты гибридных или кроссплатформенное приложение, разработанное с использованием таких фреймворков, как React Native, Ionic, NativeScript и Cordova.
Для целей защиты кода необходимо выбрать файлы JS и HTML с помощью шифрования ресурсов. Это означает установку такого фильтра:
<pre><code class="language-xml"><resourceEncryption mode="all"> <!-- Зашифровать все в ресурсах -->
<assets mode="on"> <!-- Специально выбрать активы -->
<filters>
<filter>**.html</filter> <!-- Зашифровать все файлы HTML -->
<filter>**.js</filter> <!-- Зашифровать все файлы JS -->
</filters>
</assets>
</resourceEncryption>
</code></pre>
### Xamarin
Каждая функция ГостПротектор доступна для Android-приложений на основе Xamarin, включая:
* **Защиты кода** и ресурсов посредством обфускации и шифрования классов, методов и строк для предотвращения статического анализа и реверс-инжиниринга.
* **Runtime Application Self-Protection (RASP)** — защита приложений во время выполнения с постоянными проверками операционной среды и сети связи для предотвращения динамического анализа и атак типа "человек посередине".
* **Проверки целостности** для предотвращения несанкционированного изменения кода и ресурсов и клонирования.
* Выделенный **CryptoModule** ГостПротектор, изолирующий криптографические данные и обработку для предотвращения перехвата криптографических ключей и вычислений.
Android-приложения Xamarin содержат байт-код Dalvik, ресурсы и нативные библиотеки. Внутри ресурсов находятся нативные библиотеки Mono Runtime и сборки Xamarin. Сборки Xamarin состоят из среды выполнения Xamarin и программного кода Xamarin.
Основные средства защиты ГостПротектор от статического анализа работают с байт-кодом Dalvik в Android-приложениях, разработанных на Xamarin, которые могут содержать **специальные классы Android** (Activity, ContentProvider, Receiver, Service), **классы поддержки Xamarin/Mono** и **классы сторонних библиотек**. Таким образом, все следующее применимо так же, как и для приложения, разработанного на Java или Kotlin:
* Шифрование строк
* Шифрование классов
* Сокрытие доступа
* Обфускация нативного кода (за исключением Mono Runtime)
* Шифрование нативного кода
* Защита от отладки нативного кода
* Шифрование файлов ресурсов и активов в `assets/`, `res/` и `root/`
* Обфускация имен ресурсов (`resources.arsc`)
* Обфускация `AndroidManifest.xml`: маскировка имен классов Applications/ActivityNames/ContentProviders/Receiver
Дополнительно `ГостПротектор` также способен взаимодействовать с Mono Runtime, что позволяет **шифровать сборки Xamarin**. Для этого необходимо использовать элемент `<xamarinAssemblies/>` в файле конфигурации ГостПротектор, чтобы включить шифрование сборок. Например:
<pre><code class="language-xml"><resourceEncryption>
<!-- ... другие настройки шифрования ресурсов ... -->
<xamarinAssemblies dir="assets/assemblies"/> <!-- Каталог по умолчанию -->
<!-- или -->
<!-- <xamarinAssemblies dir="custom/assembly/path"/> -->
</resourceEncryption>
</code></pre>
Для всех остальных механизмов защиты, включая проверки времени выполнения, специальная конфигурация не требуется.
### Flutter
ГостПротектор поддерживает приложения, разработанные с помощью Flutter, так же, как и нативные приложения; нет никаких различий в требованиях к конфигурации.
# ГостПротектор Студия
## Обзор
`ГостПротектор Студия` — это настольное приложение, включенное в каждую лицензию ГостПротектор. Студия предлагает простой графический интерфейс, в котором можно контролировать каждый аспект процесса защиты ГостПротектор. Студия позволяет:
* Активировать лицензию ГостПротектор
* Наблюдать за анализом исходного файла для защиты
* Настраивать параметры защиты для проекта
* Создавать профили защиты
* Визуализировать, как именно механизмы защиты ГостПротектор применяются к коду и ресурсам
* Управлять интеграцией с `Элис`
## Использование ГостПротектор Студии: Исполняемый файл ГостПротектор и файл лицензии
### Работа с исполняемым файлов ГостПротектор и файлом лицензии
Если файл `protector.jar` находится не в том же каталоге, что и ГостПротектор Студия, укажите его местоположение, прежде чем вы сможете начать использовать Студию.
Для просмотра и управления статусом лицензии, нажмите `Информация о лицензии` в правом нижнем углу открывающегося окна.
### Активация лицензии через Студию (онлайн)
1. Нажмите `'Информация о лицензии'` справа от панели в нижней части окна.
2. Нажмите `'Активировать лицензию'` и следуйте инструкциям в новом окне. Чтобы активировать лицензию и получить файл лицензии **онлайн**, необходимо ввести уникальный одноразовый код активации, указанный в электронном письме со ссылками для загрузки.
3. После успешной активации в домашнем каталоге пользователя будет создан файл лицензии `protector.licel`.
### Активация лицензии через Студию (оффлайн)
1. Нажмите `'Информация о лицензии'` справа от панели в нижней части окна.
2. Нажмите `'Активировать лицензию'` и следуйте инструкциям в новом окне. Если у вас нет активного подключения к Интернету или вы предпочитаете автономную активацию, введите уникальный одноразовый код активации, указанный в электронном письме со ссылками для загрузки, и нажмите `'Создать запрос активации'`.
3. После ввода действительного кода активации будет сгенерирован код запроса. Отправьте этот код запроса в нашу службу поддержки по электронной почте gostprotector@licel.ru. Вы получите код ответа не позднее, чем в течение 1 рабочего дня.
4. После получения кода ответа вернитесь в то же окно `'Активировать лицензию'` и нажмите `'У меня уже есть код ответа активации'`. В следующем окне введите полученный код ответа и нажмите `'Активировать'`, чтобы завершить процедуру активации лицензии.
5. После успешной активации в домашнем каталоге пользователя будет создан файл лицензии `protector.licel`.
## Защита APK, AAB или AAR с помощью ГостПротектор Студии
### Рекомендации по защите
Мы настоятельно рекомендуем использовать все предоставляемые функции защиты, поскольку каждый элемент защиты повышает уровень безопасности и устойчивость к вредоносному ПО, реверс-инжинирингу, несанкционированному вмешательству и атакам типа "человек посередине".
Настройка ГостПротектор осуществляется с помощью **единого XML-файла**, который можно редактировать непосредственно или через интерфейс ГостПротектор Студии.
Файл конфигурации по умолчанию (`protector.xml`) находится в корневом каталоге дистрибутива, но каждое приложение (или библиотека) может иметь разные требования по защите. Поэтому мы также настоятельно рекомендуем настроить свою конфигурацию, указав для защиты конфиденциальный код и ресурсы, а также включить механизмы защиты приложений во время выполнения и защиты сетевых подключений, предлагаемые ГостПротектор.
ГостПротектор Студия предлагает интуитивно понятный интерфейс, который поможет вам настроить и управлять процессом защиты. Он предлагает описания и подсказки для каждого механизма защиты в своих окнах "Параметры защиты" и позволяет применять выбранные параметры одним щелчком мыши. Затем эти параметры автоматически сохраняются в файле конфигурации XML, готовом к применению при запуске процесса ГостПротектор.
### Загрузить пакет для защиты
Первое окно позволяет указать файл для защиты, и начальный файла конфигурации, который можно будет отредактировать позже через Студию. Вы можете выбрать либо конфигурацию по умолчанию, включенную в дистрибутивный пакет, либо пользовательский файл конфигурации XML по вашему выбору.
### Управление параметрами защиты
После нажатия `'Открыть файл и применить настройки'` можно просмотреть проанализированную структуру пакета и управлять параметрами защиты.
Механизмы защиты кода и ресурсов (Шифрование классов, Сокрытие доступа, Шифрование строк, Шифрование ресурсов) можно применять непосредственно через обзор структуры пакета, выбрав класс или файл и используя переключатели фильтра.
Окно "Параметры защиты" предлагает обзор всех параметров конфигурации; можно управлять всеми механизмами защиты и применять фильтры через элементы интерфейса.
Любые изменения в конфигурации XML, внесенные через Студию, могут быть сохранены в любое время, в том числе после завершения процесса защиты.
На финальном этапе конфигурации защиты, есть возможность просмотреть анализ того, что в пакете будет защищено, выбрав вкладку "Обзор".
### Запустить защиту и просмотреть результаты защиты
Для защиты необходимо выбрать `'Запустить защиту'`, в процесс работы ГостПротектор будет отображать журнал выполненный действий.
После завершения защиты можно сохранить вновь созданный профиль конфигурации, чтобы на него можно было ссылаться, повторно использовать или адаптировать позже.
Разумеется, я переработаю текст, чтобы использовать более формальный стиль, избегая повелительного наклонения там, где это уместно, и заменяя "Защитите" на "Для защиты" или аналогичные конструкции.
# Элис - Мониторинг угроз и телеметрия
## Использование Элис с ГостПротектор
После релиза приложения, `ГостПротектор` будет отслеживать его безопасность во время использования в любой точке мира, и отправлять (при активации данного модуля) при этом все данные о рисках, угрозах и атаках в вашу учетную запись в системе телеметрии атак и аналитики угроз `Элис`.
`Элис` предлагает простую в использовании панель управления, посредством которой обеспечивается отслеживание ключевых инцидентов по мере их возникновения, включая любые случаи аномалий HTTP Public Key Pinning, несанкционированного вмешательства и сбоев. Пользователь имеет возможность просматривать указанные инциденты с разбивкой по времени и месту возникновения, а также адаптировать выходные данные в соответствии с потребностями формирования отчетов.
`ГостПротектор` и `Элис` также могут функционировать в сочетании с существующей системой анализа рисков, обеспечивая получение необходимой информации для мониторинга безопасности в формате, оптимальном для организации.
В результате обеспечивается удобный обзор каждого инцидента с момента его возникновения, гибкий инструмент поиска, осуществляющий сортировку по типу и содержимому атаки, а также уведомления при каждой активации средств защиты ГостПротектор.
---
## Начало работы с Элис
1. **Получение учетных данных для входа в Элис**
При наличии активной лицензии ГостПротектор, следует заполнить форму запроса для получения данных доступа к Элис, либо направить обращение по адресу `gostprotector@licel.ru`.
2. **Копирование ключа API для интеграции с Элис**
Вход в систему осуществляется с использованием имени пользователя и пароля, полученных ранее. На начальной странице Элис будет представлен уникальный автоматически сгенерированный ключ, используемый для интеграции Элис при конфигурировании ГостПротектор.
3. **Указание ключа API в файл конфигурации ГостПротектор**
С использованием ГостПротектор Студии или путем непосредственного редактирования файла конфигурации, добавьте элемент `<reportMonitoring>` и вложенный элемент `<apiKey>`, следующим образом:
<pre><code class="language-xml"><reportMonitoring>
<apiKey>ЗДЕСЬ_ВАШ_КЛЮЧ_API_ALICE</apiKey>
<!-- Необязательно: добавьте метод пользовательских полей, если это необходимо -->
<!-- <customFieldsUpdate>com.example.MyCustomFields</customFieldsUpdate> -->
<!-- Необязательно: установите уровень трассировки (0 или 1000 для отладки) -->
<!-- <trace>0</trace> -->
</reportMonitoring>
</code></pre>
Также возможно включение Элис через ГостПротектор Студию посредством
указания ключа API и, при необходимости, пользовательского метода.
4. **Защита приложения и получение первых отчетов**
Для защиты приложения используйте измененный файл конфигурации. Ключ API Элис будет интегрирован в приложение в процессе защиты. В дальнейшем, при обнаружении приложением угрозы, отчет будет зарегистрирован в Элис с использованием указанного ключа. В случае компрометации ключа, предусмотрена возможность генерации нового ключа в Элис и блокировки скомпрометированного. Пользователь может инициировать инцидент самостоятельно, либо ожидать регистрации реальных инцидентов. При отсутствии инцидентов, Элис отображает только начальную страницу и демонстрационный проект. При возникновении новых инцидентов, приложение автоматически передает отчетность в Элис.
Защитите свои приложения и данные клиентов с помощью ГостПротектор
