Using an LLVM Pass to modify Rust code at the LLVM IR level to make vtables relative and avoid relocations.

As I said in the previous blog posts, trait object are going to be a problem. But first, we have to understand what they are.

Generics and Trait Objects

Rust has some features for generic types. Generic allows you to write one piece of code, and use it with different types and structures. But we have to differentiate between static generic behavior and dynamic generic behavior.

Static generic behavior

Let's take the example of the Rust book for generic behavior:

fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

Here, we can see the largest function is generic over some type T, which have to implement the std::cmp::PartialOrd trait. This trait allows you to redefine the > operator so that it calls the gt function of the trait. So the type you will use the largest function with have to implement this trait, otherwise you will face a compiler error, telling you it doesn't.

But that's not the point. What's interesting to understand here is that we face static generic behavior. This means that when, in the main function, we use the largest function with i32 and then with chars, there is actually two different functions that end up in your binary. One for i32 and one for chars, and call to the largest function is replaced to a call to the right function with the right arguments. Basically, this means that your code would now look like this:

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
}

So, as you can see, after the compiler analyses your code, no generic behavior is being executed at runtime, everything is handled at compile time for you. This kind of generic behavior is not a problem for shellcode compatibility, since the above code would be totally fine inside our shellcode template. Problem arises from dynamic generic behavior.

Dynamic generic behavior or trait object

Now what happens when using trait objects. Trait objects are another kind of generic behavior that resolves at runtime. Instead of creating as many instances as needed for a specific code that uses generic, that specific code actually handles every case possible in the same function, at runtime. This is called dynamic dispatch.

It's the same concept with virtual method in C++. When having parent and child classes having their own implementation of a virtual function, when you hold a reference or a pointer to the Base class, but that could actually be a pointer to the base or child class, then the call to the virtual function goes through what is called a vtable to call the right function on the actual object we are holding a pointer to. For those who know about this behavior in C++, trait objects are exactly the same. But for those who don't, let's take an example in Rust:

trait SharedBehavior {
    fn name(&self) -> &str;
}

struct Struct1 {
    name: String,
}

impl SharedBehavior for Struct1 {
    fn name(&self) -> &str {
        &self.name
    }
}

struct Struct2 {
    name: String,
}

impl SharedBehavior for Struct2 {
    fn name(&self) -> &str {
        &self.name
    }
}

fn print_name(structure: &dyn SharedBehavior) {
    println!("Name: {}", structure.name());
}

fn main() {
    let struct1 = Struct1 { name: String::from("Struct1") };
    let struct2 = Struct2 { name: String::from("Struct2") };

    print_name(&struct1);
    print_name(&struct2);
}

Okay, so we have a trait called SharedBehavior and two structures, Struct1 and Struct2, that just have a name field that represents the structure's name and that implements the SharedBehavior trait. Then, we have a function print_name, that takes a &dyn SharedBehavior. This is where all the magic happens. Remember what we said earlier, if we had put this code:

fn print_name(structure: &impl SharedBehavior) {
    println!("Name: {}", structure.name());
}

The &impl SharedBehavior is just syntactic sugar to no have to declare specifically a generic type T, but it does exactly the same as declaring the T generic type and defining it like the first example of this post. So with this code, we would have ended up with two different functions, one that takes a Struct1 and one that takes a Struct2. But here, we used the dyn keyword, which specifically says we want dynamic dispatch, meaning we only have one function that takes care of resolving the right name function according to the actual object passed to it as argument. But how does it do that? Thanks to virtual tables.

Virtual Tables

A virtual table is a table holding pointers to the implementation of functions. For example here, we specifically asked for dynamic dispatch over the SharedBehavior trait. So the print_name function will receive a specific value as argument.

Normally, a function that takes a structure as argument receives a reference to this structure directly, so that it can work on it. But the print_name function does not take a structure directly as argument, it takes what we call a trait object, here meaning any object that actually implements this trait. So what does it receive? It receives what we call a fat pointer. A fat pointer in Rust, is a structure holding two pointers. One that points to the object itself and the other that points to the virtual table of some trait that this object implements, here SharedBehavior. Here is a drawing which will help understand:

Note how the vtable is constructed, it will be useful later:

• Drop function: The first field is a pointer toward the drop function for this structure. Sometimes, on certain object, you will have a specific drop function that will correctly free the memory used by the object. This function may not exist, and if that's the case, this pointer will be null

• Size: This field represents the size in memory that the object takes. It might be needed for example by the drop function to properly deallocate the right amount of memory when destroying the object

• Alignment: This field represents the alignment in memory of the object. Also needed by operations dealing on memory (allocation, deallocation, ...)

Note that every field are 8 byte long.

After that, you have pointers to the functions of the trait this vtable refers to. So, our print_name function will actually do the following to call the right name function: Get the second pointer of the fat pointer and follow it. Offset this pointer by the number of bytes necessary to hit the pointer to the name function inside the vtable. Get the function pointer and call it to call the right name function. The offset is actually decided by the compiler: It decides that the name function will be at offset 24, the first function pointer after the alignment field. Then for each call to the name function on a trait object for SharedBehavior, it knows it has to offset inside the vtable by 24.

What you need to understand is that one vtable will be generated per structure implementing the SharedBehavior trait. So here, you will have one vtable for Struct1 structure and one vtable for Struct2 structure, each one with different pointers and values for each of its field. But every Struct1 object will share the same vtable though, because they all need the exact same values since the drop function, the size, the alignment and the name function pointer will all be the same for every object of the Struct1 structure.

Okay so now you understand how VTables work. You might see where the problem is then. VTables holds pointer i.e. absolute addresses towards functions... It generates relocations of course! That's our problem. Remember what we said about relocations, if we have an absolute address inside our binary, it will be computed from the preferred loaded address put by the compiler. But if the OS can't load our binary to this address, then all absolute addresses becomes obsolete and needs to be fixed. Therefore, it breaks shellcode, because we can't know in advance where we are going to be loaded.

And the problem is: the core and alloc libraries may sometimes use, on certain structures, trait objects, which will resolve into vtables. The closest example of this is the format! macro. At some point, it uses a trait object on the Write Trait. And it's quite bothering, because it would mean that not all parts the core and alloc libraries can be used. We would have to test every import inside these crates and verify it doesn't generate vtables.

But, I saw on the clang compiler for C++, a flag that might be interesting: -fexperimental-relative-c++-abi-vtables. It specifically tells the compiler to generate vtables with relative offset to function instead of absolute pointers. This might be exactly what we need.

Okay, so relative vtables do exists... but only in C++, with an experimental flag of the Clang compiler frontend. Clang uses LLVM as backend for the code generation part. Turns out, Rust also uses LLVM as part of its backend. I tried to see if there was any way to enable the same behavior, at the LLVM level though. I didn't find any. However, LLVM allows you to write scripts for optimizations. The solution might reside in these scripts But first, what is LLVM really?

LLVM

When it comes to compiler, there are different parts of it. Usually you have what we call a frontend and a backend. The frontend takes care of parsing your code and turn it into an intermediate representation. The backend actually turns this intermediate representation into assembly that targets a specific processor architecture: x86, ARM, etc...

For example, Clang is the C++ frontend that uses LLVM as a backend. LLVM provides what is called LLVM IR, LLVM's own Intermediate representation. It is a language that sits between your code and assembly. It is hardware-agnostic, and also language agnostic. So Clang turns C++ code into this LLVM IR, and then uses LLVM to optimize the IR and turn it into binary code for a specific processor architecture. Sadly, the special flag for relative vtables in C++ only works at the frontend level, not on LLVM.

