phantom-frida

phantom-frida compile Android Frida Server et Gadget à partir des sources tout en modifiant un ensemble ciblé d'identifiants d'exécution observables. Il s'agit d'un outil de construction et de vérification, et non d'une garantie que toutes les méthodes de détection spécifiques à une application soient neutralisées.

La cible de compatibilité actuelle est Frida 17.16.4 sur Android. Les autres versions de Frida sont volontairement considérées comme non vérifiées tant que leurs contrats de source, leur compilation complète et leur acceptation sur appareil rooté n'ont pas été répétés.

N'utilisez ce projet que sur des applications et des appareils que vous possédez ou que vous êtes autorisé à tester.

Ce qui est vérifié

Le dépôt distingue trois types de preuves :

1. Les tests unitaires et les tests de fixtures valident la gestion des entrées, les contrats exacts de patchs de source Frida 17.16.4, la reconstruction DEX, la promotion des artefacts, les métadonnées, les workflows et les comportements en cas d'échec.
2. build.py --verify exige à la fois le Server et le Gadget, dépouille le Gadget préparé, puis rejette les marqueurs d'exécution interdits connus avant de publier l'un ou l'autre artefact.
3. scripts/android_smoke.py exerce un artefact compilé sur un appareil rooté : transport UNIX abstrait authentifié, RPC client standard, spawn, attach, assertions du pont Java, vérifications /proc, analyse mémoire root externe et Gadget chargé séparément.

Un test de source ou une analyse d'octets qui réussit n'équivaut pas à une furtivité à l'exécution. Les affirmations concernant le comportement sur Android doivent inclure le rapport de test de fumée généré et expurgé.

Compilation avec GitHub Actions

Exécutez Build Custom Frida depuis l'onglet Actions. Le workflow de compilation réutilisable :

• valide chaque entrée de compilation contrôlée par l'utilisateur ;
• télécharge Android NDK r29 depuis Google et vérifie sa somme de contrôle publiée ;
• clone un arbre source amont frais au lieu de mettre en cache la source patchée ;
• dépouille les symboles du Gadget et ne téléverse qu'après le passage des contrôles stricts d'artefacts et de marqueurs ;
• inclut build-info.json et SHA256SUMS dans un seul artefact de compilation.

Le workflow hebdomadaire résout la dernière version via l'API GitHub authentifiée, appelle le même workflow de compilation en lecture seule, vérifie l'artefact téléchargé, l'atteste et n'accorde la permission d'écriture pour la release qu'au job final.

Compilation locale

Prérequis :

• Ubuntu 22.04 ou plus récent (WSL est pris en charge) ;
• Python 3.10 ou plus récent ;
• Git, curl, unzip, une chaîne d'outils C/C++, JDK 17 et Node.js 18 ou plus récent (la CI utilise Node.js 24.13.1) ;
• plateforme et build-tools du SDK Android contenant android.jar et D8 ;
• environ 20 Go d'espace disque libre.

Si --ndk-path est omis, le builder télécharge Android NDK r29 dans build/. Une compilation arm64 vérifiée avec entrées épinglées est :

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

Options utiles :

--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

Sorties et provenance

Pour l'exemple ci-dessus, output/ contient :

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 enregistre les commits exacts du builder, de Frida et de frida-core, la version du NDK, l'heure de compilation UTC, les architectures, le nom, le port, le mode strict W^X des pools de code et l'URL du workflow lorsqu'il est compilé dans Actions. Vérifiez les fichiers binaires téléchargés avant utilisation :

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

Les releases publiques hebdomadaires reçoivent également une attestation de provenance de compilation GitHub. SHA256SUMS identifie un ensemble de sorties ; les hachages binaires ne sont pas censés correspondre entre différents hôtes de compilation.

Compatibilité avec le client standard

Le builder préserve les interfaces de protocole D-Bus sous re.frida.*, le chemin /re/frida/GadgetSession, les chaînes publiques de l'API JavaScript Frida en capitale et les symboles C ABI générés requis par les clients standard. Renommer ces valeurs romprait le contrat normal client/serveur de Frida.

