# ecode_upgrade

**Repository Path**: wei-echo/ecode_upgrade

## Basic Information

- **Project Name**: ecode_upgrade
- **Description**: Ecode 易壳应用助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 易壳应用助手 软件说明书

---

## 一、软件概述

易壳应用助手是一款面向移动应用的安全保护类桌面软件，采用本地化离线运行模式，全部处理均在用户计算机本地完成。软件面向 Flutter、原生 Android 与原生 iOS 工程及其安装包，内置代码混淆、应用加固、重包检测三大独立功能模块：

| 模块码 | 功能模块 | 说明 |
|---|---|---|
| `o` | **代码混淆** | 对工程源码进行全量混淆与差异化注入，提升逆向分析难度 |
| `h` | **应用加固** | 对 APK / AAB / IPA 安装包实施运行时防护与防篡改 |
| `d` | **重包检测** | 对两款安装包进行多维相似度比对，用于识别马甲包及同源改包 |

所有处理均在用户本地计算机完成，工程源码与安装包不上传任何第三方服务；账号档案与知识库规则存于服务器（详见 `docs/server_asset_spec.md`），混淆配置与名称映射表仅保留在本地输出目录，不上传服务器。

### 1.1 适用对象

- 移动端开发者：对自身拥有合法权利的工程进行代码保护。
- 安全 / 运营人员：批量排查市场上疑似克隆、马甲应用。

### 1.2 运行依赖

- 桌面运行时：Flutter 3.x / Dart 3.x（Windows / macOS / Linux 桌面支持）。
- 原生桥接：Swift / Objective-C（macOS）、C++ / Win32（Windows）、C / GTK（Linux）原生交互；Java / Kotlin（Android 混淆引擎适配）。
- 第三方库：Riverpod（状态管理）、tree-sitter（`tree_sitter_language_pack`，AST 解析）、file_picker / desktop_drop（文件选择 / 拖拽）、window_manager（窗口管理）、path_provider（本地缓存目录）等。

---

## 二、软件运行环境

### 2.1 硬件环境

| 项目 | 要求 |
|---|---|
| 处理器 | x86_64 / ARM64 架构处理器（Apple Silicon、Intel、AMD 等） |
| 内存 | 8 GB 及以上 |
| 磁盘空间 | 可用空间 ≥ 500 MB（含依赖与构建缓存） |
| 显示 | 标准显示器，支持鼠标 / 触控板操作 |

### 2.2 软件环境

| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11、macOS 12.0（Monterey）及以上、或主流 Linux 发行版（如 Ubuntu 20.04+） |
| 运行框架 | Flutter 3.x 桌面运行时、Dart 3.x |
| 权限 | 读写用户选择的工程 / 安装包目录、访问网络（仅登录态下的账号同步与知识库拉取） |

---

## 三、软件安装与启动

1. 安装 Flutter 3.x 与 Dart 3.x 运行环境，并配置独立工具链路径（避免与系统 Flutter 冲突）。
2. 获取本软件源码后，于工程根目录恢复依赖：
   ```bash
   flutter pub get
   ```
3. 初始化桌面支持（首次；按需指定目标平台，可并列写 `windows,macos,linux`）：
   ```bash
   flutter create --platforms=windows,macos,linux .
   ```
4. 启动软件（任选目标平台）：
   ```bash
   flutter run -d windows      # Windows
   flutter run -d macos        # macOS
   flutter run -d linux        # Linux
   ```
5. 如需对外分发，构建安装包：
   ```bash
   flutter pub run dmg_build     # 生成 .dmg 安装包
   ```

---

## 四、软件总体架构

### 4.1 分层结构

