# 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 patch program before linking, embeds that program 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 patch program before linking  
3. Embedding the patch program into the executable  
4. Executing the patch program at startup to randomize layouts and update references  

---

## 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 patch program.

Responsibilities:
- merge metadata across compilation units  
- group compatible targets  
- generate patch instructions  
- emit an assembly representation of the patch program  

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

---

### `selfpatch` — runtime patcher

The `spslr_selfpatch` static library executes the embedded patch program at runtime.

It exposes a single entry point:

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

At startup, this function:
- loads the embedded patch program  
- 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 a patch program assembly file  
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 patch program  
- links the program 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.