XopProtector

https://github.com/xopjack/xopprotector
Admin
XopProtector is an Android APK protection solution providing a build-time packer and on-device...
Tokens:177,839
Snippets:1,212
Trust Score:4.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### One-time setup: sync sample assets, build uni-app demo, sync XOP assets

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/README.md

One-time setup to export the uni-app demo resource package: syncs the SDK sample assets, installs dependencies, builds the app, and copies the output to the host assets.

```bat
gradlew.bat syncUnimpSampleAssets
cd uniapp-demo && npm install && npm run build:app && cd ..
gradlew.bat syncUnimpXopDemoAssets
```

--------------------------------

### Build installer from repository root

Source: https://github.com/xopjack/xopprotector/blob/main/installer/README.md

Run this command from the repository root to assemble the portable app and build the installer.

```bat
powershell -ExecutionPolicy Bypass -File scripts\release-desktop.ps1
```

--------------------------------

### Build portable folder and installer separately

Source: https://github.com/xopjack/xopprotector/blob/main/installer/README.md

Use these commands to build the portable folder first, then generate the installer.

```bat
powershell -ExecutionPolicy Bypass -File scripts\release-desktop.ps1 -SkipInstaller
powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1
```

--------------------------------

### Install tip: adb push and pm install -r -t

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/README.md

Fallback install method when incremental adb install fails: push the APK to /data/local/tmp and install with -r -t flags.

```bat
adb push executable\unimp-demo-protected.apk /data/local/tmp/unimp.apk
adb shell pm install -r -t /data/local/tmp/unimp.apk
```

--------------------------------

### NetGuard.install(Context)

Source: https://github.com/xopjack/xopprotector/blob/main/doc/netguard.md

Installs NetGuard from the shell bootstrap. This method initializes the NetGuard runtime for the given context.

```APIDOC
## NetGuard.install(Context)

### Description
Installs NetGuard from the shell bootstrap. This method initializes the NetGuard runtime for the given context.

### Method
install

### Parameters
- **context** (Context) - Required - The application context.

### Response
No return value.
```

--------------------------------

### Build Windows Installer

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Commands to build the Windows installer executable.

```powershell
powershell -ExecutionPolicy Bypass -File scripts\release-desktop.ps1
powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1
```

--------------------------------

### Packer execution command

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Example command to run the packer JAR file with specific protection options.

```bat
java -jar packer/build/libs/protector-packer-*.jar app.apk -o out.apk ^
  --shell-dir executable/shell-files ^
  --true-vmp-prefix Lcom/yqsh/protectordemo/Business; ^
  --protect-so
```

--------------------------------

### Build Portable Executable with Optional Flags

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Builds the portable folder without generating the installer.

```powershell
powershell -ExecutionPolicy Bypass -File scripts\release-desktop.ps1 -SkipInstaller
```

--------------------------------

### Threat JSON report example

Source: https://github.com/xopjack/xopprotector/blob/main/doc/threat-telemetry.md

Example of a threat report JSON object written to the ring and threats.log. Contains timestamp, reason, RASP action, PID, and SDK version. Drain via JniBridge.drainThreatReports() to get a JSON array.

```json
{"ts":1710000000,"reason":"frida_maps","rasp_action":2,"pid":1234,"sdk":30}
```

--------------------------------

### Channel JSON payload example

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Example of the JSON payload stored in the APK Signing Block for a channel named 'huawei'.

```json
{"channel":"huawei"}
```

--------------------------------

### Packer CLI channel get

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Prints the channel of the given APK. Prints empty if unmarked.

```APIDOC
## CLI channel get

### Description
Prints the channel of the given APK. Prints empty if unmarked.

### Command
`channel get <apk>`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.

### Output
- Prints the channel name, or empty if the APK is unmarked.
```

--------------------------------

### PVM2 image binary layout

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-mvp.md

Binary layout of the PVM2 image stored in code.bin. Starts with magic 'PVM2', version 1, then fields for register count, instruction size, reserved, code size, return kind, reserved2, string count, string pool, and instruction bytes.

```text
magic[4] = 'P''V''M''2'
u16 version = 1
u16 reg_count
u16 ins_size
u16 reserved
u16 code_size          # bytes following string pool
u8  ret_kind           # 0=V 1=I 2=J 3=L 4=Z
u8  reserved2
u16 str_count
# str_count × (u16 len + utf8 bytes)
# code_size bytes of instructions
```

--------------------------------

### Build and verify UniMP host demo

Source: https://github.com/xopjack/xopprotector/blob/main/unimp-host/README.md

Runs the UniMP host build and protection workflow for the demo: syncs sample assets, builds the XOP demo and syncs its assets, assembles the debug host APK, applies protection, and verifies the protected demo. Run from the repository root.

