phantom-frida

phantom-frida собирает Android Frida Server и Gadget из исходного кода, изменяя при этом целевой набор наблюдаемых идентификаторов времени выполнения. Это сборочный и проверочный стенд, а не обещание, что каждый специфичный для приложения метод обнаружения будет обойдён.

Текущая цель совместимости — Frida 17.16.4 на Android. Другие версии Frida намеренно считаются непроверенными, пока их контракты исходного кода, полная сборка и приёмка на рутованном устройстве не будут повторены.

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

Что проверено

Репозиторий разделяет три вида доказательств:

1. Модульные и фикстурные тесты проверяют обработку входных данных, точные контракты патчей исходного кода Frida 17.16.4, пересборку DEX, продвижение артефактов, метаданные, рабочие процессы и поведение при сбоях.
2. build.py --verify требует наличия и Server, и Gadget, удаляет символы из подготовленного Gadget, а затем отклоняет известные запрещённые маркеры времени выполнения перед публикацией любого из артефактов.
3. scripts/android_smoke.py проверяет собранный артефакт на одном рутованном устройстве: аутентифицированный транспорт abstract-UNIX, RPC стандартного клиента, spawn, attach, проверки Java-моста, проверки /proc, внешнее сканирование памяти с root-правами и отдельно загружаемый Gadget.

Успешный тест исходного кода или байтовое сканирование не эквивалентны скрытности во время выполнения. Утверждения о поведении на Android должны сопровождаться сгенерированным отчётом дымового теста с удалёнными чувствительными данными.

Сборка с помощью GitHub Actions

Запустите Build Custom Frida на вкладке Actions. Переиспользуемый рабочий процесс сборки:

• проверяет каждый управляемый пользователем входной параметр сборки;
• загружает Android NDK r29 от Google и проверяет его опубликованную контрольную сумму;
• клонирует свежее дерево исходного кода из апстрима, а не кэширует пропатченные исходники;
• удаляет символы Gadget и загружает артефакты только после прохождения жёстких проверок артефактов и маркеров;
• включает build-info.json и SHA256SUMS в один артефакт сборки.

Еженедельный рабочий процесс определяет последний релиз через аутентифицированный GitHub API, вызывает тот же рабочий процесс сборки с правами только на чтение, проверяет загруженный артефакт, заверяет его и предоставляет разрешение на запись релиза только финальной задаче.

Локальная сборка

Требования:

• Ubuntu 22.04 или новее (WSL поддерживается);
• Python 3.10 или новее;
• Git, curl, unzip, инструментарий C/C++, JDK 17 и Node.js 18 или новее (CI использует Node.js 24.13.1);
• платформа Android SDK и build-tools, содержащие android.jar и D8;
• около 20 ГБ свободного дискового пространства.

Если параметр --ndk-path не указан, сборщик загружает Android NDK r29 в каталог build/. Проверенная сборка arm64 с фиксированными входными данными выглядит так:

export ANDROID_SDK_ROOT=/path/to/Android/Sdk
python3 build.py \
  --version 17.16.4 \
  --name oemcodec \
  --arch android-arm64 \
  --port 27142 \
  --extended \
  --strict-wx \
  --verify

Полезные параметры:

--version, -v    Exact Frida semantic version (required)
--name, -n       Lowercase replacement name, 3-20 characters
--arch, -a       One or more supported Android architectures
--port, -p       Listening port; omitted keeps 27042
--extended, -e   Apply the optional extended identifier transformations
--strict-wx      Harden Frida-owned persistent anonymous RWX mappings on Android
--temp-fixes     Apply opt-in, device-specific stability changes
--verify         Reject known forbidden markers in final artifacts
--skip-build     Patch source without compiling
--skip-clone     Use an existing source tree in the work directory
--ndk-path       Use an existing Android NDK r29 directory

Результаты и происхождение

Для приведённого выше примера каталог output/ содержит:

oemcodec-server-17.16.4-android-arm64
oemcodec-server-17.16.4-android-arm64.gz
oemcodec-gadget-17.16.4-android-arm64.so
oemcodec-gadget-17.16.4-android-arm64.so.gz
build-info.json
SHA256SUMS

build-info.json фиксирует точные коммиты сборщика, Frida и frida-core, версию NDK, время сборки в UTC, архитектуры, имя, порт, режим строгого W^X для пулов кода и URL рабочего процесса при сборке в Actions. Перед использованием проверьте загруженные бинарные файлы:

cd output
sha256sum --check SHA256SUMS
python3 -m json.tool build-info.json >/dev/null

Публичные еженедельные релизы также получают аттестацию происхождения сборки от GitHub. SHA256SUMS идентифицирует один набор результатов; не ожидается, что бинарные хеши совпадут на разных хост-машинах сборки.

Совместимость со стандартным клиентом

Сборщик сохраняет интерфейсы протокола D-Bus в пространстве имён re.frida.*, путь /re/frida/GadgetSession, публичные строки JavaScript API с заглавной Frida и генерируемые символы C ABI, необходимые стандартным клиентам. Переименование этих значений нарушило бы обычный контракт клиент/сервер Frida.

Идентификатор службы D-Bus, вспомогательный JNI-пакет, префикс сокета zymbiote, выбранные идентификаторы процессов/библиотек/путей, выбранные имена потоков и опциональный пользовательский порт — это отдельные детали реализации, которые сборщик может преобразовывать. Верификатор результатов отклоняет следующий явный набор маркеров:

