NAME¶

r_egg — radare2 egg shellcode generation library

SYNOPSIS¶

#include <r_egg.h>

DESCRIPTION¶

The r_egg library provides shellcode generation capabilities for radare2, allowing users to write shellcode in a high-level language and compile it to machine code. It supports multiple architectures and provides a framework for creating, compiling, and executing shellcode.

The core structure is REgg, which manages source code, compiled binary, assembler, syscall information, and language parsing.

INITIALIZATION¶

This section describes functions to create, initialize and free an REgg context and contains helpers to (re)configure the embedded language parser and state used during compilation. REgg * r_egg_new(void)

Creates a new egg context with default settings.

void r_egg_free(REgg *egg)

Frees all resources associated with the egg context. Pp void r_egg_reset(REgg *egg)

Resets the egg context state so it can be reused for a new compilation.

char * r_egg_tostring(REgg *egg)

Returns a textual representation of the egg internal state (for debugging).

void r_egg_lang_init(REgg *egg)

Initializes the embedded language parser state (`egg->lang`).

void r_egg_lang_free(REgg *egg)

Frees resources allocated by the embedded language parser.

bool r_egg_setup(REgg *egg, const char *arch, int bits, int endian, const char *os)

Configures the egg context for the specified architecture, bitness, endianness, and operating system.

LOADING CODE¶

Functions to load egg source from strings or files, append fragments, and manage include paths and ancillary source used during compilation. void r_egg_load(REgg *egg, const char *code, int format)

Loads source code into the egg context. `format` indicates input style (egg/c).

void r_egg_append(REgg *egg, const char *src)

Appends additional source code to the egg context.

COMPILATION¶

Compilation is generally a two-step process: parse/compile the egg language into an intermediate representation, then assemble that IR into machine code. This section lists helpers for both stages and utilities to obtain assembly listings for inspection. bool r_egg_compile(REgg *egg)

Compiles the loaded source code into intermediate representation.

bool r_egg_assemble(REgg *egg)

Assembles the compiled code into machine code.

bool r_egg_assemble_asm(REgg *egg, char **asm_list)

Assembles the code and returns the assembly listing in `asm_list`.

EXECUTION¶

Functions that run the generated shellcode either directly or via a ROP execution helper; frontends use these to invoke or emulate the generated payload. int r_egg_run(REgg *egg)

Executes the compiled shellcode.

int r_egg_run_rop(REgg *egg)

Executes the shellcode using ROP (Return-Oriented Programming) techniques.

OUTPUT¶

Functions to access compilation results: the raw binary buffer, the original source text, and the emitted assembly listing. These are commonly used by frontends to print, save or further process the produced artifacts. RBuffer * r_egg_get_bin(REgg *egg)

Returns the compiled binary code as a buffer.

char * r_egg_get_source(REgg *egg)

Returns the source code.

char * r_egg_get_assembly(REgg *egg)

Returns the assembly representation of the compiled code.

SYSCALLS¶

Helpers to insert syscall invocations and to manage syscall-related language state (argument marshaling, syscall table entries and emitted code). void r_egg_syscall(REgg *egg, const char *arg, ...)

Adds a syscall instruction to the shellcode.

MEMORY MANAGEMENT¶

Functions to reserve and manipulate data used by generated code: allocate space, place strings and manage small data patches emitted into the output buffer. void r_egg_alloc(REgg *egg, int n)

Allocates memory in the shellcode.

CONTROL FLOW¶

Labeling, branching and conditional helpers used by the egg language to implement control flow constructs such as labels, if/while blocks and simple arithmetic operations. void r_egg_label(REgg *egg, const char *name)

Defines a label in the shellcode.

void r_egg_if(REgg *egg, const char *reg, char cmp, int v)

Adds a conditional statement.

RAW CODE¶

Low-level helpers to insert raw bytes or preassembled snippets directly into the output buffer for cases where the high-level language cannot express a pattern or when hand-crafted machine code is required. bool r_egg_raw(REgg *egg, const ut8 *b, int len)

Inserts raw binary code into the shellcode.

ENCODING¶

Encoder and shellcode-template helpers. Encoders transform the produced binary (for obfuscation or packing) while shellcode templates provide parameterizable payloads and generators that frontends may select. bool r_egg_encode(REgg *egg, const char *name)

Applies an encoder to the shellcode.

bool r_egg_shellcode(REgg *egg, const char *name)

Generates shellcode using a specific shellcode template.

PATCHING¶

Binary patching helpers to apply small modifications to the compiled output (bytes, words, qwords). The CLI uses these to apply user-specified patches before finalizing output. bool r_egg_patch(REgg *egg, int off, const ut8 *b, int l)

Patches the compiled binary at the specified offset. Use `-1` for append.

PLUGINS¶

The plugin framework used to extend r_egg with shellcode generators and encoders. Hosts discover and register plugin implementations which are then invoked during compilation or encoding phases. bool r_egg_plugin_add(REgg *a, REggPlugin *plugin)

Adds an egg plugin (encoder or shellcode generator).

bool r_egg_plugin_remove(REgg *a, REggPlugin *plugin)

Removes an egg plugin.

OPTIONS¶

Key/value configuration used to control compilation and encoding behavior (selected encoder, padding, chosen shellcode template and auxiliary keys used by plugins). void r_egg_option_set(REgg *egg, const char *k, const char *v)

Sets an option for the egg context.

char * r_egg_option_get(REgg *egg, const char *k)

Gets an option value from the egg context.

INCLUDES¶

Include helpers to load files or strings (for example C headers or inline code) referenced by egg source. Also contains helpers to manage include search paths used by the preprocessor. bool r_egg_include(REgg *egg, const char *file, int format)

Includes a file in the egg compilation.

bool r_egg_include_str(REgg *egg, const char *arg)

Includes a string in the egg compilation.

void r_egg_lang_include_path(REgg *egg, const char *path)

Adds an include path used by the egg preprocessor.

void r_egg_lang_include_init(REgg *egg)

Initializes include-related state (called at setup time by hosts).

FINALIZATION¶

Finalizers and convenience helpers called after compilation to finish transformations, apply padding/encoders and release temporary resources. void r_egg_finalize(REgg *egg)

Finalizes the egg compilation process.

void r_egg_printf(REgg *egg, const char *fmt, ...)

Printf-style helper to append formatted text to the current egg output (used by emitters/plugins during code generation).

void r_egg_option_set(REgg *egg, const char *k, const char *v)

Helper noted above; kept here to emphasize lifecycle usage by frontends.

EXAMPLES¶

Basic shellcode generation:

REgg *egg = r_egg_new();
r_egg_setup(egg, "x86", 32, 0, "linux");
r_egg_load(egg, "write(1,
r_egg_compile(egg);
r_egg_assemble(egg);
RBuffer *bin = r_egg_get_bin(egg);

Using syscalls:

r_egg_syscall(egg, "exit", 0);

Adding raw code:

ut8 code[] = {0x90, 0x90}; // NOP NOP
r_egg_raw(egg, code, 2);

SEE ALSO¶

r_asm(3), r_syscall(3)