Rango

Chameleon Ultra KI-Copilot — liest, knackt, dumpt, analysiert, emuliert und klont RFID-Karten durch natürliche Sprache, mit Sicherheitsvorkehrungen und einer Host-seitigen Kartenbibliothek.

Voraussetzungen · Schnellstart · Verwendung mit Codex, Claude Code, OpenCode · MCP-Tools · Kartenabdeckung · Entwicklung

Chameleon Ultra — Bild © RfidResearchGroup

Rango verwandelt ein Chameleon Ultra in einen agentengesteuerten RFID-Copilot. Es ist nur die KI-Schicht: Die offizielle ChameleonUltra-ClI ist nicht in dieses Repository eingebunden — klone sie separat; Rango findet sie und steuert sie prozessintern (siehe Voraussetzungen).

Es gibt zwei Einsatzmöglichkeiten:

1. Kimi-Code-Plugin (beste Erfahrung) — ein MCP-Server + Skill + Analyse-Subagent; der Kimi Code-Agent bedient das Gerät für dich.

2. Eigenständige KI-Shell — eine erweiterte REPL um die Standard-CLI, bei der ? mit einem LLM spricht (Moonshot/Kimi-API oder ein beliebiger OpenAI-kompatibler Endpunkt).

Architecture

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: KadeMCP

Prerequisites

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/

Der Installer ist idempotent und gibt aus, was er ausgeführt hat. Wenn du deinen Upstream-Checkout woanders aufbewahrst, übergib den Pfad (scripts/install-cli.sh /path/to/ChameleonUltra) und setze export CHAMELEON_SOFTWARE=/path/to/ChameleonUltra/software.

Benötigt werden Python ≥ 3.10, uv sowie das Gerät an einem datenfähigen USB-C-Kabel.

Schnellstart

# 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

Verwendung mit Codex, Claude Code, OpenCode

Der MCP-Server ist ein Standard- Stdio-Server — nicht nur für Kimi. Konfigurationssnippets und Notizen pro Harn stehen in adapters/: Claude Code (.mcp.json / cladure mcp add + einsatzbereiter Skill und Agent), Codex CLI ([mcp_servers.chameleon] + Skill mit entferntem Frontmatter), OpenCode (opencode.json + konvertierte Agentdatei).

MCP-Tools (16)

Was die Copilot-Schicht zusätzlich bietet

• Pre-Flight-Ritual — Workflows beginnen mit chameleon_state; geschützte Schritte werden zuerst angekündigt.

• Erkennungs-Coaching — fehlgeschlagene Scans lösen Platzierungshinweise, HF/LF-Wechsel und App-Gegenprobe aus — keine stillen Retry-Schleifen.

• Entscheidungsbaum zur Schlüsselwiederherstellung — Standardwörterbuch → gezieltes Wörterbuch, erstellt aus einer Websuche nach bekannten Schlüsseln des Kartensystems → hf mf autopwn → manuelle PRNG-Angriffe (darkside / nested / senested / hardnested, mit erwarteten Extraerlauf) → letzte Option: strategy mfkey32v2 leser-seitige Wiederherstellung (hf mf elog --decrypt).

• Bibliothek-zuerst-Modell (entspricht den „Saved Cards“ der CU-GUI): Dumps erhalten in der Bibliothek Benutzernamen; Slots sind das Arbeitsgedächtnis.

• Slot-Disziplin — erst auflisten, freie Slots bevorzugen, vor dem Überschreiben fragen, immer benennen, immer aktivieren ((disabled)-Slots emulieren nicht), speichern mit hw slot save.

• Collaboration-Modi — Copilot (jeder geschützte Schritt wird bestätigt) oder Autopilot (ein einmaliges Genehmigen des festgelegten Workflows). hw dfu, hw factory_reset und das Schreiben auf physische Karten erfordern immer eine eigene Bestätigung.

• Offline-Analyse-Subagent (card-analyst) für die eingehende Dump-Analyse.

Kartenabdeckung

known eigenheiten (auf Hardware verifiziert)

• hf mf fchk --dic ist in manchen Upstream-Builds ein funktionsloser Platzhalter — die Schlüssel werden positionell übergeben (dict_show existiert dafür).

• Serielle Desync (Frame-Fehler-Flut / Verbindungs-Timeout) passiert, wenn der Prozess, der den Port geöffnet hat, mitten in der Verschlecht gelöst wird. Ziehe das Gerät ab und wieder an; hw disconnect vor dem Neuladen des Plugins.

• Ein anfangs (disabled)undef markierter Slot muss nach dem Laden mit hw slot enable aktiviert werden, sonst emuliert er nicht.

• Die CLI betont mit einer einfachen Leerzeichen-Trennung — Argumente niemals in Anführungszeichen setzen (hw mf slot ... -n bike, nicht -n "bike"), denn die Quotes werden Teil des Nick. Pfade ohne Leerzeichen halten.

Entwicklung

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

Die CI durchläuft bei jedem Push und jeder PR dieselben drei Prüfungen (siehe .github/workflows/ci.yml).

Aufbau: ai_shell/ Wrapper-Bibliothek · plugin/ Kimi-Code-Plugin (siehe plugin/README.md) · scripts/ Checkout-Installer + Plugin-Setup · adapters/ Configs für andere Harnesses (siehe adapters/README.md) · AGENTS.md Notizen für Leute und Agenten.

Mitwirkende (Credits)

Alles Geräteide — die Chameleon-Ultra-Firmware und die offizielle CLI, die Rango steuert — stammt aus RfidResearchGroup/ChameleonUltra, © deren Autoren (siehe copy AUTHORS.md). Rango ist nur die KI-Copilot-Schicht darüber: un enthalten sein keine Upstream-Code, und die CLI wird von scripts/install-cli.sh geladen und unverändert verwendet.

Er baute außerdem auf:

• der Proxmark3-Community — Konventionen für bekannte Schlüssel und MAD-AID (mad.json kann in ~/.chameleon_ai/dicts/ liegen);

• dem Datenblatt MF1S50YMX von NXP — die Decodier-Tabellen für Access-Bits und Wertblöcke in ai_shell/analyze.py folgen im;

• dem Model Context Protocol — der Schnittstelle, die jede unterstützte Agenten-Harness spricht;

• Kimi Code — dem Plugin-Format und der Standard-LLM-Endpunkt für die eigenständige Shell.

Lizenz und verantwortungvolle Nutzung

Rango selbst ist MIT-lizenziert. Die offizielle Chameleon-Ultra-CLI ist ein separates Gtd Projekts unter GPL-3.0 — sie werden geladen, nicht eingebettet — , therefore its license gGilt für die CLI, nicht für dieses Repository. Nutze/man bedienen nur Karten und Geräte, die dir die gehören oder für die dir zugestimmt zu testen.