phantom-frida

phantom-frida compila Android Frida Server y Gadget desde el código fuente mientras cambia un conjunto específico de identificadores de tiempo de ejecución observables. Es un constructor y un arnés de verificación, no una promesa de que se derrota cualquier método de detección específico de una aplicación.

El objetivo de compatibilidad actual es Frida 17.16.4 en Android. Otras versiones de Frida se tratan intencionalmente como no verificadas hasta que sus contratos de fuente, compilación completa y aceptación en dispositivo rooteado se hayan repetido.

Use este proyecto solo en aplicaciones y dispositivos que sean suyos o que esté autorizado a probar.

Qué está verificado

El repositorio separa tres tipos de evidencia:

1. Las pruebas unitarias y de fixtures validan el manejo de entrada, los contratos exactos de parches del código fuente de Frida 17.16.4, el reensamblado de DEX, la promoción de artefactos, los metadatos, los flujos de trabajo y el comportamiento ante fallos.
2. build.py --verify requiere tanto Server como Gadget, elimina el Gadget preparado y luego rechaza los marcadores de tiempo de ejecución prohibidos conocidos antes de publicar cualquiera de los artefactos.
3. scripts/android_smoke.py ejercita un artefacto compilado en un dispositivo rooteado: transporte UNIX abstracto autenticado, RPC del cliente estándar, spawn, attach, aserciones del puente Java, comprobaciones de /proc, un escaneo externo de memoria de root y un Gadget cargado por separado.

Una prueba de fuente o escaneo de bytes que pase no es equivalente a sigilo en tiempo de ejecución. Las afirmaciones sobre el comportamiento en Android deben incluir el informe de prueba de humo generado y redactado.

Compilar con GitHub Actions

Ejecute Build Custom Frida desde la pestaña Actions. El flujo de trabajo de compilación reutilizable:

• valida cada entrada de compilación controlada por el usuario;
• descarga Android NDK r29 desde Google y comprueba su checksum publicado;
• clona un árbol de código fuente upstream nuevo en lugar de almacenar en caché el código fuente parcheado;
• elimina los símbolos de Gadget y sube solo después de que pasen las compuertas de artefactos duros y de marcadores;
• incluye build-info.json y SHA256SUMS en un solo artefacto de compilación.

El flujo de trabajo semanal resuelve la última versión a través de la API de GitHub autenticada, llama al mismo flujo de trabajo de compilación de solo lectura, verifica el artefacto descargado, lo atestigua y otorga permiso de escritura para la versión solo al trabajo final.

Compilación local

Requisitos:

• Ubuntu 22.04 o más reciente (WSL es compatible);
• Python 3.10 o más reciente;
• Git, curl, unzip, un toolchain de C/C++, JDK 17 y Node.js 18 o más reciente (CI usa Node.js 24.13.1);
• Plataforma Android SDK y build-tools que contengan android.jar y D8;
• aproximadamente 20 GB de espacio libre en disco.

Si se omite --ndk-path, el constructor descarga Android NDK r29 en build/. Una compilación arm64 verificada con entradas fijas es:

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

Opciones útiles:

--version, -v    Versión semántica exacta de Frida (obligatorio)
--name, -n       Nombre de reemplazo en minúsculas, 3-20 caracteres
--arch, -a       Una o más arquitecturas Android compatibles
--port, -p       Puerto de escucha; si se omite, mantiene 27042
--extended, -e   Aplica las transformaciones opcionales extendidas de identificadores
--strict-wx      Endurece los mapeos RWX anónimos persistentes propiedad de Frida en Android
--temp-fixes     Aplica cambios de estabilidad opcionales y específicos del dispositivo
--verify         Rechaza marcadores prohibidos conocidos en los artefactos finales
--skip-build     Parchea el código fuente sin compilar
--skip-clone     Usa un árbol de código fuente existente en el directorio de trabajo
--ndk-path       Usa un directorio Android NDK r29 existente

Salidas y procedencia

Para el ejemplo anterior, output/ contiene:

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 registra los commits exactos del constructor, Frida y frida-core, la versión del NDK, la hora UTC de compilación, las arquitecturas, el nombre, el puerto, el modo estricto de pool de código W^X y la URL del flujo de trabajo cuando se compila en Actions. Verifique los archivos binarios descargados antes de usarlos:

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

Las versiones públicas semanales también reciben una atestación de procedencia de compilación de GitHub. SHA256SUMS identifica un conjunto de salidas; no se espera que los hashes binarios coincidan entre diferentes hosts de compilación.

Compatibilidad con el cliente estándar

