https://github.com/rafael-santiago/kook

A syscall hooking system for FreeBSD, NetBSD and also Linux.
https://github.com/rafael-santiago/kook

capture-the-flag freebsd-kld hackathon hacking hacking-tool hooking kernel linux-kernel-module netbsd-kernel-module rootkit

Last synced: about 2 months ago
JSON representation

A syscall hooking system for FreeBSD, NetBSD and also Linux.

• Host: GitHub
• URL: https://github.com/rafael-santiago/kook
• Owner: rafael-santiago
• License: gpl-2.0
• Created: 2017-12-07T15:40:51.000Z (about 7 years ago)
• Default Branch: master
• Last Pushed: 2021-11-14T16:55:56.000Z (about 3 years ago)
• Last Synced: 2023-08-29T19:21:27.120Z (over 1 year ago)
• Topics: capture-the-flag, freebsd-kld, hackathon, hacking, hacking-tool, hooking, kernel, linux-kernel-module, netbsd-kernel-module, rootkit
• Language: C
• Homepage:
• Size: 40 KB
• Stars: 15
• Watchers: 5
• Forks: 4
• Open Issues: 0
• Metadata Files:
  • Readme: README
  • License: COPYING

Awesome Lists containing this project

README

        
Kook

----

What is this?

-------------

Kook is just a simple code for system call hooking. It works on FreeBSD, NetBSD and also Linux.

How can I clone it?

-------------------

Pretty simple:

    you@somewhere_over_the_rainbow:~/src# git clone https://github.com/rafael-santiago/kook

    you@somewhere_over_the_rainbow:~/src# cd kook

    you@somewhere_over_the_rainbow:~/src/kook# git submodule update --init

or by doing all at once:

    you@somewhere_over_the_rainbow:~/src# git clone https://github.com/rafael-santiago/kook --recursive

How can I build it?

-------------------

You should not "build" anything, however if you want to run the kook's tests you need my build system

(https://github.com/rafael-santiago/hefesto).

Once this build system well installed, all you should do is to clone another repo of mine called helios

(https://github.com/rafael-santiago/helios):

    you@somewhere_over_the_rainbow:~/src# git clone https://github.com/rafael-santiago/helios

After cloning it...

#if defined(__FreeBSD__)

    you@somewhere_over_the_rainbow:~/src# cd helios

    you@somewhere_over_the_rainbow:~/src/helios# hefesto --install=freebsd-module-toolset

#elif defined(__linux__)

    you@somewhere_over_the_rainbow:~/src# cd helios

    you@somewhere_over_the_rainbow:~/src/helios# hefesto --install=lnx-module-toolset

#elif defined(__NetBSD__)

    you@somewhere_over_the_rainbow:~/src# cd helios

    you@somewhere_over_the_rainbow:~/src/helios# hefesto --install=netbsd-module-toolset

#endif

    you@somewhere_over_the_rainbow:~/src/helios# cd ..

    you@somewhere_over_the_rainbow:~/src# rm -rf helios

Now you enter into kook's src sub-directory and call hefesto from there:

    you@somewhere_over_the_rainbow:~/src# cd kook/src

    you@somewhere_over_the_rainbow:~/src/kook/src# hefesto

Some tests will run and you will get an output like the following (when all is ok...):

    *** kook_test_monkey loaded...

    -- running get_syscall_table_addr_test...

    -- passed.

    -- running hook_test...

    -- passed.

    -- running unhook_test...

    -- passed.

    *** all tests passed. [3 test(s) ran]

    *** kook_test_monkey unloaded.

    BUILD INFO: All done.

How can I use this hooking stuff with my own kernel mode stuff?

---------------------------------------------------------------

I have done this repo taking in consideration the FreeBSD, NetBSD and Linux kernel programmers, so the best way of

using this code with your own stuff is by including the kook's src sub-directory and the kook's platform dependent

code directory (by the way, named with your current platform name).

Hooking with kook is a thing that can be done even by an earthworm, look:

    // Your precious code stuff...

    #include  // Include the main kook's header file.

    void *original_syscall = NULL;

    (...)

    // Hooking.

    if (kook(sys_call_constant, your_hook_function, &original_syscall) != 0) {

        // Some error has occurred during the syscall hook.

    }

    (...)

    // Unhooking.

    if (kook(sys_call_constant, original_syscall, NULL) != 0) {

        // Some error has occurred during the syscall unhooking and I think (just think...)

        // you should not unload this module.

    }

If you have no intentions of unhooking, when hooking you can pass the original function pointer as NULL:

    if (kook(sys_call_constant, your_hook_function, NULL) != 0) {

        // Some error has occurred during the syscall hook.

    }

On Linux I have tested and designed it for 4.4.x kernels or (maybe) higher versions. Until now it is currently

supporting kernels higher than 5.7.0, too. However is easy to make it usable in older versions.