System requirements

Metamorphic cross-compilation of C++ & C-code to PIC, BOF & EXE.
^{Built with ♥ by Tijme Gommers – Buy me a coffee via PayPal or Bunq.}

Requirements • Getting started • Advanced usage • Metamorphications • Limitations • Issues • License

Dittobytes compiles your C-code to truly Position Independent Code (PIC) for Windows, MacOS, and Linux, and both AMD64 and ARM64. It features a metamorphic engine that ensures each compilation produces unique, functional shellcode. It does not rely on the classic decrypt stubs often seen in e.g. polymorphic compilations, and additionally it does not require reflective loaders such as Donut or sRDI as it can compile your C-code directly to PIC. A subsequent advantage is that the output size of the shellcode is extremely small (almost no overhead), and remains very simple.

Original		Metamorphicated (example)
# push rbp # mov rbp, rsp - push r15 - push r11 - sub rsp, 40h - xor rax, rax - mov [rbp+var_1B], rax	→	# push rbp # mov rbp, rsp + push r9 + push r15 + sub rsp, 38h + mov rdx, 0 + mov [rbp+var_33], rdx

^{Illustration 1: Example metamorphications by Dittobytes (left and right are functionally equivalent).}

Dittobytes uses a custom LLVM build with two transpilers. Any compilation of your code using Dittobytes is done with this LLVM build. The first transpiler uses a modern LLVM Function Pass (on intermediate level) to inline constant variables otherwise located in e.g. .rodata segments (this aids the development of Position Independent Code). The second one is the machine transpiler that uses a legacy LLVM MachineFunction Pass to perform the metamorphic transformations (e.g. instruction substitutions), introducing randomness in the assembly code during compilation. Check the roadmap for all implemented (and yet to implement) metamorphic transformations.

The pre-shippped minimal C-code file (./code/beacon.c) can cross-compile to all supported platforms (Windows, Linux & MacOS), architectures (AMD64 & ARM64) and formats (PIC, BOF, EXE). Additionally, Dittobytes ships with loaders (for each platform and architecture) that can be used for testing purposes.

System requirements

The build environment itself works best (and is tested) on Linux (AMD64 & ARM64). Use Docker for an easy setup.

System requirements if you use Docker
^{Difficulty: easy}

A custom version of LLVM needs to be built from source, which requires quite some memory and disk space to be allocated by Docker. The build takes around 2.5 hours. I got it to work with the following Docker resource configuration.

⚠️ If Docker cannot allocate enough resources, the build might fail with an error like ResourceExhausted: cannot allocate memory.

Set CPU limit to: 8.
Set memory limit to: 10 GB.
Set swap to: 2 GB.
Set disk usage limit: 1 TB (though this can likely be much lower).

System requirements if you use Windows Subsystem for Linux
^{Difficulty: intermediate}

A custom version of LLVM needs to be built from source. Quite some memory and disk space is required. The build takes around 2.5 hours. I got it to work with the following resources.

CPU cores: 8.
Memory: 10 GB.
Disk space: 1 TB (though this can likely be much lower).

System requirements if you directly use your host
^{Difficulty: advanced}

A custom version of LLVM needs to be built from source. Quite some memory and disk space is required. The build takes around 2.5 hours. I got it to work with the following resources.

CPU cores: 8.
Memory: 10 GB.
Disk space: 1 TB (though this can likely be much lower).

Getting started

Presentation

This research has been presented at OrangeCon 2025. The slides are available and a recording will be published soon.

Overview

Directory structure

dittobytes/
├── code/                               # Your C-code that will compile to shellcode.
│   ├── beacon.c                        # Example file that you can compile using Dittobytes.
├── build/                              # Build dir containing loaders and your shellcodes.
│   ├── beacon-[platform]-[arch].raw    # Your C-code compiled to raw shellcode (.text segment only).
│   ├── beacon-[platform]-[arch].obj    # Your C-code compiled to BOF/COFF format.
│   ├── beacon-[platform]-[arch].exe    # Your C-code compiled to executable format.
│   ├── loader-[platform]-[arch]        # Pre-built raw shellcode loaders for testing purposes.
│   └── ...
└── ditto/                              # Internal files supporting the Dittobytes project.
    ├── loaders/                        # Simple shellcode loaders for testing purposes (pre-built).
    │   └── [platform]/
    │       ├── src/
    │       │   └── main.c
    │       └── lib/
    │           └── ...
    ├── scripts/                        # Helper scripts used by the makefile(s).
    │   ├── extract-text-segment.py
    │   └── ...
    ├── tests/                          # C-code files used for feature testing.
    │   ├── [feature-test].c
    │   └── ...
    └── transpilers/                    # The LLVM plugins that act as metamorphic engine.
        ├── intermediate/
        │   └── src/
        │       ├── IntermediateTranspiler.cpp
        │       └── ...
        └── machine/
            └── src/
                ├── MachineTranspiler.cpp
                └── ...

