release: update KernelSU version, internal refactoring

Author: seppzer0

.dockerignore

@@ -2,7 +2,7 @@
 .vscode
 **/__pycache__
 
-# git subrepos (==submodules)
+# git subrepos
 android_*
 *_kernel_*
 clang*

.gitignore

@@ -3,7 +3,7 @@
 **/__pycache__
 .mypy_cache
 
-# git subrepos (==submodules)
+# git subrepos
 /android_*
 /*_kernel_*
 /clang*
@@ -18,4 +18,4 @@
 /source
 /bundle
 /localversion
-/multi-build
+/multi-build

Dockerfile

@@ -4,7 +4,7 @@ FROM python:3.12-slim-bookworm AS base
 ARG WDIR=/zero_build
 ENV CONAN_UPLOAD_CUSTOM 0
 
-# place sources from host to container
+# transfer sources from host to container
 COPY . ${WDIR}
 WORKDIR ${WDIR}
 
@@ -16,6 +16,7 @@ RUN \
     apt-get install -y \
         neovim \
         curl \
+        wget \
         git \
         gcc \
         g++ \

README.md

@@ -7,9 +7,10 @@ An Android kernel with Kali NetHunter functionality.
 - [zero\_kernel](#zero_kernel)
   - [Contents](#contents)
   - [**Disclaimer**](#disclaimer)
+  - [Description](#description)
   - [Kernel Features](#kernel-features)
   - [Supported ROMs](#supported-roms)
-  - [Important Note](#important-note)
+  - [ROM Artifacts in Releases](#rom-artifacts-in-releases)
   - [Usage](#usage)
     - [Prerequisites](#prerequisites)
     - [Kernel](#kernel)
@@ -27,6 +28,14 @@ An Android kernel with Kali NetHunter functionality.
 
 **Anything you do with this kernel 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.**
 
+## Description
+
+Technically speaking, the codebase of this project is an extensive 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](https://www.kali.org/docs/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:
@@ -38,7 +47,7 @@ The kernel has the following features:
 
 ## Supported ROMs
 
-For OnePlus 5/T devices:
+For **OnePlus 5/T** devices:
 
 - 4.4 Linux kernel version:
   - LineageOS;
@@ -52,11 +61,11 @@ For OnePlus 5/T devices:
 
 \** -- this, **in theory**, is relevant to all 4.14-based ROMs for this device in existence.
 
-## Important 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 with the checksums, which should be identical to the ones presented on the ROM project's official web page.
+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 done due to the fact that some ROM projects remove their older builds once they become too outdated.
 
@@ -97,11 +106,10 @@ To run this tool in a `local` environment, you will need:
 You will also need a few Python packages. To install them, use:
 
 ```sh
+python3 -m pip install poetry
 python3 -m poetry install --no-root
 ```
 
-To install `poetry`, use `python3 -m pip install poetry`.
-
 ### Kernel
 
 Kernel build process can be launched by using the `python3 wrapper kernel <arguments>` command.
@@ -110,14 +118,14 @@ For more options you can refer to the help message below.
 
 ```help
 $ python3 wrapper kernel --help
-usage: wrapper kernel [-h] --buildenv {local,docker,podman} --base
+usage: wrapper kernel [-h] --build-env {local,docker,podman} --base
                       {los,pa,x,aosp} --codename CODENAME --lkv LKV [-c]
                       [--clean-image] [--log-level {normal,verbose,quiet}]
                       [-o OUTLOG] [--ksu]
 
 options:
   -h, --help            show this help message and exit
-  --buildenv {local,docker,podman}
+  --build-env {local,docker,podman}
                         select build environment
   --base {los,pa,x,aosp}
                         select a kernel base for the build
@@ -131,6 +139,7 @@ options:
   -o OUTLOG, --output OUTLOG
                         save logs to a file
   --ksu                 add KernelSU support
+
 ```
 
 ### Assets
@@ -139,14 +148,14 @@ As mentioned, there is also an asset downloader, which can collect latest versio
 
 ```help
 $ python3 wrapper assets --help
-usage: wrapper assets [-h] --buildenv {local,docker,podman} --base
+usage: wrapper assets [-h] --build-env {local,docker,podman} --base
                       {los,pa,x,aosp} --codename CODENAME --chroot
                       {full,minimal} [--rom-only] [--clean-image] [--clean]
                       [--log-level {normal,verbose,quiet}] [-o OUTLOG] [--ksu]
 
 options:
   -h, --help            show this help message and exit
-  --buildenv {local,docker,podman}
+  --build-env {local,docker,podman}
                         select build environment
   --base {los,pa,x,aosp}
                         select a kernel base for the build
@@ -184,15 +193,15 @@ An option named `slim` is a much lighter version of `full` packaging, as only th
 
 ```help
 $ python3 wrapper bundle --help
-usage: wrapper bundle [-h] --buildenv {local,docker,podman} --base
+usage: wrapper 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] [--log-level {normal,verbose,quiet}]
                       [-o OUTLOG] [--ksu]
 
 options:
   -h, --help            show this help message and exit
-  --buildenv {local,docker,podman}
+  --build-env {local,docker,podman}
                         select build environment
   --base {los,pa,x,aosp}
                         select a kernel base for the build
@@ -214,12 +223,23 @@ options:
 
 Here are some examples of commands:
 
-- **(Recommended)** Build kernel and collect ROM via Docker:
-  - `python3 wrapper bundle --buildenv=docker --base=los --codename=dumpling --lkv=4.4 --package-type=slim`;
-- Build kernel locally:
-  - `python3 wrapper kernel --buildenv=local --base=los --codename=dumpling --lkv=4.4`;
-- Collect all the assets locally:
-  - `python3 wrapper assets --buildenv=local --base=los --codename=dumpling --package-type=full`.
+**(Recommended)** Build kernel and collect ROM via Docker:
+
+```sh
+python3 wrapper bundle --build-env=docker --base=los --codename=dumpling --lkv=4.4 --package-type=slim
+```
+
+Build kernel locally:
+
+```sh
+python3 wrapper kernel --build-env=local --base=los --codename=dumpling --lkv=4.4
+```
+
+Collect all of the assets locally:
+
+```sh
+python3 wrapper assets --build-env=local --base=los --codename=dumpling --package-type=full
+```
 
 ## Credits
 

conanfile.py

@@ -1,13 +1,13 @@
 from conans import ConanFile
 
 
-class ZeroConan(ConanFile):
+class ZeroKernelConan(ConanFile):
     name = "zero"
-    version = "0.4.0"
+    version = "0.4.1"
     author = "seppzer0"
     url = "https://gitlab.com/api/v4/projects/40803264/packages/conan"
     description = "An Android kernel with Kali NetHunter functionality."
-    topics = ("zero_kernel", "kali-nethunter")
+    topics = ("zero_kernel", "kali-nethunter", "nethunter")
     settings = None
     options = {
                 "base": ("los", "pa", "x", "aosp"),
@@ -19,13 +19,15 @@ def export_sources(self):
         self.copy("*", src="source", dst=".")
 
     def build(self):
-        cmd = "python3 wrapper kernel local {0} {1} &&"\
-              "python3 wrapper assets local {0} {1} {2} --clean"\
-              .format(
-                  self.options.rom,
-                  self.options.codename,
-                  self.options.chroot
-              )
+        shared_args = "--build-env=local --base={} --codename={} --chroot={}"\
+                      .format(
+                        self.options.base,
+                        self.options.codename,
+                        self.options.chroot
+                       )
+        cmd = "python3 wrapper kernel {0} &&"\
+              "python3 wrapper assets {0} --clean"\
+              .format(shared_args)
         print(f"[cmd] {cmd}")
         self.run(cmd)
 

docs/FAQ.md

@@ -4,7 +4,7 @@ This page contains answers to popular questions in relation to this kernel.
 
 ## Q: How to TURN ON monitor mode on internal Wi-Fi card?
 
-There are two options to switch internal Wi-Fi card to monitor mode:
+**A:** There are two options to switch internal Wi-Fi card to monitor mode:
 
 - in Kali chroot environment, launch `airmon-ng start wlan0`;
 - in NetHunter app, navigate to the `Custom Commands` menu and launch the `Start wlan0 in monitor mode`.
@@ -13,14 +13,14 @@ Be aware that while in monitor mode, you won't be able to connect to a Wi-Fi net
 
 ## Q: How to TURN OFF monitor mode on internal Wi-Fi card?
 
-Similarly, depending on which approach you chose to turn on the monitor mode, there are two options:
+**A:** Similarly, depending on which approach you chose to turn on the monitor mode, there are two options:
 
 - in Kali chroot environment -> `airmon-ng stop wlan0`;
 - in NetHunter app -> `Custom Commands` -> `Stop wlan0 in monitor mode`.
 
 ## Q: Why is there an unused wlan1 interface?
 
-**TL;DR**: Because it's a ~~bug~~ feature of Android 13.
+**A:** Because it's a ~~bug~~ feature of Android 13.
 
 Initially, when launching `airmon-ng` in Kali chroot environment without any of the interfaces in monitor mode and no external adapters plugged in, you will see two wlan interfaces: `wlan0` and `wlan1`.
 
@@ -30,4 +30,8 @@ Switching `wlan0` to monitor mode disables `wlan1` completely. However, when res
 
 ## Q: How to TURN ON and OFF monitor mode on external Wi-Fi card?
 
-For an external card, you would have to use `airmon-ng start <interface>` and `airmon-ng stop <interface>` commands.
+**A:** For an external card, you would have to use `airmon-ng start <interface>` and `airmon-ng stop <interface>` commands.
+
+## Q: How do I switch from standard partition ROM to retrofit dynamic partition ROM and vice versa?
+
+**A:** Refer to these [instructions](https://gist.github.com/nkeor/d71b7884ee951de669b0d4baeacc58ba).

docs/FLASHING.md

@@ -23,7 +23,7 @@ Listed below files are required:
 - compiled kernel, obviously;
 - ROM;
 - Magisk or KernelSU;
-- TWRP, the unofficial 3.7.0 version (supports operations with encrypted and dynamic partitions);
+- TWRP, the special [build](https://sourceforge.net/projects/op5-5t/files/Android-12/TWRP/twrp-3.7.0_12-5-dyn-cheeseburger_dumpling.img/download) by faoliveira78 (supports operations with encrypted and dynamic partitions);
 - DM-Verity and Force Encrypt disabler;
 - Kali NetHunter + Kali NetHunter Terminal apps;
 - Kali NetHunter Chroot (you can do this later, but it would be easier to download this beforehand);
@@ -50,8 +50,9 @@ Before doing anything, please ensure that you have:
 - wipe your phone via `Wipe -> Advanced Wipe` menu, check all the shown boxes;
 - wipe your device again via `Wipe -> Format Data` menu (this will remove any encryption that is present on your device);
 - reboot into TWRP via `Reboot -> Recovery`;
-- flash ROM;
-- flash kernel;
+- if using a Retrofit Dynamic Partitions ROM such as ParanoidAndoid -> untoggle `Unmount System before installing a ZIP` in the Settings;
+- flash the ROM;
+- flash the kernel;
 - **if using Magisk** --> flash root manager (Magisk; you must change the `.apk` extension into `.zip` for this);
 - flash DM-Verity and Force Encrypt disabler zip;
 - reboot into system via `Reboot -> System` .

docs/TODO.md

@@ -26,19 +26,15 @@
 - [x] add proper OS detection for preventing local builds in unsupported systems;
 - [x] add static analysis for the wrapper;
 - [x] add a single-point manifest with main info on the tool;
-- [ ] add release body when creating a release via CI/CD;
-- [ ] add static analysis report to release body;
 - [x] improve documentation;
 - [x] apply OOP paradigm;
 - [ ] add tests (unit/integration/etc);
 - [x] switch to Poetry for dependency management;
 - [ ] create a commit-based lockfile system for reproducible kernel builds;
-- [ ] implement generators;
 - [x] switch to `pathlib`;
 - [ ] switch to `raise` instead of `sys.exit`;
 - [ ] use `pydantic`;
 - [x] add a FAQ page;
-- [ ] add wiki;
 - [x] refactor Docker/Podman command formation;
 - [ ] refactor logging mechanism;
 - [x] fix Podman usage (.dockerignore);
@@ -55,4 +51,5 @@
 - [x] add a new argument responsible for Linux kernel version selection;
 - [x] add 4.14 Linux kernel version builds;
 - [ ] decompose `run` methods into separate functions as much as possible;
-- [ ] new device support: OP9.
+- [ ] new device support: OP9;
+- [ ] add type checks with pyright.