yilongmd/zafrida-uiUma janela de ferramenta UI do Frida dentro do PyCharm / IDEs JetBrains.
中文 | [English](https://github.com/yilongmd/zafrida-ui/blob/main/README.en-US.md)
ZAFrida UI - Plugin Frida para PyCharm
===============
Versão atual: 0.3.8
[](LICENSE)
[](https://github.com/yilongmd/zafrida-ui)
[](https://plugins.jetbrains.com/)
[](https://github.com/yilongmd/zafrida-ui)
## Principais atualizações da 0.3.8
- O painel Session separa "Dispositivo" e "Modo de conexão" em duas linhas de seleção independentes: a linha Device lista apenas dispositivos reais, e a linha Mode seleciona USB / Remote / Gadget e o endpoint. O encaminhamento de porta adb em loopback para Remote/Gadget, Force Stop e Open App sempre atuam sobre o celular atualmente selecionado, sem mais usar dispositivos anteriores por engano.
- Ao abrir e atualizar dispositivos pela primeira vez, o adb server é iniciado automaticamente caso não esteja em execução, sem precisar executar `adb devices` manualmente.
- Quando um dispositivo salvo não está online, exibe o placeholder "não conectado" e bloqueia as operações relacionadas; se houver apenas um dispositivo USB conectado, ele é usado automaticamente e uma mensagem é exibida no Console.
- Abaixo da linha Mode é exibida a rota adb/frida realmente executada; no modo Gadget, o nome do pacote Target é somente leitura, mas pode ser selecionado e copiado.
- O `/state` da HTTP API agora inclui o resultado da análise de `connection`; `device-select --host` ainda funciona, mas está obsoleto — para endpoints, use `mode-set --host/--port`.
## Principais atualizações da 0.3.7
- Cada ZAFrida Project pode selecionar ou compartilhar independentemente o ambiente Python/Frida, usando por padrão o interpretador do projeto PyCharm atual, com suporte a ambientes locais como venv, Conda, uv, Poetry, Pipenv e Hatch.
- Redesenho da UI do Session e do Project Settings, exibindo completamente as informações de versão do plugin, Python e Frida, além de otimizar o painel de logs adaptável e arrastável e o estado da sessão.
- Suporte completo a `.js` / `.ts`, Frida 16/17, troca de ambiente entre múltiplos projetos e os três fluxos de conexão USB, Remote e Gadget.
- Reforço da HTTP API local, CLI e Skill em chinês para recuperação de dispositivos, espera de sessão e logs incrementais; remoção da camada de adaptação MCP duplicada e instável.
Apresentação do projeto
-----------------------------------
<h3 align="center">Ferramenta gráfica para Frida, projetada para PyCharm/IntelliJ</h3>
O ZAFrida UI é um plugin de operação gráfica do Frida integrado ao PyCharm e à série de IDEs JetBrains. Ele visa resolver os problemas de operação complicada via linha de comando do Frida e de gerenciamento desorganizado de scripts, oferecendo um conjunto completo de **interface de interação UI** para gerenciar dispositivos, processos, scripts e logs.
O destaque principal é o seu **sistema de gerenciamento de templates "estilo caixa de seleção"**: o usuário pode, marcando/desmarcando, inserir dinamicamente trechos de código no script principal ou comentá-los, realizando assim a montagem de scripts Hook "estilo blocos de montar". Ao mesmo tempo, o plugin inclui **gerenciamento completo por projeto** (`zafrida-project.xml`), com suporte à troca rápida entre múltiplos dispositivos e configurações de ambiente.
O ZAFrida não substitui o Frida, mas atua como uma poderosa interface UI para o `frida-tools`, integrando-se perfeitamente ao seu ambiente Python e Frida existente.
**Wiki simplificada**: [Wiki simplificada do ZAFrida UI (BBS)](https://github.com/yilongmd/zafrida-ui/blob/main/zafrida_ui_wiki_bbs_zh.md) (esta é uma Wiki mais simples)
**Tutorial de uso detalhado**: [Wiki com tutorial de uso detalhado do ZAFrida UI](https://github.com/yilongmd/zafrida-ui/blob/main/ZAFridaUI_Wiki_zh.md)
## Demonstração
Início rápido
-----------------------------------
1. **Instalar o plugin**: procure "ZAFrida" no marketplace de plugins da IDE ou instale a partir do disco.
2. **Configurar o ambiente padrão**: por padrão, usa o Python Interpreter do projeto PyCharm atual; em `Settings` global -> `Tools` -> `ZAFrida`, mantêm-se apenas os valores padrão de nome/caminho das ferramentas.
3. **Criar um projeto**: clique com o botão direito na visualização do projeto -> `New Frida Project`.
* Se o projeto precisar de uma versão diferente do Frida, abra o `Project Settings` do ZAFrida, selecione o interpretador Python ou o diretório do ambiente e clique em `Test`.
4. **Escrever/selecionar o script**: no painel Run, selecione seu `agent.js` ou `agent.ts`.
5. **Depuração de Hook**:
* Conecte o dispositivo (USB ou Remote ou Gadget).
* Selecione o processo ou nome do pacote alvo.
* Clique em **Run**.
6. **Usar templates**: mude para a aba `Templates` e marque as funcionalidades de Hook desejadas (como "SSL Pinning Bypass"); o código será injetado automaticamente no seu script.
7. **Automação via Skills (opcional)**: desativada por padrão. Vá em `Settings/Preferences -> ZAFrida -> Skills HTTP API`, marque `Enable Skills` para iniciar automaticamente a API local (também é possível `Start/Stop` manualmente). Localização do CLI e dos templates:
* Skill e CLI principal: `skills-template/zafrida-http-control/`
* Launcher compatível com caminho antigo: `skills-cli/zafrida_skill_cli.py`
QR code do grupo de comunicação
-----------------------------------
<img src="https://assets.kitploit.com/production/public/readmes/11475/af2e178a9eee68ad3cbdf0c5b002b39f4c18f0128b73575324967291f19eeddc.jpg" alt="QR code do grupo de comunicação ZAFrida e Reverse Engineering" width="260" />
Funcionalidades
-----------------------------------
* **Gerenciamento de dispositivos e processos**
Integra `frida-ls-devices` e `frida-ps`, com suporte a atualização da lista de dispositivos em um clique, visualização de processos em execução, Apps em execução ou aplicativos instalados.
* **Conexão em múltiplos modos**
Suporte completo aos modos **USB / Remote / Gadget**, com suporte a Host e Port remotos personalizados, sem precisar montar manualmente parâmetros complexos de linha de comando.
* **Execução interativa de scripts (Run / Attach)**
* Suporte a duas ações de execução: **Run (Spawn por padrão)** e **Attach**, em vez de uma simples "troca de modo".
* Suporte a **Force Stop** para forçar a parada do aplicativo alvo.
* Saída de log no console integrada, com salvamento automático dos logs no diretório do projeto `zafrida-logs/`.
* **Menu de contexto do editor JS / TypeScript (importante)**
* Na área de edição de arquivos `.js` ou `.ts` do Frida, clique com o botão direito para escolher diretamente:
* **Run Frida Script**: executa usando o arquivo atual como script principal (Spawn por padrão).
* **Attach Frida Script**: injeta o arquivo atual como script de anexação no processo alvo em execução.
* Antes da execução, o arquivo atual é salvo automaticamente e o ZAFrida Project ao qual o script pertence é ativado automaticamente.
* Ideal para PoC rápido, validação de Demo, modo Gadget ou injeção imediata em processos em execução.
* **Atalhos**:
* Windows / Linux: `Ctrl + Alt + S`
* macOS: `⌘ + ⌥ + S`
* **Inserção de Snippets pelo menu de contexto do editor**
* No menu de contexto do editor JS / TypeScript, oferece **ZAFrida Frida Snippets**.
* Insere trechos de código Frida comuns com um clique, como:
* Estrutura envolvente `Java.perform`
* Template de Hook de método Java
* Native Hook com `Interceptor.attach`
* O processo de inserção segue o WriteCommandAction da IDE, permitindo desfazer/refazer com segurança.
* **Sistema de templates dinâmicos (inovação central)**
* Templates de Hook comuns para Android / iOS integrados (como SSL Pinning Bypass, Method Hook, Native Hook).
* **Controle por caixa de seleção**: marcar insere o código, desmarcar comenta automaticamente o código, sem precisar excluir ou alterar manualmente.
* Suporte a templates personalizados, com pré-visualização do código do template em tempo real na IDE.
* **Design separado de Run Script + Attach Script**
* Suporte à coexistência de um **Run Script** principal e de um **Attach Script** independente.
* Adequado para desacoplar "Hook de fase de inicialização" e "lógica de injeção em tempo de execução", facilitando depuração complexa e manutenção de longo prazo.
* **Configuração por projeto (ZAFrida Project)**
* Introduz o conceito de ZAFrida Project, salvando dispositivo, alvo, script, Attach Script, parâmetros de conexão etc. como um contexto de trabalho completo.
* Suporte no Project View a:
* `New Frida Project` para criar um novo projeto
* `Select Frida Project` para alternar rapidamente o projeto ativo atual
* `Load Frida Project` para importar um diretório de projeto existente
* Após trocar de projeto, o estado da UI e as configurações são restaurados automaticamente.
* **Resolução inteligente de ambiente Python / Frida**
* Por padrão, resolve o Python SDK do projeto PyCharm atual; cada ZAFrida Project pode sobrescrever individualmente o interpretador ou o diretório do ambiente.
* Suporte a ambientes locais system/pyenv, venv/virtualenv, Conda, uv, Poetry, Pipenv e Hatch.
* Vários ZAFrida Projects podem escolher o mesmo caminho para compartilhar o ambiente, sem copiar venv; ideal para manter ambientes Frida 16/17 separados.
* Quando o ambiente atual da IDE ou o ambiente explícito do projeto não possui `frida-tools`, um erro é exibido diretamente, sem usar silenciosamente outra versão do PATH do sistema; `Test` pode mostrar a versão real do Frida.
* Interpretadores Python remotos como SSH, Docker, Docker Compose e WSL ainda não podem ser usados para subprocessos Frida locais.
* **Frida 17 / TypeScript**
* Seleção de arquivos, Run/Attach pelo botão direito e Snippets suportam `.js` / `.ts`; o REPL do Frida 17 compila automaticamente `-l agent.ts`.
* Os templates integrados foram migrados para a API moderna Module/NativePointer do Frida 17, mantendo compatibilidade com ambientes comuns do Frida 16.
* O REPL do frida-tools carrega bridges padrão Java/ObjC por compatibilidade; ao usar `import` de módulos npm/de terceiros, gerencie as dependências via `frida-create -t agent` ou projeto equivalente.
* **Interface local de automação Skills**
* A HTTP API local de Skills (desativada por padrão) suporta descoberta de capacidades, ambiente de projeto/Python, dispositivos e processos, Run/Attach, lista de logs históricos e leitura incremental de logs baseada em cursor de bytes.
* A Skill inclui fluxos de recuperação limitados `wait-device` / `wait-session`, distinguindo leituras seguras para retry de operações com efeitos colaterais que não podem ser reproduzidas automaticamente.
* Como ativar: `Settings/Preferences -> ZAFrida -> Skills HTTP API`, marque `Enable Skills`.
* CLI e templates correspondentes:
* `skills-template/zafrida-http-control/` (Skill principal e CLI)
* `skills-cli/zafrida_skill_cli.py` (launcher compatível com caminho antigo)
Cenários de uso
-----------------------------------
O ZAFrida UI é adequado para todos os cenários de engenharia reversa com Frida, especialmente:
* Testes de penetração e análise de engenharia reversa em Apps Android / iOS.
* Processos de depuração que exigem troca frequente entre diferentes scripts Hook.
* Engenheiros acostumados a usar IDEs (PyCharm/IDEA) para desenvolvimento misto de Python, JavaScript e TypeScript.
Documentação técnica
-----------------------------------
- **Requisitos de ambiente**:
- IntelliJ IDEA ou PyCharm (recomendado 2024.3+)
- Python3 e `frida-tools` instalados localmente (`pip install frida-tools`)
- Garanta que `frida`, `frida-ps`, `frida-ls-devices` estejam no PATH do sistema ou especifique os caminhos nas configurações do plugin.
- **Feedback de problemas**: [Github Issues](https://github.com/yilongmd/zafrida-ui/issues)
Iniciar o projeto
-----------------------------------
1. Clone o código-fonte: `git clone https://github.com/yilongmd/zafrida-ui.git`
2. Abra o projeto com o IntelliJ IDEA.
3. Execute a tarefa Gradle `runIde` para iniciar o ambiente de depuração.
Efeitos do sistema
-----------------------------------
##### Interface principal e painel de execução (Run Panel)
> Oferece seleção de dispositivo, seleção de script, configuração do modo de execução e saída do console.
##### Gerenciamento de templates dinâmicos (Template Panel)
> Selecione a categoria à esquerda, marque o template no centro e visualize o código em tempo real à direita. A caixa de seleção controla diretamente se o conteúdo do script está ativo ou não.
##### Interface de configurações (Settings)
> Suporta personalização do caminho das ferramentas Frida, endereço de conexão remota e configuração de logs.
##### Assistente de criação de projeto
> Cria rapidamente uma estrutura de projeto Frida padronizada.
Arquitetura técnica
-----------------------------------
#### Ambiente de desenvolvimento
- Linguagem: Java 21, Java, scripts de build usando Gradle Kotlin DSL
- Framework: IntelliJ Platform SDK
- Ferramenta de build: Gradle
- Dependências: `frida` `frida-tools` (Python environment)
Agradecimentos
-----------------------------------
Agradecimento especial aos seguintes mestres pelo suporte de templates de scripts Frida JS para este projeto:
* **小佳**
* **Lane**
* **迷人**
Para mais contribuidores e informações de agradecimento, consulte: [CONTRIBUTORS.md](https://github.com/yilongmd/zafrida-ui/blob/main/CONTRIBUTORS.md)