Preparing

Cloning the repository

Clone this repository using Git:

git clone https://github.com/tijme/dittobytes.git

Manually review the code so you know what you're compiling and running.
Finally, move into the project directory and start developing:
```
cd ./dittobytes/
```

Configuring the build environment in a Docker container
^{Difficulty: easy}

The easiest way to use Dittobytes is via Docker. For this, you need to build a Docker image using the provided Dockerfile.

Build the Docker image:
```
docker buildx build -t dittobytes .
```
Building the image will take around 2.5 hours as LLVM needs to be built from source.

Configuring the build environment in a Windows Subsystem for Linux container instead
^{Difficulty: intermediate}

If you are on Windows, a more performant option to build the build tools is to use Windows Subsystem for Linux (WSL). However, in contrast to Docker, the installation of the build tools is a manual process.

First of all, install a Debian WSL container:
```
wsl --install -d Debian
```
Then start & enter the container:
```
wsl -d Debian
```

Custom versions of Clang and LLVM are eventually used to cross-compile your code, the loaders and the transpilers. Performing this compilation in WSL requires you to configure your WSL the same way as the Docker container is configured. Take a look at the Dockerfile or GitHub Workflow for reference. Follow the exact same steps as in one of those files. For now, there is no further documentation on setting up the environment in WSL.

Configuring the build environment on your host instead
^{Difficulty: advanced}

Custom versions of Clang and LLVM are used to cross-compile your code, the loaders and the transpilers. If you want to perform this compilation on your host machine, configure your host the same way as the Docker container is configured. Take a look at the Dockerfile or GitHub Workflow for reference. Follow the exact same steps as in one of those files. And please make sure you're on a Linux host. For now, there is no further documentation on setting up the environment on your host machine.

Developing

The basics

You can modify ./code/beacon.c however you like. Just keep the following in mind:

The first function in your code must be named EntryFunction.
EntryFunction must literally (in order) be the first function in your code.
You cannot use global variables (PIC limitation).
You cannot use any data from other segments (PIC limitation).
You must resolve any API function you want to use by yourself (PIC limitation).

The following example may give you some guidance. It simulates global variables by using a context struct that you would need to pass to any function you call. It initializes a string by using a char[] array. It calls another function by defining its definition first (as the other function needs to be defined before you can call it, but it cannot be the first function in your code).

Example 'The Basics' (example-basics.c)

A hello world

A hello world requires printing to the console, thus requiring an OS API call to e.g. puts. This is OS specific. For example, for Windows it would require loading KERNEL32.dll, ultimately resolving LoadLibraryA and GetProcAddress. With these two functions resolved, you can then load any function address, such as the address of puts.

An example would become quite large, thus for now I'd like to forward you to example file below. It is a Position Independent Code (PIC) for Windows AMD64 & ARM64 which pops a calculator as example.

Example 'Popping Calc' (example-calc.c)

Compiling

Compile your code

If using Docker, run the Dittobytes container (or use an equivalent command for your build environment):
```
docker run --rm -v ".:/tmp/workdir" -it dittobytes
```
Compile your code (for all platforms, architectures & formats):
```
make
```
You can also create specific builds: make beacon-[platform]-[arch]-[format].
- Options:
  - Platforms: win,lin,mac.
  - Architectures: amd64,arm64.
  - Formats: exe,raw,bof.
- Examples:
  - make beacon-win-amd64-bof (compile your code to Windows AMD64 BOF/COFF).
  - make beacon-mac-arm64-raw (compile your code to MacOS ARM64 raw shellcode).
  - make beacon-lin-all-raw (compile your shellcode to raw shellcode for Linux and any architecture).
  - make beacon-all-all-raw (compile your shellcode to raw shellcode for any platform and architecture).
  - make beacon-all-all-all (compile your shellcode to any format any platform and any architecture).

Outputs

Position Independent Code (.raw)

Dittobytes was originally designed to output Truly Position Independent Code (PIC). Simply put, PIC consists of the executable assembly instructions from the .text segment of an executable binary, without any reference to other segments or absolute memory addresses.

