lab-401/icopy-x

# iCopy-X 打开 iCopy-X RFID 克隆设备的开源版本。 ## 这是什么： - 可用：iCopy-X 设备的**完整**重建。包含所有设备功能。 - 越狱：无需单独构建 IPK 即可安装 - 最新：运行**最新版 iceman 固件** - 灵活：完整的插件系统 + 简化的基于 JSON 的 UI 系统 ## 这不是什么： - 它并非基于原作者的知识产权构建。所有代码均从零开始编写。 - 它（可能）并非完全没有 Bug。这是一项庞大的工程。尽管进行了数千次 UI、功能和回归测试，仍难免有疏漏。 - 它不可用于商业用途。本软件不能在商业环境中使用。详情请参阅 LICENCE。 ## 有哪些新特性？ - 完全访问所有内容！ - 插件架构 - 允许仅通过 JSON 构建能与 proxmark 或 linux 子系统交互的 UI 应用程序。还允许使用“全屏”模式运行其他二进制文件（例如 DOOM） - 屏幕镜像：允许通过 USB 将屏幕流式传输到设备。不能与 PC-Mode 同时使用：在设置中禁用/启用。 # 安装说明 有**两种版本**可供选择："No Flash" 和 "Flash"。 - **"No Flash"**：完整的开源系统，但不会改动您 iCopy-X 的 proxmark 模块。您可以轻松地在出厂/原生中间件之间来回切换。但是，您将受限于大约 2022 年的 proxmark 客户端和固件。 - **"Flash"**：完整的开源系统，运行最新的 iceman 固件 + 客户端。安装 IPK 后，系统会提示您进行刷机。刷机**不会触及 bootloader** - 您的设备不会变砖。同样，iCopy-X 具有从软砖状态恢复的保护机制。 安装很简单： 0. 确保您的设备已更新至最新版本 (1.0.90 - 可从此处获取：https://icopyx.com/pages/update-your-icopy-x) 1. 下载您选择的 IPK 2. 将您的 iCopy-X 置于 PC-Mode 3. 删除设备中的所有其他 IPK 文件 4. 将 IPK 传输到您的设备并关闭 PC-Mode 5. 导航至 关于 > 更新，然后按 [OK] 6. 设备将重启 7. 重启期间，屏幕会闪烁并保持黑屏最多 10 秒。不要惊慌！ 如果您使用的是 "flash" 版本，将有一些额外的步骤： 7. 设备将重启并检测到您需要刷机。点击 OK。 8. 阅读说明：确保您的设备已充电，确保已接通电源，然后点击 开始 9. 刷机后，您的设备将重启。 10. 重启期间，屏幕最多会黑屏 10 秒。不要惊慌！ ## 我已经安装了 - 看起来一切都一样 此次升级旨在实现视觉和功能上的无缝衔接。 判断更新是否成功的一个好方法是，检查您的电池指示灯是否变为彩色，或者是否在菜单中看到了“插件”选项。 ## 插件没有（实用的）作用。 这些插件是为开发者设计的示例：如何使用 JSON UI 框架，如何向 proxmark 发送命令，如何链接屏幕等。 试试 DOOM，这是一个“能正常运行”的插件。 ## 配套 PM3 客户端（用于 PC-Mode） 当您的 iCopy-X 处于 "PC-Mode" 时，您可以直接从计算机连接到 iCopy-X 的 Proxmark 模块。 每个版本都包含多平台二进制文件，编译后与您设备的版本相匹配： - `clients-noflash.zip`：包含适用于 "factory firmware" / "no flash" 版本的 Windows、Linux 和 macOS 客户端 - `clients-flash.zip`：包含适用于最新 iceman / "flash" 版本的 Windows、Linux 和 macOS 客户端。 ### 使用配套客户端 1. 下载与您的 IPK 版本匹配的 `clients-[flash|noflash].zip` 2. 解压到您电脑上的一个文件夹中 3. 将您的 iCopy-X 置于 PC-Mode 4. 通过 USB 连接 5. 运行：`proxmark3 /dev/ttyACM0` (Linux/macOS) 或 `proxmark3.exe COMx` (Windows) 请根据分配给您 iCopy-X 的实际端口调整 `ttyACM0` 和 `COMx`。 ## 屏幕镜像？ 1. 在您的设备上，进入“设置”并启用“屏幕镜像” 2. 重启您的 iCopy-X（__非常重要__） 在您的电脑上： 1. 从代码库中获取 `tools/screen_mirror/` 工具。 2. 运行：`python -m pip install -r requirements.txt` 3. 然后：`python mirror_client.py` 一切应该就能正常工作了。 # 技术细节 ## 原因 iCopy-X 的最后一次官方更新是在 2022 年。如果没有更新，对许多用户来说，该设备不过是一个昂贵的镇纸。 将设备开源为一款功能强大、制作精良的便携式 RFID 工具注入了新的生命。 ## 方式 超过 350 小时的工作。一个 48 核、96GB 内存的 QEMU 测试环境。 该项目实际上是一对多，包含多个子项目，每一个都同样复杂和耗时。 - 可靠的越狱 + 概念验证 - 映射与测试：为每个功能、直到叶节点的每个逻辑分支构建详尽的测试 - 替换 UI 层，根据测试迭代直到完成 - 构建中间件，根据测试迭代直到完成 - 增加对 iceman fork 的支持（需要稳定的升级和刷机机制） - 重建中间件以匹配 iceman fork（或者具体来说，是一个兼容层） ## 很好，但具体是怎么做到的？ 经过多次 PoC、尝试和失败的迭代，获胜的策略是 TDD - 测试驱动设计。 尽管极其复杂，iCopy-X 具有非常明确的输入和输出 - 这是 TDD 的核心。 基于 UI 和可能的 proxmark 结果，推导出了整个逻辑树。 iCopy-X 在 QEMU 中被完全模拟，并针对每个功能构建了详尽的“流程”测试。这些分支是通过构建数千个模拟 RFID 夹具来触发的，这些夹具会触发 Proxmark 的行为。 一旦测试正常运行，UI 层就构建完成并针对模拟流程进行了测试。 当 UI 功能正常后，中间件就被一个流程接一个流程地构建出来。 当所有流程都通过了测试，就开始了真机测试，采集了数千条轨迹以替换模拟行为并确认真实行为。 这个过程在所有阶段重复进行：原型设计、"no flash"，以及最后的 "flash" 版本。 Github CI/CD 流水线和工具在这个过程中不断演进，使得任何人都可以编译，而无需在本地构建环境。 ## 开发者？ https://github.com/quantum-x 来自 https://www.lab401.com ## 我刷机了但不喜欢，想恢复到原生状态... ### 通过 UI 将出厂的 pm3 固件镜像（可在原始 .IPK 存档中找到：`res/firmware/pm3/fullimage.elf`）放入 "flash" 版本的 `res/firmware/pm3` 文件夹中。复制到您的设备，安装并刷机。然后，在您的设备上安装 "noflash.ipk"。__或者__ ### 通过 SSH 1. 通过 SSH 连接到您的设备（您需要 USB-C 以太网转换器/集线器）：登录名：root/fa 2. 将出厂的 pm3 固件镜像（可在原始 .IPK 存档中找到：`res/firmware/pm3/fullimage.elf`）传输到 icopy-x。 3. `systemctl stop icopy` 4. `/home/pi/ipk_app_main/pm3/proxmark3 /dev/ttyACM0 --flash --force --image /path/to/fullimage.elf` 5. 重启您的设备，安装 "noflash.ipk" ### 通过 PC-Mode 1. 将您的 iCopy-X 置于 PC-Mode 2. 使用最新的 proxmark3 客户端刷机：proxmark3 /dev/ttyACM0 --flash --force --image fullimage.elf ## 这能解决“启动超时”问题吗？ 不能直接解决。“启动超时”意味着 GD32（控制硬件的微控制器）没有收到将屏幕移交给 Linux 设备/UI 的信号。有多种原因可能导致此问题 - 但最快的解决方案是：重刷 microSD 卡。 请参阅以下页面获取更多信息以及用于重刷 microSD 的出厂镜像！ https://lab401.com/blogs/academy/icopy-xs-fixing-the-boot-timeout-problem 一旦您的设备重刷完成并能正常启动，您就可以应用开源的 IPK 了。 ## 已知问题 - 仅在 iCopy-XS 上进行了测试 - 其他版本 __可能__ 可以与 no-flash 版本兼容。 - 通过外部模块的 iClass SE/SEOS：未集成，标记为非关键 - 外部 Auto-Hardnested UI 工具：超出了范围，标记为非关键 - 在 iceman 固件上，某些特定芯片组存在问题。这些并未被模块检测到 - 这是一个 PM3 的问题（或者是我们的测试夹具存在问题） - GproxII - NexWatch - IDTek - Noralsy - 原始 iCopy-X Gen1a 标签似乎无法检测到。__这不是一个 Bug！__ 令人好奇的是，由于某种原因 - 在 iceman 的版本中，设备的读取距离得到了增强。您可能需要在设备上方留出最多 2cm 的间距才能稳定读取！任何靠得更近的物体都会使读卡器/标签过度饱和。 - "Flash" 版本是直接从 iceman 仓库最新标记的发布版本构建的。如果更新更改了命令语法或响应，这将破坏 iCopy-X 设备上的功能。我们的目标是让设备运行在最新的 iceman 上。这里有完整的 CI/CD 构建流水线，允许您混合匹配您自己的 proxmark 版本。然而，将 iCopy-X 的兼容层映射到 iceman 仓库的变更则取决于社区。 - "Flow Tests"（流程测试）- 本项目的基石 - 在官方发布时尚未通过。在项目与原始中间件实现 1:1 对等之后，这些测试就被解耦了。在理想情况下 - 应该让它们能够正常运行（同时也应该让它们能够模拟 iceman 固件+客户端的响应）。它们是确保整个代码库稳定性的绝佳工具。 ## 免责声明 iCopy-X 有多个硬件版本。 测试是针对第一个版本进行的，但应该适用于所有版本。 ## 等等！有一个 .so 文件！你说过没有闭源代码的！ 这是越狱程序 - 原生固件需要一个有效的 `version.so` 来处理 IPK。 # 下一步计划 本项目的目标是开源 iCopy-X。未来的维护超出了原项目的范围，但我们希望社区能够认识到该项目的价值并让它保持活力！ 一些建议如下： - 将 iceman 仓库中 4 年多积累的函数、标签类型和进展整合到 UI 中 - 整合新的魔术卡 # 许可证 本代码在 PolyForm Noncommercial License 1.0.0 下分发。 为什么选择这个许可证？当我们与原制造商讨论开源时，他们担心被仿制。出于对他们为 iCopy-X 投入的真正令人难以置信的辛勤工作的尊重 - 我们不希望成为仿制者的渠道。 本代码面向渗透测试人员和 RFID 爱好者。其目的是打开一个封闭的设备以推动发展并促进社区演进 - 而非为了盈利。 如果您计划出售该代码，出售包含该代码的 SD 卡，或将该代码及其衍生作品嵌入到设备中并出售该设备：这是不被允许的。

标签：Homebrew安装, Iceman固件, iCopy-X, IPK包, JSON UI, Proxmark, RFID, RFID克隆, UI界面, 卡片克隆, 固件, 屏幕镜像, 嵌入式开发, 开源固件, 开源硬件, 无线电安全, 硬件设备, 硬件黑客, 越狱, 身份验证强制, 逆向工具, 门禁安全