Super User

Hooking Linux Kernel Functions, Part 2: How to Hook Functions with Ftrace

Ftrace is a Linux kernel framework for tracing Linux kernel functions. But our team managed to find a new way to use ftrace when trying to enable system activity monitoring to be able to block suspicious processes. It turns out that ftrace allows you to install hooks from a loadable GPL module without rebuilding the kernel. This approach works for Linux kernel versions 3.19 and higher for the x86_64 architecture.

This is the second part of our three-part series on hooking Linux kernel function calls. In this article, we explain how you can use ftrace to hook critical function calls in the Linux kernel. We also describe and test two theories for protecting a Linux kernel module from ftrace hooks. Read Hooking Linux Kernel Functions, Part 1: Looking for the Perfect Solution to learn more about other approaches that can be used for accomplishing this task.

Written by: Alexey Lozovsky, Software Designer, System Programming Team

and Sergey Stepanchuk, Software Developer, System Programming Team

Contents:

A new approach: Using ftrace for Linux kernel hooking

Description of necessary functions

Initializing ftrace

Hooking functions with ftrace

Protection from recursive calls

The scheme of the hooking process

Protecting Linux kernel module from ftrace hooks

Kernel module protection from ftrace hooks in practice

Conclusion

A new approach: Using ftrace for Linux kernel hooking

What is an ftrace? Basically, ftrace is a framework used for tracing the kernel on the function level. This framework has been in development since 2008 and has quite an impressive feature set. What data can you usually get when you trace your kernel functions with ftrace? Linux ftrace displays call graphs, tracks the frequency and length of function calls, filters particular functions by templates, and so on. Further down this article you’ll find references to official documents and sources you can use to learn more about the capabilities of ftrace.

The implementation of ftrace is based on the compiler options -pg and -mfentry. These kernel options insert the call of a special tracing function — mcount() or __fentry__() — at the beginning of every function. In user programs, profilers use this compiler capability for tracking calls of all functions. In the kernel, however, these functions are used for implementing the ftrace framework.

Calling ftrace from every function is, of course, pretty costly. This is why there’s an optimization available for popular architectures — dynamic ftrace. If ftrace isn’t in use, it nearly doesn’t affect the system because the kernel knows where the calls mcount() or __fentry__() are located and replaces the machine code with nop (a specific instruction that does nothing) at an early stage. And when Linux kernel trace is on, ftrace calls are added back to the necessary functions.

Description of necessary functions

The following structure can be used for describing each hooked function:

/** * struct ftrace_hook describes the hooked function * * @name: the name of the hooked function * * @function: the address of the wrapper function that will be called instead of * the hooked function * * @original: a pointer to the place where the address * of the hooked function should be stored, filled out during installation of * the hook * * @address: the address of the hooked function, filled out during installation * of the hook * * @ops: ftrace service information, initialized by zeros; * initialization is finished during installation of the hook */ struct ftrace_hook { const char *name; void *function; void *original; unsigned long address; struct ftrace_ops ops; };

There are only three fields that the user needs to fill in: name, function, and original. The rest of the fields are considered to be implementation details. You can put the description of all hooked functions together and use macros to make the code more compact:

#define HOOK(_name, _function, _original) \ { \ .name = (_name), \ .function = (_function), \ .original = (_original), \ } static struct ftrace_hook hooked_functions[] = { HOOK("sys_clone", fh_sys_clone, &real_sys_clone), HOOK("sys_execve", fh_sys_execve, &real_sys_execve), };

This is what the hooked function wrapper looks like:

