phantom-frida

phantom-frida costruisce Android Frida Server e Gadget dal codice sorgente modificando un insieme mirato di identificatori runtime osservabili. È un builder e un harness di verifica, non una garanzia che ogni metodo di rilevamento specifico dell'applicazione venga sconfitto.

L'obiettivo di compatibilità corrente è Frida 17.16.4 su Android. Altre versioni di Frida sono intenzionalmente considerate non verificate fino a quando i loro contratti sorgente, la build completa e l'accettazione su dispositivo rooted non saranno stati ripetuti.

Usa questo progetto solo su applicazioni e dispositivi di tua proprietà o che sei autorizzato a testare.

Cosa è verificato

Il repository separa tre tipi di prove:

1. I test unitari e di fixture convalidano la gestione degli input, i contratti esatti delle patch del sorgente di Frida 17.16.4, la ricostruzione DEX, la promozione degli artefatti, i metadati, i flussi di lavoro e il comportamento in caso di errore.
2. build.py --verify richiede sia Server che Gadget, spoglia il Gadget preparato, quindi rifiuta i marcatori runtime vietati noti prima di pubblicare l'artefatto.
3. scripts/android_smoke.py testa un artefatto costruito su un dispositivo rooted: trasporto UNIX astratto autenticato, RPC del client stock, spawn, attach, asserzioni del bridge Java, controlli /proc, una scansione della memoria root esterna e un Gadget caricato separatamente.

Un test sorgente o una scansione byte superati non equivalgono a furtività runtime. Le affermazioni sul comportamento di Android dovrebbero includere il rapporto del smoke test generato e oscurato.

Build con GitHub Actions

Esegui Build Custom Frida dalla scheda Actions. Il flusso di lavoro build riutilizzabile:

• convalida ogni input di build controllato dall'utente;
• scarica Android NDK r29 da Google e verifica il checksum pubblicato;
• clona un albero sorgente upstream fresco invece di memorizzare nella cache il sorgente patchato;
• spoglia i simboli del Gadget e carica solo dopo che l'artefatto duro e i cancelli dei marcatori sono stati superati;
• include build-info.json e SHA256SUMS in un unico artefatto di build.

Il flusso di lavoro settimanale risolve l'ultima release attraverso l'API GitHub autenticata, chiama lo stesso flusso di lavoro di build di sola lettura, verifica l'artefatto scaricato, lo attesta e concede il permesso di scrittura della release solo al lavoro finale.

Build locale

Requisiti:

• Ubuntu 22.04 o successivo (WSL è supportato);
• Python 3.10 o successivo;
• Git, curl, unzip, una toolchain C/C++, JDK 17 e Node.js 18 o successivo (CI usa Node.js 24.13.1);
• Piattaforma Android SDK e build-tools contenenti android.jar e D8;
• circa 20 GB di spazio libero su disco.

Se --ndk-path viene omesso, il builder scarica Android NDK r29 sotto build/. Una build arm64 verificata con input bloccati è:

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

Opzioni utili:

--version, -v    Versione semantica esatta di Frida (obbligatoria)
--name, -n       Nome sostitutivo in minuscolo, 3-20 caratteri
--arch, -a       Una o più architetture Android supportate
--port, -p       Porta di ascolto; omessa mantiene 27042
--extended, -e   Applica le trasformazioni estese opzionali degli identificatori
--strict-wx      Indurisce le mappature RWX persistenti anonime di proprietà di Frida su Android
--temp-fixes     Applica modifiche di stabilità opt-in specifiche del dispositivo
--verify         Rifiuta i marcatori vietati noti negli artefatti finali
--skip-build     Applica le patch al sorgente senza compilare
--skip-clone     Usa un albero sorgente esistente nella directory di lavoro
--ndk-path       Usa una directory esistente di Android NDK r29

Output e provenienza

Per l'esempio sopra, 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 i commit esatti del builder, di Frida e di frida-core, la versione dell'NDK, l'ora UTC di build, le architetture, il nome, la porta, la modalità strict W^X del pool di codice e l'URL del flusso di lavoro quando costruito in Actions. Verifica i file binari scaricati prima dell'uso:

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

Le release pubbliche settimanali ricevono anche un'attestazione di provenienza della build GitHub. SHA256SUMS identifica un insieme di output; gli hash binari non dovrebbero corrispondere tra diversi host di build.

Compatibilità con il client stock

Il builder preserva le interfacce del protocollo D-Bus sotto re.frida.*, il percorso /re/frida/GadgetSession, le stringhe pubbliche dell'API JavaScript Frida in maiuscolo e i simboli ABI C generati richiesti dai client stock. Rinominare quei valori romperebbe il normale contratto client/server di Frida.