Dittobytes generates .raw files for Windows, Linux and MacOS (and both AMD64 and ARM64).

Beacon Object File (.obj)

In the process of creating Position Independent Code, Dittobytes creates an .obj file (COFF/ELF format). This file is later used to extract the .text segment (.raw) from, or create the executable format (.exe) with. However, the .obj file itself can be used as Cobalt Strike (or any other C&C framework) Beacon Object File (BOF) as well.

Dittobytes generates .obj files for Windows, Linux and MacOS (and both AMD64 and ARM64).

Executable/Clickable (.exe)

Dittobytes uses the generated Position Independent Code (PIC) in the .obj file to eventually generate an executable/clickable file format (.exe). This means that all executables generated by Dittobytes solely contain Position Independent Code (PIC). For example, constants are inlined instead of stored in the .rodata segment.

Dittobytes generates .exe files for Windows, Linux and MacOS (and both AMD64 and ARM64).

Testing

Running your shellcode

Run and test your shellcode using the pre-shipped shellcode loader:
```
./build/loader-[os]-[arch].[ext] ./build/beacon-[os]-[arch].raw
```

Running feature tests

Dittobytes comes pre-shipped with feature tests. A feature test is similar to a unit test, but tests from a large feature perspective, instead of a specific code unit perspective. Currently, you can only run feature tests for shellcodes that are compiled for the platform you are running the tests on. For example, in the Docker container only the Linux shellcode would be tested & verified.

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Build the tests:
```
make test-suite-build
```
Run the tests:
```
make test-suite-test
```

Advanced usage

Using C++ instead of C for your code

You can easily utilize functionality of C++ by renaming your code file from ./code/beacon.c to ./code/beacon.cpp. Just make sure to prepend the EntryFunction in the file with extern "C". Also ensure that the SOURCE_PATH option in the makefile points to the new filename. Do note that you cannot use functionality from external libraries such as libstdc++ or libc++. This means you cannot make use of e.g. std::string ⚠️.

Example 'C++ instead of C-code' (example-cpp.c)

Compiling C++ code in Dittobytes works exactly the same as compiling regular C-code.

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Then compile your code:
```
make
```

Compiling a Cobalt Strike Beacon Object File (BOF)

To compile a Beacon Object File (BOF) for Cobalt Strike or any other Command & Control framework, copy ./code/examples/example-bof/example-bof.c to ./code/beacon.c. Then adjust the source code to your needs.

Example 'Beacon Object File' (example-bof.c)

Remember to solely compile to the BOF/COFF format using the make command (see below example) ⚠️.

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Then compile your code:
```
make beacon-win-amd64-bof
```

Modification & compilation of the pre-shipped loaders

You can modify the pre-shipped loaders by editing the code in ./ditto/loaders/[platform]/src/main.c, after which you can compile them using the following commands in the root of the Dittobytes project:

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Compile the loaders:
```
make ditto-loaders
```

Modification & compilation of the pre-shipped transpilers

You can modify the pre-shipped transpiler(s) by editing the code in ./ditto/transpilers/[type]/src/[type].cpp, after which you can compile them using the following commands in the root of the Dittobytes project:

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Compile the transpilers:
```
make ditto-transpilers
```

Dittobytes ships with two transpilers. The first one is the intermediate transpiler that uses a modern LLVM Function Pass to inline constant variables otherwise located in .rodata segments. The second one is the machine transpiler that uses a legacy LLVM MachineFunction Pass to perform the metamorphism.

Compiling & running one specific feature test

The test-suite commands in the makefile usually compile and test all feature tests (cross-os and cross-architecture). If you want to test just one specific feature test, or if you want to to test build artifacts for a specific os or architecture, use the commands below. You can adjust the TEST_* arguments to your needs.

If using Docker, run a Dittobytes container:

docker run --rm -v ".:/tmp/workdir" -it dittobytes

Build the test(s):

make TEST_OS=win TEST_ARCH=arm64 TEST_SOURCE_PATH=./ditto/tests/all/all/3_metamorphication_010_transform_nullifications.c TEST_METAMORPHICATION=transform_nullifications test-suite-build

Run the test(s):

make TEST_OS=win TEST_ARCH=arm64 TEST_SOURCE_PATH=./ditto/tests/all/all/3_metamorphication_010_transform_nullifications.c TEST_METAMORPHICATION=transform_nullifications test-suite-test

