22 lines
3.2 KiB
Markdown
22 lines
3.2 KiB
Markdown
# Rewire
|
|
Rewire is a command line tool for Linux that allows code to alter the system call behavior of programs, without changing the programs themselves. It leverages **ptrace** to detect when executables perform system calls and provides a convenient interface to wire kits, user-written libraries that contain code to be executed on system call entries and exits.
|
|
|
|
## Getting Started
|
|
This repository comes with a simple **Makefile** that does all the building for you. Rewire is written in a mixture of C and C++ and it requires compiler support for the C++-20 standard. It depends on no additional libraries.
|
|
|
|
Simply run ``make`` in this repository's main directory to build rewire's main executable and all exemplary wire kits. Alternatively, run ``make rewire`` or ``make wirekits`` to compile only the main executable or wire kits, respectively.
|
|
|
|
Wire kits must be installed before they can be used with rewire. This installation happens on a per-user basis. To install the provided ``example.so``, use ``rewire install example.so``. For convenience, rewire strips the ``.so`` from the name under which the installed wire kit is accessible, so this kit will be available under the name ``example``. To prevent this, or to choose a different alias for the installation altogether, use ``rewire install example.so alias``. No suffixes are truncated from aliases specified this way. A list of all installed wire kits can be printed with ``rewire list`` and each one can be removed using ``rewire uninstall kitName``.
|
|
|
|
To run commands in rewire, it can be launched in one of two modes. It can either execute a single command with ``rewire kitName command arguments`` or be launched in shell mode using ``rewire kitName``. The latter will initialize the wire kit once and listen for the user to input commands until ``exit`` is given.
|
|
|
|
## Wire Kits
|
|
To work with rewire, wire kits have to implement a set of functions specified in rewire's ``wirekit.hpp``.
|
|
- ``wirekit_prepare`` is called **once** (even in shell mode) when the kit is loaded.
|
|
- ``wirekit_command_start`` is called for every command that is executed. It can be used to reset kit-internal data between commands or initialize kit components based on the command and its arguments. Additionally, system call hooks should be installed from this function using e.g. ``rewire_syscall_hook`` (more information in ``wirekit.hpp``).
|
|
- ``wirekit_command_exit`` is called when a command finishes execution. This means that the command main process and all its children have terminated. Use it to clear or reset kit-internal data. Providing an implementation for this function is **optional**.
|
|
- ``wirekit_subject_start`` is called whenever a new child thread or process, created under the current command, performs its first system call and thus becomes relevant to the wire kit. Implementing this function is optional.
|
|
- ``wirekit_subject_exit`` is called whenever a child process or thread, under the current command, terminates. Implementing this function is optional.
|
|
|
|
To get a better understanding of how to use these functions, have a look at the exemplary wire kits. Finally, each wire kit must be compiled as position-independent shared object, as done in the **Makefile**.
|