reflectra

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #llm #go #android #machine-learning #macos #windows #pytorch #ios #openai #open-source

(★ 33)

Modular User-Defined Reflective Loader (UDRL) built on Crystal Palace for controlled DLL execution and evasion research.

reflectra Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Reflectra

![Language](https://img.shields.io/badge/language-C%20%2F%20ASM-blue)
![Platform](https://img.shields.io/badge/platform-Windows%20x64-lightgrey)
![Type](https://img.shields.io/badge/type-UDRL-purple)
![Status](https://img.shields.io/badge/status-research-blue)

Reflectra is a **User-Defined Reflective Loader (UDRL)** built on top of [Crystal Palace][1] and inspired by the work of [Rasta Mouse][2].
It focuses on providing a reusable, modular UDRL architecture that can be integrated across multiple C2 frameworks while maintaining full control over execution flow and evasion.

## Overview

Reflectra provides:

* Custom reflective loading pipeline built on top of Crystal Palace
* Modular evasion (syscalls, spoofing, patching)
* Brings custom evasion capabilities to Beacons
* Full control over execution flow and memory layout
* Designed for integration with DLL-based C2 payloads

It can be integrated into any framework that delivers payloads as DLLs.

## What is a User-Defined Reflective Loader (UDRL)

A User-Defined Reflective Loader (UDRL) is a custom loader that:

* Manually maps a DLL into memory
* Resolves imports and relocations
* Executes the entrypoint without using the Windows loader

Unlike standard reflective loaders, a UDRL gives full control over:

* Memory layout and permissions
* Import resolution strategy
* Execution flow
* Transformation and obfuscation logic

## Features

### Core

* Manual PE loading (sections, relocations, imports)
* Dynamic DLL entrypoint resolution (`Start`, `Run`, `Main`, etc)
* Loader self-cleanup after execution (Free & Run)
* Debug mode with verbose logging (removed in release builds)

### Evasion

* Stack call spoofing using [Draugr][3]
* Indirect syscalls using [LibGate][4]
* ETW user-mode patching (byte patching)
* DLL masking via XOR encryption

### Build & Pipeline

* Integration with Crystal Palace
* Automatic YARA rule generation and mutation dealing with [islands of invariance][5]
* Simple stub generation for standalone execution

### Testing

* Tested against Defender-derived YARA rules using [defender2yara][6]

## Install

Reflectra depends on external components that are not redistributed, such as [Crystal Palace][1] and Tradecraft Garden libraries.
To install all required dependencies:

```bash
./install.sh
```

This will:

* Download Crystal Palace distribution files
* Download Tradecraft Garden sources
* Build libtcg locally
* Prepare the environment for building payloads

## Usage

### AdaptixC2

1. Generate your beacon as a DLL
2. Build the payload using Reflectra:

```bash
    ./build.sh <dll_path> <output_path>
    ```

3. Execute using the stub or the `run.x64.exe` from Crystal Palace:

```powershell
    .\run.x64.exe out.x64.bin
    ```

### With Any Other C2

1. Generate a DLL payload (preferably stageless)
2. Build it using Reflectra
3. Execute via:
    * stub executable
    * custom runner
    * integrated loader
4. You will need to modify `spec/pico.spec` and overwrite `TARGET_FUNCTION` to target the function to execute
    * This is required because Reflectra does not assume a fixed entrypoint, allowing flexibility across different C2 frameworks.

### Debug

You can debug it using this command:

```bash
./build.sh --debug ./dist/demo/test.x64.dll <output_path>
```

Debug messages are emitted via `OutputDebugStringA` and can be viewed using `DebugView` from SysinternalsSuite

### Output

* `out.x64.bin` → transformed payload
* `rules.yar` → generated YARA rules
* `stub.exe` → executable wrapper
* `out.x64.debug.bin` → optional debug payload

## Architecture

### Reflectra

```mermaid
flowchart LR
    A[Patch ETW] --> B[Load PICO]
    B --> C[Setup Hooks]
    C --> D[Unmask DLL]
    D --> E[Map DLL into Memory]
    E --> F[Resolve Imports and Apply Relocations]
    F --> G[Restore DLL Section Permissions]
    G --> H[Execute PICO]
    H --> I[Free Loader]
    I --> J[Call DllMain]
    J --> K[Call Target Function]
```

### Pipeline

```mermaid
flowchart LR
    A[Input DLL] --> B[build.sh]

B --> C[Release]
    B --> D[Debug]

C --> E[Compile Reflectra with MinGW]
    D --> F[Compile Reflectra with MinGW]

E --> G[Link with Crystal Palace]
    F --> H[Link with Crystal Palace]

G --> I[out.x64.bin]
    G --> J[rules.yar]
    I --> K[Generate pic.h with xxd]
    K --> L[Build stub.exe]

H --> M[out.x64.debug.bin]
```

## Limitations

* Some DLL payloads (e.g., Sliver) may not be compatible due to their Go-based runtime
* Dynamically resolved APIs are not hooked; only functions resolved via the IAT are affected

## Design Goals

* Bring UDRL to public C2 like AdaptixC2
* Define a flexible structure for Crystal Palace projects that can be used with any project
* Keep the loader minimal and modular
* Separate build-time logic from runtime execution
* Avoid tight coupling with any specific C2
* Enable experimentation and research

## References & Credits

* Crystal Palace - Core framework
* Rasta Mouse - [Crystal-Kit][2], [LibGate][4], [CRTL][7] research inspiration
* Draugr

## Disclaimer

This project is intended for:

* Research
* Development
* Educational purposes

Unauthorized use against systems you do not own is illegal.

## License

This project is licensed under the MIT License.

See the LICENSE file for more details.

[1]: https://tradecraftgarden.org/crystalpalace.html
[2]: https://github.com/rasta-mouse/Crystal-Kit
[3]: https://github.com/NtDallas/Draugr
[4]: https://github.com/rasta-mouse/LibGate
[5]: https://rastamouse.me/islands-of-invariance/
[6]: https://github.com/t-tani/defender2yara
[7]: https://www.zeropointsecurity.co.uk/course/red-team-ops-ii

reflectra

reflectra Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

reflectra

reflectra Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README