```bat
gradlew.bat syncUnimpSampleAssets
gradlew.bat buildUnimpXopDemo syncUnimpXopDemoAssets
gradlew.bat :unimp-host:assembleDebug
gradlew.bat protectUnimpDemo
powershell -File scripts\verify-unimp-demo.ps1 -Mode protected
```

--------------------------------

### Build uni-app demo with uni CLI

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/scripts/build-wgt.md

Build the uni-app demo using the uni CLI and sync the generated assets to the host project. The first block runs the build and sync as separate steps; the second performs both in one command.

```bat
cd uniapp-demo
npm install
npm run build:app
cd ..
gradlew.bat syncUnimpXopDemoAssets
```

```bat
gradlew.bat buildUnimpXopDemo syncUnimpXopDemoAssets
```

--------------------------------

### Programmatic Library API Usage

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Demonstrates how to initialize and run the protector using the Java API.

```java
ProtectOptions opts = new ProtectOptions();
opts.inputApk = new File("app.apk");
opts.outputApk = new File("out.apk");
opts.shellDir = new File("executable/shell-files");
ProtectResult result = new Protector().protect(opts);
```

--------------------------------

### Export probe app: buildUnimpXopDemo and syncUnimpXopDemoAssets

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/README.md

Builds the uni-app demo resource package and copies it to the host assets. Produces the www directory and optional wgt file.

```bat
gradlew.bat buildUnimpXopDemo syncUnimpXopDemoAssets
```

--------------------------------

### Build socket_example executable

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/examples/CMakeLists.txt

Defines an executable target named socket_example from main.cc and socket_example.cc, linking against the dobby library.

```cmake
add_executable(socket_example
  main.cc
  socket_example.cc
  )

target_link_libraries(socket_example
  dobby
  )
```

--------------------------------

### Build for linux

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Commands to prepare the environment and build Dobby for Linux.

```shell
# prepare and download cmake/llvm
sh scripts/setup_linux_cross_compile.sh
python3 scripts/platform_builder.py --platform=linux --arch=all --cmake_dir=$HOME/opt/cmake-3.20.2 --llvm_dir=$HOME/opt/llvm-14.0.0
```

--------------------------------

### Build packer, shell, and demo with Gradle

Source: https://github.com/xopjack/xopprotector/blob/main/CONTRIBUTING.md

Run from the repository root. Requires JDK 17+ and the Android SDK/NDK (via local.properties or ANDROID_HOME/ANDROID_SDK_ROOT).

```bat
gradlew.bat :packer:jar
gradlew.bat exportShellFiles
gradlew.bat :demo:assembleRelease
```

--------------------------------

### Build and release commands

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Commands to build the demo and release it to a device using a serial number.

```bat
gradlew.bat protectDemo
powershell -File scripts\release-demo.ps1 -Serial <deviceSerial>
```

--------------------------------

### Release Build Configuration

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Command to run the desktop application in Release mode.

```bat
cd desktop
dotnet run --project Protector.Desktop -c Release
```

--------------------------------

### Build socket_example_x shared library

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/examples/CMakeLists.txt

Defines a shared library target named socket_example_x from socket_example.cc, linking against the dobby library.

```cmake
add_library(socket_example_x SHARED
  socket_example.cc
  )

target_link_libraries(socket_example_x
  dobby
  )
```

--------------------------------

### Build and protect: assembleDebug, protectUnimpDemo, verify

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/README.md

Builds the debug APK, applies protection, and runs the protected-mode verification script on an emulator/device.

```bat
gradlew.bat :unimp-host:assembleDebug
gradlew.bat protectUnimpDemo
powershell -File scripts\verify-unimp-demo.ps1 -Mode protected
```

--------------------------------

### Build for android

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Commands to prepare the environment and build Dobby for Android.

```shell
# prepare and download cmake/llvm/ndk
sh scripts/setup_linux_cross_compile.sh
sh scripts/setup_linux_cross_compile.sh
python3 scripts/platform_builder.py --platform=linux --arch=all --cmake_dir=$HOME/opt/cmake-3.20.2 --llvm_dir=$HOME/opt/llvm-14.0.0 --android_ndk_dir=$HOME/opt/ndk-r25b
```

--------------------------------

### Run Windows desktop app with dotnet

Source: https://github.com/xopjack/xopprotector/blob/main/CONTRIBUTING.md

Run the Windows desktop project from the `desktop` directory. Requires .NET SDK 7+.

```bat
cd desktop
dotnet run --project Protector.Desktop
```

--------------------------------

### Protect the demo APK

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Assemble the release version of the demo and run the protection process.

```bat
gradlew.bat :demo:assembleRelease
gradlew.bat protectDemo
```

--------------------------------

### Build for host

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Standard CMake build commands for the host platform.

```shell
cd Dobby && mkdir cmake-build-host && cd cmake-build-host
cmake ..
make -j4
```

--------------------------------

### Output layout for UniMP

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/scripts/build-wgt.md

