Updated README
This commit is contained in:
parent
424065b4b5
commit
32a73df1cd
103
README.md
103
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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user