penumbra

---

Penumbra is a Rust crate and tool for interacting with Mediatek devices.
It provides flashing and readback capabilities, as well as bootloader unlocking and relocking on vulnerable devices.

Features

• Flashing, readback and erase of partitions
• Support for both V5 (XFlash) and V6 (XML) devices
• CLI and a TUI
• Scatter file flashing

Furthermore, on vulnerable devices, the following features are also supported:

• Bootloader unlocking and relocking on vulnerable devices
• RPMB operations (read/write/erase, EMMC only for now)
• Arbitrary memory read/write
• …and more!

Requirements

• On Windows, you’ll need to install MediaTek VCOM drivers. For using linecode exploit (also known as Kamakiri2), you’ll need to install either libusb or WinUSB drivers with Zadig.
• On Linux you’ll need to install libudev and add your user to the dialout group. In case Penumbra doesn’t recognize the device, run with sudo or allow access to the device with udev rules.

For more details, check the installation guide.

Usage

Penumbra can be used both as a crate for interacting directly with a device with your own code, as well as providing a CLI and TUI.

For learning how to use the TUI, read the documentation here For using the CLI, read the documentation with all commands here

For using the crate, a brief introduction is provided in the crate documentation.

Debug logs

Some issues may be hard to reproduce, and may require more insight of what is happening on the device. If so, you can open an issue attaching debug logs.
To get debug logs, run antumbra with the -v and -l debug flags. A file called antumbra.log will be created in the current directory. This will also enable UART debug logging. If possible, attach UART logs too. If you don’t have UART, you can use the --usb-log flag in antumbra to enable DA logging over USB. A file called da.log will be created in the current directory with the logs.

[!NOTE] Penumbra currently supports both V5 (XFlash) and V6 (XML) devices. Issues reporting incompatibility with older (V3/Legacy) chipsets will be ignored until broader support is added. If your device falls in one of the supported protocols and you get the “unknown hardware code” warning, please open an issue attaching your device info, and relevant firmware files (preloader, DA, lk).

Contributing

For contributing, you’ll first need to setup a development environment.

Read on how to setup a dev environment and how to get started here

For contributing to the payloads, head to the payloads repository.

Current Roadmap

Core:

• Add V3 support
• Add amonet exploit

TUI:

• Refactor the TUI code to be more maintainable
• Add reusable components
• Make better key bindings

CLI:

• Add plstage
• Add Read Offset, Write Offset and Erase Offset commands
• Add register read/write commands

Documentation:

• Add documentation for the crate
• Add linecode exploit documentation

Learning Resources

Penumbra has its own documentation, where you can learn more about Mediatek devices and how the Download protocol works.

Other learning resources I suggest are the following

• mtkclient
• moto-experiments
• kaeru
• Carbonara exploit
• mtk-payloads
• da-boot
• fenrir
• sprig
• HeapB8 exploit technical writeup
• hacc

Credits

• ChimeraTool team - heapb8 was originally reverse-engineered from ChimeraTool.

License

Penumbra is licensed under the GNU Affero General Public License v3 or later (AGPL-3.0-or-later), see LICENSE for details.

Logo by @archaeopteryz, all rights reserved. Use is allowed only for referencing “Penumbra” or “Antumbra”, unless explicit permission has been granted.