El constructor preserva las interfaces de protocolo D-Bus bajo re.frida.*, la ruta /re/frida/GadgetSession, las cadenas públicas de la API JavaScript Frida en mayúsculas y los símbolos ABI de C generados requeridos por los clientes estándar. Renombrar esos valores rompería el contrato normal cliente/servidor de Frida.

El identificador de servicio D-Bus, el paquete JNI auxiliar, el prefijo de socket de zymbiote, los identificadores seleccionados de proceso/biblioteca/ruta, los nombres de hilos seleccionados y un puerto personalizado opcional son detalles de implementación separados que el constructor puede transformar. El verificador de salida rechaza este conjunto explícito de marcadores:

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

La cadena exacta de API pública Frida\0 y los identificadores de protocolo permitidos re.frida.* se preservan intencionalmente. El prefijo HTTP/Inspector Frida/ es un fallo del verificador y se renombra de forma independiente.

Aceptación en Android rooteado

Instale el binding exacto de Python registrado en build-info.json, instale la dependencia fijada del puente Java y conecte exactamente un dispositivo Android rooteado:

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

El paquete debe ser una aplicación Java instalada que esté autorizado a probar. El arnés compila test_comprehensive.js con el frida-java-bridge explícito requerido por Frida 17. Server y Gadget escuchan cada uno en un socket UNIX abstracto autenticado aleatorio; sus puertos TCP del host existen solo como reenvíos ADB y no se expone ningún listener TCP del dispositivo. El arnés también compila un probe de root con ABI coincidente que escanea las imágenes del agente y Gadget mapeados a través de /proc/<pid>/mem, fuera de la propia vista de procesos de Frida. Limpia sus procesos, reenvíos y directorio de prueba remoto al salir. La compuerta /proc también rechaza los nombres de descriptores de archivo heredados de linjector y un TracerPid distinto de cero.

La configuración de Frida Gadget debe nombrarse junto a la biblioteca como lib<name>-gadget.config.so; el arnés genera e implementa este archivo.

Comprobaciones de desarrollo

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]

Consulte CONTRIBUTING.md para conocer los requisitos completos de evidencia.

Estructura del repositorio

build.py                 Clonar, parchear, compilar, verificar y recopilar artefactos
patches.py               Transformaciones binarias de fuente y de misma longitud
namegen.py               Generación de nombre de compilación y puerto con semilla
scripts/android_smoke.py Arnés de aceptación de Server/Gadget en Android rooteado
test_comprehensive.js    Aserciones estructuradas del puente Java de Frida 17
tests/                   Pruebas unitarias, de contrato, de fixtures y de flujos de trabajo
.github/workflows/       CI, CodeQL, compilación reutilizable y aislamiento de versiones

Límites conocidos

• Solo Frida 17.16.4 es el objetivo de verificación actual; no se infiere compatibilidad con todas las versiones 17.x o 16.x.
• --temp-fixes cambia el comportamiento en tiempo de ejecución y sigue siendo opcional.
• La ausencia de marcadores no prueba resistencia a la detección conductual, de integridad, de temporización o específica de la aplicación.
• La compatibilidad con el cliente estándar preserva el comportamiento público de ABI/protocolo. El sondeo activo de protocolo y las comprobaciones de integridad de código aún pueden identificar la instrumentación.
• Este constructor no oculta el root, el lanzamiento automatizado de aplicaciones, los cambios de código de Interceptor, las cadenas de scripts de usuario ni los fallos informados por atestación remota.
• --strict-wx separa el código ejecutable del inyector Android de los datos modificables y las páginas de pila, deshabilita los pools de código RWX persistentes de Gum, coloca el código de cierre de NativeCallback de GumJS en páginas RX dedicadas mientras mantiene el almacenamiento RW de libffi, y finaliza el código recién generado como RX. Si no hay una libc remota coincidente, el inyector Android falla de manera cerrada en lugar de usar su respaldo RWX upstream. Preserva las páginas que ya eran RWX y no rechaza una solicitud explícita de script de usuario para memoria RWX. Una muestra de /proc/maps en tiempo de ejecución no prueba que no ocurra un cambio transitorio de permiso RWX mientras se parchea el código ejecutable.
• La compuerta de memoria externa escanea las imágenes del agente/Gadget mapeados en busca de su conjunto explícito de marcadores; no es un escaneo de propósito general de cada página anónima del heap.
• Los agentes sin procesar de Frida 17 necesitan importaciones de puente explícitas o agrupación. El arnés usa frida.Compiler; el REPL y el tracer de Frida proporcionan sus propios puentes agrupados.

Créditos y licencias

• Frida por Ole André Ravnas y colaboradores
• ajeossida por hackcatml

El código del constructor tiene licencia MIT. Los binarios generados conservan la licencia upstream; consulte THIRD_PARTY_NOTICES.md.