frida\0
frida-zymbiote
re/frida/HelperBackend
frida-server
frida-helper
frida-agent
frida-gadget
frida-eternal-agent
frida-generate-certificate
frida-main-loop
frida:rpc
FridaScriptEngine
GLib-GIO
GDBusProxy
GumScript
Frida/
gum-js-loop
gmain\0
gdbus\0
pool-frida
pool-spawner
jit-cache\0

Точная строка публичного API Frida\0 и разрешённые идентификаторы протокола re.frida.* намеренно сохраняются. Префикс HTTP/Inspector Frida/ является ошибкой верификатора и переименовывается отдельно.

Приёмка на рутованном Android

Установите точную привязку Python, указанную в build-info.json, установите зафиксированную зависимость Java-моста и подключите ровно одно рутованное Android-устройство:

python3 -m pip install "frida==17.16.4" frida-tools
npm ci --ignore-scripts

python3 scripts/android_smoke.py \
  --server output/oemcodec-server-17.16.4-android-arm64 \
  --gadget output/oemcodec-gadget-17.16.4-android-arm64.so \
  --name oemcodec \
  --port 27142 \
  --package com.example.app \
  --ndk build/android-ndk-r29 \
  --report android-smoke-report.json

Пакет должен представлять собой установленное Java-приложение, которое вы уполномочены тестировать. Стенд компилирует test_comprehensive.js с явным frida-java-bridge, требуемым Frida 17. Server и Gadget прослушивают каждый свой случайный аутентифицированный abstract-UNIX сокет; их TCP-порты на хосте существуют только как ADB-форварды, и на устройстве не открывается ни одного TCP-слушателя. Стенд также компилирует пробник с root-правами и совпадающим ABI, который сканирует отображаемые образы агента и Gadget через /proc/<pid>/mem вне собственного представления процессов Frida. При выходе он очищает свои процессы, форварды и удалённый тестовый каталог. Проверка /proc также отклоняет устаревшие имена файловых дескрипторов linjector и ненулевой TracerPid.

Конфигурация Frida Gadget должна располагаться рядом с библиотекой и называться lib<name>-gadget.config.so; стенд генерирует и разворачивает этот файл.

Проверки при разработке

python -m pip install --requirement requirements-dev.txt
npm ci --ignore-scripts
python -m pytest
ruff check .
ruff format --check .
mypy build.py patches.py namegen.py scripts
node --check test_comprehensive.js
bash -n build-wsl.sh
go run github.com/rhysd/actionlint/cmd/[email protected]

Полные требования к доказательствам см. в CONTRIBUTING.md.

Структура репозитория

build.py                 Clone, patch, compile, verify, and collect artifacts
patches.py               Source and same-length binary transformations
namegen.py               Seeded build-name and port generation
scripts/android_smoke.py Rooted Android Server/Gadget acceptance harness
test_comprehensive.js    Structured Frida 17 Java bridge assertions
tests/                   Unit, contract, fixture, and workflow tests
.github/workflows/       CI, CodeQL, reusable build, and release isolation

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

• Только Frida 17.16.4 является текущей целью проверки; поддержка не подразумевается для всех релизов 17.x или 16.x.
• --temp-fixes изменяет поведение во время выполнения и остаётся опциональным.
• Отсутствие маркеров не доказывает устойчивость к поведенческому, целостностному, временному или специфичному для приложения обнаружению.
• Совместимость со стандартным клиентом сохраняет публичное поведение ABI/протокола. Активное зондирование протокола и проверки целостности кода всё ещё могут выявить инструментирование.
• Этот сборщик не скрывает root, автоматический запуск приложений, изменения кода, вносимые Interceptor, строки пользовательских скриптов или ошибки, сообщаемые удалённой аттестацией.
• --strict-wx отделяет исполняемый код Android-инъектора от доступных для записи страниц данных и стека, отключает постоянные RWX-пулы кода Gum, размещает код замыканий GumJS NativeCallback на выделенных RX-страницах, оставляя хранилище libffi в режиме RW, и финализирует вновь сгенерированный код как RX. Если подходящая удалённая libc недоступна, Android-инъектор завершается с ошибкой (fail closed), а не использует RWX-запасной вариант из апстрима. Он сохраняет страницы, которые уже были RWX, и не отклоняет явный запрос пользовательского скрипта на RWX-память. Снимок /proc/maps во время выполнения не доказывает, что при патчинге исполняемого кода не происходит кратковременного изменения разрешений RWX.
• Внешняя проверка памяти сканирует отображаемые образы агента/Gadget на предмет своего явного набора маркеров; это не универсальное сканирование каждой анонимной страницы кучи.
• Сырым агентам Frida 17 требуются явные импорты мостов или их бандлинг. Стенд использует frida.Compiler; REPL и трассировщик Frida предоставляют собственные встроенные мосты.

Авторы и лицензирование

• Frida — Ole André Ravnas и участники проекта
• ajeossida — hackcatml

Код сборщика распространяется под лицензией MIT. Сгенерированные бинарные файлы сохраняют лицензии вышестоящих проектов; см. THIRD_PARTY_NOTICES.md.