# Selfpatch SLR

Selfpatch SLR (SPSLR) is a research prototype that implements **structure layout randomization (SLR)** for C programs on **x86_64 Linux**.

The system instruments compilation to collect metadata about structure layouts and accesses, compiles that metadata into a descriptor data section before linking, embeds that data into the final binary, and applies randomized layouts at runtime through a self-patching mechanism.

---

## Overview

SPSLR introduces controlled randomness into the in-memory layout of C structures. Instead of relying on fixed field offsets, programs are compiled together with metadata that allows rewriting those offsets at startup.

The workflow consists of:

1. Collecting structure and access metadata during compilation
2. Compiling metadata into a descriptor data section before linking
3. Embedding the descriptor data into the executable
4. Applying layout randomization and updating references at startup

---

## Architecture

SPSLR consists of three main components:

### `pinpoint` — GCC plugin

The `spslr_pinpoint` plugin runs during compilation and emits `.spslr` metadata files for each compilation unit.

It tracks:

* structure definitions
* field accesses
* relevant data references

The plugin requires two arguments:

* `metadir` — output directory for metadata
* `srcroot` — source root directory

---

### `patchcompile` — pre-link patch compiler

The `spslr_patchcompile` tool consumes `.spslr` metadata files and produces an assembly file containing the SPSLR descriptor data section.

Responsibilities:

* merge metadata across compilation units
* group compatible targets
* generate descriptors for targets, data references, and instruction accesses
* emit an assembly representation of the descriptor data section

The generated assembly is assembled into an object file and linked into the final executable.

---

### `selfpatch` — runtime patcher

The `spslr_selfpatch` static library applies runtime transformations based on the embedded descriptor data.

It exposes a single entry point:

```c
void spslr_selfpatch(void);
```

At startup, this function:

* locates and parses the embedded descriptor data
* randomizes structure layouts
* patches instruction operands and data references
* finalizes execution before normal program logic continues

---

## Repository Structure

* `pinpoint/` — GCC plugin for metadata extraction
* `patchcompile/` — pre-link patch compiler
* `selfpatch/` — runtime patch execution library
* `subject/` — example target demonstrating integration
* `docs/` — additional documentation and notes

---

## Requirements

### Platform

* x86_64 Linux

### Toolchain

* `gcc-16`
* `g++-16`

The repository includes GCC patch files used to preserve structure-access expressions required by SPSLR metadata collection.

---

## Building the Custom GCC Toolchain

SPSLR relies on a custom GCC build so that `offsetof`-style structure access expressions remain observable to the plugin infrastructure.

```bash
git clone git://gcc.gnu.org/git/gcc.git
cd gcc
git checkout basepoints/gcc-16
git am /path/to/selfpatch-slr/gcc_component_ref.patch
cd ..

mkdir gcc-build
cd gcc-build
../gcc/configure \
  --enable-host-shared \
  --prefix=/usr/local/gcc-16 \
  --program-suffix=16 \
  --enable-languages=c,c++ \
  --enable-plugin \
  --disable-multilib \
  --disable-werror \
  --disable-bootstrap \
  --disable-libsanitizer \
  --disable-libquadmath \
  --disable-libvtv
make -j$(nproc)
sudo make install

sudo ln -s /usr/local/gcc-16/bin/gcc16 /usr/local/bin/gcc-16
sudo ln -s /usr/local/gcc-16/bin/g++16 /usr/local/bin/g++-16
```

Verify installation:

```bash
gcc-16 --version
g++-16 --version
```

---

## Build

```bash
mkdir build
cd build
cmake ..
make -j$(nproc)
```

This builds:

* `spslr_pinpoint`
* `spslr_patchcompile`
* `spslr_selfpatch`
* the example `subject` executable

---

## Integration Workflow

To integrate SPSLR into a project:

1. Compile all source files using the `spslr_pinpoint` plugin
2. Provide `metadir` and `srcroot` plugin arguments
3. Collect generated `.spslr` metadata files
4. Run `spslr_patchcompile` to produce descriptor data assembly
5. Assemble the generated assembly into an object file
6. Link the object together with:

   * compiled program objects
   * `spslr_selfpatch`
7. Call `spslr_selfpatch()` early in program startup

---

## Example

The `subject` target demonstrates the full pipeline:

* compiles sources with the plugin
* generates metadata
* builds the SPSLR descriptor data section
* links the data into the executable
* calls `spslr_selfpatch()` at the start of `main()`

The example performs operations on randomized structures and accesses both local and global data after patching.

---

## Limitations

* Platform support: **x86_64 Linux**
* Requires a **custom GCC 16 toolchain**
* Structure layout randomization alters standard memory layout assumptions

Code that relies on fixed structure layouts, manual offset calculations, or layout-dependent casting may not behave correctly under SPSLR.

---

## Notes

SPSLR is a research platform for exploring structure layout randomization and its implications for systems programming, security, and compiler-assisted transformations.