Skip to content

Latest commit

 

History

History
executable file
·
257 lines (190 loc) · 9.6 KB

README.md

File metadata and controls

executable file
·
257 lines (190 loc) · 9.6 KB
Raw

zero_kernel

An advanced Android kernel builder with assets collection and Kali NetHunter support.

Contents

Important to Read

Important

- DISCLAIMER -

This kernel is made for educational purposes only.

I am not responsible for anything that may or may not happen to your device by installing any custom ROMs, kernels and/or any other forms of software.

Anything you do with this kernel and your device you do at your own risk. By using it, you take the responsibility upon yourself and in case of any issue you are not to blame me or other related contributors.

Note

- ROM artifacts in releases -

The contents of each release include ROM builds compatible with corresponding kernel builds. These ROM files are unmodified and mirrored from official sources.

This can be verified via the checksums, which should be identical to the ones presented on the ROM project's official web page.

You can always download the same ROM file from official sources if you'd like. The mirroring in this repository is only done due to the fact that some ROM projects remove their older builds once they become too outdated.

Description

The codebase of this project is an extensive build wrapper automating the entire Android kernel build process, starting from kernel source collection and ending with artifact packaging.

The key goal is to modify the kernel in such a way that enables unique features of Kali NetHunter — a ROM layer designed to add extended functionality for penetration testing in a mobile form factor.

The architecture of this wrapper is trying to be as modular as possible, making it a little easier to add support for new devices.

Kernel Features

The kernel has the following features:

  • Kali NetHunter support;
  • RTL8812/21AU + RTL8814AU + RTL8187 Wi-Fi drivers;
  • packet injection support for internal Wi-Fi chipset;
  • optional KernelSU support (v0.9.5, max compatible version for non-GKI kernels).

Supported Devices & ROMs

OnePlus 5/T

  • 4.4 Linux kernel version:

    • LineageOS;
    • ParanoidAndroid;
    • x_kernel supported (universal)*.

  • 4.14 Linux kernel version:

    • ParanoidAndroid (unofficial & testing);
    • x-ft_kernel supported (universal)**.

* -- this is mostly relevant to ROMs based on LineageOS; however, technically speaking, this includes ParanoidAndroid as well, which makes x_kernel-based builds universal.

** -- this, in theory, is relevant to all 4.14-based ROMs for this device in existence.

Usage

The custom build wrapper (aka "builder") consists of 2 core components and 3 primary commands:

Components:

  • kernel_builder;
  • assets_collector.

Commands:

  • kernel;
  • assets;
  • bundle.
$ uv run builder --help
usage: builder [-h] [--clean] {kernel,assets,bundle} ...

A custom builder for the zero_kernel.

positional arguments:
  {kernel,assets,bundle}
    kernel              build the kernel
    assets              collect assets
    bundle              build the kernel + collect assets

optional arguments:
  -h, --help            show this help message and exit
  --clean               clean the root directory

Prerequisites

It is highly recommended to use docker option to run this tool. For that you need Docker Engine or Docker Desktop, depending on your OS.

Warning

Because of how specific Linux kernel source is, building it on Windows even with Docker (using WSL2 back-end) might be challenging.

To run this tool in a local environment, you will need:

  • a Debian-based Linux distribution (other types of distros are untested);
  • a few packages installed in your system.

You will also need to install uv. Please refer to installation guide to choose an option fit for you. It is recommended to use pip to install the version of uv used in the project.

# making "builder" executable from source
export PYTHONPATH=$(pwd)
# installing uv via pip
python3 -m pip install -r requirement-uv.txt
# collecting project dependencies into a local .venv
uv sync --frozen --no-install-project

Kernel

Kernel build process can be launched using the kernel subcommand.

$ uv run builder kernel --help
usage: builder kernel [-h] --build-env {local,docker,podman} --base {los,pa,x,aosp}
                      --codename CODENAME --lkv LKV [-c] [--clean-image] [--ksu]

options:
  -h, --help            show this help message and exit
  --build-env {local,docker,podman}
                        select build environment
  --base {los,pa,x,aosp}
                        select a kernel base for the build
  --codename CODENAME   select device codename
  --lkv LKV             select Linux Kernel Version
  -c, --clean           don't build anything, only clean kernel directories
  --clean-image         remove Docker/Podman image from the host machine after
                        build
  --ksu                 add KernelSU support

Assets

As mentioned, there is also an asset downloader, which can collect latest versions of ROM, TWRP, Magisk and it's modules, Kali Chroot etc.

$ uv run builder assets --help
usage: builder assets [-h] --build-env {local,docker,podman} --base {los,pa,x,aosp}
                      --codename CODENAME --chroot {full,minimal} [--rom-only]
                      [--clean-image] [--clean] [--ksu]

options:
  -h, --help            show this help message and exit
  --build-env {local,docker,podman}
                        select build environment
  --base {los,pa,x,aosp}
                        select a kernel base for the build
  --codename CODENAME   select device codename
  --chroot {full,minimal}
                        select Kali chroot type
  --rom-only            download only the ROM as an asset
  --clean-image         remove Docker/Podman image from the host machine after
                        build
  --clean               autoclean 'assets' folder if it exists
  --ksu                 add KernelSU support
  --defconfig DEFCONFIG
                        specify path to custom defconfig

Bundle

The bundle command is a combined usage of kernel builder and assets collector core modules.

This is especially useful for linking the kernel build with the appropriate ROM build.

There are cases when an old kernel build is used with the newer ROM build. Such cases can ultimately lead to your system working improperly or breaking down completely, which is why it is important to use a specific kernel build with a corresponding ROM build.

Currently, there are three types of packaging available:

  • conan;
  • slim;
  • full.

Options full and conan collect all of the assets required to successfuly flash the kernel onto your device. The difference between the two is that full option places everything into a local directory, while conan organizes everything as a Conan package.

Option named slim is a much lighter version of full packaging, as only the ROM is collected from the asset list. This is done to reduce package sizes while ensuring the kernel+ROM compatibility.

$ uv run builder bundle --help
usage: builder bundle [-h] --build-env {local,docker,podman} --base {los,pa,x,aosp}
                      --codename CODENAME --lkv LKV --package-type
                      {conan,slim,full} [--conan-upload] [--clean-image] [--ksu]

options:
  -h, --help            show this help message and exit
  --build-env {local,docker,podman}
                        select build environment
  --base {los,pa,x,aosp}
                        select a kernel base for the build
  --codename CODENAME   select device codename
  --lkv LKV             select Linux Kernel Version
  --package-type {conan,slim,full}
                        select package type of the bundle
  --conan-upload        upload Conan packages to remote
  --clean-image         remove Docker/Podman image from the host machine after
                        build
  --ksu                 add KernelSU support

Examples

Here are some examples of commands:

(Recommended) Build kernel and collect ROM via Docker:

uv run builder bundle --build-env=docker --base=los --codename=dumpling --lkv=4.4 --package-type=slim

Build kernel locally:

uv run builder kernel --build-env=local --base=los --codename=dumpling --lkv=4.4

Collect all of the assets locally:

uv run builder assets --build-env=local --base=los --codename=dumpling --package-type=full

See also

Credits