# 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 create a build directory, enter it and run ``cmake ..`` and then ``make``. This yields rewire's main functionality in a shared library, a command line tool and an exemplary wire kit.

Wire kits must be installed before they can be used with the command line tool. 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.

To shorten commands, any executable can directly link to the rewire's shared library and internally decide which commands to execute in an altered environment.

## 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**.