Expected output layout for the UniMP build: the www directory and the .wgt file are placed under the host's assets folder.

```text
unimp-host/src/main/assets/apps/__UNI__XOPDEMO/www/
unimp-host/src/main/assets/__UNI__XOPDEMO.wgt
```

--------------------------------

### Java: Read encrypted asset with ProtectorAssets

Source: https://github.com/xopjack/xopprotector/blob/main/doc/assets-encrypt.md

Use ProtectorAssets.readString and ProtectorAssets.open to read encrypted assets after --encrypt-assets. Plain AssetManager.open will fail with FileNotFoundException because the original paths are removed.

```java
String s = ProtectorAssets.readString(context, "secret.txt");
InputStream in = ProtectorAssets.open(context, "config/app.json");
```

--------------------------------

### Build packer and export shell files

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Build the packer JAR and export the necessary shell files to the executable/shell-files directory.

```bat
gradlew.bat :packer:jar
gradlew.bat exportShellFiles
```

--------------------------------

### Verify with Gradle and PowerShell

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-phase5.md

Run the protectDemo Gradle task and the release-demo PowerShell script to verify the implementation. Expect logcat output with status=PASS and no skips for floatProbe/syncProbe.

```powershell
.\gradlew.bat protectDemo
.\scripts\release-demo.ps1 -Serial <device>
# expect: TRUE_VMP ...floatProbe / syncProbe (no skip), status=PASS
```

--------------------------------

### Verify release with release-demo.ps1

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-phase4.md

Run the release script with a serial number to verify the build. Expect logcat output with status=PASS and so=42, optionally showing 'decrypted business SO .text: libdemo_biz.so'.

```powershell
.\scripts\release-demo.ps1 -Serial 111410D096402300012
# expect logcat: status=PASS and so=42; optional "decrypted business SO .text: libdemo_biz.so"
```

--------------------------------

### Configure Android SDK in local.properties

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Set the Android SDK path in the local.properties file at the repository root. Ensure backslashes are escaped on Windows.

```properties
# Windows example (escape backslashes)
sdk.dir=D\:\\Android\\Sdk
```

--------------------------------

### Development Build Commands

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Commands to build the packer jar, export shell files, and run the desktop application.

```bat
gradlew.bat :packer:jar
gradlew.bat exportShellFiles
cd desktop
dotnet run --project Protector.Desktop
```

--------------------------------

### Run protected demo smoke test with release-demo.ps1

Source: https://github.com/xopjack/xopprotector/blob/main/CONTRIBUTING.md

Runs the protected demo smoke test. Requires `ANDROID_HOME` or `ANDROID_SDK_ROOT` to be set.

```bat
powershell -ExecutionPolicy Bypass -File scripts\release-demo.ps1 -SkipInstall
```

--------------------------------

### Gradle commands for source and LLVM obfuscation

Source: https://github.com/xopjack/xopprotector/blob/main/doc/llvm-obfuscation.md

Commands to build with default source-level obfuscation, disable source macros, enable LLVM passes, and pass Hikari-style flags. Requires OLLVM/Hikari clang for LLVM mode.

```bash
# Default release: source-level obfuscation only
.\gradlew.bat :native:assembleRelease

# Disable source macros
.\gradlew.bat :native:assembleRelease -Pprotector.srcObf=false

# Enable LLVM passes (requires OLLVM/Hikari clang as NDK toolchain)
.\scripts\probe-llvm-obf.ps1
.\gradlew.bat :native:assembleRelease -Pprotector.llvmObf=true

# Hikari-style flags (comma-separated → CMake ';')
.\gradlew.bat :native:assembleRelease -Pprotector.llvmObf=true `
  -Pprotector.llvmObfFlags="-mllvm,-enable-cffobf,-mllvm,-enable-bcfobf,-mllvm,-enable-subobf"
```

--------------------------------

### CMake configuration for demo_biz shared library

Source: https://github.com/xopjack/xopprotector/blob/main/demo/src/main/cpp/CMakeLists.txt

Defines a shared library target 'demo_biz' from demo_biz.cpp, links the Android log library, and sets a linker option to use a 16KB page size.

```cmake
cmake_minimum_required(VERSION 3.22.1)
project(demo_biz)

add_library(demo_biz SHARED demo_biz.cpp)
find_library(log-lib log)
target_link_libraries(demo_biz ${log-lib})
target_link_options(demo_biz PRIVATE "-Wl,-z,max-page-size=16384")
```

--------------------------------

### CMake configuration for bytehook sample

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/bytehook_sample/src/main/cpp/CMakeLists.txt

Build script for the bytehook sample. Sets minimum CMake version 4.0.2, defines architecture-specific link flags for arm64-v8a, x86_64, and riscv64, normalizes build type to 'release' for relwithdebinfo, includes bytehook dependency either from local_dependency.cmake or via find_package, and creates two shared libraries: hacker (hacker.c, hacker_bytehook.cpp) and sample (sample.c). Both libraries use strict warnings (-Weverything -Werror) and link against log; hacker also links bytehook::bytehook.

```cmake
cmake_minimum_required(VERSION 4.0.2)