The Rust compiler roughly works the same way. It's only a frontend that turn your Rust code into LLVM IR and then uses LLVM as the backend. LLVM performs optimizations at this stage. This allows to benefits from the same optimizations, whatever languages you use or processor architecture you target. It gives you consistency across each of your projects and targets. Of course, you can also have optimizations at the assembly level later on.

Let's take a look at the LLVM IR now.

LLVM IR

LLVM IR is a Static Single Assignment language, meaning each variable is assigned exactly once. Let's take a rust code for example and see its corresponding IR:

fn add(i: i32, j: i32) -> i32 {
    i + j
}

; Test_Rust::add
; Function Attrs: nonlazybind uwtable
define internal i32 @_RNvCsivtQJMP6Nh_9Test_Rust3add(i32 %i, i32 %j) unnamed_addr #0 !dbg !147 !guid !155 {
start:
  %j.dbg.spill = alloca [4 x i8], align 4
  %i.dbg.spill = alloca [4 x i8], align 4
  store i32 %i, ptr %i.dbg.spill, align 4
  store i32 %j, ptr %j.dbg.spill, align 4
  %0 = call { i32, i1 } @llvm.sadd.with.overflow.i32(i32 %i, i32 %j), !dbg !158
  %_3.0 = extractvalue { i32, i1 } %0, 0, !dbg !158
  %_3.1 = extractvalue { i32, i1 } %0, 1, !dbg !158
  br i1 %_3.1, label %panic, label %bb1, !dbg !158

bb1:                                              ; preds = %start
  ret i32 %_3.0, !dbg !159

panic:                                            ; preds = %start
; call core::panicking::panic_const::panic_const_add_overflow
  call void @_RNvNtNtCsj07cU7DEYcL_4core9panicking11panic_const24panic_const_add_overflow(ptr align 8 @alloc_f50689592e4950fb14ebe24334607aab) #9, !dbg !158
  unreachable, !dbg !158
}

Okay, so we have a simple add function that just adds two number and return the result. First, you can see the function's identifier, where the name add that we put ends up at the end of the string name. Then you have both parameters, preceded with their type: i32 %i, i32 %j. Let's see how this function turned out in terms of IR.

First, you have two new variables: %j.dbg.spill and %i.dbg.spill. I call these variables, but LLVM refers to them as registers. It's like a register in assembly, except you can have and infinite number of them, they are like virtual registers. Let's just call them variables. So they are both produced with alloca, which is a small procedure to allocate on the stack. They allocate [4 x i8] meaning 4 bytes each, which is logic since parameters are i32, and their alignment is 4.

Then, the store operation is used, to store the value of %i and %j into their corresponding newly created variable.

After that, you have a call instruction, which calls the @llvm.sadd.with.overflow.i32 procedure. We can see that it returns { i32, i1 }, meaning it returns an i32 and an i1. Type in LLVM can have any number of bits you want. In Rust, you would have for example i8, i16, i32 and i64. In LLVM, you can have i1 but also i12 or i23, it doesn't matter. So this procedure returns the result as the first return value, and then it returns a boolean essentially, since it's only one bit. This boolean indicates if the add provoked an overflow or not.

Since %0 now holds a tuple, you need to extract every value to work with them. This is why you have two extractvalue instructions, one for extracting the result and the other for extracting the overflow flag.

Then, you have a br instruction, which is a branch instruction. It checks if an overflow happened, and if that's the case, jumps directly to a branch where your rust code panics. But if no overflow happened, then it returns the result thanks to the ret instruction.

So as you can see, LLVM IR is a language that sits between your code and the final assembly code. This is where lots of optimizations are going to take place, done by LLVM. But you have to understand that the final backend will also do optimizations. For example, here we allocate on the stack to store the values, but in the final assembly, for such a short code, everything could happen inside registers, without ever allocating in the stack.

If you want more information on LLVM or LLVM IR, here are some resources: LLVM Tutorial, A gentle introduction to LLVM IR, LLVM Project.

How calls work in modern operating system, at the assembly level

Before diving into how vtables calls work in LLVM IR, we first need to understand how calls actually work at the assembly level for modern operating systems.

So calls can either be:

• Direct: This means the address is hardcoded inside the call instruction. You call this function, the compiler resolves the address of the call and directly embed it inside the call instruction. You will always call the same location with a direct call.

• Indirect: Here, the address is retrieved from somewhere, either a memory location or a register for example. Function pointers in C or virtual function table in C++ should behave like this in assembly (minus compiler optimizations). Several executions of this instruction might end up calling different locations, depending on your code behavior. For example, if I define a C function that takes a function pointer as argument and call this function pointer, then the resulting assembly for this function will have a call instruction like this: call reg. And the value inside the register will change depending on which function pointer I pass as argument when I call the function. What I want you to understand here is that the same call instruction could resolve into different calls locations.

But calls can also either be:

• Absolute: The call operand is the absolute, non-relative address toward the memory where the function resides.

• Relative: This is not an address, but rather on offset to the function from the current instruction pointer, pointing at the call instruction (RIP register).

Let's take some examples to really understand how every function call resolves in assembly:

int test(int i) {
    return i + 10;
}

int main(int argc, char* argv[]) {
    int i = 10;
    int j = test(i);

    return 0;
}

The call to the test function will be of the form: call rip+offset. Because it is a direct call inside your own code, so the compiler can, at compile time, computes the offset directly and do a RIP relative call.

But if you do this:

#include <stdio.h>

int test(int i) {
    return i + 10;
}

int main(int argc, char* argv[]) {
    int i = 10;
    int j = test(i);
    
    printf("The value of j is: %d\n", j);

    return 0;
}

Then, the call to the printf function will also be a direct call, but it will be an absolute direct call, because the printf function is not inside your code. When loading your executable, the operating system will give you the absolute address to the printf function, and will insert it inside the call instruction.

So that was the two possibilities for direct calls, what about Indirect calls:

#include <stdio.h>

int test(int i) {
    return i + 10;
}

int main(int argc, char* argv[]) {
    // Getting a function pointer to the test function
    int (*test_pointer)(int) = test;
    int i = 10;

    // Calling the pointer to the test function
    int j = test_pointer(i);
    
    printf("The value of j is: %d\n", j);

    return 0;
}

The call to test_pointer is actually a call to a function pointer on the test function. This means the call will resolve into a call instruction of the form: call reg or call mem_location, mem_location being somewhere on the stack or the heap or any other memory location. The pointer will have an absolute address to the function. Indirect calls cannot be made relative, they are always made on absolute addresses.

So as we saw, a call can either be direct and relative or direct and absolute or indirect and absolute. VTables are just function pointers inside a structure that resides in your own binary. Some memory jumps and structure parsing is needed, but in the end, it's just an indirect and absolute call.

Making VTables relative

I first started to imagine a solution at the assembly level. But that was not the right solution for several reasons:

• No API to edit assembly code: Compared to LLVM IR, which has LLVM passes that you can custom write, assembly patching would have been done relying only on string matching and weird tricks to make it work. LLVM passes seemed a lot better for this use case.

• A lot harder to fix: At the assembly level, we work on a lower level than LLVM IR. The fix would have taken a lot of assembly instructions to work properly. Plus, vtables pointers couldn't have been made relative in assembly, so a calculation and a fix would have been only possible at the binary level, which increase complexity of a stable, reliable fix.

