dittobytes

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).

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).

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).

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
                └── ...

• 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/

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.

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.

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.

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 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)

• 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).

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).

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).

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).

• Run and test your shellcode using the pre-shipped shellcode loader:
  

  ./build/loader-[os]-[arch].[ext] ./build/beacon-[os]-[arch].raw

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

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

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

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

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

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

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

- 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]

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

- mov     rcx, BAh

+ mov     rax, EFh
+ mov     rcx, 55h
+ xor     rcx, rax

+ mov     rax, 3Bh
+ mov     rcx, 7Fh
+ add     rcx, rax

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

- 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

Substitutes various instructions that nullify a register each compile.

- xor     r12, r12

+ mov     r12, 0

! Yet to be implemented
+ sub     r12, r12

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

- 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 --

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

- mov     rax, r8

+ push    r8
+ pop     rax

+ xor rax, rax
+ add rax, r8

Transform mathematical instructions with equivalents each compile.

- sub reg, imm

+ add reg, -imm

+ lea reg, [reg - imm]

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

- mov     rax, r8

+ push    r8
+ pop     rax

+ xor rax, rax
+ add rax, r8