Kasumi

Kasumi is an out-of-tree Linux kernel module (kasumi_lkm.ko) for Android GKI/Linux path control in root/SU environments.

It provides redirection, hiding, merge/injection, and spoofing behavior through an anonymous-fd + ioctl control plane.

Kasumi was previously developed as HymoFS. The project name, module name, userspace ABI, and public symbols now use Kasumi/KSM naming; HymoFS should be treated as a historical name.

中文版本: README.zh-CN.md

Scope and Status

• Repository type: LKM (not an in-tree kernel patch set)
• Main code: src/
• Control protocol: src/include/kasumi_uapi.h
• Current protocol version: KSM_PROTOCOL_VERSION = 15
• Hook strategy: ftrace/tracepoint first when available, with kprobe/kretprobe fallback
• 6.6+ compatibility for arch_ftrace_get_regs is included in current code

Core Capabilities

• Path redirect: src -> target
• Reverse mapping for path presentation (d_path related flow)
• Directory entry hiding (iterate_dir filtering)
• Directory merge/injection behavior
• kstat spoofing (ino/dev/size/time, etc.)
• Overlay/xattr related filtering
• uname spoofing
• /proc/cmdline spoofing
• /proc/<pid>/maps spoofing rules (ino/dev/pathname)
• Mount-hide and statfs spoof features

Use in controlled environments only. This module hooks VFS and syscall hot paths.

Hook Overview

• GET_FD path: tracepoint preferred, fallback to kprobe/kretprobe
• VFS path: ftrace (entry) + kretprobe (ret) preferred, fallback to kprobe
• Symbol resolution: prefer kallsyms_lookup_name, fallback to per-symbol kprobe resolution

CI KMI Targets

Current workflow builds:

• android12-5.10
• android13-5.10
• android13-5.15
• android14-5.15
• android14-6.1
• android15-6.6
• android16-6.12

See .github/workflows/build-lkm.yml and .github/workflows/ddk-lkm.yml.

Build

Option A: DDK (recommended)

ddk build
ddk build android14-6.1
ddk build android15-6.6

Option B: Kernel tree local build

Run against a prepared kernel tree (modules_prepare done):

make -C /path/to/kernel ARCH=arm64 M=$(pwd)/src modules

Load and Debug Parameters

insmod kasumi_lkm.ko

If symbol export limitations prevent loading, and you are using newer KernelSU or its forks, you can also try:

ksud insmod kasumi_lkm.ko

Common module parameters in src/core/kasumi_bootstrap.c:

• kasumi_syscall_nr
• kasumi_no_tracepoint=1
• kasumi_skip_vfs=1
• kasumi_skip_extra_kprobes=1
• kasumi_skip_getfd=1
• kasumi_skip_kallsyms=1
• kasumi_dummy_mode=1

Userspace Control Plane

1. Userspace obtains an anonymous fd through GET_FD (root-only).
2. Userspace sends ioctl on that fd to manage rules/features.

Main ioctls (see src/include/kasumi_uapi.h for full ABI):

• KSM_IOC_ADD_RULE, KSM_IOC_DEL_RULE, KSM_IOC_HIDE_RULE
• KSM_IOC_ADD_MERGE_RULE, KSM_IOC_CLEAR_ALL, KSM_IOC_SET_ENABLED
• KSM_IOC_GET_FEATURES, KSM_IOC_GET_HOOKS, KSM_IOC_LIST_RULES
• KSM_IOC_ADD_SPOOF_KSTAT, KSM_IOC_UPDATE_SPOOF_KSTAT
• KSM_IOC_SET_UNAME, KSM_IOC_SET_CMDLINE
• KSM_IOC_ADD_MAPS_RULE, KSM_IOC_CLEAR_MAPS_RULES
• KSM_IOC_SET_MOUNT_HIDE, KSM_IOC_SET_MAPS_SPOOF, KSM_IOC_SET_STATFS_SPOOF

You can use YukiSU (C++) for KernelSU-integrated flows. In addition, the hybrid-mount meta-module includes Kasumi support with a Rust userspace implementation.

Given mount logic quality and update cadence, hybrid-mount is generally the preferred meta-module choice.

Quick Troubleshooting

• Unknown symbol __tracepoint_sys_enter: try kasumi_no_tracepoint=1
• Builds but cannot load: check vermagic, module signature policy, and dmesg
• Hook/ABI changes: validate with KSM_IOC_GET_HOOKS and KSM_IOC_GET_FEATURES

Repository Layout

• src/: LKM implementation
• docs/: design and notes
• scripts/: automation scripts
• .github/workflows/: multi-KMI build/release pipeline

License

• SPDX: Apache-2.0 OR GPL-2.0
• See LICENSE, LICENSE-GPL-2.0, and NOTICE