Rango

ИИ-copilot для Chameleon Ultra — читает, взламывает, снимает дампы, анализирует, эмулирует и клонирует RFID-карты через естественный язык, с защитными барьерами и библиотекой карт на стороне хоста.

Предварительные требования · Быстрый старт · Прочие окружения · Инструменты MCP · Поддержка карт · Разработка

Chameleon Ultra — изображение © RfidResearchGroup

Rango превращает Chameleon Ultra в RFID-копilot под управлением агента. Это только ИИ-слой: официальный CLI Chameleon Ultra не вендорится в этом репозитории — клонируйте его отдельно; Rango находит и запускает его in-process (см. Предварительные требования).

Два способа использования:

1. Плагин Kimi Code (лучший опыт) — MCP-сервер + скилл + субагент анализа; агент Kimi Code сам управляет устройством за вас.

2. Автономная ИИ-оболочка — расширенная REPL-оболочка вокруг стандартного CLI, где ? обращается к 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"])

Related MCP server: agentic-hil

Предварительные требования

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/

Инсталлятор идемпотентен и печатает, что он сделал. Если вы держите upstream-чекаут в другом месте, передайте путь (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] + скилл со срезанным frontmatter), OpenCode (opencode.json + конвертированный файл агента).

Инструменты MCP (16)

Что добавляет уровень копilot

• Ритуал pre-flight — рабочие процессы начинаются с chameleon_state; защищённые шаги сначала анонсируются.

• Коучинг определения — при неудачных сканированиях — подсказки по размещению карты, переключение HF/LF, перекрёстная проверка в приложении — а не тихие циклы повторов.

• Дерево решений по восстановлению ключей — словарь по умолчанию → целевой словарь, построенный по веб-поиску известных ключей системы → hf mf autopwn → ручные PRNG-атаки (darkside / nested / senested / hardnested, с ожидаемой длительностью) → последний резерв: извлечение на стороне ридера через mfkey32v2 (hf mf elog --decrypt).

• Модель «сначала библиотека» (аналог Saved Cards в CU GUI): дампы получают выбранные пользователем имена в библиотеке; слоты — рабочая память.

• Дисциплина слотов — сначала список, предпочтение свободным слотам, спрашивать перед перезаписью, всегда имя, всегда включать ((disabled)-слоты не эмулируются), сохранять через hw slot store.

• Режимы сотрудничества — copilot (подтверждение каждого защищённого шага) или autopilot (одобрение описанного сценария один раз). hw dfu, hw factory_reset и запись на физические карты всегда получают отдельное подтверждение.

• Субагент офлайн-анализа (card-analyst) для глубокого разбора дампов.

Поддержка карт

Известные особенности (проверено на железе)

• hf mf fchk --dic в некоторых сборках upstream — заглушка no-op: передавайте ключи позиционно (для этого есть dict_show).

• Десинхронизация порта (шквал frame-errors / timeout соединения) случается, если процесс, держащий порт, убит на середине соединения — переподключите устройство, 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 (см. .github/workflows/ci.yml).

Структура: ai_shell/ — библиотека-обёртка · plugin/ — плагин Kimi Code (см. plugin/README.md) · scripts/ — установщик upstream CLI + настройка плагина · adapters/ — конфиги для других окружений (см. adapters/README.md) · AGENTS.md — заметки контрибьютора и агента.

Благодарности

Всё, что касается устройства — прошивка Chameleon Ultra и официальный CLI, которым управляет Rango, — пришла из RfidResearchGroup/ChameleonUltra, © её авторы (см. её AUTHORS.md). Rango — это только слой ИИ-копilot сверху: она не содержит upstream-кода, а CLI забирается скриптом scripts/install-cli.sh и используется без изменений.

Также на плечах:

• Proxmark3 community — конвенции известных ключей и MAD AID (mad.json можно положить в ~/.chameleon_ai/dicts/);

• даташита NXP MF1S50YYX — на него опираются таблицы декодирования access-bits и value-блоков в ai_shell/analyze.py;

• Model Protocol — интерфейс, по которому говорит каждое поддерживаемое агентное окружение;

• Kimi Code — формат плагина и стандартный LLM-эндпоинт для автономной оболочки.

Лицензия и ответственное использование

Сам Rango — MIT. Upstream CLI Chameleon Ultra — отдельный проект под GPL-3.0: скачивается, а не вендорится — его лицензия регулирует CLI, а не этот репозиторий. Работайте только с картами и устройствами, которые принадлежат вам или на тестирование которых вы имеете явное разрешение.