lkpatcher
lkpatcher is a comprehensive Python tool and module designed for modifying and patching LK (Little Kernel) bootloader images. The utility offers flexibility along with an intuitive API for maximum control.
To use the library, Python 3.10 or higher is required. An alternative method is available via the web version, which is not open-source but offers the same functionality with a GUI.
Installation
sudo apt install python3-pip # If you don't have pip installed.
pip3 install --upgrade pip # If pip hasn't been updated yet.
pip3 install --upgrade git+https://github.com/R0rt1z2/lkpatcher
[!NOTE]
Windows users should omit the first two command(s) and install Python manually from here.
Basic Usage
python3 -m lkpatcher [-h] [options] bootloader_image
Command-line Options
Main Options:
-o, --output FILE Path to the output patched image
-c, --config FILE Path to configuration file (JSON)
-j, --json-patches FILE Path to JSON file with custom patches
Operational Modes:
-l, --list-partitions List all partitions in the bootloader image
-d, --dump-partition NAME Dump partition with NAME to a file
-i, --partition-info NAME Display detailed information about partition NAME
--analyze-policies Analyze security policies in the LK partition
--dry-run Perform a dry run without writing changes
--export-config FILE Export default configuration to FILE and exit
Patch Control:
--category CATEGORY Patch category to apply (can be used multiple times)
--exclude CATEGORY Patch category to exclude (can be used multiple times)
--patch-policies Patch security policies to disable verification
--cert-bypass [MODE] Re-sign a patched image with the cert bypass.
MODE is 'override' (default) or 'wrap'
Partition Management:
--add-partition NAME FILE Add new partition with NAME from FILE
--replace-partition NAME FILE Replace partition with NAME from FILE
--remove-partition NAME Remove partition with NAME
--add-certificate PART FILE Add certificate from FILE to partition PART
--partition-address ADDR Memory address for new or replaced partition (hex or decimal)
--partition-legacy Use legacy header format for new partitions
--cert-type TYPE Certificate type for --add-certificate (cert1, cert2)
Backup Options:
--backup Create a backup before patching
--backup-dir DIR Directory to store backups
Logging Options:
--log-level LEVEL Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
--log-file FILE Log to specified file in addition to console
Miscellaneous:
-v, --version Show version information and exit
-h, --help Show help message and exit
Examples:
# Basic patching with default settings
python3 -m lkpatcher lk.img
# Specify output file
python3 -m lkpatcher lk.img -o patched.img
# Use custom configuration and patches
python3 -m lkpatcher lk.img -c config.json -j patches.json
# List partitions in an image
python3 -m lkpatcher lk.img --list-partitions
# Dump a specific partition
python3 -m lkpatcher lk.img -d lk
# Apply only specific patch categories
python3 -m lkpatcher lk.img --category fastboot --category dm_verity
# Export default configuration
python3 -m lkpatcher --export-config config.json
# Analyze security policies
python3 -m lkpatcher lk.img --analyze-policies
# Add a new partition
python3 -m lkpatcher lk.img --add-partition custom data.bin --partition-address 0x41000000
# Replace an existing partition
python3 -m lkpatcher lk.img --replace-partition lk u-boot.bin --cert-bypass wrap
# Remove an existing partition
python3 -m lkpatcher lk.img --remove-partition unwanted
# Add certificate to a partition
python3 -m lkpatcher lk.img --add-certificate lk cert1.der --cert-type cert1
# Re-sign an already-patched image
python3 -m lkpatcher patched-lk.img --cert-bypass
# Same, but using the wrap strategy
python3 -m lkpatcher patched-lk.img --cert-bypass wrap
Using as a Library
You can use lkpatcher in your own projects:
from lkpatcher.patcher import LkPatcher
from lkpatcher.config import PatcherConfig
# Create a custom configuration (optional)
config = PatcherConfig()
config.log_level = "DEBUG"
config.backup = True
config.patch_categories = {"fastboot", "dm_verity"} # Only apply these categories
# Create the patcher object
patcher = LkPatcher(
image='lk.img',
patches='patches.json',
config=config
)
# List available partitions
partitions = patcher.image.get_partition_list()
print(f"Available partitions: {partitions}")
# Apply patches and save the result
output_path = patcher.patch(output='lk-patched.bin')
# Extract all partitions to a directory
patcher.extract_all_partitions("partitions_dir")
# Analyze the image
analysis = patcher.analyze_image()
print(analysis)
Patch Files
Patch files are JSON files containing categories of binary patches to apply. Each patch consists of a “needle” (bytes to find) and a “patch” (replacement bytes).
Example patch file:
{
"mode": "update",
"fastboot": {
"2de9f04fadf5ac5d": "00207047"
},
"dm_verity": {
"30b583b002ab0022": "00207047"
}
}
The mode can be:
update: Add/update patches while keeping defaults (default)replace: Replace all default patches with only those in the file
Configuration
You can customize behavior through a JSON configuration file:
{
"log_level": "INFO",
"backup": true,
"backup_dir": "./backups",
"verify_patch": true,
"allow_incomplete": true,
"dry_run": false,
"patch_categories": ["fastboot", "dm_verity"],
"exclude_categories": []
}
Important Notes
- To successfully boot patched images, unlock seccfg using mtkclient.
- Create backups of your existing images before patching. You are responsible for any damage to your device.
- If your device doesn’t boot after unlocking with mtkclient, it likely uses SBC and is not supported.
- For debugging issues, dump the
expdb partition with mtkclient and open a new issue with the dump attached.
- For device-specific patch requests, open a new issue with your LK image and the generated
image.txt file.
- To learn how these patches work and create your own, see the guide.
License
This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
评论