android-decompile-mcp 0.0.0-stage → 1.0.0

package/README.it.md

@@ -0,0 +1,226 @@
+# DexAndroid
+
+[English](./README.md) · [简体中文](./README.zh-CN.md) · [繁體中文](./README.zh-TW.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · **Italiano** · [Türkçe](./README.tr.md)
+
+> ⚠️ **Solo per apprendimento e didattica.** Non usare per attività illegali, cracking non autorizzato, violazione di copyright o elusione di protezioni di terzi. Rispettare le leggi locali e i termini dell’app. L’abuso è responsabilità dell’utente.
+
+**MCP Server** per unpacking Android + analisi smali. Da Cursor / Claude: dispositivi, rilevamento packer, unpack statico / BlackDex / Frida, dex→smali, ricerca stringhe API.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## Funzionalità
+
+| Capacità | Tool MCP | Note |
+| --- | --- | --- |
+| Devices | `list_devices` | Connected ADB devices |
+| Packages | `list_packages` | Optional keyword filter |
+| Packer detect | `detect_packer` | 360 / Tencent / Bangcle / ijiami / Alibaba, etc. |
+| Pull APK | `pull_apk` | Installed app (+ splits) |
+| Static unpack | `static_unpack` | Extract `classes*.dex` |
+| No-Root unpack | `blackdex_prepare` / `blackdex_pull` | BlackDex memory dump |
+| Root unpack | `frida_prepare` / `frida_unpack` | frida-server + frida-dexdump |
+| Decompile | `dex_to_smali` | baksmali → smali |
+| Analyze | `smali_list_classes` / `smali_read_class` / `smali_search` | List / read / regex |
+
+### Metodi di unpack
+
+| Metodo | Root? | Quando |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## Requisiti
+
+- **Windows / macOS / Linux** (docs use Windows examples)
+- **Node.js** ≥ 18
+- **ADB** on PATH, or set `ADB_PATH`
+- **Java 8+** (for baksmali via `dex_to_smali`)
+- Optional: [BlackDex](https://github.com/CodingGay/BlackDex/releases); rooted device + `frida-server`; `pip install frida-tools frida-dexdump`
+
+Place baksmali fat jar / frida-server / BlackDex under local `tools/` (large binaries are gitignored).
+
+---
+
+## Installazione e build
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+Avvia MCP (stdio):
+
+```bash
+npm start
+# node dist/index.js
+```
+
+Modalità dev:
+
+```bash
+npm run dev
+```
+
+---
+
+## Setup Cursor (MCP)
+
+Aggiungi a `.cursor/mcp.json` (**modifica i path**):
+
+```json
+{
+  "mcpServers": {
+    "dex-android-unpack": {
+      "command": "node",
+      "args": ["E:/DexAndroid/dist/index.js"],
+      "env": {
+        "ADB_PATH": "E:/Android/Sdk/platform-tools/adb.exe",
+        "DEX_OUT_DIR": "E:/DexAndroid/unpack-output"
+      }
+    }
+  }
+}
+```
+
+Riavvia Cursor / ricarica MCP.
+
+---
+
+## Variabili d’ambiente
+
+| Variabile | Significato | Default |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## Flussi tipici
+
+### 1. Unpack statico (più veloce)
+
+1. `list_devices` or prepare local `apkPath`.
+2. `detect_packer`.
+3. `static_unpack` → `classes*.dex`.
+4. `dex_to_smali` → smali folder.
+5. `smali_search` / `smali_read_class`.
+
+**Note:** Protected apps often yield only the shell via static unpack—use BlackDex / Frida for business code.
+
+### 2. Senza Root (BlackDex)
+
+1. `list_devices`.
+2. `blackdex_prepare` with `blackdexApkPath`.
+3. Unpack the target app in BlackDex UI.
+4. `blackdex_pull` with `targetPkg`.
+5. `dex_to_smali` then `smali_*`.
+
+### 3. Con Root (Frida)
+
+1. Rooted device (e.g. Magisk), `adb` ready.
+2. `frida_prepare` to push/start `tools/frida-server`.
+3. Matching `frida` / `frida-dexdump` locally (prefer 16.x).
+4. `frida_unpack` with `pkg`, prefer `spawn: true`, `deepSearch: true`.
+5. `dex_to_smali` on output, then analyze.
+
+If Frida 17 attach fails, align tools to 16.x; some devices need temporary `setenforce 0`.
+
+### 4. Esempi smali
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## Struttura
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+---
+
+## Esempi di decompilazione
+
+Vedi [`examples/`](./examples/) (smali in zip):
+
+| Esempio | Percorso | Contenuto |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`info.cd120.two`) |
+
+Dopo l’estrazione usa `smali_*`.
+
+---
+
+## Cheatsheet MCP
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+
+---
+
+## FAQ
+
+**Q: Empty `list_devices`?**  
+Check USB debugging, `adb devices`, pass `serial` if multiple.
+
+**Q: No business classes after static unpack?**  
+Likely packed—use BlackDex or Frida.
+
+**Q: `dex_to_smali` failed?**  
+Install Java; put baksmali jar in `tools/` or set `BAKSMALI_JAR`.
+
+**Q: Frida jailed / version mismatch?**  
+Keep `frida-server` and host `frida` major versions aligned; try 16.x.
+
+**Q: Where is output?**  
+Default `unpack-output/` (or `DEX_OUT_DIR`). **Do not commit dumps.**
+
+---
+
+## Avviso legale
+
+Questo progetto è **solo per apprendimento, didattica e ricerca di sicurezza autorizzata**. È vietato usarlo per reati o illegalità (accesso non autorizzato, cracking, pirateria, attacchi, violazione IP). Autori e contributor non rispondono degli abusi. L’uso implica accettazione.
+
+> ⚠️ **Solo per apprendimento e didattica.** Non usare per attività illegali, cracking non autorizzato, violazione di copyright o elusione di protezioni di terzi. Rispettare le leggi locali e i termini dell’app. L’abuso è responsabilità dell’utente.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/README.ja.md

@@ -0,0 +1,226 @@
+# DexAndroid
+
+[English](./README.md) · [简体中文](./README.zh-CN.md) · [繁體中文](./README.zh-TW.md) · **日本語** · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md)
+
+> ⚠️ **学習・教育目的のみ。** 違法行為、無断クラック、権利侵害、第三者保護の回避には使用しないでください。各国の法令と対象アプリの利用規約を遵守してください。悪用の責任は利用者にあります。
+
+Android アンパック + smali 解析用 **MCP Server**。Cursor / Claude などから、端末管理・保護検知・静的/非 Root/Root アンパック・dex→smali・API 文字列検索が可能です。
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## 機能
+
+| 機能 | MCP ツール | 説明 |
+| --- | --- | --- |
+| Devices | `list_devices` | Connected ADB devices |
+| Packages | `list_packages` | Optional keyword filter |
+| Packer detect | `detect_packer` | 360 / Tencent / Bangcle / ijiami / Alibaba, etc. |
+| Pull APK | `pull_apk` | Installed app (+ splits) |
+| Static unpack | `static_unpack` | Extract `classes*.dex` |
+| No-Root unpack | `blackdex_prepare` / `blackdex_pull` | BlackDex memory dump |
+| Root unpack | `frida_prepare` / `frida_unpack` | frida-server + frida-dexdump |
+| Decompile | `dex_to_smali` | baksmali → smali |
+| Analyze | `smali_list_classes` / `smali_read_class` / `smali_search` | List / read / regex |
+
+### アンパック方式の比較
+
+| 方式 | Root? | 用途 |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## 要件
+
+- **Windows / macOS / Linux**（手順は Windows 例）
+- **Node.js** ≥ 18
+- **ADB**（PATH または `ADB_PATH`）
+- **Java 8+**（baksmali）
+- 任意：[BlackDex](https://github.com/CodingGay/BlackDex/releases)、Root + `frida-server`、`pip install frida-tools frida-dexdump`
+
+`tools/` に baksmali / frida-server / BlackDex を配置（大きなバイナリは gitignore）。
+
+---
+
+## インストールとビルド
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+MCP 起動（stdio）:
+
+```bash
+npm start
+# node dist/index.js
+```
+
+開発モード:
+
+```bash
+npm run dev
+```
+
+---
+
+## Cursor（MCP）連携
+
+`.cursor/mcp.json` などに追加（**パスは環境に合わせて変更**）：
+
+```json
+{
+  "mcpServers": {
+    "dex-android-unpack": {
+      "command": "node",
+      "args": ["E:/DexAndroid/dist/index.js"],
+      "env": {
+        "ADB_PATH": "E:/Android/Sdk/platform-tools/adb.exe",
+        "DEX_OUT_DIR": "E:/DexAndroid/unpack-output"
+      }
+    }
+  }
+}
+```
+
+保存後 Cursor を再起動 / MCP を再読込。
+
+---
+
+## 環境変数
+
+| 変数 | 意味 | 既定 |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## 典型的な手順
+
+### 1. 静的アンパック（最速）
+
+1. `list_devices` またはローカル `apkPath`。
+2. `detect_packer`。
+3. `static_unpack` → `classes*.dex`。
+4. `dex_to_smali`。
+5. `smali_search` / `smali_read_class`。
+
+**注意:** 保護アプリの静的 dex はシェルのみのことが多いです。業務コードは BlackDex / Frida を。
+
+### 2. 非 Root（BlackDex）
+
+1. `list_devices`。
+2. `blackdex_prepare`（`blackdexApkPath`）。
+3. 端末の BlackDex で対象アプリをダンプ。
+4. `blackdex_pull`（`targetPkg`）。
+5. `dex_to_smali` → `smali_*`。
+
+### 3. Root（Frida）
+
+1. Root 済み、`adb` 利用可。
+2. `frida_prepare` で `frida-server` を起動。
+3. ホスト側 `frida` / `frida-dexdump` をバージョン合わせ（推奨 16.x）。
+4. `frida_unpack`（`spawn: true`、`deepSearch: true` 推奨）。
+5. `dex_to_smali` 後に解析。
+
+Frida 17 で失敗する場合は 16.x に揃えてください。必要なら一時的に `setenforce 0`。
+
+### 4. smali 解析例
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## 構成
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+---
+
+## デコンパイル例
+
+[`examples/`](./examples/) を参照（smali は zip）：
+
+| 例 | パス | 内容 |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API 文書 |
+| Huaxi | [`examples/huaxi/`](./examples/huaxi/) | 静的 smali.zip（`info.cd120.two`） |
+
+解凍後に `smali_*` を実行できます。
+
+---
+
+## MCP ツール早見表
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+
+---
+
+## FAQ
+
+**Q: `list_devices` が空？**  
+USB デバッグと `adb devices` を確認。複数端末は `serial`。
+
+**Q: 静的後に業務クラスがない？**  
+保護の可能性大 → BlackDex / Frida。
+
+**Q: `dex_to_smali` 失敗？**  
+Java と baksmali jar（または `BAKSMALI_JAR`）を確認。
+
+**Q: Frida jailed / 版不一致？**  
+`frida-server` とホスト `frida` のメジャー版を揃える。
+
+**Q: 出力先は？**  
+既定は `unpack-output/`。**Git にコミットしないでください。**
+
+---
+
+## 法令遵守と免責
+
+本プロジェクトは**学習・教育および許可されたセキュリティ研究のみ**を目的とします。不正アクセス、クラック、著作権侵害など違法行為への使用を固く禁じます。悪用について作者・貢献者は責任を負いません。利用により本条件に同意したものとみなします。
+
+> ⚠️ **学習・教育目的のみ。** 違法行為、無断クラック、権利侵害、第三者保護の回避には使用しないでください。各国の法令と対象アプリの利用規約を遵守してください。悪用の責任は利用者にあります。
+
+---
+
+## License
+
+MIT — [`LICENSE`](./LICENSE) を参照。

package/README.ko.md

@@ -0,0 +1,226 @@
+# DexAndroid
+
+[English](./README.md) · [简体中文](./README.zh-CN.md) · [繁體中文](./README.zh-TW.md) · [日本語](./README.ja.md) · **한국어** · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md)
+
+> ⚠️ **학습 및 교육 목적으로만 사용하세요.** 불법 행위, 무단 크래킹, 저작권 침해, 제3자 보호 우회에 사용하지 마십시오. 현지 법령과 대상 앱 약관을 준수해야 하며, 오남용 책임은 사용자에게 있습니다.
+
+안드로이드 언패킹 + smali 분석 **MCP Server**. Cursor / Claude 등에서 기기 관리, 보호(패커) 탐지, 정적/비루팅/루팅 언패킹, dex→smali, API 문자열 검색을 수행합니다.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## 기능
+
+| 기능 | MCP 도구 | 설명 |
+| --- | --- | --- |
+| Devices | `list_devices` | Connected ADB devices |
+| Packages | `list_packages` | Optional keyword filter |
+| Packer detect | `detect_packer` | 360 / Tencent / Bangcle / ijiami / Alibaba, etc. |
+| Pull APK | `pull_apk` | Installed app (+ splits) |
+| Static unpack | `static_unpack` | Extract `classes*.dex` |
+| No-Root unpack | `blackdex_prepare` / `blackdex_pull` | BlackDex memory dump |
+| Root unpack | `frida_prepare` / `frida_unpack` | frida-server + frida-dexdump |
+| Decompile | `dex_to_smali` | baksmali → smali |
+| Analyze | `smali_list_classes` / `smali_read_class` / `smali_search` | List / read / regex |
+
+### 언패킹 방식 비교
+
+| 방식 | Root? | 용도 |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## 요구 사항
+
+- **Windows / macOS / Linux** (문서는 Windows 기준)
+- **Node.js** ≥ 18
+- **ADB** (PATH 또는 `ADB_PATH`)
+- **Java 8+** (baksmali)
+- 선택: [BlackDex](https://github.com/CodingGay/BlackDex/releases), 루팅 + `frida-server`, `pip install frida-tools frida-dexdump`
+
+`tools/`에 baksmali / frida-server / BlackDex 배치 (대용량은 gitignore).
+
+---
+
+## 설치 및 빌드
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+MCP 시작 (stdio):
+
+```bash
+npm start
+# node dist/index.js
+```
+
+개발 모드:
+
+```bash
+npm run dev
+```
+
+---
+
+## Cursor MCP 연동
+
+`.cursor/mcp.json` 등에 추가 (**경로를 로컬에 맞게 수정**):
+
+```json
+{
+  "mcpServers": {
+    "dex-android-unpack": {
+      "command": "node",
+      "args": ["E:/DexAndroid/dist/index.js"],
+      "env": {
+        "ADB_PATH": "E:/Android/Sdk/platform-tools/adb.exe",
+        "DEX_OUT_DIR": "E:/DexAndroid/unpack-output"
+      }
+    }
+  }
+}
+```
+
+저장 후 Cursor 재시작 / MCP 리로드.
+
+---
+
+## 환경 변수
+
+| 변수 | 의미 | 기본값 |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## 사용 흐름
+
+### 1. 정적 언패킹 (가장 빠름)
+
+1. `list_devices` 또는 로컬 `apkPath`.
+2. `detect_packer`.
+3. `static_unpack` → `classes*.dex`.
+4. `dex_to_smali`.
+5. `smali_search` / `smali_read_class`.
+
+**참고:** 보호 앱의 정적 dex는 쉘만일 수 있습니다. 비즈니스 코드는 BlackDex / Frida.
+
+### 2. 비루팅 (BlackDex)
+
+1. `list_devices`.
+2. `blackdex_prepare` (`blackdexApkPath`).
+3. BlackDex UI에서 대상 앱 덤프.
+4. `blackdex_pull` (`targetPkg`).
+5. `dex_to_smali` 후 `smali_*`.
+
+### 3. 루팅 (Frida)
+
+1. 루팅된 기기, `adb` 사용 가능.
+2. `frida_prepare`로 `frida-server` 실행.
+3. 호스트 `frida` / `frida-dexdump` 버전 맞춤 (권장 16.x).
+4. `frida_unpack` (`spawn: true`, `deepSearch: true` 권장).
+5. `dex_to_smali` 후 분석.
+
+Frida 17 실패 시 16.x로 맞추세요. 일부 기기는 임시 `setenforce 0`.
+
+### 4. smali 분석 예
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## 디렉터리 구조
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+---
+
+## 디컴파일 예제
+
+[`examples/`](./examples/) 참고 (smali는 zip):
+
+| 예제 | 경로 | 내용 |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`info.cd120.two`) |
+
+압축 해제 후 `smali_*` 실행.
+
+---
+
+## MCP 도구 치트시트
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+
+---
+
+## FAQ
+
+**Q: `list_devices`가 비어 있음?**  
+USB 디버깅/`adb devices` 확인, 다중 기기는 `serial`.
+
+**Q: 정적 후 비즈니스 클래스 없음?**  
+패커 가능성 → BlackDex/Frida.
+
+**Q: `dex_to_smali` 실패?**  
+Java와 baksmali jar/`BAKSMALI_JAR` 확인.
+
+**Q: Frida jailed / 버전 불일치?**  
+`frida-server`와 호스트 `frida` 메이저 버전 일치.
+
+**Q: 출력 위치?**  
+기본 `unpack-output/`. **Git에 커밋하지 마세요.**
+
+---
+
+## 법적 고지 및 면책
+
+본 프로젝트는 **학습·교육 및 승인된 보안 연구 전용**입니다. 무단 접근, 크래킹, 불법 복제, 시스템 공격, 지식재산권 침해 등 일체의 불법 행위에 사용하는 것을 엄격히 금지합니다. 오남용에 대해 저자와 기여자는 책임지지 않습니다. 사용 시 본 조건에 동의한 것으로 간주합니다.
+
+> ⚠️ **학습 및 교육 목적으로만 사용하세요.** 불법 행위, 무단 크래킹, 저작권 침해, 제3자 보호 우회에 사용하지 마십시오. 현지 법령과 대상 앱 약관을 준수해야 하며, 오남용 책임은 사용자에게 있습니다.
+
+---
+
+## License
+
+MIT — [`LICENSE`](./LICENSE) 참고.