if((${ANDROID_ABI} STREQUAL "arm64-v8a") OR (${ANDROID_ABI} STREQUAL "x86_64") OR (${ANDROID_ABI} STREQUAL "riscv64"))
    set(ARCH_LINK_FLAGS "-Wl,-z,max-page-size=16384")
else()
    set(ARCH_LINK_FLAGS "")
endif()

string(TOLOWER ${CMAKE_BUILD_TYPE} BUILD_TYPE_DIRNAME)
if(${BUILD_TYPE_DIRNAME} STREQUAL "relwithdebinfo")
    set(BUILD_TYPE_DIRNAME "release")
endif()

# bytehook
if(DEPENDENCY_ON_LOCAL_LIBRARY)
    include(${CMAKE_CURRENT_SOURCE_DIR}/../../../../bytehook/local_dependency.cmake)
else()
    find_package(bytehook REQUIRED CONFIG)
endif()

# libhacker.so
add_library(hacker SHARED hacker.c hacker_bytehook.cpp)
target_compile_features(hacker PRIVATE c_std_11 cxx_std_17)
target_compile_options(hacker PRIVATE -Weverything -Werror -Wno-c++98-compat-pedantic -Wno-zero-as-null-pointer-constant -Wno-old-style-cast)
target_include_directories(hacker PRIVATE .)
set_target_properties(hacker PROPERTIES LINK_FLAGS "${ARCH_LINK_FLAGS}")
target_link_libraries(hacker log bytehook::bytehook)

