SheLLVM (pronounced either "shell-ell-ell-vee-em" or "shell-vee-em" but never with a long e as in "she") is a collection of LLVM analysis and transform passes to help developers compile lightly- to moderately-complex C(++) programs as position-independent "load anywhere and jump to the beginning" machine code.
While this project started as a toolkit for writing shellcode in plain C, it can really apply to any situation where a developer needs a program compiled in a platform-independent and position-independent way.
// main.c
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
extern void say_hello();
__attribute__((annotate("shellvm-main")))
void shellcode()
{
while(1) {
Sleep(1000);
say_hello();
}
}
// hello.c
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
void say_hello()
{
MessageBox(NULL, "Hello, SheLLVM world!", "Hello", 0);
}
clang -target i686-w64-mingw32 -c -emit-llvm -o main.bc main.c
clang -target i686-w64-mingw32 -c -emit-llvm -o hello.bc hello.c
llvm-link -o linked.bc main.bc hello.bc shellvm-built/winnt-{user,kernel}32.bc
clang -load=shellvm-built/shellvm.so -O3 -shellvm -o shellcode.elf linked.bc
objcopy -O binary --only-section=.text shellcode.elf shellcode.bin
msfvenom -p - -a i386 --platform win32 -e x86/shikata_ga_nai < shellcode.bin > shellcode_encoded.bin
- Portable: SheLLVM makes no assumption about architecture. While this is most heavily tested and developed on x86/amd64, the passes involved run on pure LLVM IR and should work anywhere the LLVM ecosystem works.
- Flexible: While there are some guides to writing shellcode in C on the 'net already, these usually impose a lot of restrictions on how the C code can be written; for example, by forbidding the use of string constants and global variables. SheLLVM attempts to provide a more "conventional" C environment while producing comparably self-contained code.
- Platform-independent: SheLLVM-generated code tries to keep to itself as much as possible. It does not rely on OS API calls or make assumptions about the memory layout of the target system. It does not need to unpack itself or allocate additional memory; all it requires is that it be loaded into a readable/executable segment and have the processor's stack initialized when execution begins. This makes SheLLVM suitable for use even in deeply embedded circumstances.
- Compatible: While this is primarily focused on C compatibility, there's no reason it can't work with other languages which use LLVM in the code generation pipeline, such as Swift or Rust. Patches for those languages very welcome!
Before we talk about the limitations of SheLLVM, let's first talk about the limitations of shellcode.
- It must be position-independent. While there are some circumstances where shellcode might land at a fixed address in an injected program, most of the time there's no guarantee whatsoever. Shellcode must rely on relative addressing only.
- It must fit in a single segment. Shellcode does not get the luxury of having a .text, .data, and .rdata segment. A single contiguous block must be loaded somewhere and the program must operate entirely in this environment.
- It does not get the benefit of the OS loader. While this is the cause for #1 and #2 above, it also means relying on OS dynamic libraries is forbidden.
- It's usually loaded into a non-writeable segment. Back in the 90s, before the importance of W^X was widely understood, shellcode could reasonably expect to land in RWX (readable, writeable, and executable) memory. Nowadays, shellcode may have to execute in R-X memory (and sometimes even --X memory).
- The only memory sure to be writeable is the stack. This is a blessing and a curse. On one hand, the stack is always there and most architectures have a register pointing to it and everything. On the other hand, the stack can overflow if not used judiciously.
So, let's look at how these translate into limitations when using SheLLVM:
- All code must be compiled to LLVM bitcode. These are LLVM passes. They
can only work on LLVM IR. The code must be presented to SheLLVM as a single
LLVM .bc file, which means heavy use of
llvm-linkandclang -emit-llvm. - No linker. Or, more precisely, no object code linker. Linking functionality is still provided by LLVM, but this means all linking must be done with LLVM modules and not object files. Importantly, this means...
- No libraries. Sorry, no
myfavoritelib.liborlibcoolthing.a. If you want to use a third-party library, you're going to have to compile it as LLVM bitcode yourself and link it in withllvm-link. Most notably, however, this means you cannot rely on the Win32 API or C standard library. SheLLVM provides loader stubs for dynamic libraries on certain platforms, which provide the standard platform API without needing to write symbol-hunting code by hand. - You must have a single main function. No linker/loader means no symbols. You can't export a collection of functions. The only function callable from the outside world is your main function.
- Your main function must have the longest lifetime. Because the only writeable memory is the stack (as explained above), the main function ends up taking the responsibility for allocating all memory in its stack frame and freeing it when done. Similarly, the main function handles all constructors and destructors. As a consequence, the main function must be the first thing to run and the last thing to exit. (This is only really an issue for programs using threading and callbacks.)
- Your code has amnesia. Since all state resides on the stack, this means your globals (and, by extension, static variables) have a lifetime only as long as your main function is running. This means that, while your globals (and static variables) will behave normally during a given run of your code, they will be reset to their default values during a subsequent run of your main function.
There are further limitations depending on which SheLLVM style you use.
In this style, SheLLVM functions as, essentially, a hyperaggressive inliner. It attempts to reduce your entire program down to a single function, with no callstack and no constants or globals on the heap.
- Works in --X memory.
- Compatible with most (all?) LLVM code generators.
- Highest code density.
- Does not use the stack for calls at all.
- All functions must be inlinable. In particular, this means no recursion is allowed (you may be able to get away with tail-call self-recursion, as LLVM's optimizer is pretty good at turning those into ordinary loops) and, perhaps more importantly, you must never take the address of any of your functions. This means no callbacks or threads.
- Everything resides on the stack, even large const arrays. This can be a problem for large programs, since read-only data is written to the stack instruction-by-instruction instead of being loaded into memory as-is.
Note: This has not been implemented yet.
In this style, SheLLVM does not attempt to inline functions or restrict itself to a single frame on the call stack. Instead, all global variables are placed in a massive struct which lives in the stack frame of the main function. Every other function's parameters list is modified to accept a pointer to this struct, in order to provide global variable support.
Functions used as external callbacks must be annotated so as not to receive this
modification. In this case, it's the programmer's responsibility to restore the
pointer to the globals object (via __shellvm_save() and __shellvm_restore()
intrinsics).
Multiple functions (and constant heap variables) are concatenated together in the output binary, and a small assembler stub at the entry point deduces from the instruction pointer where it has been loaded in memory and computes, from an offset table, the addresses of each function and constant in the program.
- Supports recursion and taking the addresses of functions.
- Supports threading and callbacks, when done carefully.
- Requires much less stack, due to constants being interspersed in the program data instead.
- Only works when the code segment is readable (R-X).
- Requires special handling at the assembly level.
- Much more complex.
- Callbacks from outside of LLVM code (e.g. due to spawning a thread) require the use of special SheLLVM intrinsics to save/restore the globals object.
These are the passes implemented in SheLLVM:
This pass makes sure exactly one function is marked as the main function (via
the __attribute__((annotate("shellvm-main"))) annotation). It removes this
annotation, replaces it with an LLVM attribute, and marks all other functions
in the module as private.
This just checks that all functions in the module are marked norecurse,
and that all functions are unnamed_addr (except for the main function, which
must be local_unnamed_addr).
This merges call instructions which target the same function into the same
basic block, using a switch statement on the other end to branch back to
where the call left off.
Because this could be useful outside of SheLLVM, it does not have the
-shellvm- prefix.
This uses -mergecalls on the main function repeatedly, inlining each merged
callsite each time. It's responsible for taking a full function call graph and
flattening it down to a single function.
This inlines all global variables (constant or not) which are used by only one function into the stack of said function. Note that this can/will heavily break non-SheLLVM programs if not used with care.
This inlines LLVM ctors/dtors into the SheLLVM main function.
This ensures that the resultant module contains no globals, only one function, no switch statements, etc.
It generally makes sure that the LLVM module is ready for code generation and will behave as proper shellcode when lowered into machine instructions.