```
┌──────────────────────────────────────────────────────┐
│                       UI 层                           │
│  HomePage(Tab) → [代码混淆] [应用加固] [重包检测]      │
│  + 顶部栏：Logo / 窗口控制 / LoginInfoWidget(登录)    │
└───────────────────────┬──────────────────────────────┘
                        │ Riverpod 状态
┌───────────────────────▼──────────────────────────────┐
│                  配置与账号层                          │
│  config_provider / auth_provider / navigation_provider │
│  （登录：手机号+密钥；服务器：账号档案与知识库）       │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│                 核心能力层                            │
│  ├─ 代码混淆 pipeline.dart（扫描→混淆→后处理）        │
│  ├─ 应用加固  hardening.dart（EngineFactory 分平台）   │
│  └─ 重包检测  dedup.dart（DedupRunner 多维评分）       │
└───┬───────────────┬───────────────┬─────────────────┘
    │               │               │
┌───▼───┐     ┌─────▼─────┐     ┌───▼─────┐
│ 引擎层 │     │ 资源引擎  │     │ Isolate │
│ Dart/  │     │ resource  │     │  worker │
│ Java/  │     │ _engine   │     │  pool   │
│ Kt/    │     │           │     │ (≤6)    │
│ Swift/ │     └───────────┘     └─────────┘
│ ObjC   │
└───────┘
```

### 4.2 主流程

```
启动 → 顶部 Tab 选择模块 →（可选）登录获取模块权限
   ├─ o 代码混淆：选择工程 → 配置 → 三阶段管道 → 结果弹窗
   ├─ h 应用加固：拖入安装包 → 勾选防护项 → 分平台引擎加固
   └─ d 重包检测：拖入 A/B 两包 → 多维比对 → 综合重复度 + 建议
```

### 4.3 模块权限门控

三个模块均受 `guardModule(context, ref, code)` 控制：未登录或无对应模块权限时，操作前弹出提示并拦截，保证授权可控。

---

## 五、功能模块一：代码混淆（模块码 `o`）

### 5.1 入口与界面

进入「代码混淆」Tab，主界面由 `ObfuscationPanel` 构成，含工程选择、项目类型、配置选项、处理日志与进度。

### 5.2 操作步骤

1. **选择工程**：点击「选择项目文件夹」，通过系统文件选择器定位本地工程根目录。
2. **选择项目类型**：在 Flutter / Android / iOS 之间切换；系统依据类型校验目录合法性
   - Flutter：需含 `pubspec.yaml`
   - Android：需含 `build.gradle` 或 `build.gradle.kts`
   - iOS：需含 `.xcworkspace` / `.xcodeproj` / `Podfile`
3. **填写混淆种子（Seed）**：必填；同种子 + 同配置可复现混淆结果。
4. **配置混淆项**（见 5.3），可「保存配置 / 加载配置」为 `ecode_config.json`（含 `projectType` 与 `config` 两部分）。
5. **开始混淆**：点击处理，界面实时展示阶段进度与日志。
6. **查看结果**：处理完成后弹出结果对话框，展示各平台统计、资源重命名数、混淆类数、差异化注入数据等，并提供产物目录入口。

### 5.3 配置项明细

| 分组 | 配置项 | 说明 |
|---|---|---|
| 模块开关 | `dartObfuscation` | 开启 Dart（Flutter）代码混淆 |
| 模块开关 | `nativeObfuscation` | 开启原生（Android/iOS）代码混淆 |
| 代码选项 | `obfuscateClassNames` | 类名混淆 |
| 代码选项 | `obfuscateEnums` | 枚举混淆 |
| 代码选项 | `encryptValues` | 字符串加密（`dd('...')` 运行时解密） |
| 代码选项 | `diffInjection` | 差异化注入垃圾类 / 方法 / 常量 |
| 代码选项 | `shuffleFunctions` | 函数顺序打乱 |
| 代码选项 | `cleanComments` | 清除注释 |
| 资源 | 资源混淆 | 图片元数据注入、音视频 / 字体脚标（解码无损） |

> 校验规则：开启 Dart / 原生混淆时，上述代码选项至少需选一项，否则拦截并提示。

### 5.4 处理流程（三阶段管道）

