237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# Extension verification — kernel-level weapons (templates, gates, and a closed door)
|
|
|
|
Covers the extension pass that added `scripts/kernelsu_syscall_mask.py` and the `§4a` section of
|
|
`references/kernel-and-environment-hardening.md`. Strength labels as defined in this directory's
|
|
README: **observed** (exact command + output here), **inferred** (follows from observed facts,
|
|
step not executed), **unverified** (assumed or externally reported, not independently confirmed).
|
|
|
|
Reference environment: Windows 11 host, Python 3.14.0; `<DEVICE>` = rooted Android 11 (API 30)
|
|
arm64-v8a, Magisk alpha, no APatch/KernelPatch.
|
|
|
|
**Headline: the generator, the gate table and the userspace module skeleton are measured. No
|
|
kernel-side artifact was compiled or loaded anywhere, and every route is closed on the reference
|
|
device. That is the deliverable — a template plus a measured statement of the door.**
|
|
|
|
---
|
|
|
|
## 1. Kernel gate, measured on the device — observed
|
|
|
|
```
|
|
$ adb shell 'uname -r; cat /proc/version'
|
|
4.14.186+
|
|
Linux version 4.14.186+ (nobody@android-build) (Android (6443078 based on r383902) clang version
|
|
11.0.1 (https://android.googlesource.com/toolchain/llvm-project b397f81060ce6d701042b782172ed13bee898b79),
|
|
LLD 11.0.1 (/buildbot/tmp/tmp6_m7QH ...)) #1 SMP PREEMPT Wed Mar 30 23:32:42 CST 2022
|
|
```
|
|
|
|
4.14.186 is below the 5.10 GKI gate for the eBPF route, and the device carries no
|
|
KernelPatch-patched image. Read-only query; no device lock was needed and no state was changed.
|
|
|
|
## 2. Host toolchain probe — observed
|
|
|
|
```
|
|
$ python skills/apk-reverse/scripts/kernelsu_syscall_mask.py gates
|
|
== kernel-side routes and their gates ==
|
|
|
|
eBPF tracepoint/kprobe GKI kernel 5.10+ (Android 12+)
|
|
why: Android's BPF/tracing support as bpftrace-class tooling and
|
|
stackplz expect it is a GKI-era feature; BTF is required for
|
|
CO-RE style probes.
|
|
check: uname -r -> expect 5.10.x or newer; ls /sys/kernel/btf/vmlinux
|
|
|
|
KernelPatch / APatch KPM KernelPatch-patched boot image + kpm toolchain
|
|
why: KPMs load through kpimg injected into the kernel image's
|
|
payload segment; building one needs a bare-metal ARM64
|
|
compiler (aarch64-none-elf-gcc), not the NDK.
|
|
check: ls /data/adb/ | grep -i apatch ; which aarch64-none-elf-gcc
|
|
|
|
Out-of-tree LKM Kernel source matching the device's exact version + vermagic
|
|
why: A module built against a different kernel revision is refused
|
|
at load time on a mismatched vermagic, and the device's kernel
|
|
source is frequently not published at all.
|
|
check: uname -r ; look for a matching kernel source tree for the device
|
|
|
|
seccomp-BPF (for contrast) any modern kernel, but it is not this route
|
|
why: seccomp can make a syscall FAIL (SECCOMP_RET_ERRNO/TRAP); it
|
|
cannot rewrite the CONTENT a successful read returns. It closes
|
|
doors, it does not paint them -- which is the whole requirement
|
|
for a spoofed /proc read.
|
|
check: n/a -- this is a capability ceiling, not a version check
|
|
|
|
== host probe (what can be checked from here) ==
|
|
|
|
bare-metal ARM64 compiler: NOT FOUND
|
|
the KPM route cannot be built from this host as configured
|
|
ndk-build: NOT FOUND
|
|
make: NOT FOUND
|
|
|
|
A kernel source tree, a patched boot image and the device's own kernel headers cannot be
|
|
checked from the host; they are device facts.
|
|
```
|
|
|
|
The three `NOT FOUND` lines are the measured reason the KPM route cannot be built from here, and
|
|
they are also consistent with `ENV.md`'s record that the machine has no Android NDK. The LKM route
|
|
additionally needs kernel source that does not exist for this device.
|
|
|
|
## 3. `generate` — observed
|
|
|
|
```
|
|
$ python skills/apk-reverse/scripts/kernelsu_syscall_mask.py generate \
|
|
--out tools/_work/t5-vmp/sysmask --package '<PKG>'
|
|
generated module scaffold in tools/_work/t5-vmp/sysmask
|
|
module.prop 165 B
|
|
customize.sh 166 B
|
|
post-fs-data.sh 830 B
|
|
service.sh 467 B
|
|
uninstall.sh 298 B
|
|
config/syscall_mask.json 1079 B
|
|
kpm/syscall-mask.c 8096 B
|
|
kpm/Makefile 880 B
|
|
lkm/syscall-mask.c 2434 B
|
|
ebpf/syscall_mask.bpf.c 4338 B
|
|
README.md 3752 B
|
|
|
|
STATUS: the userspace module is installable; every kernel-side file is an UNVERIFIED template.
|
|
No kernel code was compiled or loaded.
|
|
```
|
|
|
|
`module.prop`, as generated (the package identity is the `<PKG>` placeholder by design — this file
|
|
carries no real package name):
|
|
|
|
```
|
|
id=syscall-mask
|
|
name=Syscall Mask
|
|
version=0.1.0
|
|
versionCode=1
|
|
author=apk-reverse
|
|
description=config-driven syscall return masking (openat/read/stat on /proc/self/*)
|
|
```
|
|
|
|
The configuration table rendered into the KPM template from `config/syscall_mask.json`, so the
|
|
rule set is data rather than hand-edited C:
|
|
|
|
```
|
|
static const struct mask_rule rules[] = {
|
|
{ "/proc/self/maps", 0, MASK_DENY, -2, 0 },
|
|
{ "/proc/self/maps", 0, MASK_FAKE_SIZE, -2, 0 },
|
|
{ "/proc/self/status", "TracerPid", MASK_FILTER_LINE, -2, 0 },
|
|
{ "/proc/self/status", "TracerPid", MASK_FILTER_LINE, -2, 0 },
|
|
};
|
|
```
|
|
|
|
And the KPM lifecycle surface, which is the part an interface drift would break first:
|
|
|
|
```
|
|
int kfunc_def(strncpy_from_user)(char *dst, const char __user *src, long count);
|
|
/* fp_hook_syscalln(__NR_openat, before_openat, 0, 0); */
|
|
/* fp_hook_syscalln(__NR_newfstatat, before_newfstatat, 0, 0); */
|
|
/* fp_hook_syscalln(__NR_read, before_read, 0, 0); */
|
|
KPM_INIT(mask_init);
|
|
KPM_EXIT(mask_exit);
|
|
```
|
|
|
|
Those names (`KPM_NAME` / `KPM_INIT` / `KPM_EXIT`, `kfunc_def`, `fp_hook_syscalln`,
|
|
`hook_fargs4_t`, `syscall_argn`, `args->skip_origin`, `args->ret`) are taken from a public KPM
|
|
development write-up rather than invented — blackr0ck, *APatch KPM 开发：绕过 DirtySepolicy /
|
|
Duck Detector 的 SELinux Root 检测*, [bbs.kanxue.com/thread-291665.htm](https://bbs.kanxue.com/thread-291665.htm),
|
|
fetched 2026-02. **They are still `unverified` here**: nobody compiled against a `kpmodule.h` in
|
|
this pass, and the generated template says so in its own header for exactly that reason.
|
|
|
|
The registration calls are left **commented out** in the template. A generated file that arms a
|
|
kernel hook by default is a file that arms a kernel hook the first time somebody runs `make` in a
|
|
hurry.
|
|
|
|
## 4. `verify` — observed
|
|
|
|
```
|
|
$ python skills/apk-reverse/scripts/kernelsu_syscall_mask.py verify --dir tools/_work/t5-vmp/sysmask
|
|
== verifying tools/_work/t5-vmp/sysmask ==
|
|
module.prop: author=apk-reverse, description=config-driven syscall return masking
|
|
(openat/read/stat on /proc/self/*), id=syscall-mask, name=Syscall Mask,
|
|
version=0.1.0, versionCode=1
|
|
config: 4 rule(s), actions=['deny', 'fake_size', 'filter_line']
|
|
kpm target present: Makefile, syscall-mask.c
|
|
status: UNVERIFIED TEMPLATE -- not compiled, not loaded
|
|
lkm target present: syscall-mask.c
|
|
status: UNVERIFIED TEMPLATE -- not compiled, not loaded
|
|
ebpf target present: syscall_mask.bpf.c
|
|
status: UNVERIFIED TEMPLATE -- not compiled, not loaded
|
|
kpm/syscall-mask.c: KPM_* lifecycle macros present, kfunc_def not extern
|
|
|
|
== 0 problem(s): structure is consistent ==
|
|
(this says nothing about whether the kernel side compiles or loads)
|
|
```
|
|
|
|
`verify` is deliberately read-only and deliberately narrow: it checks `module.prop` fields, the rule
|
|
JSON, and the one static trap in the KPM template that has a documented consequence (an `extern`
|
|
`kfunc_def` becomes `*UND*` and the loader refuses the module). It states on its last line what it
|
|
does **not** establish, because "0 problems" on a template is the easiest sentence in this file to
|
|
over-read.
|
|
|
|
### 4a. A false positive this check produced, and its fix — observed
|
|
|
|
The first run reported:
|
|
|
|
```
|
|
== 1 problem(s) ==
|
|
- syscall-mask.c declares kfunc_def with `extern`, which the loader rejects as an unknown symbol
|
|
verify rc=1
|
|
```
|
|
|
|
The template does not declare it with `extern` — its comment *explains* why `extern` is forbidden,
|
|
and the check's own regex ran from that prose across to the real declaration's semicolon. A linter
|
|
that reads comments as code produces reports nobody can act on. The fix strips `/* */` and `//`
|
|
comments before any token check (`_strip_c_comments`). Both the false positive and the fix are
|
|
recorded here rather than quietly repaired, because the failure mode — a check that fires on its
|
|
own documentation — is one a reader will meet again.
|
|
|
|
## 5. The userspace module's ceiling — observed by construction, and worth stating plainly
|
|
|
|
`post-fs-data.sh` and `service.sh` in the generated skeleton do not load anything. That is not an
|
|
omission: a KernelSU/Magisk/APatch-userspace module runs as root in the normal world and cannot
|
|
change what a syscall returns. The generated `README.md` says this in its first paragraph, and
|
|
`post-fs-data.sh` carries the reasoning in a comment:
|
|
|
|
```
|
|
# The kernel side (if you built and loaded one) owns the syscall table; this
|
|
# script's whole job is to make the configuration visible to it and to leave a
|
|
# record that the module actually ran. Do not put a syscall hook here: this is
|
|
# userspace, and nothing here can change what openat/read/stat return.
|
|
```
|
|
|
|
The uninstall hook likewise refuses to unload a kernel module, because a silent unload during
|
|
package removal is how a device ends up in a boot loop.
|
|
|
|
## 6. eBPF route — gate table and the capability ceiling
|
|
|
|
| Route | Gate | Check on the device | Status here |
|
|
|---|---|---|---|
|
|
| eBPF tracepoint/kprobe | GKI 5.10+ with tracing/BTF | `uname -r`; `ls /sys/kernel/btf/vmlinux` | **closed** — device is 4.14.186 |
|
|
| seccomp-BPF | any modern kernel | n/a | not this route: it can only fail a syscall, not rewrite a successful read |
|
|
| KernelPatch / APatch KPM | patched boot image + `aarch64-none-elf-gcc` | `ls /data/adb/ \| grep -i apatch`; `which aarch64-none-elf-gcc` | **closed** — neither present; patch-the-boot-image risk declined |
|
|
| Out-of-tree LKM | kernel source matching vermagic | `uname -r` + a matching source tree | **closed** — no source for this device |
|
|
|
|
The probe template (`ebpf/syscall_mask.bpf.c`) is a `sys_enter_openat` tracepoint observer with a
|
|
uid filter map and a ringbuf event, and it documents two dead ends in the file itself:
|
|
`bpf_override_return()` only applies to `ALLOW_ERROR_INJECTION` functions, which raw syscall
|
|
entries are not, and a tracepoint cannot rewrite a result at all. **A tracepoint observes; it does
|
|
not spoof.** The honest eBPF shape for this job is therefore observation — which is still worth
|
|
having, because `§5` of the reference file requires you to establish whether the target uses a raw
|
|
`svc` or a libc call *before* designing any spoof.
|
|
|
|
## 7. What was not done
|
|
|
|
- **No kernel-side code was compiled.** Not the KPM, not the LKM, not the eBPF program. No
|
|
`kpmodule.h`, no kernel headers, no `bpftool`, no bare-metal ARM64 compiler on this host.
|
|
- **Nothing was loaded, flashed or activated on `<DEVICE>`.** No boot-image patch, no module load,
|
|
no kernel modification. The task forbids it for good reason: a kernel module that faults takes
|
|
the device down before it can report why.
|
|
- **The KPM API surface is `unverified`.** The macro and helper names follow a public write-up; the
|
|
argument arity of `fp_hook_syscalln` in particular is marked `TODO(verify-on-device)` in the
|
|
generated source rather than guessed, because a wrong arity in a hook registration is a
|
|
load-time failure at best.
|
|
- **The struct-stat size offset is a TODO, not a value.** The `newfstatat` handler deliberately does
|
|
not carry a magic offset: it is ABI-specific and copying one from a different architecture is how
|
|
a spoof corrupts an unrelated field.
|
|
- **`verify` establishes structure, not capability.** Its own output says so.
|