A Python toolkit for parsing and editing IMEI records and WiFi/Bluetooth addresses stored in MediaTek NVRAM files and partition images, aimed at device-repair and firmware-research work on hardware you own.
| Tool | alltechdev/mtk-imei-switcheroo — Python tooling for reading and writing IMEI and WiFi/Bluetooth address records in MediaTek NVRAM files and partition images |
| Category | Mobile firmware analysis and repair tooling (Python 3.6+, GPL-3.0) |
| Primary Use | Inspecting and restoring device identity records (IMEI, WIFI, BT_Addr) from NVRAM dumps or partition images, plus live patching via ADB on rooted devices you own |
| Safe Use | Intended for authorized device repair, restoration of legitimate factory identifiers, and firmware research in lab environments on hardware the operator owns; altering identifiers on networks or devices you do not own may violate law and carrier policy |
| Telemetry Note | Offline operation leaves no device footprint; live scripts interact through ADB shell, pull and push records, and offer a reboot, all visible in device logs and adb history |
mtk-imei-switcheroo is a compact Python toolkit, licensed under GPL-3.0 and hosted at alltechdev/mtk-imei-switcheroo, that gives operators direct read and write access to identity records inside MediaTek NVRAM files and raw partition images. The records in question are the IMEI entries and the WIFI and BT_Addr MAC-like identifiers that Android devices persist in modem-partition data structures. Rather than treating these blobs as opaque hex, the toolkit parses the record layout so an operator can audit, back up, and — where authorized — restore identifiers on hardware they own. The framing throughout the README is device repair and firmware research, with firmware images, partition dumps, and private keys deliberately excluded from the repository itself.
Architecturally the project is split into two modes: offline file manipulation and live device patching. The offline path is carried by tools/nvram/imei_tool.py and tools/nvram/mac_tool.py, which accept either individual record files such as LD0B_001 or full supported partition images like nvdata.img. The live path consists of tools/nvram/live_patch.sh and tools/nvram/live_patch_mac.sh, interactive ADB wrappers for rooted devices that pull the relevant records, prompt the operator for values, push the patched files back, and offer a reboot. This separation is sensible engineering: the parsing logic can be exercised on dumps without touching a handset, and the device-touching logic is isolated behind small shell wrappers.
The dependency footprint is modest and tells you something about the internals. The NVRAM tools need Python 3.6+, and IMEI operations specifically pull in pycryptodome, which strongly suggests the IMEI records are stored encrypted or checksum-protected in a way that requires symmetric crypto to rewrite coherently. WiFi and Bluetooth address operations, by contrast, use only the standard library, implying those records are plain structured fields with no cryptographic wrapping. The live scripts additionally require a working ADB setup and a rooted device, which is a hard boundary that keeps the toolkit out of casual misuse territory on stock consumer handsets.
The command surface is a conventional read/write verb model executed from the repository root. python3 tools/nvram/imei_tool.py read LD0B_001 dumps the parsed record; the write verb takes a target record, a new value, an output file via -o, and a -s slot selector where -s 2 addresses the second SIM on dual-SIM hardware. The MAC tool mirrors this: mac_tool.py read WIFI inspects the WiFi record, and write WIFI --wifi 02:11:22:33:44:66 or write BT_Addr --bt 02:11:22:33:44:55 produce patched outputs. The guides referenced in the README cover detection rules, duplicate record handling, backups, and error handling, which indicates the author has thought through the failure modes that bite people doing partition surgery.
One detail in the README deserves particular attention from anyone doing Android 12+ device work: the toolkit explicitly documents that modern Android caches the factory WiFi MAC address, and that the live MAC script updates that cache while a purely offline partition edit does not. This is the kind of gap that makes an offline patch appear to succeed while the running OS continues reporting the old address, and the author links dedicated writeups under docs/guides/live_patch_mac.md and docs/devices/tiq_m5_live_mac.md. The same section notes that Android's per-network MAC randomization can obscure the true device address, which matters when you are trying to verify what a patch actually accomplished.
The verification matrix in the README is unusually honest about evidentiary quality. Three devices — F21 Pro, F25, and TIQ M5 — have recorded hardware-level verification for the IMEI and WiFi/BT flows, with F25 partially confirmed through a Java port of the toolkit rather than direct testing. For the biloba firmware track, V12 modem plus the supplied LK is reported working as a paired patch, though a modem-only patch bootlooped; V13 and V14 have passed offline checks only, with no hardware result reported. The author explicitly distinguishes direct tests from external reports from offline checks, and warns that shared chipset identity does not establish compatibility — a caveat that anyone considering applying these tools to new hardware should take literally.
The biloba component is the most research-flavored part of the repository. Instead of the generic NVRAM tools, it ships separate, version-specific Python patchers for exact modem and LK firmware pairs, organized under firmware/biloba/ with a reproduction runner, and supported by research/biloba/ holding analysis helpers, execution harnesses, and saved evidence. The README notes that biloba adds a signed critical-data check that the NVRAM tools do not implement, meaning the firmware patchers handle verification the generic tools deliberately avoid. The full verification workflow carries its own dependency list under docs/biloba/reproduce.md, keeping the main install light.
Repository hygiene is solid for a tool of this type. tools/nvram/ holds the offline tools and live scripts, docs/ carries guides, format documentation, and per-device findings, firmware/biloba/ and research/biloba/ isolate the vendor-specific work, and tests/ contains NVRAM regression drivers and repository checks. The tmp/ and runs/ directories are gitignored holding pens for local samples, backups, and generated results, which reinforces the point that no firmware images ship with the code. At roughly 27 stars and written in Python, this is a niche specialist tool rather than a general-purpose framework, and its value lies in the documented record-format knowledge more than in raw popularity.
From a defensive and forensic perspective, this toolkit is useful in the other direction: it is a clean reference implementation for how MediaTek stores IMEI and radio identifiers in NVRAM, which is directly relevant to analysts examining seized or triaged handsets, validating whether identity records have been tampered with, or understanding what a partition dump actually contains. The README's notes on cached WiFi MACs and randomized per-network addresses are equally valuable to forensic examiners trying to reconcile what the OS reports against what the hardware persists.
The legal dimension cannot be waved away. IMEI manipulation is criminalized in many jurisdictions, particularly where it facilitates evading network blacklists, and the toolkit's legitimate niche — restoring a device's own factory identifiers after legitimate board repair, or research on owned hardware — is narrow. The repo's own posture is consistent with that: no firmware images, no dumps, no keys, root required for live work, and extensive documentation about verification rather than shortcuts. Professionals using it should confine themselves to owned devices, repair bench contexts, and lab research, and treat carrier-reporting obligations seriously.
Installation follows the standard clone-and-pip pattern: git clone https://github.com/alltechdev/mtk-imei-switcheroo followed by python3 -m pip install -r requirements.txt from the repository root. There is also a community Android app port of the toolkit linked in the README's related section, which brings the same record operations onto the handset itself, though the main repository remains the reference implementation. For firmware researchers, repair technicians, and mobile forensic analysts working on authorized hardware, mtk-imei-switcheroo offers unusually well-documented access to a data structure that is otherwise buried in vendor obscurity.
alltechdev/mtk-imei-switcheroo.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.