• Only working for x86: Working on the assembly level provides a solution for only x86 code, not ARM or other processor architecture. Working on the LLVM IR directly, you can then compile for every processor architecture that LLVM supports

For all these reasons, I started to look at how VTables calls are managed in LLVM IR.

VTables in LLVM IR

VTables definition

First, let's take a look at the vtable definition in LLVM IR:

@vtable.0 = private unnamed_addr constant <{ [24 x i8], ptr }> <{ [24 x i8] c"\00\00\00\00\00\00\00\00\10\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", ptr @_RNvXs1g_NtCshoIjhMyZzUf_4core3fmtReNtB6_5Debug3fmtB8_ }>, align 8
@vtable.1 = private unnamed_addr constant <{ ptr, [16 x i8], ptr, ptr, ptr }> <{ ptr @_RINvNtCshoIjhMyZzUf_4core3ptr9drop_glueNtNtCshodfiC9HsYt_5alloc6string6StringEBF_, [16 x i8] c"\18\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_str, ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write10write_char, ptr @_RNvYNtNtCshodfiC9HsYt_5alloc6string6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_fmtB6_ }>, align 8

Here we have two vtables definition. The first one, we can see the drop function is zeroed out, meaning the trait object doesn't have one. The size is 0x10 and the alignment is 0x8. Then you have a ptr to ****@RNvXs1g_NtCshoIjhMyZzUf_4core3fmtReNtB6_5Debug3fmtB8** function. We can see that there is also the types' definition at the beginning of the line. The ptr keyword type for the function tells us it's going to be an absolute address toward the function.

VTables calls

To better understand how vtables calls are made, let's first look at a normal call instruction:

  call fastcc void @_RNvNtCs7UalrjukX49_20RustyShell_shellcode15runtime_resolve18get_module_address(ptr noalias nofree noundef nonnull align 8 captures(none) dereferenceable(24) %_1, ptr noalias nofree noundef nonnull readonly captures(address, read_provenance) @alloc_51761afdde5661790743ff42719270e3.5, i64 noundef 12) #21

This is a call instruction to call into the get_module_address method of the runtime_resolve.rs module. We can see here that the call operand, i.e. the value that we actually call is a function definition: @_RNvNtCs7UalrjukX49_20RustyShell_shellcode15runtime_resolve18get_module_address. We can find this function definition somewhere in the same file:

; RustyShell_shellcode::runtime_resolve::get_module_address
; Function Attrs: nounwind optsize uwtable
define internal fastcc void @_RNvNtCs7UalrjukX49_20RustyShell_shellcode15runtime_resolve18get_module_address(ptr dead_on_unwind noalias nofree noundef nonnull writable writeonly align 8 captures(none) dereferenceable(24) %_0, ptr noalias nofree noundef nonnull readonly captures(address, read_provenance) %module_name.0, i64 noundef %module_name.1) unnamed_addr #0 {
start:
  %self_iter.i = alloca [24 x i8], align 8
  %_4.i = alloca [24 x i8], align 8

I've put only the first instruction of the function, because what I wanted to show you is that you have here the define internal fastcc void @_RNvNtCs7UalrjukX49_20RustyShell_shellcode15runtime_resolve18get_module_address function definition, which is the exact same name than the one in the call instruction.

This kind of call is a direct call, whether it be inside your own code (relative) or not (absolute). They will never be absolute in our shellcode template, because we make sure that we don't call functions outside our code, at least not statically.

Now let's take an example of indirect function call:

  %f.i.i = tail call noundef nonnull align 8 ptr @_RNvNtNtNtCshoIjhMyZzUf_4core2io5error12os_functions16get_os_functions() #9, !noalias !369
  %_4.i.i = load ptr, ptr %f.i.i, align 8, !noalias !369, !nonnull !4, !noundef !4
  %_0.i.i = tail call noundef zeroext i1 %_4.i.i(i32 noundef %_3.i, ptr noalias nofree noundef nonnull align 8 dereferenceable(24) %f) #9, !noalias !363

Here we first have a call to get_os_functions, which is a function inside the core library, that returns a pointer to a structure holding function pointers. Then, the load ptr is here to dereference the pointer returned by get_os_function and take the pointer that is at this address, which is a function pointer. Finally, you have a call to this function pointer.

Remember what I said earlier, indirect calls like this are always absolute, and that's true. The call instruction will end up calling a pointer to an absolute address toward an os function (os function here being a function inside the core library. It's just how it has been named inside the core library, it's not actually a WINAPI function or any other system call on other OS). And yet, this works inside our shellcode. But why? It's an absolute address, it should involve relocations and break shellcode!

Well the magic happens at the moment where the function pointer is initialized. The structure returned by the get_os_function is initialized at some point. It is not statically initialized at compile time. The pointers to the os functions is retrieved at runtime. And when they are initialized, it can be done relatively. Just like a direct call inside you own code, the compiler can compute the offset between your function pointer initialization and the actual function location. So the resulting instruction in assembly will be in the form: mov reg, rip+offset, where reg end up inside your function pointer to initialize it properly.

Therefore, function pointers inside our code is not a problem, because they are also initialized relatively, as long as they are not declared as a global or static variable. Awesome!

Okay, but what about VTables calls then? That's a problem because function pointers inside vtables are actually statically initialized. Inside the .rdata section of the binary, you will find the vtable, with the function pointers computed based on the preferred base address of the binary. Therefore, it will generate relocations. Let's see first how vtables calls are emitted with LLVM IR:

  %4 = getelementptr inbounds nuw i8, ptr %f.8.val, i64 32
  %5 = load ptr, ptr %4, align 8, !invariant.load !5, !nonnull !5
  %_7 = tail call noundef zeroext i1 %5(ptr noundef nonnull %f.0.val, i32 noundef %0) #23

So here we have pretty much the same instruction as the example on get_os_functions. You have %f.8.val, which is the pointer toward the vtable. Then, the getelementptr offsets this pointer by 32 bytes, to get into the second function pointer after the drop, size and align fields. The load ptr is here to dereference the pointer to get the actual function pointer and then the call instruction calls it.

The first question I asked myself was: This looks a lot like when calling a function pointer. How can I differentiate the two? Because in the function pointer example, it is obvious that it comes from a function, and not a vtable. But on the vtable example, the %f.8.val could actually be the return value of the get_os_function, that was called earlier. How can I be sure we are talking about a vtable here?

Well the answer lies in the details. You might have noticed that at the end of the line on a call instruction, you have a number with # before it. For this vtable call, it is #23. This number corresponds to some metadata that is defined at the end of the current file. And here is its value:

attributes #23 = { inlinehint nounwind }

And the attribute inlinehint especially is only added by Rust on vtables calls. It is inside the Rust compiler code. Now I didn't dig enough to understand why that is the case, but I think I can still use this correlation to correctly identify function pointers calls that actually are vtables calls. Until Rust changes this behavior of course. So it works for now, but it might change in the future.

Relative VTables in LLVM IR

When I was trying to find a specific flag that would make vtables relatives, I stumbled upon a GitHub issue from developers of the fuchsia OS about relative vtable in rust. They want to add a flag similar to the -fexperimental-relative-c++-abi-vtables C++ Clang flag, so that it would allow vtables to be PC-relative. And in the issue, they explain how such ABI would work. I actually had everything I needed to make my vtables relative. I tried to imagine a solution and when I found this issue, I didn't want to reinvent the wheel, especially when I was sure it wouldn't be an improvement on the matter. So thank you to PiJoules and Erick Tryzelaar for their solution. I only did a minor changes to their solution.

VTables definition modification

So here are the changes we need to do to the LLVM IR, so that vtable calls become relatives:

; Original form of vtables
@vtable.0 = private unnamed_addr constant <{ [24 x i8], ptr }> <{ [24 x i8] c"\00\00\00\00\00\00\00\00\10\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", ptr @_RNvXs1g_NtCshoIjhMyZzUf_4core3fmtReNtB6_5Debug3fmtB8_ }>, align 8

; New version after LLVM Pass
@vtable.0 = private unnamed_addr constant { [24 x i8], i32 } { [24 x i8] c"\00\00\00\00\00\00\00\00\10\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", i32 trunc (i64 sub (i64 ptrtoint (ptr @_RNvXs1g_NtCshoIjhMyZzUf_4core3fmtReNtB6_5Debug3fmtB8_ to i64), i64 ptrtoint (ptr @vtable.0 to i64)) to i32) }, align 8

Okay so here, we see that we don't modify the first array of i8, since the drop function is zeroed out, nothing to do here, we leave this unchanged. The first pointer becomes i32, because now the pointer becomes an offset toward the function from the start of the vtable. We will see why this design was chosen by analyzing the transformation on vtable calls. So the last part, i32 trunc (i64 sub (i64 ptrtoint (ptr @RNvXs1g_NtCshoIjhMyZzUf_4core3fmtReNtB6_5Debug3fmtB8 to i64), i64 ptrtoint (ptr @vtable.0 to i64)) to i32) is here to say we take the pointer to the function, we substract the pointer to the vtable to it, and we take the result into an i32. i32 is enough here as long as your binary size is smaller than 2 GB, which should be fine for now. I could imagine a solution with i64 if this issue ever comes up.

So the value that is going to be loaded from the vtable is the offset to the function from the start of the vtable. This is important, because when fixing the vtables calls, we are going to use a specific LLVM procedure that works this way.

Another example with the drop function defined:

; Original form of vtables
@vtable.1 = private unnamed_addr constant <{ ptr, [16 x i8], ptr, ptr, ptr }> <{ ptr @_RINvNtCshoIjhMyZzUf_4core3ptr9drop_glueNtNtCshodfiC9HsYt_5alloc6string6StringEBF_, [16 x i8] c"\18\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_str, ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write10write_char, ptr @_RNvYNtNtCshodfiC9HsYt_5alloc6string6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_fmtB6_ }>, align 8

; New version after LLVM Pass
@vtable.1 = private unnamed_addr constant { i32, [4 x i8], [16 x i8], i32, i32, i32 } { i32 trunc (i64 sub (i64 ptrtoint (ptr @_RINvNtCshoIjhMyZzUf_4core3ptr9drop_glueNtNtCshodfiC9HsYt_5alloc6string6StringEBF_ to i64), i64 ptrtoint (ptr @vtable.1 to i64)) to i32), [4 x i8] zeroinitializer, [16 x i8] c"\18\00\00\00\00\00\00\00\08\00\00\00\00\00\00\00", i32 trunc (i64 sub (i64 ptrtoint (ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_str to i64), i64 ptrtoint (ptr @vtable.1 to i64)) to i32), i32 trunc (i64 sub (i64 ptrtoint (ptr @_RNvXsZ_NtCshodfiC9HsYt_5alloc6stringNtB5_6StringNtNtCshoIjhMyZzUf_4core3fmt5Write10write_char to i64), i64 ptrtoint (ptr @vtable.1 to i64)) to i32), i32 trunc (i64 sub (i64 ptrtoint (ptr @_RNvYNtNtCshodfiC9HsYt_5alloc6string6StringNtNtCshoIjhMyZzUf_4core3fmt5Write9write_fmtB6_ to i64), i64 ptrtoint (ptr @vtable.1 to i64)) to i32) }, align 8

Basically, every function pointer works the same here. We do the same transformation to the drop function. The interesting part here is about the 4 bytes array of i8, inserted after the i32 representing the offset to the drop table. I chose to add padding here, because yes it is just padding, so that the size and align fields are still at the same offset inside the vtable. In the GitHub issue relative vtable in rust, fuchsia developers didn't add this padding, because they also changed the size_of_val and align_of_val compiler intrinsics to correspond to the new offsets. As I am not modifying these functions, I need to not modify the size and align offsets inside the vtable to no break them.

Okay, let's see now how a vtable call is modified

VTables call modification

  ; Previous vtable call
  %4 = getelementptr inbounds nuw i8, ptr %f.8.val, i64 32
  %5 = load ptr, ptr %4, align 8, !invariant.load !5, !nonnull !5
  %_7 = tail call noundef zeroext i1 %5(ptr noundef nonnull %f.0.val, i32 noundef %0) #23
  
  ; New version after LLVM Pass
  %6 = call ptr @llvm.load.relative.i32(ptr %f.8.val, i32 28)
  %_7 = tail call noundef zeroext i1 %6(ptr noundef nonnull %f.0.val, i32 noundef %0) #23

Okay, in the original instructions, we had a getelementptr instruction to offset of 32 bytes inside the vtable, which would be the second function pointer. Then a load ptr to load the ptr at that offset, and finally call it. The first two instructions are now replaced with a single one. A call to the @llvm.load.relative.i32, which takes a pointer and an offset. This specific LLVM function retrieves the i32 value at the address ptr + offset, and add the ptr value to it. You can find information about this intrinsic here: Introduce llvm.load.relative intrinsic.. It does exactly what is needed to compute the absolute address to the function. Moreover, the offset is changed based on this equation: new_offset = prev_offset - (((prev_offset / 8) -3) * 4). This will compute the new offset, taking into account that every function pointer is now 4 bytes long instead of 8. That's why 32 becomes 28 in the new version. And that's it, this way, the vtables and vtable call are all done relatively.

Again, thank you to fuchsia dev for their solution. Interesting to say that their goal is actually to make process startup faster by removing relocations that the OS has to handle and reduce memory usage by reducing the size of vtables. I have a totally different goal, and yet, we end up with the same problematic and their solution fits perfectly to the problem I was facing. They used the Clang compiler front-end specific flag, now they are trying to modify the Rust compiler front-end. Maybe implementing their solution to the LLVM IR level directly, just like I did, would allow them to have a solution that is language agnostic. I have not looked at how vtables in C++ by Clang are handled, maybe such a solution is impossible, but that would be an interesting lead to follow.

Compiler flags to enable LLVM Pass

Like I said before, LLVM proposes an API to do all this programmatically, through what is called LLVM Pass. It's like a script, in C++, that allows you to run optimizations on the LLVM IR. All these modifications are done via the LLVM Pass script. I won't go over the code here, but if you want to check it out, here it is: PC_relative_vtable.cpp.

At first, I thought it wasn't possible to integrate this inside the Rust workflow. So I started to see how I could, given the LLVM IR of my code, run the pass and then assemble and link thanks to LLVM assembler and mingw linker, outside the Rust workflow. I managed to do it, but then I discovered, you can actually enable your own LLVM pass inside the Rust compiler workflow, thanks to several compilation flags:

• -Z llvm-plugins=${PWD}/PC-relative_vtable_llvm_pass/bin/PC-relative-vtable.so: This flag is here to load the LLVM plugin inside the Rust compiler, so that we can call the optimization.

• -C passes=relative-vtable: Inside the LLVM Pass, I named the optimization relative-vtable. -C passes=name is here to specifically request optimization from LLVM, because LLVM comes with lots of optimization already bundled. But thanks to the previous flag, we have loaded our own LLVM Pass, so we call optimization from it right away.

• --emit=llvm-ir: This flag actually tells the rust compiler to emit LLVM IR files with the LLVM IR generated from your code so that you can take a look at it. I couldn't figure out why, but when it is not enabled, it's like my pass doesn't do anything. It runs, I made sure of that, but the modifications done inside it seems to only be in the final binary when this flag is enabled. If anyone wants to look into this topic, I would love to hear what you find out.

And there you have it, the full shellcode template, with the main entry point, shellcode.rs, showing an example of format! macro usage, which generates vtables, but is still shellcode compatible, thanks to the custom LLVM Pass that makes them relative.

Conclusion

This concludes this series about RustyShell, a new shellcode template that empowers you with even more of the Rust programming language available right out of the box. For now, this template works for small use cases, but I would love people to spot problems with bigger codebases. So don't hesitate to publish issues or submit pull request if you find use cases that the template doesn't handle properly, and you have a solution for it. Feedbacks from the community is really important to me, I mean it!

Credits

PiJoules and Erick Tryzelaar for their work on relative vtable in rust

Sources

Generic Data Types

PartialOrd Trait

format! macro

Write Trait

Static Single Assignment

LLVM Tutorial

A gentle introduction to LLVM IR

LLVM Project

Introduce llvm.load.relative intrinsic.

LLVM Pass

Making writing shellcode easier and more fluid.

Writing shellcode means writing code with a lot of constraints.

The simple fact that you cannot use any standard library already forces you to use OS API to do anything. Add to that the fact that you have to resolve dynamically these function pointers, and you need ten lines of code to do what would have taken only one usually.

So how do we make this easier?

Using windows-sys crate for Windows types and structures

We can include the windows-sys crate that already includes a lot of types and structures definition in pure Rust. This is useful to not having to rewrite every definition by hand. It is always possible to rewrite our own implementation of a structure, because sometimes some fields are not quite represented, because Windows consider these fields as private fields that we should not use.

Let's take an example, the LDR_DATA_TABLE_ENTRY, which is the structure representing a loaded module in the current process, found in the doubly linked list of loaded module inside the PEB. The windows-sys crate is implementing this structure like this:

#[repr(C)]
pub struct LDR_DATA_TABLE_ENTRY {
    pub Reserved1: [*mut c_void; 2],
    pub InMemoryOrderLinks: LIST_ENTRY,
    pub Reserved2: [*mut c_void; 2],
    pub DllBase: *mut c_void,
    pub Reserved3: [*mut c_void; 2],
    pub FullDllName: UNICODE_STRING,
    pub Reserved4: [u8; 8],
    pub Reserved5: [*mut c_void; 3],
    pub Anonymous: LDR_DATA_TABLE_ENTRY_0,
    pub TimeDateStamp: u32,
}

We see here that, following FullDllName is a field named Reserved4, and is composed of 8 bytes. But it is commonly known that this field is the BaseDllName, which is only the module filename, without the full path. That's why I redefined this structure to replace this Reserved4 field into BaseDllName as a UNICODE_STRING, because it is the actual type behind this field.

This allows me to directly access this field in the runtime_resolve.rs, without having to do a cast at the moment I retrieve the data behind this field. You can find the redefinitions of this structure in the peb_types.rs module.

Apart from that, I can just include every structure I need from this crate directly, which is a great way to get pure Rust definitions of Windows structures.

Using windows-bindgen crate for WINAPI function types

The windows-bindgen crate allows to automatically generate bindings for Windows structures and functions. The goal here is to automatically retrieve function pointers for the Windows API. We just need to add a build.rs script:

use regex::Regex;
use std::fs::{read_to_string, write};
use std::{env, path::PathBuf};

fn main() {
    // Only rerun the build script if it has changed
    println!("cargo:rerun-if-changed=build.rs");

    // Retrieving the OUT_DIR environment variable to get the output dir which we are allowed to use
    let mut bindings_path = PathBuf::from(env::var("OUT_DIR").expect("Couldn't retrieve OUT_DIR environment variable to put generated bindings inside it"));
    bindings_path.push("winapi_bindings.rs");

    // Using windows bindgen to generate bindings for WINAPI we use
    windows_bindgen::Bindgen::new()
        .output(&bindings_path)
        .flat()
        .sys()
        .filters(["LoadLibraryA", "MessageBoxA"])
        .extern_fns()
        .write();

    // The windows bindgen crate generates 2 things for a WINAPI:
    // - The direct function you can call directly into your code
    // - The function pointer type that can be used as a function pointer
    //
    // Only the latter is of interest for us, since we are resolving WINAPI calls dynamically at runtime for shellcode purposes.
    // This small code only keep the type definitions and remove the functions

    // Reading the generated bindings from file into a String
    let bindings_content =
        read_to_string(&bindings_path).expect("Error: Couldn't read bindings file");

    // Applying a regular expression to it to remove the function definitions
    let regex = Regex::new(r#"unsafe extern "system" \{[^}]*\}"#)
        .expect("Couldn't construct regex object from regex string");
    let filtered_bindings = regex.replace_all(&bindings_content, "").to_string();

    // Overwriting the winapi_bindings.rs content with the new filtered one
    write(&bindings_path, filtered_bindings)
        .expect("Error: Couldn't replace bindings content with filtered one");
}

Inside the filters function, we can simply add the name of the WINAPI we want to use inside our code. This generates two things in the generated file: The function directly that you can simply use and a function pointer for that exact same function. The small piece of code at the end of the build script is here to remove the function definition, because we don't want to use that directly, since it will induce imports in the final binary, thus breaking shellcode.

Here is the generated winapi bindings:

pub type LoadLibraryA = unsafe extern "system" fn(lplibfilename: PCSTR) -> HMODULE;

pub type MessageBoxA =
    unsafe extern "system" fn(hwnd: HWND, lptext: PCSTR, lpcaption: PCSTR, utype: u32) -> i32;

pub type HINSTANCE = *mut core::ffi::c_void;
pub type HMODULE = HINSTANCE;
pub type HWND = *mut core::ffi::c_void;
pub type PCSTR = *const u8;

We can see the two function pointers at the start. We can simply use these anywhere we need to cast a function pointer to call the corresponding function. Is also defines the types used inside the function pointer definition.

We just simply need to add this to our entry point, or in any module of the project:

mod winapi_bindings {
    include!(concat!(env!("OUT_DIR"), "/winapi_bindings.rs"));
}

This macro invocation will expand to copy everything from the winapi_bindings generated by the build script. You can then import function pointers you need from this module directly. Even though the generation will also define types used in the function pointer, if you ever need one of these types, I would advise you to simply import it from the windows-sys crate directly. It will make your code clearer, since the import will be completely written inside the file and not hidden behind the include! macro invocation.

If you ever need to inspect the content of this file, note that it is available here: target/x86_64-pc-windows-gnu/release/build/yourcrate/id/out/winapi_bindings.rs. Of course, you need to adapt this path if you have a different target or if you are in debug mode.

Macros to make dynamically calling WINAPI function easier

I added two macros to the template : resolve_call_winapi! and call_winapi!. Let's explore how each one can be used.

Resolve_call_winapi!

It can be used to automatically resolve the module address and the function address and call the function directly. Here's an example on how to use it for LoadLibraryA:

// Calling LoadLibraryA to load user32.dll in memory
let user32_address = resolve_call_winapi!(
    kernel32,
    LoadLibraryA,
    c"user32.dll".as_ptr().cast()
);

At first, you have to declare and initialize the variable into which you want to receive the return value of the WINAPI. Then, you can start to call the macro. Here is the argument list:

• Module Name: The first argument is the name of the module into which the WINAPI is exported. You have to put the name of the file, without the extension .dll which is automatically added inside the macro.

• The WINAPI name: The name of the WINAPI you want to use. You need to write it exactly as it is defined inside the winapi_bindings.rs module, because this argument will also be used to define the type of the function pointer retrieved.

• The arguments of the call: Lastly, you simply put the argument lists, in the order they are defined on the MSDN documentation, just like you would have put them inside a call to the function directly.

So this is how you can quickly resolve the module address and function address and call the WINAPI function.

call_winapi!

This one, on the other hand, is useful if you already have a pointer to the right module and don't want to resolve it again. It can be used like this:

// Example calling MessageBoxA
let result_message_box = call_winapi!(
    user32_address,
    MessageBoxA,
    null_mut(),
    c"Hello World!".as_ptr().cast(),
    c"Example".as_ptr().cast(),
    0
);

This is exactly like the first macro, except that user32_address refers directly to a pointer to user32.dll that has already been resolved.

These macros return a Result with the Ok variant being the return value of the WINAPI you called and the Err variant being a RuntimeResolveErrors of the runtime_resolve.rs module.

The code for these macros can be found in the utils.rs module.

Several compilation mode for easy debugging

The repo contains three different crates:

• rusty_shell: This is the actual RustyShell crate, containing allocator.rs module, the runtime_resolve.rs module and the utils.rs module, that you can depend on to automatically enable all this to use in your project.

• shellcode_example: This crate showcases how you can depend on rusty_shell to create your own shellcode crate. It shows you an example of entry point for shellcode and how you can use features of the rusty_shell crate.

• no_shellcode_example: This crate actually depends on the rusty_shell crate but not compiling as shellcode, for debug purposes mainly. It allows you to use the full std, and enables printing with println! inside the runtime_resolve.rs module, since this is the only way to print inside this module.

The rusty_shell crate comes with two features:

• shellcode: this is basically to gate every std related code behind this feature not being enabled. Again, the println! inside runtime_resolve.rs are gated behind it. This is a default feature.

• debug: This enables the printf! macro. In utils.rs, you can also find a printf! macro, which is gated behind the debug feature. This macro allows you to pass a literal string or a formatted string, thanks to the format! macro, to print something to the console.

I used the cargo make project to compile the different binaries. Here they are:

• cargo make windows_gnu_shellcode: Compiles the shellcode_example as shellcode, without debug feature enabled.

• cargo make windows_gnu_shellcode_debug: Compiles the shellcode_example as shellcode, with debug feature enabled, enabling printing through printf! macro.

• cargo make windows_gnu_debug_no_shellcode: Compiles the no_shellcode_example crate, allowing you to get prints inside the runtime_resolve.rs module.

So as you can see, the repo offers a lot of different way to compile the code, mostly for debug purposes.

Conclusion

You can find the shellcode entry point in the shellcode.rs file. This example simply showcases what you can do with the template, like using Vec and Strings thanks to the Global Allocator. It also shows how to use macros to call MessageBoxA for the example.

At this point, you have a well-designed template that lets you code in Rust as position-independent code in a simple and easy way. You can also use a great part of the std, the core and alloc components at least.

But one problem remains: Trait object. They are used in some parts of the core and alloc crate, and they break shellcode compatibility, meaning we cannot use every part of these crates. We'll see in the third part of this blog how we can tackle this problem.

Sources

windows-sys

windows-bindgen

A basic shellcode template in Rust to compile simply as position-independent code.

This blog is the first part of a series of blog posts about a tool I developed using the Rust programming language.

A while back, I wanted to investigate what was possible with the Rust programming language when it comes to develop position-independent code, aka shellcode. I'll first explain what a position-independent binary means, then show you how you can achieve shellcode using Rust. Finally, I'll present a new, innovative way to use more of the Rust programming language for your shellcode.

I just want to be clear that this blog will focus on shellcode for the Windows operating system. Shellcode for other operating systems is out of the scope of this blog.

You can find the code here: RustyShell. You can also directly import this inside your project thanks to the rusty_shell crate publish on crates.io.

What's a shellcode?

Originally, a shellcode meant an attack payload that would open up a reverse shell on a victim's computer. It had to be what is called position-independent code, because most of the time, it relied on code injection where your code would be directly injected in memory, without ever touching the disk.

But to really comprehend what position-independent code means, you have to know: None of the code you write is position-independent. When you run your binary on an operating system, several steps of loading will be executed to ensure that your binary can execute correctly. But first, let's open a simple binary to see what's inside.

Hello world!, tell me what you are!

We'll take the simplest example possible: a Hello World! executable written in C:

#include <stdio.h>

// This is just for the purpose of the example
int global = 0;

int main(int argc, char* argv[]) {
    // This contains a literal string: 'Hello World!\n'
    printf("Hello World!\n");

    return 0;
}

This code will turn into an executable with the extension .exe on Windows. This type of file on Windows uses the Portable Executable format, which is the main form of executable file on Windows.

PE format?

Let's start with a simple diagram that outlines the PE format:

This is what the PE format looks like broadly. You first have different headers:

• DOS Header: This header comes from MS-DOS operating system, the predecessor of Windows.

• DOS Stub: This is a small MS-DOS executable, here for retro-compatibility. It contains a simple string that is displayed if you try to run you executable on MS-DOS. The default value is This program cannot be run in DOS mode.

• NT Headers: This is actually several headers. The important one is the Optional Header, it contains a lot of information about the executable, a lot of it useful for the loading process that we will study later.

• Section Table: This header lists the different sections of your executable with their size, location, etc...

Headers are mostly here for Windows to properly load the executable in memory. Then, you have the different sections of your binary that contains the actual payload of your executable. Let's look at the most important one, especially regarding shellcode compatibility:

• .text: The section that contains your executable code. All assembly instructions needed to execute your code will be stored in this section. Memory protections: executable and readable.

• .rdata: This section will contain data that only needs to be read. For example, the string Hello World! here is stored inside this section, because we only need to read the string, we never modify it. Memory protections: readable.

• .data: Unlike rdata, this section contains data that can be read and written to. For example, the global variable global in the C code will be stored in this section. Memory protections: readable and writable.

• .idata: This section is a bit peculiar. Note that you use the printf function, but it is not defined anywhere inside the code you compiled. In simple terms, you defer this work to the OS, by calling a function exported by a DLL on Windows. The printf function is actually implemented inside these files. The .idata section is here to store information that tell Windows I need this function from this DLL, and Windows will load the corresponding DLL and give you the address of the function you need inside it, basically. Memory protections: readable.

• .edata: This section is here to tell the OS where your functions are inside your binary. Most compile code does not export their functions, if this is not needed. But DLLs do, in order for you to import their function thanks to the .idata section. Memory protections: readable.

• .reloc: This section is an important one for our position-independent code issue. Relocations are location in your code where you rely on absolute addresses. They might need fixing, and that's the job of the OS when it is loading you. Memory Protection: No memory protection since this is only needed for the loading process, the OS discards it when loading the executable.

This last section needs a bit more explanation I would say: Imagine the Hello World! string is at offset 1000 (I will take simple addresses, that don't reflect reality at all, but help explain things clearly) in your binary. Somewhere in your code, you need to read that string, in order to send it as argument to the printf function. That's where the compiler will compute an absolute address. But the compiler cannot know the address you are going to be loaded at. Therefore, it will choose a preferred base address, let's say 10 000, and compute all absolute addresses from this address. The Hello World! string is then at address 10 000 + 1 000 = 11 000, so in your code, you will have a reference to this specific address.

The compiler also put 10 000 inside the optional header of your binary, in a field know as Image Base. Windows, when loading your binary, will try to load your code at this address first. If it succeeds, then relocations do not need to be fixed, since all absolute addresses correspond to the real address in memory where to find the data, like your Hello World! string. But if it can't load the binary at this address, and loads it at address 20 000 for example, then your Hello World! string ends up at address 20 000 + 1 000 = 21 000. As a result of this, you need to fix relocations, to make absolute addresses inside your code point to the actual location of the data in memory. Windows will then add the difference between the preferred base address and the actual address the binary is loaded at, to fix it. So for example, the Hello World! string will become: 11 000 + (20 000 - 10 000) = 11 000 + 10 000 = 21 000.

Now that you have a better grasp of the PE format, we can look at the loading process.

Loading process

Most of what is explained here has been partly explained when analyzing every section of the PE format. It's just to explicitly enumerate all steps done by the OS for the loading process. This will help us see clearly what we have to avoid in order to get shellcode compatible code.

• Copy all sections: First, the OS will copy all the sections at their respective offsets. In your RAM, there is what we call a paging system. On Windows for example, it allocates a minimum of 4 Ko at a time, which is a page. The sections of your binary will always be copied at the start of a page, which means you will have a certain offset between the end of the previous section and the start of a new page, where the following section will be copied.

• Resolve all imports: Just like we saw earlier, your binary will actually need to call functions of the OS. So the OS will read the .idata section to load every DLL you need and give you the address of the function you need inside these DLLs.

• Handles every relocation: The OS, if it couldn't load your binary at its preferred address, will fix every absolute addresses you use so that you don't try to write or read into non allocated memory.

So this is basically the steps that the OS provides every time you run your executable. But what happens when you can't have them? Say for process injection? When you inject yourself inside a process, the OS is not here to do all these steps for you. Then you need a code that doesn't rely on all these steps, hence, position-independent code.

Hello World!, but shellcode

So, to get a position-independent code, now we know what we need. Let's explore each constraint to see how can we respect it.

Only the .text section

To avoid having to copy every section in memory, the goal is then to have only one section, the .text section containing our code. Now remember, this section is defined as executable and readable. Historically, strings were made into stack based strings so that they live only inside the .text section. But a new solution has emerged in recent years with linker script.

I believe it was Sylvain Kerkour who first presented this method in his article How to Write and Compile a Shellcode in Rust, for writing shellcode in Rust for Linux. Later on, C5pider with its Stardust also used the same method. The goal is to merge, thanks to a linker script, the .rdata section, where string literals resides, into the .text section, where your code resides. Since .rdata section is read-only, it poses no problem to include it inside the .text section, which is readable and executable. This allows you to have literal strings inside your executable, and with PC-relative access to it, it remains fully shellcode compatible.

Apart from that, we can't have .data section, this means no global or static variable is allowed in your code.

No standard library

When you compile your code normally, either using C or Rust, a lot of extra code gets compiled into your binary. For example, your main function is not the real entry point of your binary. The real entry point is another function, automatically added that initialize tons of stuff before calling your own code.

This means you don't have any access to function you normally use right out of the box. We'll see how this translates in the next paragraph.

No imports whatsoever

Because we can't use the standard library, we rely only on WINAPI calls. But we can't just call these functions directly, otherwise it will also end up in the import table inside .idata section.

We need to resolve dynamically each function we want to call. We can find the addresses of DLLs inside the process thanks to the PEB structure on Windows. Then, we can read export table from .edata section in the DLL to find the addresses of the function we need, and then call these functions with function pointer.

No relocations

With the two first constraint respected, you already avoided most of the use cases that would spin up relocations in your binary.

The position-independent template

Let's check out the template now. What do you need to use Rust and compile your code in position-independent code? A proposition was already published in Rust by safedv in Rustic64. This template is mostly inspired by his proposition, with a few adjustments to new features of the Rust programming language.

No main function

The first thing is to remove the main function and the use of the standard library. We can do this in Rust with these two lines:

#![no_std]
#![no_main]

The first tells the language we won't use the standard library. Therefore, we cannot import anything from std library. The second tells the language we don't have a main function per se. Of course, we will have an entry point, but it won't be called main.

The entry point looks like this:

#[unsafe(no_mangle)]
#[unsafe(link_section = ".text.entry")]
pub fn align_stack() -> i32 {
    unsafe {
        asm!(
            "push rsi",
            "mov rsi, rsp",
            "and rsp, 0x0FFFFFFFFFFFFFFF0",
            "sub rsp, 0x020",
            "call ExecutePayload",
            "mov rsp, rsi",
            "pop rsi"
        );
    }
    0
}

There is a lot to say here.

#[unsafe(no_mangle)]

This line tells the compiler to not mangle the function name. Name mangling is a concept used in some programming languages. It does not exist in C for example, that's why you can't have two functions that have the same name. But in C++ or Rust, you can name two functions the same way, on two different classes or structures. The name mangling will mangle names to integrate the class or structure name inside the symbol name for the linker, to dissociate the function that have the same name.

But for our template, we need to tell the linker which function name to use for the entry point, therefore, we have to disable name mangling to ensure the function name will stay align_stack for the linker.

#[unsafe(link_section = ".text.entry")]

This attribute tells the compiler to put this function into its own section, separated from all the code. When executing the shellcode in memory, we will just copy the content of the .text section and begin execution at the start of this section. Unfortunately, the Rust compiler might just choose to put the entry point in the middle of the .text section, which would break execution at its very beginning.

Later, in the linker script that we will also check out, we'll tell the linker to put this section first in the final .text section of the binary to ensure this function we'll be the starting bytes of the final .text section.

Inline asm

Then we use the asm! macro to inline a small asm procedure inside the function. This procedure was originally proposed by @mattitestation in his PIC_Bindshell project. It just here to align the stack to a 16 bytes alignment. This is needed for x64 code on Windows because the OS assumes that the stack is 16 bytes aligned, and some WINAPI function might use XMM register, which needs the stack to be 16 bytes aligned. Without this small procedure, execution might crash upon calling such WINAPI function.

After aligning the stack, this entry point calls into a function I called ExecutePayload, which is the real entry point of the code, where the user's code will start.

Dynamic resolution of WINAPI function

Like I said earlier, you cannot have any import inside your binary. So when you want to call a function, you have to get its address at runtime and call it thanks to a function pointer.

This is done through two functions: get_module_address and get_exported_symbol.

The first function, get_module_address, will try to retrieve the address of a DLL inside the RAM. On Windows, every process as its own virtual RAM. DLLs are loaded inside that virtual memory. The Process Environment Block (PEB) is a structure, available inside that virtual memory as well, that holds lots of information about the current process and notably a doubly linked-list of structures representing each DLL loaded inside the process.

In x64 Windows, the gs register holds a pointer toward the Thread Environment Block (TEB), which is the same thing as PEB but for one thread specifically. At offset 0x60 of this TEB, there is a pointer towards the PEB. Then, it is simply about looping through the linked list until you find the DLL you want. In each structure representing a DLL, you have its name and its address inside the process, everything you need to find every DLL you might need.

If you can't find the DLL you're looking for, it means it is not loaded inside the process. You can specifically require its loading thanks to LoadLibrary function.

Then, get_exported_symbol simply reads through the export table of the DLL. The PE format tells you where this table is located. You just have to loop through it, find the function you seek, and get its address in this export table.

So, when you want to call a function, you first need to retrieve the DLL's address that contains your function, then find the function you're looking for in the export table of this DLL to find its address.

All the code for this can be found here: runtime_resolve.rs.

Global Allocator

When I said you couldn't use any code from standard libraries, I lied. In Rust, the standard library is actually composed of the core library and the alloc library plus several modules unique to the std. The core library you can use right out of the box for shellcode compatibility, but the alloc crate is where structures allocated on the heap reside. And it needs a way to allocate on the heap.

Normally, this should be done with the std crate, but as we can't use it for our use case, we need to redefine it. Since Rust comes with great modularity, we can redefine the global allocator that will be used for every heap-allocated structure inside the alloc crate, and we can make it shellcode compatible. Therefore, we can use things like Vec, String, etc... Inside our position-independent code.

All the code can be found here: allocator.rs. We simply use the get_module_address and get_exported_symbol function to dynamically call into HeapAlloc, HeapFree and HeapReAlloc.

Compilation flags

For this template to compile as position-independent code, we also need to pass some specific compilation flag. Important to note that you need Rust nightly to compile properly this template, since it relies on features and compilation flags that are only available on nightly. Let's understand each of these flags.

• -Z unstable-options: This flag is to enable unstable flags that exist in the Rust compiler. It simply allows us to use other flags.

• -C panic=immediate-abort: This is actually a new panic method, where you can simply say you want to interrupt execution upon panicking. Before, you had to propose your own function to define the panicking behavior. With this flag, you don't have to anymore if you just want to abort execution.

• -C link-arg=-nostdlib: This flag tells the linker to not include any standard library. Like we said before, when compiling your program, a lot of code you didn't write gets included in the final binary, serving several purposes. But we don't want any of this for shellcode compatibility, so we ask the linker to not include any of this.

• -C codegen-units=512: This flag is a bit more complicated. When your code is transformed by the compiler, it will be transformed into object files. This flag controls how many units the code will be split into. For example, when compiling the core library, setting this to 1 will make one big object file with everything from the core library in it. Depending on this static library means that all the code from the core library will end up in your binary. Putting a great number, like 512, means splitting the core library into 512 different units, meaning you will end up with 512 object files. Depending on this library, the linker will only include the object files containing the symbols you really need. So why do we put a great number here? Because it allows us to have a small binary in the end. The more units you have, the more fine-grained control the linker have to only include what is of interest to you, reducing the size of your binary. When we are talking about payloads, we want them as small as possible. For this template, we are recompiling the core, alloc, and compiler_builtins crate. We put 512 to have the maximum codegen units on each of these crates. This depends on the crate size, a crate has a maximum number of splitting it can take.

• -C link-arg=-Wl,-T./Linker.ld: This flag just tells the Rust compiler to include a linker script at the linking stage. We are using the target triple x86_64-pc-windows-gnu, which relies on mingw for linking. We will take a look at the linker script later in this blog.

• -C strip=symbols: This is equivalent to -s for the gnu linker ld. It tells the linker to remove debugging info and the symbol table from the executable. These are not needed for correct execution of the binary, it's just metadata we can remove.

• -C lto=yes: This enables link time optimization. You might think this is about the mingw linker, but it is actually for LLVM. LLVM is a compiler backend for many languages. It provides an intermediate language frontend compiler will turn your code into. Then, LLVM takes care of optimizations on this intermediate representation. This flag tells LLVM to enable lto for your build. If you want to learn more about lto: Link-time optimization (LTO). For now, you just need to understand that it allows us to better optimize the binary in terms of size and execution speed.

• -C embed-bitcode=yes: It tells the rust compiler to embedded LLVM bitcode inside the object files. It is needed for fat lto, which is enabled with the previous flag.

• -C opt-level=s: This flag controls the optimization to be used. -s value specifically enable optimizations for binary size.

• -Z build-std=core,alloc,compiler_builtins: This flag tells the compiler to rebuild the core, alloc and compiler_builtins crate. This is needed, since we enabled the panic immediate-abort panicking behavior, which is not the already precompiled behavior standards crate are shipped with, hence, the need to recompile them.

• -Z build-std-features=compiler-builtins-mem: This allows the compiler_builtins crate to propose standard builtins memory function, so that we don't have to redefine them. Rustic64 for example, has to define these function here. They are needed for all kind of things, and your linker might tell you it misses a definition for it. When working with C style null terminated string, your rust code might try to call strlen for example, and you would have to define it yourself, since we ask for no std lib. But enabling this flag allows the compiler_builtins crate to propose out of the box an implementation for these kinds of functions, so you don't have to write your own implementation.

These are all the compiler flags we need to get a position-independent executable. All these compilation flag documentation is available here, if you want to go deeper into it.

Linker Script

As we have seen earlier, we pass a linker script to the linker. Here it is:

/* Simple ENTRY statement to put the entry point toward the align_stack routine */
ENTRY(align_stack);

SECTIONS
{
    /* Grouping code and read only data, starting with .text.entry which contains the small align_stack procedure, which is the real entry point of the shellcode */
    .text  __image_base__ + ( __section_alignment__ < 0x1000 ? . : __section_alignment__ ) :
    {
        *(.text.entry)
        *(.text)
        *(.rdata*)
    }

    /* Discarding the pdata and xdata sections, which are not needed in the final binary */
    /DISCARD/ :
    {
        *(.pdata)
        *(.xdata)
    }
}

The first line ENTRY(align_stack) is here to define the function named align_stack to be the entry point of the binary. This is why we had to disable name mangling on the function, so that the linker can find it later with this directive.

Then, we define the .text section in the final binary to be:

• *(.text.entry): First, the section containing only the align_stack function. This is here to ensure the first bytes of the .text section are in fact the align_stack function, to make sure the entry point is at the start of the section, because when injecting the shellcode, execution will start at the beginning of the binary.

• *(.text): Then, simply the rest of the code.

• *(.rdata*): Finally, we put the read only section which contains our read only data. This won't generate relocations since the code and the rdata will be in the same section, the code will use relative addresses to interact with the read only data.

To finish, we just discard sections that are not essential, here .pdata and .xdata, which contains metadata about exceptions, to correctly handle errors for every function of your code. Since we want panic immediate abort behavior anyway to leave the least traces possible, we don't really need these sections.

Conclusion

So this here is everything we need to make a position-independent Rust code. This template is not really new, as we have seen that Rustic64 already proposes the same features. There are minor improvement to what safedv did like the panic immediate abort behavior or the standard function directly proposed by the compiler_builtins crate. In the two blog posts that will follow, we will focus on what RustyShell really brings to the table.

Credits

How to Write and Compile a Shellcode in Rust by Sylvain Kerkour

Stardust by C5pider

Rustic64 by safedv

PIC_Bindshell by @mattitestation

Sources

Link-time optimization (LTO)

Rust Codegen Options