# libsample.so
add_library(sample SHARED sample.c)
target_compile_features(sample PRIVATE c_std_17)
target_compile_options(sample PRIVATE -Weverything -Werror)
target_include_directories(hacker PRIVATE .)
set_target_properties(sample PROPERTIES LINK_FLAGS "${ARCH_LINK_FLAGS}")
target_link_libraries(sample log)
```

--------------------------------

### Packer command-line options

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

List of available flags and configuration options for the packer tool.

```text
--profile <name>           hollow/VMP: balanced (default) | industry | aggressive | perf | max
--hollow-prefix <desc>     allowlist type prefix (repeatable; disables auto include)
--vmp-prefix <desc>        PVM1-pack methods under type prefix (repeatable)
--true-vmp-prefix <desc>   PVM2 true VMP under type prefix (repeatable)
--protect-so               RC4-encrypt safe business lib/*.so .text (default ON)
--no-protect-so            disable business SO .text encryption
--encrypt-assets           PAS1+AES-GCM encrypt assets/** → protector/aenc (default OFF)
--no-encrypt-assets        disable assets encryption
--enable-res-protect       shorten res/ paths + rewrite resources.arsc (default OFF)
--detect-proxy             enable NetGuard proxy/VPN heuristics (default OFF)
--pin-certs <file>         leaf cert SHA-256 pins for NetGuard TrustManager wrapper
--channel <name>           stamp Walle-compatible channel after sign (needs --keystore)
--channels <file>          batch stamp → <out>-<channel>.apk (needs --keystore)
--protect-so-mode <m>      safe (default) | aggressive | max
--protect-so-budget-mb <n> SO protect size budget MB (default 12; max ignores)
--protect-so-max-file-mb <n> skip SO if unpacked >N MB (default 8; max ignores)
--protect-so-abi <abi>|all only select basenames present under ABI (default all)
--so-decrypt-mode <m>      eager (default)=full SO materialize+preload at cold start;
                           lazy=on-demand + background fill → so_plain_ready warm reuse
--json-progress            NDJSON progress on stdout (desktop UI)
--risk-flags / --rasp-action / --report-enabled
```

--------------------------------

### Include bytehook.h header

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Includes the bytehook.h header file for using the hooking functions.

```C
#include "bytehook.h"
```

--------------------------------

### CMake build options

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Configuration options available for the Dobby build process.

```cmake
option(DOBBY_GENERATE_SHARED "Build shared library" ON)

option(DOBBY_DEBUG "Enable debug logging" OFF)

option(NearBranch "Enable near branch trampoline" ON)

option(FullFloatingPointRegisterPack "Save and pack all floating-point registers" OFF)

option(Plugin.SymbolResolver "Enable symbol resolver" ON)

option(Plugin.ImportTableReplace "Enable import table replace " OFF)

option(Plugin.Android.BionicLinkerUtil "Enable android bionic linker util" OFF)

option(BUILD_EXAMPLE "Build example" OFF)

option(BUILD_TEST "Build test" OFF)
```

--------------------------------

### Build for iphoneos

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Command to build Dobby for the iphoneos platform.

```shell
python3 scripts/platform_builder.py --platform=iphoneos --arch=all
```

--------------------------------

### Verify res-protect with Gradle

Source: https://github.com/xopjack/xopprotector/blob/main/doc/res-protect.md

Run the protectDemo Gradle task to verify res path obfuscation. Expect output lines showing paths=N, arsc_rewritten=N, files_moved=N. Then unzip the demo-protected.apk to check for r/a/... paths and the mapping file assets/protector/res_mapping.txt.

```powershell
.\gradlew.bat protectDemo
# expect: res-protect: paths=N arsc_rewritten=N files_moved=N
# unzip demo-protected.apk → look for r/a/... and assets/protector/res_mapping.txt
```

--------------------------------

### CLI: Pack APK with --encrypt-assets

Source: https://github.com/xopjack/xopprotector/blob/main/doc/assets-encrypt.md

Run the packer with --encrypt-assets to enable asset encryption. This is a CLI-only flag; the Desktop UI panel is collapsed. Related flags --enable-res-protect, --detect-proxy, --pin-certs are also CLI-only.

```text
java -jar protector-packer.jar app.apk -o out.apk --shell-dir … \
  --encrypt-assets
```

--------------------------------

### Packer CLI channel batch

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Batch stamps multiple APKs from a file.

```APIDOC
## CLI channel batch

### Description
Batch stamps multiple APKs from a file.

### Command
`channel batch <apk> <file> [-o-dir dir]`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.
- `-o-dir dir` (string) - Optional - Output directory for the stamped APKs.
```

--------------------------------

### Run industry profile packer command

Source: https://github.com/xopjack/xopprotector/blob/main/doc/industry-profile.md

Executes the protector-packer JAR with the industry profile and signing configuration.

```bat
java -jar protector-packer-0.6.25.jar app.apk -o out.apk ^
  --shell-dir executable\shell-files ^
  --profile industry ^
  --keystore release.jks --alias KEY --storepass *** --keypass *** ^
  --channel customer-a
```

--------------------------------

### Initialize ByteHook in Java

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Initializes ByteHook by calling ByteHook.init() in a synchronized static method.

```Java
import com.bytedance.android.bytehook.ByteHook;

public class MySdk {
    public static synchronized void init() {
        ByteHook.init();
    }
}
```

--------------------------------

### Packer CLI --channels

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Emits sibling out-<channel>.apk files for each line in the given file.

```APIDOC
## CLI --channels

### Description
Emits sibling out-<channel>.apk files for each line in the given file.

### Command
`--channels <file>`

### Parameters
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.

### Output
- For each channel, a sibling file named `out-<channel>.apk` is emitted.
```

--------------------------------

### PowerShell: Verify asset encryption

Source: https://github.com/xopjack/xopprotector/blob/main/doc/assets-encrypt.md

Manual verification after packing with --encrypt-assets. Expect output 'assets encrypt: 0/N … 100%' and 'encrypt_assets=true'.

```powershell
# Manual CLI pack with --encrypt-assets; app must call ProtectorAssets.
# expect: assets encrypt: 0/N … 100%; encrypt_assets=true
```

--------------------------------

### protectDemo PVM2 admission output

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-compatibility-matrix.md

Output from running `.\.gradlew.bat protectDemo` with `--true-vmp-prefix Lcom/yqsh/protectordemo/Business;`. Shows 100% admission rate and empty unsupported opcode map.

```text
PVM2 admission: candidates=14 attempted=14 success=14 fallback=0 rate=100.0%
PVM2 skip reasons: unsupported_opcode=0 too_many_regs=0 try_catch=0 branch=0 type=0 other=0
TRUE_VMP unsupported opcodes (count): {}
```

--------------------------------

### CI check: gradlew.bat checkUnimpDemo

Source: https://github.com/xopjack/xopprotector/blob/main/uniapp-demo/README.md

Runs CI checks without a device: assembleRelease, packer tests, exportShellFiles, and asset sanity checks.

```bat
gradlew.bat checkUnimpDemo
```

--------------------------------

### Run packer CLI

Source: https://github.com/xopjack/xopprotector/blob/main/README.md

Execute the packer JAR directly against an APK file, specifying the output path and shell directory.

```bat
java -jar packer\build\libs\protector-packer-*.jar app.apk -o out.apk ^
  --shell-dir executable\shell-files
```

--------------------------------

### Apply prefab_bypass.gradle for x86/x86_64

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Adds the prefab_bypass.gradle script to the module's build.gradle when using prefab dependency bytehook under x86 and x86_64 architectures.

```Gradle
apply from: rootProject.file('gradle/prefab_bypass.gradle')
```

--------------------------------

### Packer CLI --channel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Stamps the primary signed output with the specified channel name. Requires --keystore.

```APIDOC
## CLI --channel

### Description
Stamps the primary signed output with the specified channel name. Requires --keystore.

### Command
`--channel <name>`

### Parameters
- `<name>` (string) - Required - The channel name to stamp.

### Notes
- Requires `--keystore`.
- Stamping happens after V2/V3 signing and does not invalidate the signature.
```

--------------------------------

### Packer CLI channel batch

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Batch stamps multiple APKs with channels from a file.

```APIDOC
## CLI channel batch

### Description
Batch stamps multiple APKs with channels from a file.

### Command
`channel batch <apk> <file> [-o-dir dir]`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.
- `-o-dir dir` (string) - Optional - Output directory for the stamped APKs.

### Output
- For each channel, an APK stamped with that channel is emitted.
```

--------------------------------

### Packer CLI channel batch

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Batch stamps an APK with multiple channels from a file.

```APIDOC
## CLI channel batch

### Description
Batch stamps an APK with multiple channels from a file.

### Command
`channel batch <apk> <file> [-o-dir dir]`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.
- `-o-dir dir` (string) - Optional - Output directory for the stamped APKs.

### Output
- Emits stamped APKs for each channel in the file.
```

--------------------------------

### Build for macos

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Command to build Dobby for the macos platform.

```shell
python3 scripts/platform_builder.py --platform=macos --arch=all
```

--------------------------------

### Pick first libbytehook.so in app packaging

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Resolves conflicts caused by duplicate libbytehook.so files when using ByteHook in an APP project.

```Gradle
android {
    packagingOptions {
        pickFirst '**/libbytehook.so'
    }
}
```

--------------------------------

### Packer CLI channel batch

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Batch stamps multiple channels onto an APK from a file.

```APIDOC
## CLI channel batch

