{"id":13452949,"url":"https://github.com/kubo/funchook","last_synced_at":"2025-03-24T00:32:41.904Z","repository":{"id":43673754,"uuid":"62488744","full_name":"kubo/funchook","owner":"kubo","description":"Hook function calls by inserting jump instructions at runtime","archived":false,"fork":false,"pushed_at":"2024-04-07T11:59:26.000Z","size":333,"stargazers_count":642,"open_issues_count":6,"forks_count":92,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-28T20:37:09.265Z","etag":null,"topics":["arm64","hook","hooking","x86-32","x86-64"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-03T08:54:05.000Z","updated_at":"2024-10-27T12:41:24.000Z","dependencies_parsed_at":"2023-12-16T14:30:17.802Z","dependency_job_id":"b6d6dd6e-439b-4932-bf1a-06d66f69a528","html_url":"https://github.com/kubo/funchook","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubo%2Ffunchook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubo%2Ffunchook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubo%2Ffunchook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubo%2Ffunchook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubo","download_url":"https://codeload.github.com/kubo/funchook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245191489,"owners_count":20575246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm64","hook","hooking","x86-32","x86-64"],"created_at":"2024-07-31T08:00:29.047Z","updated_at":"2025-03-24T00:32:41.659Z","avatar_url":"https://github.com/kubo.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"Funchook - an API hook library\n==============================\n\n[![tests](https://github.com/kubo/funchook/actions/workflows/run-tests.yml/badge.svg?branch=master)](https://github.com/kubo/funchook/actions/workflows/run-tests.yml)\n\nThis library depends on one of the following disassemblers.\n\nOn x86_64 and x86\n* [diStorm3][] (default)\n* [zydis][] (when `-DFUNCHOOK_DISASM=zydis` is passed to the `cmake` command)\n* [capstone][] (when `-DFUNCHOOK_DISASM=capstone` is passed to the `cmake` command)\n\nOn arm64\n* [capstone][]\n\nTODO\n----\n\n* write documents.\n\nNews\n----\n\n### 2.0.0 (20XX-XX-XX)\n\n* Add `funchook_prepare_with_params()` to support prehook.\n* Add `funchook_get_arg()` to get arguments in prehook.\n\n### 1.1.3 (2023-06-04)\n\n* Fix build for Windows with raw MSC ([#45][])\n* Fix debug log format warnings by mingw-w64 compiler.\n\n### 1.1.2 (2023-03-12)\n\n* Experimental support for Windows arm64\n\n### 1.1.1 (2022-10-02)\n\n* More permissive check for page allocation mmap ([#25][])\n* Flush instruction cache for arm64. It does nothing for intel CPU.\n* Disassember engine\n  * Upgrade capstone to 4.0.2\n  * Upgrade distorm to 3.5.2\n* CMake\n  * Allow user to specify FUNCHOOK_CPU explicitly ([#19][])\n  * Avoid polluting global include and link dirs ([#20][])\n  * Use target based compile options for gcc's -Wall ([#21][])\n  * Use ExternalProject_add to download captone only ([#30][])\n  * Add option FUNCHOOK_INSTALL ([#31][])\n  * Use \"FUNCHOOK_CPU MATCHES \u003cstring\u003e\" ([#32][])\n* Documentation\n  * added example usage from python ([#22][])\n* Fix tests on Android ([#29][])\n\n### 1.1.0 (2020-03-22)\n\n* Arm64 Linux support. [capstone][] is used as the disassembler library on arm64.\n* Options to use [zydis][] and [capstone][] as a disassembler library on x86_64 and x86.\n* `extern \"C\"` was added in funchook.h for C++. ([#15][])\n* Libc-compatible functions were removed to simplify code.\n\n### 1.0.0 (2020-01-19)\n\n* [diStorm3][] is used as the disassembler library.\n* Libc-compatible functions were implemented on Linux in order not to hook function calls issued by funchook itself.\n\nSupported Platforms\n-------------------\n\n* Linux x86_64\n* Linux x86\n* Linux arm64 (since 1.1.0)\n* macOS x86_64 (Functions in executables cannot be hooked when Xcode version \u003e= 11.0. (*1))\n* Windows x64 (except C-runtime functions under [Wine][])\n* Windows 32-bit\n\n*1 [`mprotect`] fails with EACCES.  \n\nTested Platforms\n----------------\n\nTested on some versions. Not tested in CI.\n\n* Windows arm64 (version 1.1.2)\n\nUnsupported Platforms\n---------------------\n\n* macOS arm64 (*1)\n* x64/x86 emulation for Windows arm64\n\n*1 I received a mail that [`mprotect`] failed with `EINVAL`. This issue may be same with [#51][] and fixed by [this commit](https://github.com/kubo/funchook/commit/d5faee56e9fb0b7798754692ed4f1ed5579c4759).\n\nCompilation and installation\n-----------\n\n### Unix\n\n```shell\n$ git clone --recursive https://github.com/kubo/funchook.git\n$ mkdir build\n$ cd build\n$ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/install/directory ../funchook\n$ make\n$ make install\n```\n\n* Available [`CMAKE_BUILD_TYPE`][] values are empty(default), `Debug`, `Release`, `RelWithDebInfo`(release build with debug information) and `MinSizeRel`.\n* When [`CMAKE_INSTALL_PREFIX`][] isn't set, funchook is installed at `/usr/local`.\n\n  installed files:\n  * `${CMAKE_INSTALL_PREFIX}/include/funchook.h` (header file)\n  * `${CMAKE_INSTALL_PREFIX}/lib/libfunchook.so` (symbolic link to `libfunchook.so.1`)\n  * `${CMAKE_INSTALL_PREFIX}/lib/libfunchook.so.1` ([soname][]; symbolic link to `libfunchook.so.1.1.0`)\n  * `${CMAKE_INSTALL_PREFIX}/lib/libfunchook.so.1.1.0` (shared library)\n  * `${CMAKE_INSTALL_PREFIX}/lib/libfunchook.a` (static library)\n\n### Windows\n\nHere is an example to compile funchook with Visual Studio 2017 Win64.\nChange the argument of `-G` to use other compilers.\n\n```shell\n$ git clone --recursive https://github.com/kubo/funchook.git\n$ mkdir build\n$ cd build\n$ cmake -G \"Visual Studio 15 2017 Win64\" -DCMAKE_INSTALL_PREFIX=c:\\path\\to\\install\\directory ..\\funchook\n$ cmake --build . --config Release --target INSTALL\n```\n\n* Available `-G` arguments (generators) are listed in the output of `cmake --help`.\n* Available `--config` arguments are `Debug`(default), `Release`, `RelWithDebInfo` and `MinSizeRel`.\n* When [`CMAKE_INSTALL_PREFIX`][] isn't set, funchook is installed at `c:\\Program Files\\funchook`.\n\n  installed files:\n  * `${CMAKE_INSTALL_PREFIX}\\include\\funchook.h` (header file)\n  * `${CMAKE_INSTALL_PREFIX}\\bin\\funchook.dll` (shared library)\n  * `${CMAKE_INSTALL_PREFIX}\\bin\\funchook.pdb` (debug file for `funchook.dll` when `--config` is `Debug` or `RelWithDebInfo`)\n  * `${CMAKE_INSTALL_PREFIX}\\lib\\funchook.lib` (static library)\n  * `${CMAKE_INSTALL_PREFIX}\\lib\\funchook_dll.lib` (import library for `funchook.dll`)\n\nExample\n-------\n\n```c\nstatic ssize_t (*send_func)(int sockfd, const void *buf, size_t len, int flags);\nstatic ssize_t (*recv_func)(int sockfd, void *buf, size_t len, int flags);\n\nstatic ssize_t send_hook(int sockfd, const void *buf, size_t len, int flags)\n{\n    ssize_t rv;\n\n    ... do your task: logging, etc. ...\n    rv = send_func(sockfd, buf, len, flags); /* call the original send(). */\n    ... do your task: logging, checking the return value, etc. ...\n    return rv;\n}\n\nstatic ssize_t recv_hook(int sockfd, void *buf, size_t len, int flags)\n{\n    ssize_t rv;\n\n    ... do your task: logging, etc. ...\n    rv = recv_func(sockfd, buf, len, flags); /* call the original recv(). */\n    ... do your task: logging, checking received data, etc. ...\n    return rv;\n}\n\nint install_hooks()\n{\n    funchook_t *funchook = funchook_create();\n    int rv;\n\n    /* Prepare hooking.\n     * The return value is used to call the original send function\n     * in send_hook.\n     */\n    send_func = send;\n    rv = funchook_prepare(funchook, (void**)\u0026send_func, send_hook);\n    if (rv != 0) {\n       /* error */\n       ...\n    }\n\n    /* ditto */\n    recv_func = recv;\n    rv = funchook_prepare(funchook, (void**)\u0026recv_func, recv_hook);\n    if (rv != 0) {\n       /* error */\n       ...\n    }\n\n    /* Install hooks.\n     * The first 5-byte code of send() and recv() are changed respectively.\n     */\n    rv = funchook_install(funchook, 0);\n    if (rv != 0) {\n       /* error */\n       ...\n    }\n}\n\n```\n\nExample - Using Python ctypes\n-----------------------------\n```python\n# should work on python 2.7/3 windows/linux\n\n# load funchook\nimport ctypes\nfh_lib = ctypes.cdll.LoadLibrary('/path/to/funchook/dll/or/so')\n\n# define signatures\nfunchook_create = fh_lib.funchook_create\nfunchook_create.restype = ctypes.c_void_p\nfunchook_create.argtypes = []\n\nfunchook_prepare = fh_lib.funchook_prepare\nfunchook_prepare.restype = ctypes.c_ssize_t\nfunchook_prepare.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p]\n\nfunchook_install = fh_lib.funchook_install\nfunchook_install.restype = ctypes.c_ssize_t\nfunchook_install.argtypes = [ctypes.c_void_p, ctypes.c_int]\n\nPySys_WriteStdout = ctypes.pythonapi.PySys_WriteStdout\nPySys_WriteStdout.restype = None\nPySys_WriteStdout.argtypes=[ctypes.c_char_p]\n\n# must keep those references alive, or stuff will be GC'd and weird errors will occur\nglobal orig_write, hook, orig_write_ptr\n\n# create hook (this function will replace the original function)\nhook_type = ctypes.PYFUNCTYPE(None, ctypes.c_char_p)\norig_write = None\ndef hook_impl(msg):\n    print('about to write: ' + str(msg)) # do what we want\n    orig_write(msg)                      # call the original function\n\nhook = hook_type(hook_impl)\n\nfh = funchook_create()\n# create a pointer object with the function address\norig_write_ptr = ctypes.c_void_p(ctypes.c_void_p.from_address(ctypes.addressof(PySys_WriteStdout)).value)\n# orig_write_ptr.value will get a ptr to the original PySys_WriteStdout and PySys_WriteStdout will now point to the hook\nret = funchook_prepare(fh, ctypes.addressof(orig_write_ptr), hook)\nassert not ret, 'ret is ' + str(ret)\nret = funchook_install(fh, 0)\nassert not ret, 'ret is ' + str(ret)\norig_write = hook_type.from_address(ctypes.addressof(orig_write_ptr))\nPySys_WriteStdout(b'hi there\\n')\n```\n\nLicense\n-------\n\nGPLv2 or later with a [GPL linking exception][].\n\nYou can use funchook in any software. Though funchook is licensed under\nthe GPL, it doesn't affect outside of funchook due to the linking exception.\nYou have no need to open your souce code under the GPL except funchook itself.\n\nIf you modify funchook itself and release it, the modifed part must be\nopen under the GPL with or without the linking exception because funchook\nitself is under the GPL.\n\n[diStorm3][] and [capstone][] are released under the 3-clause BSD license.\n[zydis][] is released under the MIT license. They are compatible with the GPL.\n\n[GPL linking exception]: https://en.wikipedia.org/wiki/GPL_linking_exception\n[diStorm3]: https://github.com/gdabah/distorm/\n[zydis]: https://github.com/zyantific/zydis\n[capstone]: https://github.com/aquynh/capstone\n[Wine]: https://www.winehq.org/\n[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html\n[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html\n[soname]: https://en.wikipedia.org/wiki/Soname\n[#15]: https://github.com/kubo/funchook/issues/15\n[#19]: https://github.com/kubo/funchook/pull/19\n[#20]: https://github.com/kubo/funchook/pull/20\n[#21]: https://github.com/kubo/funchook/pull/21\n[#22]: https://github.com/kubo/funchook/pull/22\n[#25]: https://github.com/kubo/funchook/pull/25\n[#29]: https://github.com/kubo/funchook/pull/29\n[#30]: https://github.com/kubo/funchook/pull/30\n[#31]: https://github.com/kubo/funchook/pull/31\n[#32]: https://github.com/kubo/funchook/pull/32\n[#45]: https://github.com/kubo/funchook/pull/45\n[#51]: https://github.com/kubo/funchook/issues/51\n[`mprotect`]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/mprotect.2.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubo%2Ffunchook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubo%2Ffunchook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubo%2Ffunchook/lists"}