phantom-frida

phantom-frida compila o Frida Server e o Gadget para Android a partir do código-fonte, alterando um conjunto direcionado de identificadores observáveis em tempo de execução. Trata-se de um harness de compilação e verificação, não de uma promessa de que todos os métodos de detecção específicos de cada aplicação serão derrotados.

O alvo de compatibilidade atual é o Frida 17.16.4 no Android. Outras versões do Frida são intencionalmente tratadas como não verificadas até que seus contratos de código-fonte, compilação completa e aceitação em dispositivo com root tenham sido repetidos.

Use este projeto apenas em aplicações e dispositivos que você possui ou está autorizado a testar.

O que é verificado

O repositório separa três tipos de evidência:

1. Testes unitários e de fixtures validam o tratamento de entradas, os contratos exatos de patch do código-fonte do Frida 17.16.4, a reconstrução de DEX, a promoção de artefatos, metadados, workflows e comportamento em caso de falha.
2. build.py --verify exige tanto o Server quanto o Gadget, remove os símbolos do Gadget preparado e, em seguida, rejeita marcadores de runtime proibidos conhecidos antes de publicar qualquer artefato.
3. scripts/android_smoke.py exercita um artefato compilado em um dispositivo com root: transporte abstrato-UNIX autenticado, RPC de cliente padrão, spawn, attach, asserções da ponte Java, verificações em /proc, uma varredura externa de memória com root e um Gadget carregado separadamente.

Um teste de código-fonte aprovado ou uma varredura de bytes não é equivalente a furtividade em tempo de execução. Alegações sobre o comportamento no Android devem incluir o relatório de smoke-test gerado e com dados sensíveis removidos.

Compilar com GitHub Actions

Execute Build Custom Frida na aba Actions. O workflow de compilação reutilizável:

• valida cada entrada de compilação controlada pelo usuário;
• baixa o Android NDK r29 do Google e verifica seu checksum publicado;
• clona uma árvore de código-fonte upstream nova em vez de fazer cache do código-fonte com patches;
• remove os símbolos do Gadget e faz upload somente após os gates rígidos de artefato e marcadores serem aprovados;
• inclui build-info.json e SHA256SUMS em um único artefato de compilação.

O workflow semanal resolve a versão mais recente por meio da API autenticada do GitHub, chama o mesmo workflow de compilação somente leitura, verifica o artefato baixado, o atesta e concede permissão de escrita para release apenas ao job final.

Compilação local

Requisitos:

• Ubuntu 22.04 ou mais recente (WSL é suportado);
• Python 3.10 ou mais recente;
• Git, curl, unzip, uma toolchain C/C++, JDK 17 e Node.js 18 ou mais recente (a CI usa Node.js 24.13.1);
• plataforma e build-tools do Android SDK contendo android.jar e D8;
• cerca de 20 GB de espaço livre em disco.

Se --ndk-path for omitido, o builder baixa o Android NDK r29 em build/. Uma compilação arm64 verificada com entradas fixadas é:

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

Opções úteis:

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

Saídas e proveniência

Para o exemplo acima, output/ contém:

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 os commits exatos do builder, do Frida e do frida-core, a versão do NDK, o horário de build em UTC, as arquiteturas, o nome, a porta, o modo estrito de pool de código W^X e a URL do workflow quando compilado no Actions. Verifique os arquivos binários baixados antes do uso:

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

Lançamentos públicos semanais também recebem uma atestação de proveniência de build do GitHub. SHA256SUMS identifica um conjunto de saída; não se espera que os hashes dos binários coincidam entre diferentes hosts de build.

Compatibilidade com o cliente padrão

O builder preserva as interfaces do protocolo D-Bus sob re.frida.*, o caminho /re/frida/GadgetSession, as strings públicas da API JavaScript Frida com capitalização e os símbolos da ABI C gerados exigidos pelos clientes padrão. Renomear esses valores quebraria o contrato normal cliente/servidor do Frida.

O identificador do serviço D-Bus, o pacote JNI do helper, o prefixo do socket do zymbiote, identificadores selecionados de processo/biblioteca/caminho, nomes selecionados de threads e uma porta personalizada opcional são detalhes de implementação separados que o builder pode transformar. O verificador de saída rejeita 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

A string exata da API pública Frida\0 e os identificadores de protocolo re.frida.* na lista de permissões permanecem intencionalmente preservados. O prefixo HTTP/Inspector Frida/ é uma falha do verificador e é renomeado de forma independente.

Aceitação em Android com root

Instale a vinculação Python exata registrada em build-info.json, instale a dependência fixada da ponte Java e conecte exatamente um dispositivo Android com 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

O pacote deve ser uma aplicação Java instalada que você está autorizado a testar. O harness compila test_comprehensive.js com o frida-java-bridge explícito exigido pelo Frida 17. O Server e o Gadget escutam cada um em um socket UNIX abstrato autenticado aleatório; suas portas TCP no host existem apenas como encaminhamentos ADB e nenhum listener TCP no dispositivo é exposto. O harness também compila uma sonda de root compatível com a ABI que varre as imagens mapeadas do agente e do Gadget através de /proc/<pid>/mem, fora da própria visão de processo do Frida. Ele limpa seus processos, encaminhamentos e diretório de teste remoto ao sair. O gate /proc também rejeita nomes de descritores de arquivo legados do linjector e um TracerPid diferente de zero.

A configuração do Frida Gadget deve ser nomeada ao lado da biblioteca como lib<name>-gadget.config.so; o harness gera e implanta este arquivo.

Verificações de desenvolvimento

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]