Self-Modifying Code

A collection of working demonstrations of self-modifying code techniques, built for educational and defensive security research purposes.

Research Disclaimer: This repository contains code that demonstrates techniques historically associated with malware (polymorphic engines, runtime code patching, JIT shellcode execution). Every example uses benign payloads (printing messages, returning numbers, string manipulation). The code is provided strictly for educational purposes: understanding how these techniques work is essential for building effective defenses, writing detection signatures, and conducting security research.

Do not use these techniques for malicious purposes. The authors are not responsible for misuse. If you work in security, you already know that understanding the offense is prerequisite to building the defense.

Table of Contents

• Quines — Self-reproducing programs
• Polymorphic Code — Code that mutates its own representation
• Runtime Code Generation — JIT compilation, self-patching, metaprogramming
• Technical Documentation
• Building and Running
• Project Structure

Quines

Self-reproducing programs — programs that output their own source code with no input. A quine is the simplest form of self-referential code and the conceptual foundation of all self-modifying techniques.

File	Language	Run
quines/quine.py	Python	python3 quines/quine.py
quines/quine.c	C	gcc -Wno-format-security -o quine quines/quine.c && ./quine
quines/quine.rs	Rust	rustc quines/quine.rs -o quine_rs && ./quine_rs
quines/quine.sh	Bash	bash quines/quine.sh

Verify any quine reproduces itself:

# Python
python3 quines/quine.py | diff - quines/quine.py

# C
gcc -Wno-format-security -o quine quines/quine.c && ./quine | diff - quines/quine.c

# Rust
rustc quines/quine.rs -o quine_rs && ./quine_rs | diff - quines/quine.rs

# Bash
bash quines/quine.sh | diff - quines/quine.sh

If diff produces no output, the quine is correct.

Polymorphic Code

Programs that change their own representation while preserving behavior.

File	Description	Run
polymorphic/poly_engine.py	Python AST-level polymorphic engine — generates mutated function variants with different source/bytecode but identical output	python3 polymorphic/poly_engine.py
polymorphic/poly_xor.c	XOR-based polymorphic encoder/decoder — each run produces a unique key, unique encoded bytes, and a unique decoder stub	gcc -o poly_xor polymorphic/poly_xor.c && ./poly_xor

See polymorphic/README.md for detailed explanations.

Runtime Code Generation

Programs that create and execute code that doesn't exist at compile time.

File	Description	Compile & Run
runtime_codegen/jit_hello.c	Minimal JIT compiler — writes x86-64 machine code into mmap'd memory and executes it	gcc -o jit_hello runtime_codegen/jit_hello.c && ./jit_hello
runtime_codegen/self_patch.c	Runtime self-patching — modifies a function's machine code to change its return value	gcc -O0 -o self_patch runtime_codegen/self_patch.c && ./self_patch
runtime_codegen/metaprogram.py	Python metaprogramming — generates a complete class from a config dictionary at runtime	python3 runtime_codegen/metaprogram.py

See runtime_codegen/README.md for detailed explanations.

Technical Documentation

docs/TECHNIQUES.md — Comprehensive technical writeup covering:

• How each technique works at the system level
• Legitimate applications in production software
• How each technique can be (and has been) abused
• Defensive mitigations and detection strategies

Building and Running

Prerequisites

• C compiler: GCC (or Clang)
• Rust compiler: rustc (for the Rust quine only)
• Python 3.10+: for the Python demos
• Platform: x86-64 Linux (the JIT and self-patching demos use Linux syscalls and x86-64 machine code)

Build Everything

# Quines
gcc -Wno-format-security -o quines/quine quines/quine.c
rustc quines/quine.rs -o quines/quine_rs

# Polymorphic
gcc -o polymorphic/poly_xor polymorphic/poly_xor.c

# Runtime codegen
gcc -o runtime_codegen/jit_hello runtime_codegen/jit_hello.c
gcc -O0 -o runtime_codegen/self_patch runtime_codegen/self_patch.c

Run Everything

# Quines (verify they reproduce themselves)
python3 quines/quine.py | diff - quines/quine.py
quines/quine | diff - quines/quine.c
quines/quine_rs | diff - quines/quine.rs
bash quines/quine.sh | diff - quines/quine.sh

# Polymorphic demos
python3 polymorphic/poly_engine.py
polymorphic/poly_xor

# Runtime codegen demos
runtime_codegen/jit_hello
runtime_codegen/self_patch
python3 runtime_codegen/metaprogram.py

Project Structure

self-modifying-code/
├── README.md                          # This file
├── LICENSE                            # MIT License
├── quines/                            # Self-reproducing programs
│   ├── quine.py                       # Python quine
│   ├── quine.c                        # C quine
│   ├── quine.rs                       # Rust quine
│   └── quine.sh                       # Bash quine
├── polymorphic/                       # Polymorphic code demos
│   ├── README.md                      # Technique explanation
│   ├── poly_engine.py                 # Python AST polymorphic engine
│   └── poly_xor.c                     # XOR polymorphic encoder/decoder
├── runtime_codegen/                   # Runtime code generation
│   ├── README.md                      # Technique explanation
│   ├── jit_hello.c                    # Minimal x86-64 JIT compiler
│   ├── self_patch.c                   # Runtime binary self-patching
│   └── metaprogram.py                 # Python metaprogramming
└── docs/
    └── TECHNIQUES.md                  # Deep technical writeup

License

MIT — see LICENSE.