L'identificatore del servizio D-Bus, il pacchetto JNI helper, il prefisso del socket zymbiote, gli identificatori selezionati di processo/libreria/percorso, i nomi di thread selezionati e una porta personalizzata opzionale sono dettagli di implementazione separati che il builder può trasformare. Il verificatore di output rifiuta questo insieme esplicito di marcatori:

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 stringa esatta dell'API pubblica Frida\0 e gli identificatori del protocollo re.frida.* nella whitelist rimangono intenzionalmente preservati. Il prefisso HTTP/Inspector Frida/ è un fallimento del verificatore e viene rinominato indipendentemente.

Accettazione su Android rooted

Installa il binding Python esatto registrato in build-info.json, installa la dipendenza del bridge Java fissata e collega esattamente un dispositivo Android rooted:

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

Il pacchetto deve essere un'applicazione Java installata che sei autorizzato a testare. L'harness compila test_comprehensive.js con il frida-java-bridge esplicito richiesto da Frida 17. Server e Gadget ascoltano ciascuno su un socket UNIX astratto autenticato casuale; le loro porte TCP host esistono solo come inoltri ADB e nessun listener TCP del dispositivo è esposto. L'harness compila anche una sonda root abbinata all'ABI che scansiona le immagini dell'agente e del Gadget mappati attraverso /proc/<pid>/mem, al di fuori della vista del processo di Frida. Pulisce i suoi processi, inoltri e directory di test remota all'uscita. Il gate /proc rifiuta anche i nomi di descrittori di file linjector legacy e un TracerPid diverso da zero.

La configurazione di Frida Gadget deve essere nominata accanto alla libreria come lib<name>-gadget.config.so; l'harness genera e distribuisce questo file.

Controlli di sviluppo

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]

Vedi CONTRIBUTING.md per i requisiti completi delle prove.

Struttura del repository

build.py                 Clona, applica patch, compila, verifica e raccoglie artefatti
patches.py               Trasformazioni del codice sorgente e binarie a lunghezza fissa
namegen.py               Generazione di nome di build e porta basata su seed
scripts/android_smoke.py Harness di accettazione per Server/Gadget su Android rooted
test_comprehensive.js    Asserzioni strutturate del bridge Java Frida 17
tests/                   Test unitari, di contratto, fixture e di flusso di lavoro
.github/workflows/       CI, CodeQL, build riutilizzabile e isolamento delle release

Limiti noti

• Solo Frida 17.16.4 è l'obiettivo di verifica corrente; il supporto non è dedotto per tutte le release 17.x o 16.x.
• --temp-fixes modifica il comportamento runtime e rimane opt-in.
• L'assenza di marcatori non prova la resistenza a rilevamenti comportamentali, di integrità, temporali o specifici dell'applicazione.
• La compatibilità con il client stock preserva il comportamento pubblico di ABI/protocollo. Il probing attivo del protocollo e i controlli di integrità del codice possono ancora identificare la strumentazione.
• Questo builder non nasconde il root, l'avvio automatico dell'app, le modifiche al codice di Interceptor, le stringhe dello script utente o i guasti segnalati dall'attestazione remota.
• --strict-wx separa il codice eseguibile dell'iniettore Android dai dati e dalle pagine stack, disabilita i pool di codice RWX persistenti di Gum, posiziona il codice di chiusura di GumJS NativeCallback su pagine RX dedicate mantenendo l'archiviazione libffi RW, e finalizza il codice appena generato come RX. Se una libc remota corrispondente non è disponibile, l'iniettore Android fallisce in modo bloccato invece di usare il suo fallback RWX upstream. Preserva le pagine che erano già RWX e non rifiuta una richiesta esplicita dello script utente per memoria RWX. Un campione runtime di /proc/maps non prova che non si verifichi alcun cambiamento transitorio del permesso RWX mentre il codice eseguibile viene patchato.
• Il gate di memoria esterna scansiona le immagini mappate dell'agente/Gadget per il suo insieme esplicito di marcatori; non è una scansione generica di ogni pagina heap anonima.
• Gli agent raw di Frida 17 necessitano di importazioni esplicite del bridge o del raggruppamento. L'harness usa frida.Compiler; il REPL di Frida e il tracer forniscono i propri bridge raggruppati.

Crediti e licenze

• Frida di Ole André Ravnas e contributori
• ajeossida di hackcatml

Il codice del builder è con licenza MIT. I binari generati mantengono la licenza upstream; vedi THIRD_PARTY_NOTICES.md.