1. **扫描阶段**：`path_classifier` 将文件分类为 代码 / 资源 / 受保护 / 排除 四类；`project_layout` 判定工程类型；建立各端 AST。
2. **混淆阶段**：各端 Worker Isolate 并行重命名，并同步类名、import、资源路径、`pbxproj`、`AndroidManifest`、私有 `State` 等引用，保证编译通过；第三方 `package:` 导入不被改写；受保护文件走专用同步通道。
3. **后处理阶段**：仅执行与工程类型匹配的专属步骤（如 iOS 的 Xcode UUID 确定性刷新）；按平台生成解密辅助文件、垃圾类与 SDK 包装类；差异化注入按强度档位生成。

### 5.5 结果展示

结果弹窗按工程类型分别统计：各平台文件数、资源重命名数、混淆类数、差异化注入的类数与代码行数，并展示「生成垃圾类文件」「三方 SDK 插件混入」等模块数据。

---

## 六、功能模块二：应用加固（模块码 `h`）

### 6.1 入口与界面

进入「应用加固」Tab，左侧为防护选项分组，右侧为文件拖拽区、安全设置与加固日志。

### 6.2 支持的文件

- Android：`*.apk` / `*.aab`
- iOS：`*.ipa`
- 亦支持拖拽（desktop_drop）`.app` / `.dmg` / `.exe` 进行识别。

### 6.3 防护选项明细

**运行时检测（注入防护前哨）**

| 选项 | 说明 |
|---|---|
| 调试防护 | 检测调试器连接 |
| Root / 越狱防护 | 检测 Android Root 或 iOS 越狱 |
| 模拟器防护 | 检测 Build.MODEL 是否为模拟器 |
| Hook 检测 | 检测 Xposed / Substrate / Cydia |
| 代理检测 | 检测网络代理抓包工具 |
| 反内存 dump | 检测进程跟踪状态 |

**注入防护**

| 选项 | 说明 |
|---|---|
| Frida 防护 | 扫描 Frida 动态注入痕迹 |
| 动态加载检测 | 扫描可疑动态加载行为 |
| 反注入（IPA） | 检测进程环境变量，防动态库劫持 |
| 全 Activity 注入 | 在所有 Activity.onCreate 注入保护 |
| 垃圾类注入 | 注入 30–50 个无意义 smali 类 |
| .so 注入 | 注入空 .so 文件冒充 Native 保护 |

**安全防护**

| 选项 | 说明 |
|---|---|
| 完整性校验 | 生成 SHA-256 校验清单 |
| 签名校验 | 验证 APK / IPA 签名 |
| 防截屏检测 | 禁止截屏和屏幕录制 |

> 选项可用性随所选安装包平台自动过滤（如 iOS 专属项仅在 IPA 时可选）。

### 6.4 处理流程

拖入安装包 → 勾选防护项 → 点击「开始加固」→ `EngineFactory` 按文件类型创建对应平台引擎（Android 借助 apktool 操作 dex / 资源，iOS 操作 IPA 结构）→ 逐项注入防护 → 输出加固后安装包并记录日志。

---

## 七、功能模块三：重包检测（模块码 `d`）

### 7.1 入口与界面

进入「重包检测」Tab，左栏为双应用包选择与综合重复度评分卡，右栏为差异化建议面板。

### 7.2 双应用包选择

- 通过两个槽位（应用包 A / 应用包 B）拖拽或点击选择 `*.apk` / `*.aab` / `*.ipa`。
- 系统自动识别平台（Android / iOS）；若两包平台不一致，启动前弹出确认框（提示重复度将被判为 0、结果无意义）。

### 7.3 多维度相似度

检测在 14 个维度上分别计算重复度，加权融合为综合重复度：

