Rango

Chameleon Ultra AI 副驾驶 — 通过自然语言读取、破解、转储、分析、模拟和克隆 RFID 卡片，并配有安全门控与主机端卡片库。

前置要求 · 快速开始 · 从 Codex、Claude Code、OpenCode 使用 · MCP 工具 · 卡片覆盖 · 开发

Chameleon Ultra — 图片 © RfidResearchGroup

Rango 将 Chameleon Ultra 变成一个由 agent 驱动的 RFID 副驾驶。它只是 AI 层：官方 Chameleon Ultra CLI 不会被内置到本仓库中——请单独克隆；Rango 会找到它并在本进程内驱动它 （参见前置要求）。

两种使用方式：

1. Kimi Code 插件（体验最佳）—— 一个 MCP 服务器 + skill + 分析子代理； 由 Kimi Code agent 替你操作设备。

2. 独立 AI Shell —— 在原生 CLI 之上增强的 REPL 环境； 输入 ? 即与 LLM（Moonshot/Kimi API 或任意兼容 OpenAI 的接口）对话。

架构

flowchart LR
    U(["You — natural language"]) --> A["Agent harness<br/>Kimi Code · Claude Code · Codex · OpenCode"]
    SK["SKILL.md<br/>workflows · safety gates · coaching"] -. guides .-> A
    A -->|"MCP over stdio"| M["chameleon MCP server<br/>16 tools · one persistent serial owner"]
    M --> S["ai_shell<br/>bridge · ops · library · dictionaries · analyze"]
    S --> C["official Chameleon Ultra CLI<br/>fetched · unmodified · not vendored"]
    C -->|"USB serial"| D(["Chameleon Ultra"])

Related MCP server: MCP-Edge

前置要求

git clone https://github.com/fedroraddict/rango rango && cd rango

scripts/install-cli.sh   # fetches the stock upstream CLI into ../ChameleonUltra
                         # (git clone, with a codeload tarball fallback when
                         #  github.com is unreachable)
uv sync
scripts/setup-plugin.sh  # writes plugin/.rango-root so the MCP launcher still
                         # finds this repo after /plugins install copies plugin/

安装脚本是幂等的，并会打印它的执行动作。如果你想保留其他目录中的上游检出， 请传入路径（scripts/install-cli.sh /path/to/ChameleonUltra）并设置 export CHAMELEON_SOFTWARE=/path/to/ChameleonUltra/software。

需要 Python ≥ 3.10、uv，并通过支持数据传输的 USB-C 线连接设备。

快速开始

# Standalone AI shell (stock CLI commands pass through; '? ...' asks the AI)
cd rango && uv run python -m ai_shell
#   needs MOONSHOT_API_KEY (or another OpenAI-compatible endpoint in
#   ~/.chameleon_ai/config.toml) for AI features; plain CLI works without it

# Kimi Code plugin
#   in Kimi Code: /plugins install <this-repo>/plugin   then  /reload

从 Codex、Claude Code、OpenCode 使用

MCP 服务器是标准 stdio 服务器——不仅限于 Kimi。各 harness 的配置片段和安装说明 位于 adapters/：Claude Code（.mcp.json / claude mcp add + 可直接放入的 skill 与 agent）、Codex CLI（[mcp_servers.chameleon]

• 去除 frontmatter 的 skill）、OpenCode（opencode.json + 转换后的 agent 文件）。

MCP tools (16)

副驾驶层带来的能力

• 预检仪式 — 工作流总是以 chameleon_state 开头；受安全门控的步骤会先预告。

• 检测引导 — 扫描失败时会给出卡片贴合的位置、HF/LF 换用、交叉确认建议——而不是静默地反复重试。

• 密钥恢复决策树 — 默认字典 → 从该门禁系统已知密钥的 web 搜索生成针对性字典 → hf mf autopwn → 手工 PRN 攻击（darkside 攻击 / nested / senested / hardnested，并提示预计耗时）→ 最后手段：mfkey32v2 reader 端恢复（hf mf elog --decrypt）。