L'identifiant de service D-Bus, le package JNI du helper, le préfixe de socket zymbiote, les identifiants sélectionnés de processus/bibliothèque/chemin, les noms de threads sélectionnés et un port personnalisé optionnel sont des détails d'implémentation distincts que le builder peut transformer. Le vérificateur de sortie rejette cet ensemble explicite de marqueurs :

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 chaîne exacte de l'API publique Frida\0 et les identifiants de protocole re.frida.* en liste blanche restent intentionnellement préservés. Le préfixe HTTP/Inspector Frida/ est une erreur de vérification et est renommé indépendamment.

Acceptation sur Android rooté

Installez la liaison Python exacte enregistrée dans build-info.json, installez la dépendance épinglée du pont Java et connectez exactement un appareil Android rooté :

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

Le package doit être une application Java installée que vous êtes autorisé à tester. Le harnais compile test_comprehensive.js avec le frida-java-bridge explicite requis par Frida 17. Le Server et le Gadget écoutent chacun sur un socket UNIX abstrait authentifié aléatoire ; leurs ports TCP hôtes n'existent qu'en tant que redirections ADB et aucun écouteur TCP de l'appareil n'est exposé. Le harnais compile également une sonde root compatible ABI qui analyse les images mappées de l'agent et du Gadget via /proc/<pid>/mem, en dehors de la vue processus de Frida elle-même. Il nettoie ses processus, ses redirections et son répertoire de test distant à la sortie. Le contrôle /proc rejette également les anciens noms de descripteurs de fichiers linjector et un TracerPid non nul.

La configuration du Gadget Frida doit être nommée à côté de la bibliothèque en tant que lib<name>-gadget.config.so ; le harnais génère et déploie ce fichier.

Vérifications de développement

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]

Voir CONTRIBUTING.md pour l'ensemble des exigences de preuves.

Structure du dépôt

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

Limites connues

• Seule Frida 17.16.4 est la cible de vérification actuelle ; la prise en charge n'est pas déduite pour toutes les versions 17.x ou 16.x.
• --temp-fixes modifie le comportement à l'exécution et reste optionnel (opt-in).
• L'absence de marqueurs ne prouve pas la résistance aux détections comportementales, d'intégrité, temporelles ou spécifiques à une application.
• La compatibilité avec le client standard préserve le comportement public ABI/protocole. Les sondages actifs de protocole et les vérifications d'intégrité de code peuvent toujours identifier l'instrumentation.
• Ce builder ne cache pas le root, le lancement automatisé d'applications, les modifications de code Interceptor, les chaînes de scripts utilisateur ou les échecs signalés par l'attestation à distance.
• --strict-wx sépare le code exécutable de l'injecteur Android des données modifiables et des pages de pile, désactive les pools de code RWX persistants de Gum, place le code de fermeture NativeCallback de GumJS sur des pages RX dédiées tout en conservant le stockage libffi en RW, et finalise le code nouvellement généré en RX. Si une libc distante correspondante n'est pas disponible, l'injecteur Android échoue en mode verrouillé (fail-closed) au lieu d'utiliser son repli RWX amont. Il préserve les pages déjà en RWX et ne rejette pas une demande explicite de mémoire RWX de la part d'un script utilisateur. Un échantillon /proc/maps à l'exécution ne prouve pas qu'aucun changement transitoire de permission RWX ne se produit pendant que le code exécutable est patché.
• Le contrôle mémoire externe analyse les images mappées de l'agent/Gadget pour détecter son ensemble explicite de marqueurs ; ce n'est pas une analyse générique de chaque page de tas anonyme.
• Les agents bruts de Frida 17 nécessitent des imports explicites de ponts ou leur intégration (bundling). Le harnais utilise frida.Compiler ; le REPL de Frida et le tracer fournissent leurs propres ponts intégrés.

Crédits et licence

• Frida par Ole André Ravnas et les contributeurs
• ajeossida par hackcatml

Le code du builder est sous licence MIT. Les binaires générés conservent la licence amont ; voir THIRD_PARTY_NOTICES.md.