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.

• On Windows, you'll need to install Mediatek Drivers.

• 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.

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 (preliminary) TUI.

For using the CLI, read the documentation with all commands here

For using the crate, use the device API:

use std::fs::File;

use anyhow::Result;
use env_logger::Builder;
use penumbra::{Device, DeviceBuilder, find_mtk_port};
use tokio::io::{AsyncWriteExt, BufWriter};

#[tokio::main]
async fn main() -> Result<()> {
    env_logger::init();
    let da_path = std::path::Path::new("../DA_penangf.bin");
    let da_data = std::fs::read(da_path).expect("Failed to read DA file");

    println!("Searching for MTK port...");
    let mtk_port = loop {
        if let Some(port) = find_mtk_port().await {
            break port;
        }
    }

    println!("Found MTK port: {}", mtk_port.get_port_name());
    
    let mut device = DeviceBuilder::default()
        .with_mtk_port(mtk_port)
        .with_da_data(da_data)
        .build()?
    
    // Init the device (Handshake and populate dev info)
    dev.init().await?;
    
    let tgt_cfg = dev.dev_info.target_config().await;
    println!("SBC: {}", (tgt_cfg & 0x1) != 0);
    
    // This will enter DA mode. Seccfg unlock only works if the device can load extensions / is vulnerable
    device.set_seccfg_lock_state(LockFlag::Unlock).await

    // Ignore progress for now
    let mut progress = |_read: usize, _total: usize| {};

    let file = File::create("lk_a.bin").await?;
    let mut writer = BufWriter::new(file);

    let mut lk_a_data = device.read_partition("lk_a", &mut progress, &mut writer).await;
    
    writer.flush().await?;
    
    Ok(())
}

Penumbra is still in early development, thus it can break quite easily. If so, you can open an issue attaching debug logs.
To get debug logs, run antumbra with the -v flag. 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.

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

Core:

• Add UFS support
• Dynamically determine SEJ base (for more chipsets support)
• Build DA extensions from source
• Limit extensions only commands when exts are not added to avoid timeouts
• Add a way to restore state
• Clean up duplicated code
• Add support for BROM mode (and setup DRAM)
• Add support for DA SLA and preloader auth
• Add target config to Device Info (SBC, DAA and SLA)
• Improve support for preloader/brom only connection (for testing purposes with just preloader commands)
• Improve DA parsing and add DA patching

TUI:

• Add partition read and write (Add partition list next to the action list)
• Make code reusable (add components like a custom FileExplorer, selectable list...)
• Change logo with an animated waning crescent moon with blinking stars around
• Add a switch on the welcome screen to enable or disable logging (with selection for log level)

Documentation:

• Document XFlash protocol
• Improve Carbonara information

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

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

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

Part of the code in Penumbra is adapted from mtkclient. The code adapted from mtkclient is licensed under the GNU Public License v3 or later (GPL-3.0).

As for term 13 of the GPL-3.0 license, the GPL-3.0 components must comply the networking terms of the AGPL-3.0 license when used together.

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