Rango

Chameleon Ultra AI Copilot — 자연어로 RFID 카드를 읽고, 크랙하고, 덤프하고, 분석하고, 에뮬레이션하고, 복제하는 AI 코파일럿입니다. 안전 게이트와 호스트 측 카드 라이브러리를 갖추고 있습니다.

전제 사항 · 빠른 시작 · 기타 하네스 · MCP 도구 · 카드 지원 범위 · 개발

Chameleon Ultra — 이미지 © RfidResearchGroup

Rango는 Chameleon Ultra를 에이전트 기반 RFID 코파일럿으로 만들어 줍니다. 이 저장소는 오직 AI 레이어만 포함합니다. 공식 Chameleon Ultra CLI는 이 저장소에 포함되어 있지 않으며, 별도로 클론해야 합니다. Rango는 해당 CLI를 찾아 프로세스 내(in-process)에서 구동합니다 (전제 사항 참고).

사용 방법은 두 가지입니다:

1. Kimi Code plugin (최상의 경험) — MCP 서버 + 스킬 + 분석 서브에이전트를 제공하며, Kimi Code 에이전트가 기기를 조작합니다.

2. Standalone AI shell — 기본 CLI를 감싼 향상된 REPL로, ?를 입력하면 LLM(Moonshot/Kimi API 또는 모든 OpenAI 호환 엔드포인트)과 대화할 수 있습니다.

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: MCP-Edge

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/

설치 스크립트는 멱등적이고 수행한 작업을 출력합니다. 업스트림 체크아웃을 다른 위치에 두었다면 경로를 전달(scripts/install-cli.sh /path/to/ChameleonUltra)하고 export CHAMELEON_SOFTWARE=/path/to/ChameleonUltra/software를 설정하세요.

Python ≥ 3.10, uv와 데이터 전송이 가능한 USB-C 케이블로 연결된 기기가 필요합니다.

Quick start

# 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

Use from 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 tools (16)

What the copilot layer adds

• Pre-flight ritual — 워크플로우는 chameleon_state로 시작하고, 게이트가 걸린 단계는 먼저 안내됩니다.

• Detection coaching — 스캔 실패 시 카드 위치 안내, HF/LF 전환, 앱 교차 확인을 유도합니다. 무음 재시도 루프를 돌지 않습니다.

• 키 복구 의사 결정 트리 — 기본 사전 → 카드 시스템의 알려진 키를 웹 검색하여 만든 대상 맞춤 사전 → hf mf autopwn → 수동 PRNG 공격(darkside / nested / senested / symoot, 예상 시간 포함) → 최후 수단: mfkey32v2 리더 측 복구(hf mf elog --decrypt).

• 라이브러리 우선 모델 (CU GUI의 Saved Cards 미러링) — 덤프는 사용자가 선택한 이름으로 라이브러리에 저장되고, 슬롯은 작업 메모리로 사용됩니다.

• 슬롯 규율 — 먼저 목록을 확인하고, 빈 슬롯을 우선하며, 덮어쓰기 전에 승인을 받은 후, 항상 이름을 붙이고, 항상 활성화((disabled) 슬롯은 에뮬레이션되지 않음)하고, hw slot store로 저장합니다.

• 협업 모드 — copilot (게이트된 단계 각각 확인) 또는 autopilot (명시된 워크플로우를 한 번 승인). hw dfu, hw factory_reset, 물리 카드 쓰기는 항상 별도로 확인을 받습니다.

• 오프라인 분석 서브에이전트 (card-analyst) — 고차 덤프 검사용.

Card coverage

알려진 결함 (하드웨어에서 확인됨)

• 일부 업스트림 빌드에서 hf an mf fchk --dic은 동작하지 않는 스텁이므로, 키를 위치 인자로 전달하세요(dict_show는 이 용도로 존재합니다).

• 직렬 동기화가 해제(프레임 오류의 물결 / 연결 시간 초과)되는 경우, 포트를 점유한 프로세스가 연결 중에 중지되었기 때문입니다. 기기를 뼈다가 다시 꽂고, 플러그인을 다시 로드하기 전에 hw disconnect를 실행하세요.

• (파트 0) 5. 슬롯이 계(disabled)undef 상태로 시작하면, 로드한 후 `hw 는 슬롯을 활성화 어떤 로드가 되지 않습니다.

• CLI는 일반 공백 둘레로 토큰을 나눕니다. 인자를 따옴표로 감싸면 안 됩니다(hw 슬롯 닉 ... -n 자전거가 아니라 -n "bike"로 쓰면 따옴표가 닉네임의 일부가 됩니다), 경로에는 공백을 넣지 마세요.

Development

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/S Chameleon Code 플러그인 (plugin/README.md 참고) · scripts/ upward CLI 설치 스크립트 + 플러그인 설정 · adapters/ 기타 하네스 구성 (adapters/README.md 참고) · AGENTS.md 기여자/에이전트 메모.

크레딧

기기와 관련된 모든 부분 — Chameleon Ultra 펌웨어와 Rango 변형 CLI — 은 것은 RfidResearchGroup/ChameleonUltra, © 저자 그룹 (그 저장소의 AUTHORS.md 참고). Rango는 그 위의 큼으로만 만들었습니다. Rango는 업스트림 코드를 포함하지 않으며, 이 원 리포지토리에서는 CLI가 안 받습니다. dist intended CLI는 scripts/install-cli.sh가 수정 없이 내려받은 것을 그대로 사용합니다.

또한 다음 프로젝트가 있습니다:

• the 대표단 — the key-store key & MAD AID 규약 (mad.json file in ~/.chameleon_ai/dicts/).

• NXP의 MF1S50YYX 데이터시트에서 제공한 액세스 동 등 ai_shell/analyze.py 값 구성 표를 모두 따릅니다;

• the Model Context Protocol — this는 모든 지원 에이전트 harness가 통신하는 인터페이스입니다;

• the Kimi Code platform — "standalone 알고리즘" shell의 기본 LLM 엔드포인트 및 플러그인 형식입니다.

License & responsible use

Rango 자체는 MIT 라이선스입니다. 업스트림 Chameleon Ultra CLI는 GPL-3.0 하의 별도 프로젝트입니다 — 안쪽이 아니라 외부 상용 다운로드되므로, 그 라이선스는 이 저장소가 아니라 CLI에 적용됩니다. 소유하거나 명시적으로 테스트 권한을 받은 카드와 기기에서만 작업하십시오.