From 32a73df1cdf56af27e13cde64e2b549498b9bd16 Mon Sep 17 00:00:00 2001 From: York Jasper Niebuhr Date: Wed, 8 Apr 2026 12:08:15 +0200 Subject: [PATCH] Updated README --- README.md | 103 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 54 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index e77f3b5..2eb403f 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ - # 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. +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. --- @@ -13,10 +12,10 @@ SPSLR introduces controlled randomness into the in-memory layout of C structures 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 +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 --- @@ -29,25 +28,28 @@ SPSLR consists of three main components: 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 + +* structure definitions +* field accesses +* relevant data references The plugin requires two arguments: -- `metadir` — output directory for metadata -- `srcroot` — source root directory + +* `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. +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 patch instructions -- emit an assembly representation of the patch program + +* 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. @@ -55,7 +57,7 @@ The generated assembly is assembled into an object file and linked into the fina ### `selfpatch` — runtime patcher -The `spslr_selfpatch` static library executes the embedded patch program at runtime. +The `spslr_selfpatch` static library applies runtime transformations based on the embedded descriptor data. It exposes a single entry point: @@ -64,20 +66,21 @@ 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 + +* 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 +* `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 --- @@ -85,12 +88,12 @@ At startup, this function: ### Platform -- x86_64 Linux +* x86_64 Linux ### Toolchain -- `gcc-16` -- `g++-16` +* `gcc-16` +* `g++-16` The repository includes GCC patch files used to preserve structure-access expressions required by SPSLR metadata collection. @@ -147,10 +150,11 @@ make -j$(nproc) ``` This builds: -- `spslr_pinpoint` -- `spslr_patchcompile` -- `spslr_selfpatch` -- the example `subject` executable + +* `spslr_pinpoint` +* `spslr_patchcompile` +* `spslr_selfpatch` +* the example `subject` executable --- @@ -158,15 +162,16 @@ This builds: 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 +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 + + * compiled program objects + * `spslr_selfpatch` +7. Call `spslr_selfpatch()` early in program startup --- @@ -174,11 +179,11 @@ To integrate SPSLR into a project: 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()` +* 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. @@ -186,9 +191,9 @@ The example performs operations on randomized structures and accesses both local ## Limitations -- Platform support: **x86_64 Linux** -- Requires a **custom GCC 16 toolchain** -- Structure layout randomization alters standard memory layout assumptions +* 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.