zpoline is a novel system call hook mechanism that offers the following advantages.
Therefore, zpoline is a quite good option if you think...
zpoline is categorized into binary rewriting, but you do not need to worry that your program binary files are overwritten. The setup procedure of zpoline rewrites the code binary loaded on the memory, just before the user-space program starts its main function. Therefore, it does not overwrite your program binary files.
The cool part of zpoline is that it does not fail to hook system calls, which is difficult for existing binary rewriting techniques.
The key ideas of zpoline are to exploit the calling convention and instantiate a special trampoline code. The overview is shown in the picture below.
In a nutshell, zpoline replaces the syscall
and sysenter
instructions with callq *%rax
, and crafts a trampoline code at virtual address 0 (zero); this is why this technique is named zpoline.
For more technical details, please check the Further Information section.
Currently, this implementation assumes Linux on the x86-64 architecture.
zpoline uses the disassembler in libopcodes
that is part of binutils.
sudo apt install binutils-dev
This example uses two shared libraries.
apps/basic/libzphook_basic.so
only implements the hook function. (we call the hook function library).libzpoline.so
is loaded by LD_PRELOAD. This configures the trampoline code, conducts binary rewriting, and loads ./apps/basic/libzphook_basic.so
using dlmopen.To build apps/basic/libzphook_basic.so
, please type the following command.
make -C apps/basic
For libzpoline.so
, please type the following command.
make
To use zpoline, please set 0 to /proc/sys/vm/mmap_min_addr
.
sudo sh -c "echo 0 > /proc/sys/vm/mmap_min_addr"
Pleae specify apps/basic/libzphook_basic.so
for the LIBZPHOOK
environment variable, and libzpoline.so
for LD_PRELOAD. The example command is as follows.
$ LIBZPHOOK=./apps/basic/libzphook_basic.so LD_PRELOAD=./libzpoline.so [program you wish to run]
LIBZPHOOK
is defined in main.c
of libzpoline.so
.
libzpoline.so
performs dlmopen for a shared library file specified by LIBZPHOOK
.
Currently, the hook function in apps/basic/libzphook_basic.so
prints the system call number using printf. The following is the example output.
$ LIBZPHOOK=./apps/basic/libzphook_basic.so LD_PRELOAD=./libzpoline.so /bin/ls
output from __hook_init: we can do some init work here
output from hook_function: syscall number 257
output from hook_function: syscall number 262
output from hook_function: syscall number 9
output from hook_function: syscall number 3
output from hook_function: syscall number 16
output from hook_function: syscall number 16
output from hook_function: syscall number 257
output from hook_function: syscall number 262
output from hook_function: syscall number 217
output from hook_function: syscall number 217
output from hook_function: syscall number 3
output from hook_function: syscall number 262
output from hook_function: syscall number 1
apps Documentation libzpoline.so LICENSE main.c main.o Makefile README.md
output from hook_function: syscall number 3
Currently, libzpoline.so
is independent of the hook function library. So, you can build your own hook function library, and to activate it, you only need to specify it to the LIBZPHOOK
environment variable.
In the hook function library, you should implement __hook_init
.
It will have the pointer to the hook function address as the argument, and by overwriting it, the hook function library can apply an arbitrary hook function.
For details, please check apps/basic/main.c
.
The following materials provide more information.
A paper about zpoline appears at USENIX ATC 2023 ( https://www.usenix.org/conference/atc23/presentation/yasukata ).
This paper includes a technical overview (Section 2) and comparison with other existing hook mechanisms (Section 1 and 3); for busy readers, the abstract of the paper summarises 1) advantages over the previous mechanisms, 2) the challenge that this work addresses, 3) the overview of the solution, and 4) rough numbers of the experiment results.
We would appreciate it if you cite this paper when you refer to zpoline in your work.
Documentation/README.md is supplemental documentation.
The source code contains comments that explain how actually the system is implemented; these comments are the most detailed documentation currently we have.
The starting point of the program (main.c
) is __zpoline_init
, that is triggered by LD_PRELOAD
, and this executes the following functions:
setup_trampoline
instantiates the trampoline code.rewrite_code
performs binary rewriting.load_hook_lib
loads the core library function using dlmopen
.