| 维度 | 名称 | 维度 | 名称 |
|---|---|---|---|
| code | 代码 | metadata | 元数据 |
| layout | UI 布局 | icon | 图标 |
| resource | 资源 | string | 字符串 |
| sdk | SDK | tree | 文件树 |
| nativelib | 原生库 | cert | 签名 |
| dex | DEX（iOS 为 Mach-O） | size | 大小结构 |
| component | 组件 | permission | 权限 |

### 7.4 综合重复度与严重度

- 综合分以环形进度 + 大号百分比展示，并给出严重度判定：
  - ≥ 85：严重重复
  - ≥ 70：较高重复
  - ≥ 50：中等重复
  - < 50：较低重复
- 各维度以迷你进度条列出百分比，颜色随重复度由绿（低）到红（高）变化。

### 7.5 差异化建议

右栏「差异化建议」按维度给出可解读的排查建议（如代码层查重、UI 布局拓扑、资源文件重复、签名证书关联、SDK 版本检测等），检测完成后按严重度（critical / warning / info）着色，辅助判断是否为同源改包。

---

## 八、账号与服务器

- **登录方式**：顶部栏 `LoginInfoWidget` 提供手机号 + 密钥登录。
- **模块权限**：登录后由服务端下发可使用的模块码（`o` / `h` / `d`），未授权模块在操作时经 `guardModule` 拦截。
- **服务器账号档案**：登录后账号档案（含设备绑定 `allowedDevices`）经服务器（纯 Dart `CosHttpService`）读写，首次登录自动绑定当前设备；混淆配置与名称映射表仅保留在本地输出目录，不上传服务器，亦不支持跨设备恢复。

### 8.1 知识库前置（防破解情报）

三大模块运行所需的「规则 / 签名表」统称为**知识库**，外置于服务器，构成反破解设计的核心：

- **实时拉取**：登录成功后由客户端从 `assets/knowledge.json` 拉取进内存；该文件**不打包进软件二进制**（已移出资源打包），未登录的裸客户端无法获得这些规则数据，依赖它们的模块直接不可用。
- **未就绪即禁用**：未登录，或登录后拉取失败（网络异常 / 文件缺失）时，对应模块在点「开始」会提示「XXX 知识库未就绪，请先登录后重试」并拒绝执行，**绝不回退到旧写死常量**。
- **无本地缓存**：知识库仅约 9 KB，取消版本清单与本地加密缓存，每次登录状态直接拉取覆盖内存即可；跨 Isolate 的混淆 / 查重任务在启动时注入当前知识库，保证各端规则一致。
- 技术细节见配套文档 `docs/server_asset_spec.md`。

---

## 九、技术特点

1. **AST 优先**：优先基于 tree-sitter 抽象语法树做精准重命名；仅在无法获取 AST 时回退正则，确保标识符替换不误伤。
2. **引用同步**：类名、import、资源路径、`pbxproj`、`AndroidManifest`、私有 `State` 等引用统一随声明同步改写，保证编译通过。
3. **内部类同步**：嵌套类型（如 `Outer.Inner`）引用与声明同步混淆，避免 Unresolved reference。
4. **平台隔离与多端一致**：各端独立作用域，但词干映射一致，便于跨端维护与排错。
5. **资源类型感知**：资源引用替换按类型区分（如 Android `view id` 定义从不被重命名），防止同名非 id 资源被错误改写。
6. **确定性可复现**：seed 驱动的 Xcode UUID 刷新与词库选择，保证同配置可复现。
7. **并发加速**：基于 Dart Isolate 的 worker 池，最多 6 端同时混淆。
8. **多维查重**：重包检测在 14 个维度独立评分后加权融合，兼顾框架相似度与应用自身相似度。
9. **知识库外置防篡改**：混淆 / 加固 / 查重三大模块的规则与签名表外置于服务器，不打包进软件二进制；未登录或拉取失败则对应模块直接禁用，绝不回退旧写死常量，从数据层面提升反破解与防篡改能力。

---


*本说明书所述功能均基于 V1.80 实际实现，已申请计算机软件著作权。*