• 库优先模式（与 CU GUI 的 Saved Cards 一致）：转储以用户命名的名字存入卡库；槽位只是工作内存。

• 槽位规范 — 先列出，优先空闲槽位，写入前先询问，总是命名，总是启用（(disabled) 槽位不会进行模拟），用 hw slot store 持久化。

• 协作模式 — copilot（每个受门控步骤都要确认）或 autopilot（一次同意所做声明的工作流）。hw dfu、hw factory_reset 以及物理写卡永远需要单独确认。

• 离线分析子代理（card-analyst）用于深度的 dump 分析。

卡片覆盖范围

请重写从 hf 开始的行：| **HF** | Mifare Classic (full attack suite) · Ultralight/NTAG (incl. ...。但用户要求逐字保留。so I should not skip. The row is longer and contains English terms. Need include full translated row. Remove accidental.

Let's focus on final output. Need avoid too long. The output should be provided. Now we can include the table rows properly.

Final full translation

Rango

Chameleon Ultra AI 副驾驶 — 通过自然语言读取、破解、转储、分析、模拟和克隆 RFID 卡片，并带有安全门控和主机端卡片库。

前置要求 · 快速开始 · 从 Codex、Claude Code、OpenCode 使用 · MCP 工具 · 卡片覆盖 · 开发

Chameleon Ultra — 图片 © RfidResearchGroup

Rango 将 Chameleon Ultra 变成一个由 agent 驱动的 RFID 副驾驶。它仅是 AI 层：官方 Chameleon Ultra CLI 不会被内置（vendored）进本仓库——请单独克隆；Rango 会定位并随着进程直接驱动它（见前置要求）。

两种使用方式：

1. Kimi Code 插件（体验最佳） — 一个 MCP 服务器 + skill 卡包 + 分析子代理；由 Kimi Code agent 帮你操作设备。

2. 独立 AI Shell — 在原生 CLI 之上增强的 REPL 交互，? 会和 LLM（Moonshot/Kimi API 或任意 OpenAI 兼容的 endpoint）对话。

架构

flowchart LR
    U(["You — natural language"]) --> A["Agent harness<br/>Kimi Code · Claude Code · Codex · OpenCode"]
    SK["SKILL.md<br/>workflows · safety gates · coaching"] -. guides .-> A
    A -->|"MCP over stdio"| M["chameleon MCP server<br/>16 tools · one persistent serial owner"]
    M --> S["ai_shell<br/>bridge · ops · library · dictionaries · analyze"]
    S --> C["official Chameleon Ultra CLI<br/>fetched · unmodified · not vendored"]
    C -->|"USB serial"| D(["Chameleon Ultra"])

前置要求

git clone https://github.com/fedroraddict/rango rango && cd rango

scripts/install-cli.sh   # fetches the stock upstream CLI into ../ChameleonUltra
                         # (git clone, with a codeload tarball fallback when
                         #  github.com is unreachable)
uv sync
scripts/setup-plugin.sh  # writes plugin/.rango-root so the MCP launcher still
                         # finds this repo after /plugins install copies plugin/

安装器是幂等的，并会打印它所做的操作。如果你把上游 checkout 放在其他位置，请传入该路径（scripts/install-cli.sh /path/to/ChameleonUltra），并设置 export CHAMELEON_SOFTWARE=/path/to/ChameleonUltra/software。

需要 Python ≥ 3.10、uv，以及使用支持数据的 USB-C 数据线连接设备。

快速开始

# Standalone AI shell (stock CLI commands pass through; '? ...' asks the AI)
cd rango && uv run python -m ai_shell
#   needs MOONSHOT_API_KEY (or another OpenAI-compatible endpoint in
#   ~/.chameleon_ai/config.toml) for AI features; plain CLI works without it

# Kimi Code plugin
#   in Kimi Code: /plugins install <this-repo>/plugin   then  /reload

从 Codex、Claude Code、OpenCode 使用

该 MCP 服务器是一个标准的 stdio 服务器——并不只是 Kimi 用。各 harness 的配置片段和安装说明见 adapters/：Claude Code（.mcp.json / claude mcp add + 可直接放入的 skill 与 agent）、Codex CLI（[mcp_servers.chameleon] + 去掉 frontmatter 的 skill）、OpenCode（opencode.json + 转换后的 agent 文件）。

MCP 工具（16）

副驾驶层额外提供的内容

• 预检仪式 — 工作流总是先用 chameleon_state 开始；受门控的步骤会先声明。

• 检测辅导 — 扫描失败时给出卡片放置建议、HF/LF 切换建议、app 交叉核对——而不是静默重试循环。

• 密钥恢复决策树 — 默认字典 → 基于对该卡系已知密钥的 Web 搜索构建目标字典 → hf mf autopwn → 手工 PRNG 攻击（darkside / nested / senested / hardnested，附预计耗时）→ 最后手段：mfkey32v2 读卡器端恢复（hf mf elog --decrypt）。

• 库优先模式 — 与 CU 打开器的 Saved Cards 设计一致：转储以你自己选择的名字存入库中；槽位只是工作内存。

• 槽位纪律 — 先 list，优先空槽，覆写前询问，每次都命名，每次都 enable（(disabled) 槽位不可模拟），用 hw slot store 持久化。

• 协作模式 — copilot（每个门控步骤都需确认）或 autopilot（一次批准已声明的工作流）。hw dfu、hw factory_reset 和物理卡写入始终需要单独确认。

• 离线分析 subagent（card-analyst）用于深层转储分析。

卡片兼容范围

已知细节（真机验证）

• 某些上游版本中 hf mf fchk --dic 是 no-op stub——要改用传入参数（所以有这个 dict_show）。

• 若在连接中杀掉占用端口进程，会出现串口失步（帧错误洪水 / 连接超时），解决办法：拔线重插设备，并先执行 hw disconnect 再重载插件插件。

• 某个槽位开始时如果是 (disabled)undef，加载后必须用 hw slot enable 启用力，否则不模拟。

• CLI 只按普通空白分词——永远不要给参数加引号（hw slot nick ... -n dog 而不是 -n "bike"，否则引号会被当成卡名的一部分），同时路径不要带空格。

开发

cd rango
uv run ruff check ai_shell/ plugin/mcp/          # lint
uv run python -m ai_shell.selfcheck            # cited commands exist in the real CLI tree,
                                               # gate semantics, simulated /plugins install boot
uv run python -m ai_shell.test_analyze         # dump-analyzer regression tests

CI 在每次 push 和 PR 上运行同样的三道门检（见 .github/workflows/ci.yml）。

项目结构：ai_shell/ 包裹库 · plugin/ Kimi Code 插件（见 plugin/README.md）· scripts/ 上游 CLI 安装 + 插件配置 · adapters/ 其他 harness 配置（见 adapters/README.md）· AGENTS.md 贡献者/agent 笔记。

致谢

所有设备侧能力 —— Chameleon Ultra 固件以及 Rango 驱动的官方 CLI —— 都来自 RfidResearchGroup/ChameleonUltra，© 它的作者（见其 AUTHORS.md）。Rango 只是上面的 AI 副驾层：它不包含上游代码，CLI 由 scripts/install-cli.sh 获取原样使用。

此外还站在：

• Proxmark3 社区 Rev —— 已知目标和 MAD 名册约定（mad.json 可直接放到 ~/.chameleon_ai/dicts/）；

• NXP 的 MF1S50YYX 数据手册 —— ai_shell/analyze.py 中的访问位和 value-block 解码表依照该手册；

• Model Context Protocol—— 所有受支持的智能体 harness 都使用这一接口；

• Kimi Code —— 插件格式和独立 shell 的默认 LLM endpoint。

License & 负责任使用

Rango 本身是 MIT 许可证。上游 Chameleon Ultra CLI 是单独的、基于 GPL-3.0 的项目（通过脚本拉取而不是内置），因此 GPL 管辖的是 CLI，而非本仓库。请只对你自己拥有或已明确授权测试的卡片和设备进行操作。