The above example would build the feature test 3_metamorphication_010_transform_nullifications.c for Windows ARM64. This may result in many build artifacts ([amount of feature tests] × [amount of os's] × [amount of arch's] × [amount of metamorphications]), in this case 1 (1 × 1 × 1 × 1). The second command verifies the build artifacts based on the @verify statements in the feature test source code file(s).

Metamorphications

There is no specific planning, so this might be more of a to-do or progress list.

✅ Randomize register allocation
^{Implemented in release 1.0.0.}

Randomizes the allocation order of CPU registers, causing different registers to be used each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- mov rcx, 3Eh - mov rdx, 4Fh - lea r8, [rbp+var]	→	+ mov r11, 3Eh + mov r10, 4Fh + lea r9, [rbp+var]	+ mov r9, 3Eh + mov r12, 4Fh + lea rdi, [rbp+var]

✅ Transform `mov reg, imm`
^{Implemented in release 1.0.0.}

Substitutes instructions that move an immediate value to a register in various ways each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- mov rcx, BAh	→	+ mov rax, EFh + mov rcx, 55h + xor rcx, rax	+ mov rax, 3Bh + mov rcx, 7Fh + add rcx, rax

✅ Transform `mov [reg+var], imm`
^{Implemented in release 1.0.9.}

Substitutes instructions that move an immediate value to the stack in various ways each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- mov [rcx+var_8], 83h	→	+ mov rax, D9h + mov [rcx+var_8], AAh + add [rcx+var_8], rax	+ mov rax, 11h + mov [rcx+var_8], 92h + xor [rcx+var_8], rax

✅ Transform nullifications
^{Implemented in release 1.0.2.}

Substitutes various instructions that nullify a register each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- xor r12, r12	→	+ mov r12, 0	! Yet to be implemented + sub r12, r12

⏳ Insert semantic noise (meaningful dead code)
^{To be implemented.}

Insertion of opaque instructions or basic blocks (from trusted software) that do not affect code functionality.

Original

Metamorphicated (sample 1)

Metamorphicated (sample 2)

- mov     rax, 1

→

+ mov     rax, 1
+ mov     rbx, [false_flag]
+ cmp     rbx, 1
+ -- more instructions --
+ je      skip_next_instr
+ -- more instructions --
+ mov     rax, 42

+ mov     rax, 1
+ -- more instructions --
+ mov     rbx, [false_flag]
+ -- more instructions --
+ cmp     rbx, 0
+ je      skip_next_instr
+ mov     rax, 1
+ -- more instructions --

⏳ Transform `mov reg, reg`
^{To be implemented.}

Substitutes instructions that move a register value to another register in various ways each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- mov rax, r8	→	+ push r8 + pop rax	+ xor rax, rax + add rax, r8

⏳ Swap simple math
^{To be implemented.}

Transform mathematical instructions with equivalents each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- sub reg, imm	→	+ add reg, -imm	+ lea reg, [reg - imm]

⏳ Transform `mov reg, reg`
^{To be implemented.}

Substitutes instructions that move a register value to another register in various ways each compile.

Original		Metamorphicated (sample 1)	Metamorphicated (sample 2)
- mov rax, r8	→	+ push r8 + pop rax	+ xor rax, rax + add rax, r8

Limitations

There are currently two known limitation in the use of Dittobytes.

LLVM cannot inline compile float's and double's, causing them to end up in the .rodata segment. As a result, these types do not work when compiled with Dittobytes.
C++ exceptions are not yet supported as they generate exception tables outside the .text segment.

Issues & requests

Issues or new feature requests can be reported via the issue tracker. Please make sure your issue or feature has not yet been reported by anyone else before submitting a new one.

License & copyright

Copyright © 2025 Tijme Gommers. Dittobytes is released under the Mozilla Public License Version 2.0. View LICENSE.md for the full license. Dittobytes depends on various open-source components which all have their own license and copyright.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Repository files navigation

System requirements

Getting started

Presentation

Overview

Preparing

Developing

Compiling

Outputs

Testing

Advanced usage

Metamorphications

Limitations

Issues & requests

License & copyright

About

Uh oh!

Releases 11

Sponsor this project

Uh oh!

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 189 Commits
.github		.github
build		build
code		code
ditto		ditto
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
README.md		README.md
makefile		makefile

Uh oh!

License

tijme/dittobytes

Folders and files

Latest commit

History

Repository files navigation

System requirements

Getting started

Presentation

Overview

Preparing

Developing

Compiling

Outputs

Testing

Advanced usage

Metamorphications

Limitations

Issues & requests

License & copyright

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 11

Sponsor this project

Uh oh!

Uh oh!

Languages