yilongmd/zafrida-uiPyCharm / JetBrains IDE 내부의 Frida UI 도구 창.
中文 | [English](https://github.com/yilongmd/zafrida-ui/blob/main/README.en-US.md)
ZAFrida UI - PyCharm Frida Plugin
===============
현재 버전: 0.3.8
[](LICENSE)
[](https://github.com/yilongmd/zafrida-ui)
[](https://plugins.jetbrains.com/)
[](https://github.com/yilongmd/zafrida-ui)
## 0.3.8 주요 업데이트
- Session 패널에서 "장치"와 "연결 모드"를 두 개의 독립된 행으로 분리했습니다. Device 행은 실제 장치만 나열하고, Mode 행에서 USB / Remote / Gadget과 엔드포인트를 선택합니다. Remote/Gadget 루프백의 adb 포트 포워딩, Force Stop, Open App은 항상 현재 선택된 휴대폰에 적용되며, 더 이상 이전 장치를 잘못 사용하지 않습니다.
- 장치를 처음 열거나 새로 고칠 때 실행 중이 아닌 adb server를 자동으로 시작하므로, 더 이상 수동으로 `adb devices`를 실행할 필요가 없습니다.
- 저장된 장치가 온라인이 아닐 때 "미연결" 자리 표시자를 표시하고 관련 작업을 차단합니다. USB 장치가 한 대만 연결되어 있으면 자동으로 해당 장치로 전환하고 Console에 알립니다.
- Mode 행 아래에 실제로 실행되는 adb/frida 라우팅을 표시합니다. Gadget 모드에서는 Target 패키지 이름이 읽기 전용이지만 선택하여 복사할 수 있습니다.
- HTTP API의 `/state`에 `connection` 파싱 결과가 추가되었습니다. `device-select --host`는 여전히 사용 가능하지만 더 이상 권장되지 않으며, 엔드포인트는 `mode-set --host/--port`로 변경하세요.
## 0.3.7 주요 업데이트
- 각 ZAFrida Project는 Python/Frida 환경을 독립적으로 선택하거나 공유할 수 있으며, 기본적으로 현재 PyCharm 프로젝트 인터프리터를 사용하고 venv, Conda, uv, Poetry, Pipenv, Hatch 등 로컬 환경을 지원합니다.
- Session UI와 Project Settings를 재설계하여 플러그인, Python, Frida 버전 정보를 완전히 표시하고, 적응형 및 드래그 가능한 로그 패널과 세션 상태를 최적화했습니다.
- `.js` / `.ts`, Frida 16/17, 다중 프로젝트 환경 전환, 그리고 USB, Remote, Gadget 세 가지 연결 흐름을 완전히 지원합니다.
- 로컬 HTTP API, CLI 및 중국어 Skill의 장치 복구, 세션 대기, 증분 로그 기능을 강화했습니다. 중복되고 불안정한 MCP 어댑터 계층을 제거했습니다.
프로젝트 소개
-----------------------------------
<h3 align="center">PyCharm/IntelliJ를 위해 설계된 Frida 그래픽 도구</h3>
ZAFrida UI는 PyCharm 및 JetBrains 시리즈 IDE에 통합된 Frida 그래픽 조작 플러그인입니다. Frida 명령줄 조작이 번거롭고 스크립트 관리가 혼란스러운 문제를 해결하는 것을 목표로 하며, 장치, 프로세스, 스크립트 및 로그를 관리하기 위한 완전한 **UI 인터랙션 인터페이스**를 제공합니다.
핵심 하이라이트는 **"체크박스식" 템플릿 관리 시스템**입니다. 사용자는 체크/체크 해제를 통해 코드 조각을 메인 스크립트에 동적으로 삽입하거나 주석 처리할 수 있어, "블록 조립식" Hook 스크립트 구성을 구현할 수 있습니다. 동시에 플러그인에는 완전한 **프로젝트화 관리** (`zafrida-project.xml`)가 내장되어 있어 다중 장치, 다중 환경 구성의 빠른 전환을 지원합니다.
ZAFrida는 Frida를 대체하는 것이 아니라, `frida-tools`의 강력한 UI 셸로서 기존 Python 및 Frida 환경과 원활하게 연동됩니다.
**간이 Wiki**: [ZAFrida UI 간이 Wiki (BBS)](https://github.com/yilongmd/zafrida-ui/blob/main/zafrida_ui_wiki_bbs_zh.md) (더 간단한 Wiki입니다)
**상세 사용 튜토리얼**: [ZAFrida UI 상세 사용 튜토리얼 Wiki](https://github.com/yilongmd/zafrida-ui/blob/main/ZAFridaUI_Wiki_zh.md)
## 효과 데모
빠른 시작
-----------------------------------
1. **플러그인 설치**: IDE 플러그인 마켓에서 "ZAFrida"를 검색하거나 디스크에서 설치합니다.
2. **기본 환경 구성**: 기본적으로 현재 PyCharm 프로젝트의 Python Interpreter를 사용합니다. 전역 `Settings` -> `Tools` -> `ZAFrida`에는 도구 이름/경로 기본값만 유지됩니다.
3. **프로젝트 생성**: 프로젝트 뷰에서 우클릭 -> `New Frida Project`.
* 해당 프로젝트에 다른 Frida 버전이 필요하면 ZAFrida `Project Settings`를 열고 Python 인터프리터 또는 환경 디렉터리를 선택한 후 `Test`를 클릭합니다.
4. **스크립트 작성/선택**: Run 패널에서 `agent.js` 또는 `agent.ts`를 선택합니다.
5. **Hook 디버깅**:
* 장치 연결 (USB 또는 Remote 또는 Gadget).
* 대상 프로세스 또는 패키지 이름 선택.
* **Run** 클릭.
6. **템플릿 사용**: `Templates` 탭으로 전환하여 필요한 Hook 기능(예: "SSL Pinning Bypass")을 체크하면 코드가 자동으로 스크립트에 주입됩니다.
7. **Skills 자동화 (선택)**: 기본적으로 비활성화되어 있습니다. `Settings/Preferences -> ZAFrida -> Skills HTTP API`로 이동하여 `Enable Skills`를 체크하면 로컬 API가 자동으로 시작됩니다(수동 `Start/Stop`도 가능). CLI 및 템플릿 위치:
* Skill 및 메인 CLI: `skills-template/zafrida-http-control/`
* 구 경로 호환 런처: `skills-cli/zafrida_skill_cli.py`
교류 그룹 QR 코드
-----------------------------------
<img src="https://assets.kitploit.com/production/public/readmes/11475/af2e178a9eee68ad3cbdf0c5b002b39f4c18f0128b73575324967291f19eeddc.jpg" alt="ZAFrida与逆向交流群二维码" width="260" />
기능 특성
-----------------------------------
* **장치 및 프로세스 관리**
`frida-ls-devices`와 `frida-ps`를 통합하여 장치 목록을 원클릭으로 새로 고치고, 실행 중인 프로세스, 실행 중인 App 또는 설치된 애플리케이션을 확인할 수 있습니다.
* **다중 모드 연결**
**USB / Remote / Gadget** 모드를 완전히 지원하며, 사용자 정의 원격 Host와 Port를 지원하여 복잡한 명령줄 인자를 수동으로 조합할 필요가 없습니다.
* **인터랙티브 스크립트 실행 (Run / Attach)**
* 단순한 "모드 전환"이 아닌 **Run(기본 Spawn)** 과 **Attach** 두 가지 실행 동작을 지원합니다.
* **Force Stop**으로 대상 애플리케이션을 강제 중지할 수 있습니다.
* 내장 콘솔 로그 출력을 제공하며, 로그를 프로젝트 디렉터리 `zafrida-logs/`에 자동 저장합니다.
* **JS / TypeScript 에디터 우클릭 메뉴 (중요)**
* Frida `.js` 또는 `.ts` 파일 편집 영역에서 우클릭하여 직접 선택할 수 있습니다:
* **Run Frida Script**: 현재 파일을 메인 스크립트로 실행(기본 Spawn).
* **Attach Frida Script**: 현재 파일을 추가 스크립트로 실행 중인 대상 프로세스에 주입.
* 실행 전 현재 파일을 자동 저장하고, 스크립트가 속한 ZAFrida Project로 자동 전환합니다.
* 빠른 PoC, Demo 검증, Gadget 모드 또는 실행 중인 프로세스에 즉시 주입하는 데 적합합니다.
* **단축키**:
* Windows / Linux: `Ctrl + Alt + S`
* macOS: `⌘ + ⌥ + S`
* **에디터 우클릭 Snippets 삽입**
* JS / TypeScript 에디터 우클릭 메뉴에서 **ZAFrida Frida Snippets**를 제공합니다.
* 자주 사용하는 Frida 코드 조각을 원클릭으로 삽입합니다. 예:
* `Java.perform` 래핑 구조
* Java 메서드 Hook 템플릿
* `Interceptor.attach` Native Hook
* 삽입 과정은 IDE WriteCommandAction을 따르며 안전하게 실행 취소/재실행할 수 있습니다.
* **동적 템플릿 시스템 (핵심 혁신)**
* Android / iOS에서 자주 사용하는 Hook 템플릿(예: SSL Pinning Bypass, Method Hook, Native Hook)을 내장.
* **체크박스 제어**: 체크하면 코드가 삽입되고, 체크를 해제하면 코드가 자동으로 주석 처리되어 수동으로 삭제하거나 수정할 필요가 없습니다.
* 사용자 정의 템플릿을 지원하며, IDE 내에서 템플릿 코드를 실시간으로 미리 볼 수 있습니다.
* **Run Script + Attach Script 분리 설계**
* 메인 **Run Script**와 독립적인 **Attach Script**의 공존을 지원합니다.
* "시작 시점 Hook"과 "실행 시점 주입 로직"을 분리하는 데 적합하여 복잡한 디버깅과 장기 유지보수에 편리합니다.
* **프로젝트화 구성 (ZAFrida Project)**
* ZAFrida Project 개념을 도입하여 장치, 대상, 스크립트, Attach Script, 연결 매개변수 등을 하나의 완전한 작업 컨텍스트로 저장합니다.
* Project View에서 다음을 지원합니다:
* `New Frida Project`로 새 프로젝트 생성
* `Select Frida Project`로 현재 활성 프로젝트 빠른 전환
* `Load Frida Project`로 기존 프로젝트 디렉터리 가져오기
* 프로젝트 전환 후 UI 상태와 구성이 자동으로 복원됩니다.
* **지능형 Python / Frida 환경 해석**
* 기본적으로 현재 PyCharm 프로젝트의 Python SDK를 해석하며, 각 ZAFrida Project는 인터프리터 또는 환경 디렉터리를 개별적으로 재정의할 수 있습니다.
* 로컬 system/pyenv, venv/virtualenv, Conda, uv, Poetry, Pipenv, Hatch 환경을 지원합니다.
* 여러 ZAFrida Project가 동일한 경로를 선택하여 환경을 공유할 수 있어 venv를 복사할 필요가 없습니다. Frida 16/17 환경을 각각 유지 관리하는 데 적합합니다.
* 현재 IDE 환경 또는 명시적 프로젝트 환경에 `frida-tools`가 없으면 즉시 오류를 보고하며, 시스템 PATH의 다른 버전을 조용히 혼용하지 않습니다. `Test`로 실제 Frida 버전을 표시할 수 있습니다.
* SSH, Docker, Docker Compose, WSL 등 원격 Python Interpreter는 현재 로컬 Frida 하위 프로세스에 사용할 수 없습니다.
* **Frida 17 / TypeScript**
* 파일 선택, 우클릭 Run/Attach 및 Snippets가 `.js` / `.ts`를 지원합니다. Frida 17의 REPL은 `-l agent.ts`를 자동으로 컴파일합니다.
* 내장 템플릿이 Frida 17의 현대적인 Module/NativePointer API로 마이그레이션되었으며, Frida 16의 일반적인 환경도 계속 사용할 수 있습니다.
* frida-tools REPL은 호환성을 위해 표준 Java/ObjC bridges를 함께 제공합니다. npm/서드파티 모듈 `import`를 사용할 때는 `frida-create -t agent` 또는 동등한 엔지니어링 방식으로 의존성을 관리해야 합니다.
* **Skills 로컬 자동화 인터페이스**
* 로컬 Skills HTTP API(기본 비활성화)는 기능 탐색, 프로젝트/Python 환경, 장치 및 프로세스, Run/Attach, 기록 로그 목록, 바이트 커서 기반 증분 로그 읽기를 지원합니다.
* Skill에는 유계 `wait-device` / `wait-session` 복구 흐름이 내장되어 있으며, 안전하게 재시도 가능한 읽기와 자동 재생할 수 없는 부작용 작업을 구분합니다.
* 활성화 방법: `Settings/Preferences -> ZAFrida -> Skills HTTP API`에서 `Enable Skills` 체크.
* 함께 제공되는 CLI 및 템플릿:
* `skills-template/zafrida-http-control/` (메인 Skill 및 CLI)
* `skills-cli/zafrida_skill_cli.py` (구 경로 호환 런처)
적용 시나리오
-----------------------------------
ZAFrida UI는 Frida를 사용한 모든 리버스 엔지니어링 시나리오에 적합하며, 특히:
* Android / iOS App 침투 테스트 및 리버스 분석.
* 서로 다른 Hook 스크립트를 자주 전환해야 하는 디버깅 과정.
* IDE (PyCharm/IDEA)를 사용하여 Python, JavaScript, TypeScript 혼합 개발을 즐기는 엔지니어.
기술 문서
-----------------------------------
- **환경 요구 사항**:
- IntelliJ IDEA 또는 PyCharm (2024.3+ 권장)
- 로컬에 Python3 및 `frida-tools` 설치됨 (`pip install frida-tools`)
- `frida`, `frida-ps`, `frida-ls-devices`가 시스템 PATH에 있거나 플러그인 설정에서 경로를 지정해야 합니다.
- **문제 피드백**: [Github Issues](https://github.com/yilongmd/zafrida-ui/issues)
프로젝트 시작
-----------------------------------
1. 소스 클론: `git clone https://github.com/yilongmd/zafrida-ui.git`
2. IntelliJ IDEA로 프로젝트를 엽니다.
3. Gradle 작업 `runIde`를 실행하여 디버그 환경을 시작합니다.
시스템 효과
-----------------------------------
##### 메인 인터페이스 및 실행 패널 (Run Panel)
> 장치 선택, 스크립트 선택, 실행 모드 구성 및 콘솔 출력을 제공합니다.
##### 동적 템플릿 관리 (Template Panel)
> 왼쪽에서 분류를 선택하고, 가운데에서 템플릿을 체크하며, 오른쪽에서 코드를 실시간으로 미리 봅니다. 체크박스가 스크립트 내용의 적용 여부를 직접 제어합니다.
##### 설정 인터페이스 (Settings)
> 사용자 정의 Frida 도구 경로, 원격 연결 주소 및 로그 구성을 지원합니다.
##### 프로젝트 생성 마법사
> 표준화된 Frida 프로젝트 구조를 빠르게 생성합니다.
기술 아키텍처
-----------------------------------
#### 개발 환경
- 언어: Java 21, Java, 빌드 스크립트는 Gradle Kotlin DSL 사용
- 프레임워크: IntelliJ Platform SDK
- 빌드 도구: Gradle
- 의존성: `frida` `frida-tools` (Python environment)
감사의 글
-----------------------------------
다음 분들이 본 프로젝트에 Frida JS 스크립트 템플릿 지원을 제공해 주신 것에 특별히 감사드립니다:
* **小佳**
* **Lane**
* **迷人**
더 많은 기여자와 감사 정보는 다음을 참조하세요: [CONTRIBUTORS.md](https://github.com/yilongmd/zafrida-ui/blob/main/CONTRIBUTORS.md)