/* * It’s a pointer to the original system call handler execve(). * It can be called from the wrapper. It’s extremely important to keep the function signature * without any changes: the order, types of arguments, returned value, * and ABI specifier (pay attention to “asmlinkage”). */ static asmlinkage long (*real_sys_execve)(const char __user *filename, const char __user *const __user *argv, const char __user *const __user *envp); /* * This function will be called instead of the hooked one. Its arguments are * the arguments of the original function. Its return value will be passed on to * the calling function. This function can execute arbitrary code before, after, * or instead of the original function. */ static asmlinkage long fh_sys_execve(const char __user *filename, const char __user *const __user *argv, const char __user *const __user *envp) { long ret; pr_debug("execve() called: filename=%p argv=%p envp=%p

", filename, argv, envp); ret = real_sys_execve(filename, argv, envp); pr_debug("execve() returns: %ld

", ret); return ret; }

Now, hooked functions have a minimum of extra code. The only thing requiring special attention is the function signatures. They must be completely identical; otherwise, the arguments will be passed on incorrectly and everything will go wrong. This isn’t as important for hooking system calls, though, since their handlers are pretty stable and, for performance reasons, the system call ABI and function call ABI use the same layout of arguments in registers. However, if you’re going to hook other functions, remember that the kernel has no stable interfaces.

Related services Engineering for Cybersecurity Projects

Initializing ftrace

Our first step is finding and saving the hooked function address. As you probably know, when using ftrace, Linux kernel tracing can be performed by the function name. However, we still need to know the address of the original function in order to call it.

You can use kallsyms — a list of all kernel symbols — to get the address of the needed function. This list includes not only symbols exported for the modules but actually all symbols. This is what the process of getting the hooked function address can look like:

static int resolve_hook_address(struct ftrace_hook *hook) { hook->address = kallsyms_lookup_name(hook->name); if (!hook->address) { pr_debug("unresolved symbol: %s

", hook->name); return -ENOENT; } *((unsigned long*) hook->original) = hook->address; return 0; }

Next, we need to initialize the ftrace_ops structure. Here we have one necessary field, func, pointing to the callback. However, some critical flags are needed:

int fh_install_hook(struct ftrace_hook *hook) { int err; err = resolve_hook_address(hook); if (err) return err; hook->ops.func = fh_ftrace_thunk; hook->ops.flags = FTRACE_OPS_FL_SAVE_REGS | FTRACE_OPS_FL_IPMODIFY; /* ... */ }

The fh_ftrace_thunk () feature is our callback that ftrace will call when tracing the function. We’ll talk about this callback later. The flags are needed for hooking — they command ftrace to save and restore the processor registers whose contents we’ll be able to change in the callback.

Now we’re ready to turn on the hook. First, we use ftrace_set_filter_ip() to turn on the ftrace utility for the needed function. Second, we use register_ftrace_function() to give ftrace permission to call our callback:

int fh_install_hook(struct ftrace_hook *hook) { /* ... */ err = ftrace_set_filter_ip(&hook->ops, hook->address, 0, 0); if (err) { pr_debug("ftrace_set_filter_ip() failed: %d

", err); return err; } err = register_ftrace_function(&hook->ops); if (err) { pr_debug("register_ftrace_function() failed: %d

", err); /* Don’t forget to turn off ftrace in case of an error. */ ftrace_set_filter_ip(&hook->ops, hook->address, 1, 0); return err; } return 0; }

To turn off the hook, we repeat the same actions in reverse:

void fh_remove_hook(struct ftrace_hook *hook) { int err; err = unregister_ftrace_function(&hook->ops); if (err) { pr_debug("unregister_ftrace_function() failed: %d

", err); } err = ftrace_set_filter_ip(&hook->ops, hook->address, 1, 0); if (err) { pr_debug("ftrace_set_filter_ip() failed: %d

", err); } }

When the unregister_ftrace_function() call is over, it’s guaranteed that there won’t be any activations of the installed callback or our wrapper in the system. We can unload the hook module without worrying that our functions are still being executed somewhere in the system. Next, we provide a detailed description of the function hooking process.

Related services Kernel and Driver Development

Hooking functions with ftrace

So how can you configure kernel function hooking? The process is pretty simple: ftrace is able to alter the register state after exiting the callback. By changing the register %rip — a pointer to the next executed instruction — we can change the function executed by the processor. In other words, we can force the processor to make an unconditional jump from the current function to ours and take over control.

This is what the ftrace callback looks like:

static void notrace fh_ftrace_thunk(unsigned long ip, unsigned long parent_ip, struct ftrace_ops *ops, struct pt_regs *regs) { struct ftrace_hook *hook = container_of(ops, struct ftrace_hook, ops); regs->ip = (unsigned long) hook->function; }

We get the address of struct ftrace_hook for our function using a macro container_of() and the address of struct ftrace_ops embedded in struct ftrace_hook. Next, we substitute the value of the register %rip in the struct pt_regs structure with our handler’s address. For architectures other than x86_64, this register can have a different name (like PC or IP). The basic idea, however, still applies.

Note that the notrace specifier added for the callback requires special attention. This specifier can be used for marking functions that are prohibited for Linux kernel tracing with ftrace. For instance, you can mark ftrace functions that are used in the tracing process. By using this specifier, you can prevent the system from hanging if you accidentally call a function from your ftrace callback that’s currently being traced by ftrace.

The ftrace callback is usually called with a disabled preemption (just like kprobes), although there might be some exceptions. But in our case, this limitation wasn’t important since we only needed to replace eight bytes of %rip value in the pt_regs structure.

Since the wrapper function and the original are executed in the same context, both functions have the same restrictions. For instance, if you hook an interrupt handler, then sleeping in the wrapper is still out of the question.

Read also:

Anti Debugging Protection Techniques With Examples

Protection from recursive calls

There’s one catch in the code we gave you before: when the wrapper calls the original function, the original function will be traced by ftrace again, thus causing an endless recursion. We came up with a pretty neat way of breaking this cycle by using parent_ip — one of the ftrace callback arguments that contains the return address to the function that called the hooked one. Usually, this argument is used for building function call graphs. However, we can use this argument to distinguish the first traced function call from the repeated calls.

The difference is significant: during the first call, the argument parent_ip will point to some place in the kernel, while during the repeated call it will only point inside our wrapper. You should pass control only during the first function call. All other calls must let the original function be executed.

We can run the entry test by comparing the address to the boundaries of the current module with our functions. However, this approach works only if the module doesn’t contain anything other than the wrapper that calls the hooked function. Otherwise, you’ll need to be more picky.

So this is what a correct ftrace callback looks like:

static void notrace fh_ftrace_thunk(unsigned long ip, unsigned long parent_ip, struct ftrace_ops *ops, struct pt_regs *regs) { struct ftrace_hook *hook = container_of(ops, struct ftrace_hook, ops); /* Skip the function calls from the current module. */ if (!within_module(parent_ip, THIS_MODULE)) regs->ip = (unsigned long) hook->function; }

This approach has three main advantages:

Low overhead costs. You need to perform only several comparisons and subtractions without grabbing any spinlocks or iterating through lists.

You need to perform only several comparisons and subtractions without grabbing any spinlocks or iterating through lists. It doesn’t have to be global. Since there’s no synchronization, this approach is compatible with preemption and isn’t tied to the global process list. As a result, you can trace even interrupt handlers.

Since there’s no synchronization, this approach is compatible with preemption and isn’t tied to the global process list. As a result, you can trace even interrupt handlers. There are no limitations for functions. This approach doesn’t have the main kretprobes drawback and can support any number of trace function activations (including recursive) out of the box. During recursive calls, the return address is still located outside of our module, so the callback test works correctly.

In the next section, we take a more detailed look at the hooking process and describe how ftrace works.

The scheme of the hooking process

So, how does ftrace work? Let’s take a look at a simple example: you’ve typed the command Is in the terminal to see the list of files in the current directory. The command-line interpreter (say, Bash) launches a new process using the common functions fork() plus execve() from the standard C library. Inside the system, these functions are implemented through system calls clone() and execve() respectively. Let’s suggest that we hook the execve() system call to gain control over launching new processes.

Figure 1 below gives an ftrace example and illustrates the process of hooking a handler function.

Figure 1. Linux kernel hooking with ftrace.

In this image, we can see how a user process (blue) executes a system call to the kernel (red) where the ftrace framework (violet) calls functions from our module (green).

Below, we give a more detailed description of each step of the process:

The SYSCALL instruction is executed by the user process. This instruction allows switching to the kernel mode and puts the low-level system call handler entry_SYSCALL_64() in charge. This handler is responsible for all system calls of 64-bit programs on 64-bit kernels. A specific handler receives control. The kernel accomplishes all low-level tasks implemented on the assembler pretty fast and hands over control to the high-level do_syscall_64 () function, which is written in C. This function reaches the system call handler table sys_call_table and calls a particular handler by the system call number. In our case, it’s the function sys_execve (). Calling ftrace. There’s an __fentry__() function call at the beginning of every kernel function. This function is implemented by the ftrace framework. In the functions that don’t need to be traced, this call is replaced with the instruction nop. However, in the case of the sys_execve() function, there’s no such call. Ftrace calls our callback. Ftrace calls all registered trace callbacks, including ours. Other callbacks won’t interfere since, at each particular place, only one callback can be installed that changes the value of the %rip register. The callback performs the hooking. The callback looks at the value of parent_ip leading inside the do_syscall_64() function — since it’s the particular function that called the sys_execve() handler — and decides to hook the function, changing the values of the register %rip in the pt_regs structure. Ftrace restores the state of the registers. Following the FTRACE_SAVE_REGS flag, the framework saves the register state in the pt_regs structure before it calls the handlers. When the handling is over, the registers are restored from the same structure. Our handler changes the register %rip — a pointer to the next executed function — which leads to passing control to a new address. Wrapper function receives control. An unconditional jump makes it look like the activation of the sys_execve() function has been terminated. Instead of this function, control goes to our function, fh_sys_execve(). Meanwhile, the state of both processor and memory remains the same, so our function receives the arguments of the original handler and returns control to the do_syscall_64() function. The original function is called by our wrapper. Now, the system call is under our control. After analyzing the context and arguments of the system call, the fh_sys_execve() function can either permit or prohibit execution. If execution is prohibited, the function returns an error code. Otherwise, the function needs to repeat the call to the original handler and sys_execve() is called again through the real_sys_execve pointer that was saved during the hook setup. The callback gets control. Just like during the first call of sys_execve(), control goes through ftrace to our callback. But this time, the process ends differently. The callback does nothing. The sys_execve() function was called not by the kernel from do_syscall_64() but by our fh_sys_execve() function. Therefore, the registers remain unchanged and the sys_execve() function is executed as usual. The only problem is that ftrace sees the entry to sys_execve() twice. The wrapper gets back control. The system call handler sys_execve() gives control to our fh_sys_execve() function for the second time. Now, the launch of a new process is nearly finished. We can see if the execve() call finished with an error, study the new process, make some notes to the log file, and so on. The kernel receives control. Finally, the fh_sys_execve() function is finished and control returns to the do_syscall_64() function. The function sees the call as one that was completed normally, and the kernel proceeds as usual. Control goes to the user process. In the end, the kernel executes the IRET instruction (or SYSRET, but for execve() there can be only IRET), installing the registers for a new user process and switching the processor into user code execution mode. The system call is over and so is the launch of the new process.

As you can see, the process of hooking Linux kernel function calls with ftrace isn’t that complex. Now, it's time to focus on the ways you can protect your Linux kernel modules from ftrace hooks.

Read also:

How to Debug the Linux Kernel with QEMU and Libvirt

Protecting a Linux kernel module from ftrace hooks

Function hooks can be used for different purposes, from monitoring the performance of the system to patching a specific bug. But if you want to make sure that kernel module functionality remains unchanged, you need to be able to prevent the installation of any hooks.

So how can you protect a Linux kernel module from ftrace hooks? When thinking about possible solutions, we came up with two ideas:

Figure 2: Possible solutions for protecting kernel functions from ftrace hooks

Let’s consider these two approaches more closely:

Hooking ftrace functions . In this case, we would need to hook the ftrace function that can set hooks, such as ftrace_set_filter_ip or ftrace_set_hash . Then, theoretically, once the framework tried to hook a function from our module, we would be able to block it. We could use the addresses of our module functions from the .text section to distinguish our kernel module functions from other functions.

. In this case, we would need to hook the ftrace function that can set hooks, such as or . Then, theoretically, once the framework tried to hook a function from our module, we would be able to block it. We could use the addresses of our module functions from the .text section to distinguish our kernel module functions from other functions. Modifying ftrace structs . For this, we would need to delete all the information about our module functions that’s stored in the records and structs of the ftrace framework. Then, to make the blocking of ftrace hooks possible, we’d also need to fill the mcount records with nop instructions.

Let’s see which of these theories proves effective.

Kernel module protection from ftrace hooks in practice

We’ll start with a simple kernel module named TestModule. The name of the function that ftrace wants to hook is HookMe:

void HookMe(void) { KLOGI("Try to hook me"); }

Let’s try out the theory that seems to be the most logical: use ftrace hooks against themselves.

Hooking an ftrace hooking function

First, we need to set a hook for one of the ftrace functions responsible for hooking function calls. In our example, we try to hook the ftrace_set_hash function:

#define REGISTER_FUNC(NAME) {&NAME ## _handler, (unsigned long*)&NAME ## _orig, #NAME} struct SyscallHookInfo { void* callback; unsigned long* orig; unsigned char* name; }; extern int (*ftrace_set_hash_orig)(struct ftrace_ops *ops, unsigned char *buf, int len, unsigned long ip, int remove, int reset, int enable); static struct SyscallHookInfo g_hook = REGISTER_FUNC(ftrace_set_hash);

Our first step is getting the address of the ftrace_set_hash function:

*(g_hook.orig) = kallsyms_lookup_name(g_hook.name); if (!*(g_hook.orig)) { KLOGE("Failed to get address for %s.", g_hook.name); return -EFAULT; }

Then, we can try to register a hook for this ftrace function:

res = ftrace_set_filter_ip(ops, *(g_hook.orig), 0, 0); if (res < 0) { KLOGE("Failed to set hook for %s. Error: %d

", g_hook.name, res); return res; }

Unfortunately, this wasn’t successful. We got a message about an error that occurred when we tried to hook the ftrace_set_hash function:

[ 2978.777140] TestModule: SetFtraceHook: Failed to set hook for ftrace_set_hash. Error: -22

The reason why this error occured is quite simple: apparently, ftrace can’t be hooked with its own methods. The framework is protected from setting hooks in its critical functions. You can see it here:

if (!ftrace_location(ip)) return -EINVAL;

As a result, even though this option seemed the most obvious and logical solution to our problem, we can’t use it to protect our kernel module from ftrace function hooks.

Clearing ftrace records

Our next approach is a bit more cunning, since we need to delete some information from the ftrace records. The framework keeps all data about installed hooks in special ftrace pages. Each page is described by the ftrace_page struct.

struct ftrace_page { struct ftrace_page *next; struct dyn_ftrace *records; int index; int size; };

The size field of an ftrace page shows the size of the specific page in bytes. The index field displays the number of dyn_ftrace structs that this page contains, sorted by dyn_ftrace.ip.

The dyn_ftrace struct keeps the address (IP) of the mcount entry needed for setting a hook for a selected function. So to block the setting of a function hook, we need to delete the dyn_ftrace struct related to a specific function and then fill its mcount entry with a nop.

Once the dyn_ftrace struct is deleted, we’ll also need to shift other entries by one for the current ftrace page.

#define MAX_STUB_DISTANCE 30 const char g_nopCode[] = "\x90\x90\x90\x90\x90\x90\x90"; typedef int ftrace_cmp_recs_type(const void *a, const void *b); typedef struct ftrace_rec_iter *ftrace_rec_iter_start_type(void); struct { ftrace_cmp_recs_type *ftrace_cmp_recs; ftrace_rec_iter_start_type *ftrace_rec_iter_start; } g_helpers = {}; int ShiftFtraceStub(void *data) { struct NewFtraceStub* entry = data; int entrySize = sizeof(struct dyn_ftrace); int end = *(entry->index); int curr = 0; DisableWp(); /*Filling the mcount entry with the nop option*/ memcpy(entry->ip, g_nopCode, MCOUNT_INSN_SIZE); /*creating a loop for erasing the first entry and shifting all other entries by one*/ for(; curr < end - 1; curr++) { char* curEntry = entry->entryForDeleting + curr * entrySize; memcpy(curEntry, curEntry + entrySize, entrySize); } *entry->index = curr; RestoreWp(); return 0; } int res = -EADDRNOTAVAIL; struct NewFtraceStub data = {0}; struct ftrace_page *pg = NULL; struct ftrace_rec_iter *iter = NULL; struct dyn_ftrace *rec = NULL; struct dyn_ftrace key = {}; /*These functions are not listed in the Linux kernel headers, so we need to find them first*/ if (!g_helpers.ftrace_rec_iter_start) { g_helpers.ftrace_rec_iter_start = (void *)kallsyms_lookup_name("ftrace_rec_iter_start"); if (!g_helpers.ftrace_rec_iter_start) { KLOGE("Can't find ftrace_rec_iter_start"); goto exit; } } if (!g_helpers.ftrace_cmp_recs) { g_helpers.ftrace_cmp_recs = (void *)kallsyms_lookup_name("ftrace_cmp_recs"); if (!g_helpers.ftrace_cmp_recs) { KLOGE("Can't find ftrace_cmp_recs"); goto exit; } } key.ip = (unsigned long)HookMe; key.flags = key.ip + MAX_STUB_DISTANCE; iter = (*g_helpers.ftrace_rec_iter_start)(); for (pg = iter->pg; pg; pg = pg->next) { if (key.ip < pg->records[0].ip || key.flags >= (pg->records[pg->index - 1].ip + MCOUNT_INSN_SIZE)) { /*Searching the ftrace page for the dyn_ftrace struct related to our function*/ continue; } /*Searching our dyn_ftrace in the current page*/ rec = bsearch(&key, pg->records, pg->index, sizeof(struct dyn_ftrace), g_helpers.ftrace_cmp_recs); if (rec) { data = (struct NewFtraceStub) { .ip = HookMe, .index = &pg->index, .entryForDeleting = (char*)rec, }; res = stop_machine(ShiftFtraceStub, &data, 0); } }

We can use the following script to check if this approach works for protecting our kernel module from ftrace hooks:

dir=/sys/kernel/debug/tracing sysctl kernel.ftrace_enabled=1 echo function > ${dir}/current_tracer echo HookMe > /sys/kernel/debug/tracing/set_ftrace_filter echo 1 > ${dir}/tracing_on #TestBinary calls HookMe in the kernel space ./TestBinary echo 0 > ${dir}/tracing_on cat ${dir}/trace | grep HookMe

Here’s what we get when we don’t use this type of protection against ftrace hooks:

kernel.ftrace_enabled = 1 TestBinary-2465 [000] .... 275.733572: HookMe

However, when using this type of Linux kernel module protection, we get the following result:

sh: echo: I/O error TestBinary-3035 [000] .... 715.803182: printk <-HookMe

We’ll also receive the exact same error, sh: echo: I/O error, if the HookMe function isn’t loaded. This method works and can be used for protecting a Linux kernel module from ftrace hooks.

Related services Security Testing

Conclusion

Ftrace is a helpful framework that can be used for solving different tasks, from tracing kernel functions to setting function hooks. Apriorit developers use this tool regularly and keep expanding their knowledge of its capabilities. But in some cases, when you need to keep kernel functionality unchanged, you might want to protect your kernel module from ftrace hooks.

Even though the main purpose of ftrace is to trace Linux kernel function calls rather than hook them, our innovative approach turned out to be both simple and effective. However, the approach we describe above works only for kernel versions 3.19 and higher and only for the x86_64 architecture.

Since ftrace functions are securely protected from being hooked with ftrace methods, you’ll need a different technique for hooking ftrace functions and thereby protecting your kernel module. Nevertheless, we managed to find a solution.

All we had to do was delete the information about a specific function from ftrace records and then fill its mcount entry with an nop option. Once this was done, our kernel module was effectively protected from being hooked with the help of the ftrace framework.

In the third and final part of our series, we’ll tell you about the main ftrace pros and cons and some unexpected surprises that might be waiting for you if you decide to implement this approach. Meanwhile, you can read about another unusual solution for installing hooks — by using the GCC attribute constructor with LD_PRELOAD.