Rango

Chameleon Ultra AI Copilot — 自然言語で RFID カードの読み取り、クラック、ダンプ、解析、エミュレート、クローンができ、セーフティゲートとホスト側カードライブラリを備えた AI コパイロットです。

前提条件 · クイックスタート · 他のハーネス · MCP ツール · 対応カード · 開発

Chameleon Ultra — 画像 © RfidResearchGroup

Rango は、Chameleon Ultra をエージェント駆動の RFID コパイロットに変えます。Rango はあくまで AI レイヤーです。公式の Chameleon Ultra CLI はこのリポジトリに同梱されておらず、別途クローンする必要があります。Rango はその CLI を見つけ出し、プロセス内で操作します（前提条件 を参照）。

利用方法は次の 2 通りです。

1. Kimi Code プラグイン（最良の選択肢）— MCP サーバー + スキル + 分析サブエージェントを提供します。Kimi Code エージェントがあなたに代わってデバイスを操作します。

2. スタンドアロン AI シェル — 標準 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 専用ではありません。ハーネスごとの設定スニペットとインストール手順は adapters/ にあります。Claude Code は .mcp.json / claude mcp add に加えてドロップインのスキルとエージェント、Codex CLI は [mcp_servers.chameleon] に加えてフロントマターを除去したスキル、OpenCode は opencode.json に加えて変換済みのエージェントファイルを使用します。

MCP ツール (16)

コパイロット層が追加する機能

• フライト前チェック — ワークフローは chameleon_state から始まり、ゲート付きの手順は最初に知らされます。

• 検出のコーチング — スキャン失敗時には、配置のアドバイス、HF/LF の切替、アプリとのクロスチェックを促します。黙ってリトライを繰り返すことはしません。

• キー復元の判断ツリー — 既定の辞書 → 対象カードのシステムの既知キーを Web 検索して作ったターゲット辞書 → hf mf autopwn → 手動 PRNG 攻撃（darkside / nested / senested / hardnested、所要時間の目安付き） → 最後の手段としてリーダー側 mf mfkey32v2 復元（hf mf elog --decrypt）

• ライブラリ優先モデル（CU GUI の Saved Cards に対応）— ダンプにはユーザーが選んだ名前を付けてライブラリに保存。スロットは作業用メモリです。

• スロット運用の優先順位 — 一覧を確認してから空きスロットを優先し、上書き前に確認し、必ず名前を付け、必ず有効化し（(disabled) スロットはエミュレートされない）、hw slot store で永続化します。

• コラボレーションモード — コパイロット（ゲート付きの各手順を確認）か オートパイロット（明示したワークフローを 1 回だけ承認）。hw dfu、hw factory_reset、実カード書き込みは常に個別確認が必要です。

• オフライン分析サブエージェント（card-analyst）— ダンプの詳細調査用。

対応カード

既知の癖（実機で確認済み）

• hf mf fchk --dic は一部のアップストリームビルドでは何もしないスタブ。キーは位置引数で渡してください（dict_show はそのために使えます）。

• ポートを保持しているプロセスが接続中に kill されるとシリアル同期の乱れ（フレームエラーの続発／接続タイムアウト）が起こります。デバイスを抜き挿しし、プラグインを再読込みする前に hw disconnect を実行してください。

• (disabled)undef として表示されるスロットは、読み込み後に hw slot enable で有効化しないとエミュレートに使えません。

• CLI は空白のみで引数を分割します。引数を引用符で囲まないでください（hw slot nick ... -n bike とし、-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 で同じ 3 つのゲートを実行します（.github/workflows/ci.yml 参照）。

構成: ai_shell/ ラッパーライブラリ・plugin/ Kimi Code プラグイン（plugin/README.md 参照）・scripts/ アップストリーム CLI のインストーラとプラグインセットアップ・adapters/ 他ハーネスの設定（adapters/README.md 参照）・AGENTS.md コントリビューター／エージェント用メモ

クレジット

デバイス側のすべて — Chameleon Ultra ファームウェアと、Rango が操作する公式 CLI — は、 RfidResearchGroup/ChameleonUltra （© その作者。AUTHORS.md 参照）に由来します。Rango はその上に重ねる AI コパイロット層にすぎず、アップストリームのコードは含みません。CLI は scripts/install-cli.sh が取得し、変更されずに使用されます。

以下にも支えられています。

• Proxmark3 コミュニティ — 既知キーと MADV AID の規則（mad.json は ~/.chameleon_ai/dicts/ に置けます）。

• NXP の MF1S50YYX データシート — ai_shell/analyze.py 内のアクセスビットと 値ブロックの復号テーブルはそれに従います。

• Model Context Protocol — 対応するすべてのエージェントハーネスが話すインタフェース。

• Kimi Code — プラグイン形式と、スタンドアロンシェルでのデフォルト LLM エンドポイント。

ライセンスと責任ある使い方

Rango 自体は MIT ライセンスです。アップストリームの Chameleon Ultra CLI は GPL-3.0 のもとにリリースされる別プロジェクトで、取得したものであり同梱ではありません。そのためライセンスはこのリポジトリではなく CLI に適用されます。操作をするのは、自分の所有するカード・デバイス、または明示的にテストを許可されたものだけにしてください。