### Description
Batch stamps multiple channels onto an APK from a file.

### Command
`channel batch <apk> <file> [-o-dir dir]`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.
- `-o-dir dir` (string) - Optional - Output directory for the stamped APKs.

### Output
- For each channel, a stamped APK is emitted in the specified output directory (or current directory if not specified).
```

--------------------------------

### Entry method signature: VmBridge->interpret

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-mvp.md

The JNI trampoline entry point for PVM2 interpretation. The method signature is Lcom/yqsh/protector/shell/VmBridge;->interpret(II[Ljava/lang/Object;)Ljava/lang/Object;.

```text
Lcom/yqsh/protector/shell/VmBridge;->interpret(II[Ljava/lang/Object;)Ljava/lang/Object;
```

--------------------------------

### Hi-MC after PR10 PVM2 admission output

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-compatibility-matrix.md

Output from running with `--true-vmp-prefix Lcom/zhd/mech/himc/` after PR10 (0x2b lowered to CONST+IF_EQ). Shows 99.4% admission rate, no unsupported opcodes, and remaining skips due to regs/size.

```text
PVM2 admission: candidates=900 attempted=900 success=895 fallback=5 rate=99.4%
PVM2 skip reasons: unsupported_opcode=0 too_many_regs=3 try_catch=0 branch=0 type=0 other=2
TRUE_VMP unsupported opcodes (count): {}
```

--------------------------------

### Build with Android Studio CMake

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/Dobby/docs/compile.md

Configuration snippet for integrating Dobby into an Android Studio project via CMake.

```cmake
if(NOT TARGET dobby)
set(DOBBY_DIR /Users/jmpews/Workspace/Project.wrk/Dobby)
macro(SET_OPTION option value)
  set(${option} ${value} CACHE INTERNAL "" FORCE)
endmacro()
SET_OPTION(DOBBY_DEBUG OFF)
SET_OPTION(DOBBY_GENERATE_SHARED OFF)
add_subdirectory(${DOBBY_DIR} dobby)
get_property(DOBBY_INCLUDE_DIRECTORIES
  TARGET dobby
  PROPERTY INCLUDE_DIRECTORIES)
include_directories(
  .
  ${DOBBY_INCLUDE_DIRECTORIES}
  $<TARGET_PROPERTY:dobby,INCLUDE_DIRECTORIES>
)
endif()

add_library(native-lib SHARED
  ${DOBBY_DIR}/examples/socket_example.cc
  native-lib.cpp)
```

--------------------------------

### Packer command: --true-vmp-prefix

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-mvp.md

Command-line option for the packer to mark methods with the given prefix for PVM2 true VMP. Repeatable; only admission-checked methods are affected. Unsupported opcodes or prototypes fall back to normal hollowing or PVM1 via --vmp-prefix.

```text
--true-vmp-prefix Lcom/foo/   # repeatable; admission-checked methods only
```

--------------------------------

### Packer CLI channel batch

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Batch stamps multiple channels from a file onto an APK.

```APIDOC
## CLI channel batch

### Description
Batch stamps multiple channels onto an APK from a file.

### Command
`channel batch <apk> <file> [-o-dir dir]`

### Parameters
- `<apk>` (string) - Required - Path to the APK file.
- `<file>` (string) - Required - Path to a file containing channel names, one per line. Lines starting with `#` and blank lines are ignored.
- `-o-dir dir` (string) - Optional - Output directory for the stamped APKs.

### Output
- For each channel, an APK stamped with that channel is emitted.
```

--------------------------------

### Hi-MC before PR10 PVM2 admission output

Source: https://github.com/xopjack/xopprotector/blob/main/doc/pvm2-compatibility-matrix.md

Output from running with `--true-vmp-prefix Lcom/zhd/mech/himc/` before PR10. Shows 99.3% admission rate, one unsupported opcode (0x2b), and three too_many_regs skips.

```text
PVM2 admission: candidates=900 attempted=900 success=894 fallback=6 rate=99.3%
PVM2 skip reasons: unsupported_opcode=1 too_many_regs=3 try_catch=0 branch=0 type=0 other=2
TRUE_VMP unsupported opcodes (count): {0x2b=1}
```

--------------------------------

### Encode Java strings from config with obsc_encode.py

Source: https://github.com/xopjack/xopprotector/blob/main/doc/string-obfuscation.md

Runs the Python encoding tool in Java mode, reading strings from 'protector/config.json'.

```bash
python scripts/obsc_encode.py --java "protector/config.json"
```

--------------------------------

### Runtime channel retrieval in Java

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Java code to retrieve the channel from the APK Signing Block at runtime. Use getChannel(context) for the current app or getChannel(apkFile) for a specific APK file.

```java
String ch = ChannelReader.getChannel(context); // or getChannel(apkFile)
```

--------------------------------

### NetGuard usage in app: wrapping trust manager and rescanning

Source: https://github.com/xopjack/xopprotector/blob/main/doc/netguard.md

Use after shell bootstrap to wrap the system trust manager for certificate pinning and to rescan before sensitive calls. NetGuard is opt-in and not enabled by default.

```java
// After shell bootstrap (automatic):
X509TrustManager pinned = NetGuard.wrappingTrustManager(systemTm);
NetGuard.rescan(context); // before sensitive calls
```

--------------------------------

### Runtime ChannelReader.getChannel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Runtime API to retrieve the channel from the APK Signing Block.

```APIDOC
## Runtime ChannelReader.getChannel

### Description
Retrieves the channel name from the APK Signing Block. Can be called with a Context or an APK file.

### Method
`ChannelReader.getChannel(context)` or `ChannelReader.getChannel(apkFile)`

### Parameters
- `context` (Context) - Required - The application context.
- `apkFile` (File) - Required - The APK file to read the channel from.

### Returns
- `String` - The channel name, or empty if unmarked.
```

--------------------------------

### Optional aggregate flag: --auto-true-vmp

Source: https://github.com/xopjack/xopprotector/blob/main/doc/auto-true-vmp-contract.md

Optional aggregate CLI flag for auto True-VMP. Accepts values payment, industry, both, or off. Not required for Desktop MVP.

```text
--auto-true-vmp payment|industry|both|off
```

--------------------------------

### Add ByteHook dependency in Android.mk

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Links the bytehook library to a native module using Android.mk. Imports the prefab/bytehook module.

```Makefile
include $(CLEAR_VARS)
LOCAL_MODULE           := mylib
LOCAL_SRC_FILES        := mylib.c
LOCAL_SHARED_LIBRARIES += bytehook
include $(BUILD_SHARED_LIBRARY)

$(call import-module,prefab/bytehook)
```

--------------------------------

### Runtime ChannelReader.getChannel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Retrieves the channel from the APK Signing Block at runtime.

```APIDOC
## Runtime ChannelReader.getChannel

### Description
Retrieves the channel name from the APK Signing Block. Can be called with a Context or an APK file.

### Method
`String ChannelReader.getChannel(Context context)`
`String ChannelReader.getChannel(File apkFile)`

### Parameters
- `context` (Context) - Required - The application context.
- `apkFile` (File) - Required - The APK file to read the channel from.

### Returns
- `String` - The channel name, or empty if unmarked.
```

--------------------------------

### Runtime ChannelReader.getChannel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Retrieves the channel from the APK Signing Block at runtime.

```APIDOC
## Runtime ChannelReader.getChannel

### Description
Retrieves the channel name from the APK Signing Block. Can be called with a Context or an APK file.

### Method
`String ChannelReader.getChannel(Context context)`
`String ChannelReader.getChannel(File apkFile)`

### Parameters
- `context` (Context) - Required - The application context.
- `apkFile` (File) - Required - The APK file to read the channel from.

### Returns
- (String) - The channel name, or null/empty if unmarked.
```

--------------------------------

### Runtime ChannelReader.getChannel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Retrieves the channel from the APK Signing Block at runtime.

```APIDOC
## Runtime ChannelReader.getChannel

### Description
Retrieves the channel name from the APK Signing Block. Can be called with a Context or an APK file.

### Method
`String ChannelReader.getChannel(Context context)`
`String ChannelReader.getChannel(File apkFile)`

### Parameters
- `context` (Context) - Required - The application context.
- `apkFile` (File) - Required - The APK file to read the channel from.

### Returns
- (String) - The channel name, or empty if unmarked.
```

--------------------------------

### Pin sensitive packages with True-VMP prefixes

Source: https://github.com/xopjack/xopprotector/blob/main/doc/industry-profile.md

Manually specifies packages for True-VMP protection when they reside outside the Manifest package or when token rules miss.

```bat
  --true-vmp-prefix Lcom/zhd/ts/license/ ^
  --true-vmp-prefix Lcom/zhd/common/crypto/
```

--------------------------------

### True-VMP policy line format

Source: https://github.com/xopjack/xopprotector/blob/main/doc/auto-true-vmp-contract.md

Exact key prefix for the policy line, stable for grepping. Shows effective values for payment and industry, count of prefixes, industry scope, and source indicators.

```text
True-VMP policy: payment=<on|off> industry=<on|off> prefixes=<n> industry_scope=<Lcom/…/|none> (profile=<name>, payment_src=<default|cli>, industry_src=<default|cli>)
```

--------------------------------

### CMake build configuration for bytehooksystest

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/bytehook_systest/src/main/cpp/CMakeLists.txt

Defines the CMake project, sets architecture-specific link flags, includes the bytehook dependency, and builds the bytehooksystest shared library with strict warnings and optional sanitizer or size optimizations.

```cmake
cmake_minimum_required(VERSION 4.0.2)
project(systest)

if((${ANDROID_ABI} STREQUAL "arm64-v8a") OR (${ANDROID_ABI} STREQUAL "x86_64"))
    set(ARCH_LINK_FLAGS "-Wl,-z,max-page-size=16384")
else()
    set(ARCH_LINK_FLAGS "")
endif()

# bytehook
if(DEPENDENCY_ON_LOCAL_LIBRARY)
    include(${CMAKE_CURRENT_SOURCE_DIR}/../../../../bytehook/local_dependency.cmake)
else()
    find_package(bytehook REQUIRED CONFIG)
endif()

# libbytehooksystest.so
file(GLOB SYSTEST_SRC *.c)
add_library(bytehooksystest SHARED ${SYSTEST_SRC})
target_compile_features(bytehooksystest PRIVATE c_std_11)
target_compile_options(bytehooksystest PRIVATE -Weverything -Werror -Wno-unused-function -Wno-unused-macros)
target_include_directories(bytehooksystest PRIVATE .)
target_link_libraries(bytehooksystest log bytehook::bytehook)

if(DEPENDENCY_ON_LOCAL_LIBRARY)
    target_compile_options(bytehooksystest PRIVATE -DDEPENDENCY_ON_LOCAL_LIBRARY)
endif()

if(USEASAN)
    target_compile_options(bytehooksystest PRIVATE -fsanitize=address -fno-omit-frame-pointer)
    target_link_options(bytehooksystest PRIVATE ${ARCH_LINK_FLAGS} -fsanitize=address)
else()
    target_compile_options(bytehooksystest PRIVATE -Os -ffunction-sections -fdata-sections)
    target_link_options(bytehooksystest PRIVATE ${ARCH_LINK_FLAGS} -Os -Wl,--exclude-libs,ALL -Wl,--gc-sections -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/systest.map.txt)
endif()
```

--------------------------------

### Set prefabVersion for AGP earlier than 7.1.0

Source: https://github.com/xopjack/xopprotector/blob/main/native/src/main/cpp/external/bhook/README.md

Adds the android.prefabVersion=2.0.0 configuration to gradle.properties when using Android Gradle Plugin earlier than 7.1.0, because ByteHook uses the prefab package schema v2.

```Properties
android.prefabVersion=2.0.0
```

--------------------------------

### ChannelReader.getChannel

Source: https://github.com/xopjack/xopprotector/blob/main/doc/channel.md

Runtime API to retrieve the channel from the APK Signing Block.

```APIDOC
## ChannelReader.getChannel

### Description
Retrieves the channel name from the APK Signing Block. Can be called with a Context or an APK file.

### Method
`String ChannelReader.getChannel(Context context)`
`String ChannelReader.getChannel(File apkFile)`

### Parameters
- `context` (Context) - Required - The application context.
- `apkFile` (File) - Required - The APK file to read the channel from.

### Returns
- (String) - The channel name, or empty if unmarked.
```

--------------------------------

### Crash breadcrumb file format

Source: https://github.com/xopjack/xopprotector/blob/main/doc/threat-telemetry.md

Format of the crash_reason.txt file written before RASP Block kill paths. Contains timestamp, PID, crash kind (sigill, sigsegv, abort, hang, exit), reason, and SDK version.

```text
ts=...
pid=...
kind=sigill|sigsegv|abort|hang|exit
reason=...
sdk=...
```
Tokens:
Raw