Last month, I released a Yara signature generator for Crystal Palace. AKA, an invariant content observation tool. I then used the feature to document the physics of various content-signature parameters (e.g., length, signature agreement, etc.) Now, I’m releasing the follow-on features to give you tools to play with the program content assumptions that signatures act on.

ised – A program rewriting tool

The main feature in this release is the ised command. ised is a tool to insert and replace code in a program at locations matching instruction patterns. This feature can surgically break an attractive signature target. You can also spam junk code everywhere and bloat your program too. And, while this feature is very powerful—it’s also a footgun. But, Crystal Palace has some checks to help with that too.

The syntax is:

ised [verb] [pattern] [$CODE] [+options]

Valid verbs are ‘insert’ and ‘replace’.

Pattern is one or more strings that describe individual instructions.

$CODE is a byte[] of object code.

+options select the instruction verb applies to and a few other things.

$CODE

$CODE is a byte array of valid object code. This is the insert or replace value used by ised. You are responsible for preserving the semantics of the program and not generating harmful side effects. Crystal Palace does not check this value for errors. One way to populate $CODE is with pack:

pack $NOP "b" 0x90

Patterns

Patterns describe which parts of the program ised affects. ised patterns come from Crystal Palace’s disassembler output.

There are three pattern forms:

The specific form is a string that matches the Crystal Palace disassembler output for an instruction. Below is a command to match any instruction that disassembles to call findModuleByHash and insert the contents of $NOP after it.

ised insert "call findModuleByHash" $NOP

The generic form is a string that matches Iced’s string representation of an instruction mnemonic and the types of argument it accepts. Use ./disassemble -f (or disassemble +forms in a .spec) to see an instruction’s generic form alongside the disassembled output. This command finds any call to a local function and inserts $NOP after it:

ised insert "CALL rel32" $NOP

Finally, if you want to get aggressive, Crystal Palace can match the instruction mnemonic from the generic form too. This inserts $NOP after any push instruction:

ised insert "PUSH" $NOP

Each pattern describes one instruction. Multiple patterns, specified together, describe a sequence of instructions. This command inserts $NOP after a mov that immediately follows a local call instruction.

ised insert "CALL rel32" "MOV" $NOP

Crystal Palace’s pattern matching engine depends on specific string matches. If you specify “sub rsp, 32h” as a pattern—don’t expect a match. Crystal Palace does not parse and normalize your pattern strings. It expects that your pattern is “sub rsp, 0x20” as output by the disassembler.

ised commands are evaluated before +regdance and after +mutate. If you’re looking for instructions to target, I recommend you disable +regdance during that process.

Verb: insert

The insert verb inserts the contents of $CODE into a program somewhere relative to the pattern. The default is to insert $CODE after the last instruction in a matched pattern.

Before I can describe the other options, I need to cover ised’s two-pass implementation.

From ised’s view, each instructions has three buckets associated with it. There’s append, prepend, and replace. During ised’s first pass, it walks the program and finds all commands that match a sequence of instructions in the program. When there’s a match, the affected instruction and bucket are found, and the command’s $CODE is dumped into that bucket.

On the second pass, ised walks each instructions and acts on one random value from its buckets. If a prepend bucket has four $CODE options, ised will pick one value to prepend to the instruction. If a bucket is empty, ised does nothing. In this design, multiple ised commands that match the same thing is how you get polymorphism.

The +first, +last, +before, and +after options dictate which instruction (relative to the matched pattern) and which bucket the candidate $CODE goes into.

ised insert "A" "B" "C" $CODE +last +after

+last and +after are the default. They place $CODE into the append (+after) bucket of the last matched instruction (“C”) in this sequence.

ised insert "A" "B" "C" $CODE +last +before

Here, $CODE is placed into the prepend (+before) bucket of the last matched instruction (“C”) in this sequence. So, $CODE would show up between matched instructions “B “ and “C” in the final program.

ised insert "A" "B" "C" $CODE +first +after

Here, $CODE is placed into the append (+after) bucket of the first matched instruction (“A”) in this sequence. So, $CODE would show up between matched instructions “A” and “B” in the final program.

ised insert "A" "B" "C" $CODE +first +before

And, here $CODE is placed into the prepend (+before) bucket of the first matched instruction (“A”). $CODE would show up just before the sequence “A” “B” “C” in the final program.

insert can act and match on most instructions in most situations. There are some checks to discard dangerous changes (e.g., protecting the integrity of fixptrs, rflags/eflags preservation, etc.).

Verb: replace

The replace verb replaces an instruction in the matched sequence with $CODE.

The options here are simpler. +first replaces the first instruction in the matched sequence with $CODE. +last (default) replaces the last instruction in the matched sequence with $CODE.

You’re responsible for making sure $CODE replicates the semantics and side effects of the instruction you’re replacing. If you target add rax, 0x20 with replace, your $CODE better get rax + 0x20 into rax by the end of its run.

There are also instructions you can’t replace. Crystal Palace won’t replace a call, branch, or an instruction with an associated relocation. No error is fired for these. They’re just passed-over if a replace targets them.

Option: +safe

One danger of program modification is the risk of RFLAGS/EFLAGS corruption. The flags register tracks meta-information about the last arithmetic operation and its contents affect follow-on branch instructions. Crystal Palace goes to some length to track flag readers, flag writers, and instructions that fall between these two.

If Crystal Palace determines a target instruction is within a “danger zone”—a run of instructions where a flag is set and later used—Crystal Palace will ignore most ised changes. This is a anti-footgun safety feature. If your $CODE is flags aware (or free of side effects to flags), add +safe to your ised command to override this check.

Option: +split

The +split option applies to both insert and replace. This option inserts a 0-byte jump before (+before) or after $CODE. This dynamically splits a block of code at that specific instruction boundary. This pairs with Crystal Palace’s block randomization features which shuffle blocks function wide (+blockparty) or program wide (+shatter).

If you just want to split at an instruction boundary, without any $CODE, use $NULL. The $NULL value is a (new!) Crystal Palace built-in which is always an empty byte array.

Constant Blinding

While ised has the power to target single instructions well, it’s cumbersome for getting rid of classes of constants (ror13 hashes, stack strings, etc.) used throughout the program. I’ve evolved +mutate to help with this.

+mutate now locks onto key instruction forms and subtracts a 32-bit magic value from their constant. This scatters the constant’s bit pattern. +mutate then inserts an add to restore the constant at runtime. Example:

mov rax, constant

Becomes:

mov rax, constant – magic
add rax, magic

By default, +mutate uses a random magic value for each instruction. Use magic to limit the magic constant to a pool of values you specify:

magic "0x7FFFFFFF, 0x12345678, 0xD34DB33F"

Limiting magic to a few constants makes the add instruction into ised-targetable scaffolding. Use ised and magic together to bring variety to these sequences of instructions.

Migration Notes

(1) Update any use of pack with the template char ‘b’ to ‘v’. ‘b’ was taken over for a single byte and v now means expand a $variable in the packed string.

(2) The ./disassemble CLI changed slightly. You must now prefix +options with -o (e.g., -o +optimize,+regdance,+mutate)

Closing Thoughts

Early in this project, I shared that content signature resilience was one of my goals for Crystal Palace. I didn’t know what that would look like and I didn’t expect the journey to take us here. But, here we are.

First, there’s a belief that an obfuscator is an obfuscator is an obfuscator. Obfuscating a program is just a step that happens and it’s a solved problem. I want to challenge you to imagine that obfuscators may have gaps in what they obfuscate. Or, the obfuscator may produce sequences of instructions that are a new tell. As I thought about +options for Crystal Palace, these were the problems I wrestled with.

The other thing I want to challenge is the notion that detection surface is program content that’s highly unique and specific to the program. In the last development cycle, I sat down with a goodware corpus, and I explored the left and right bounds of content false positives. My conclusion was that a good signature is three or more instructions with a sane minimum number of bytes. A highly program-specific Yara rule is one where six or more of these signatures agree. Any untouched invariance in a program is a place to pull signatures from.

So, when I sat with the content signature resilience problem set, I had a sense that a baked in obfuscation cocktail wasn’t the way. And, I had a sense that I wanted to come up with something that gives you agency over your program’s final content. But, I didn’t know what that would look like. Would I write an API to extend Crystal Palace’s BTF? Would I create hooks for a Python (or Sleep 🙂 always Sleep) script to transform instructions? ised is what I came up with. I’m pretty happy with it. I’m especially curious to see what you do with it.

The above said, there’s another implication for this technology. Within one foundation, we have a tool to generate high-fidelity Yara rules. And, within that same foundation, we have high-leverage tools to break content signatures. A potential outcome is that researchers building tools on this platform may feel quite comfortable releasing Yara rules for all of their capability. It’s no loss, because they and their users would likely have a private ised-cocktail ready to go. What would change in red teaming (or cybersecurity even), if there was no fear of “burning a tool” because of its content tells and behavior was the only meaningful battleground?

The Adversary Fan Fiction Writers Guild is a culture engineering project. One of the ways I’m trying to change culture is by changing the incentives that have made things the way they are. The combination of the Yara generator and ised are a tangible example of this.

To see what’s new, check out the release notes.

Crystal Palace now has a Yara rule generator. In this blog post, I’ll walk you through the design and evaluation of this feature.

rule PageStream_rDLL_03495de1 {
   meta:
      description = "PageStream rDLL: Use VEHs and guard pages to limit DLL visibility in eXecutable memory"
      author = "Raphael Mudge"
      date = "2026-01-27"
      reference = "https://tradecraftgarden.org/pagestream.html"
      arch_context = "x64"
      scan_context = "file, memory"
      os = "windows"
      license = "BSD"
      generator = "Crystal Palace"
   strings:
      // ----------------------------------------
      // Function: TrackPage
      // ----------------------------------------
      /*
       * 48 69 D2 56 55 55 55          imul rdx, 0x55555556
       * 48 C1 EA 20                   shr rdx, 0x20
       * 89 C1                         mov ecx, eax
       * C1 F9 1F                      sar ecx, 0x1F
       * (Score: 530)
       */
      $r0_TrackPage = { 48 69 D2 56 55 55 55 48 C1 EA 20 89 C1 C1 F9 1F }

      // ----------------------------------------
      // Function: go
      // ----------------------------------------
      /*
       * 48 89 D5                      mov rbp, rdx
       * E8 87 01 00 00                call SizeOfDLL
       * 48 8D 15 20 00 00 00          lea rdx, [.bss+0x20]
       * 48 8D 8A 00 02 00 00          lea rcx, [rdx+0x200]
       * (Score: 142)
       */
      $r1_go = { 48 89 D5 E8 ?? ?? ?? ?? 48 8D 15 ?? ?? ?? ?? 48 8D 8A 00 02 00 00 }

   condition:
      all of them
}

Add -g "outfile.yar" to generate Yara rules alongside ./link and ./piclink’s output. There’s a Java API for this too.

The .spec file rule command gives advice to the Yara generation. This command is optional:

rule "name" [max] [minAgree] [minLen-maxLen] ["funcA, …"]

A rule is a collection of signatures associated with part of a Crystal Palace project (e.g., the main PIC, an embedded PICO, etc.). “name” sets the rule’s name. If name is empty (e.g., “”), the rule generator will derive a name.

max sets how many signatures Crystal Palace allows within a rule. Crystal Palace scores candidate signatures and selects the best ones. This score favors instructions that are information dense (e.g., have a lot of parameters) and it likes unique-seeming constants. The default is 10.

Set max to 0 to disable signature generation for a piece of a project.

minAgree is the number of signatures that must agree for a rule to match a sample. If the number of signatures generated is less than minAgree, Crystal Palace will require all of the signatures to fire. This value is the power tool to reduce false positives.

minLen-maxLen sets the minimum and maximum non-wildcarded bytes in a signature. The default range is 10-16.

The last parameter is a list of functions to generate signatures from. By default, Crystal Palace considers all functions in scope. Use this option to specify functions most-specific to your tradecraft implementation.

The rule generator is scoped to object code (e.g., the .text section) of a program only. It does not generate signatures from .rdata constants (strings) and it does not look at appended shellcode (e.g., linkfunc).

Generating Signatures

The heart of the rule generator is Crystal Palace’s binary transformation framework (BTF). This framework is a pipeline to disassemble a program, lift its contents to a higher-level abstraction, transform the program, and lower the program back to working object code.

I’ve implemented some code randomization features on top of the BTF. +shatter splits a program into basic blocks and randomizes their order program wide. +regdance does some register randomization. One of the benefits of doing this bin2bin is I know which of the instructions changed and which didn’t. Runs of unchanged instructions are our islands of invariance. The rule generator focuses on these runs of unchanged instructions.

The first signature generation step is to identify basic blocks in a program. Basic blocks are runs of instructions with one entry point and one exit point. Crystal Palace uses the leaders algorithm to identify basic blocks. Given that +shatter and +blockparty randomize the order of these blocks, it makes sense that signatures should not overlap blocks.

One difference from normal block splitting: the signature generator uses modified instructions as a block splitting “leader” criteria. This is how the algorithm isolates the islands of invariance.

One limitation in the BTF pipeline is it only knows which instructions changed during the current pass through the pipeline. By itself, this is valuable, as it captures shifting branch targets, RIP-relative references, and call instructions. But, it doesn’t help with the stuff from other passes (e.g., PIC ergonomics transforms, +regdance, etc.). To make all of this work, I’ve made the earlier pass transforms deterministic. They’ll always generate the same output for the same input. And, later passes (e.g., +regdance, if enabled) are dry-run to taint instructions as changed—for the purpose of rule generation.

The signature generator preserves call instructions within an island. I see these as important “something is happening” context anchors. This implementation wildcards the call target and wildcards are excluded from the minimum/maximum signature-length criteria. Relocations, by themselves, are not treated as a change that breaks an island. The relocation values are wildcarded too.

Filtering Signatures

At this point, we have several islands. Each individual island is treated as a signature.  The signature generator’s next step is to filter the list to get rid of unacceptable signatures.

The filter gets rid of instructions that don’t belong in a signature. This includes function prologue register preservation and stack setup. And, function epilogues that undo all of that. I also get rid of INT3 and NOP instructions that pad some functions. These are boilerplate to every program and too false positive prone. The algorithm also gets rid of instructions that are marked as “changed”.

One of this system’s hard-baked criteria is that, regardless of byte length, a signature must contain three or more instructions. Two instructions are too false positive prone. Three is where things start to get unique.

The algorithm also takes care to reject duplicate signatures too.

The filtering process is where signatures below the minimum byte length are removed. Signatures over the maximum byte length are handled differently. The algorithm walks these islands to find the run of instructions that fits within the maximum size and has the highest heuristic score.

The algorithm makes no attempt to derive 2+ signatures from a single large island. I feel the diversity of signatures from different localities, across the program, outweigh having 2+ signatures tied to one island.

Scoring Signatures

The final step is to score signatures and use this score to select signatures that are likely unique to the program. Crystal Palace doesn’t ship with a “good” opcode database or anything like that. We have to rely on a heuristic guess. This project uses information density within each instruction as a proxy for uniqueness.

To calculate information density, I walk each instruction’s operands, I score the individual operands, and I multiply the scores together. The idea is for an individual instruction’s score to grow geometrically with more information. RBP/RSP and constants 0, 1, and -1 are scored the lowest. I score other constants much higher. The heuristic rewards large constant values over small ones.

The effect of the above is that scores bias for instructions that have constants and they bias for instructions with a lot of complexity (e.g., instructions with a base register, displacement, index register, and scale value that’s not 1).

I do artificially bias a couple of situations:

Call instructions get a boost. I do this to make sure where there’s a choice to select call over another low density instruction, the call is chosen. This is because the call has symbol information and that’s helpful context in the signature’s comments.

I also artificially score instructions that use RBP or RSP as their base register. I assume these instructions are register spills or other stack book keeping and do not reward their complexity.

And, after evaluation and investigation of the score heuristic, I reduced the score of RAX relative to other registers. This change is discussed at the end of the false positives section.

I calculate the score for an island by adding the scores of individual instructions together.

Performant Rules

As part of this work, I looked at Yara best practices for performant rules.

Yara’s signature matching is a two phase approach. The first phase is a triage phase. Here, Yara selects a high-entropy 4-byte value (called an atom) from each signature and feeds them as input into the Aho-Corasick algorithm. Yara’s heuristic treats entropy as a proxy for uniqueness.

Signatures that match during triage are fully evaluated during the second phase. This is where the wildcards, jumps, and regular expressions are handled.

Prior to this background research, I assumed any two-byte value could anchor a Yara signature (e.g., a jump and a wildcard). I didn’t know the system’s expectations. Now, if I were trying to break a known signature, I would focus on isolating or changing the candidate 4-byte atom values. Wildcards and regular expressions without a suitable atom are not a performant signature.

During this work, I experimented with bringing Yara’s atom quality heuristic to Crystal Palace’s signature selection process. My thought was to have an option to specify a atom entropy floor as a performance aiding option. But, I found that candidate signatures, pulled from object code, with the three instruction floor enforced, almost universally contained a max score or near max score atom. Any work to select rules with these criteria wouldn’t have an effect.

False Negatives (aka Scope Disclaimers)

The rule generator creates signatures from the instructions that survived Crystal Palace’s binary transformation framework. Signatures generated against an input COFF and .spec should match 100% against the output of that linking process.

The goal of these rules is to zero-in on the specific implementation and configuration. They are not content tells for the technique itself nor are they expected to survive rewrites, compiler changes, or other obfuscations and modifications to the program.

False Positives

I did take steps to validate Crystal Palace’s signature score heuristic. And, during this process, I had a lot of fun playing with the data and parameters.

For this experiment, I put together a 33GB corpus of goodware EXE and DLL files. I took care to include programs probably compiled with MinGW (e.g., Git, QEMU, Inkscape, msys2, GIMP). The corpus also includes EXE and DLLs taken from my on-hand Windows 7 and Windows 10 VMs.

Standing in for my “tradecraft” I opted to generate signatures from a collection of Beacon Object Files. I used TrustedSec’s CS-Situational Awareness BOFs as my non-blind data set to tweak my heuristic and shake bugs out of the system. I used BOFs from TrustedSec’s CS-Remote-Ops, Alfie Champion’s BOF collection, and REDMED-X’s OperatorsKit as my blind evaluation data. There are ~100 BOFs in this data set.

One important note between these data sets: Crystal Palace supports MinGW compiled programs. MSVC is probably OK sometimes, but not encouraged. The TrustedSec BOFs and Alfie Champion’s BOFs are compiled with MinGW. REDMED-X’s BOFs are compiled with MSVC and make up 40% of the evaluation data set.

> Testing Signatures

To generate signatures I used this Crystal Palace .spec file:

process.x64:
	load %1
		make coff +optimize
		rule "" 10 1 10-16
		export

	pop $TEMP
 
x64:
	foreach %BOFS: .process %_
	push $TEMP

This .spec file walks the comma-separated values in %BOFs and runs the callable label process on them.

To generate my comma-separated list of BOFs, I just used:

find /path/to/BOFs | grep \\.x64 | tr '\n' ','

And, to pass this information to Crystal Palace:

./piclink detect.spec x64 out.bin %BOFS="..." -g "rules.yar"

I used yara-x to bounce the generated signatures against the goodware corpus:

./yr scan -r -s rules.yar goodware

> Is the score heuristic better than chance?

My first open question was to evaluate whether or not the score heuristic selects signatures that are better than signatures selected by chance. For this experiment, I generated three groups of information:

• Pick 10 selects up to 10 signatures at random from each BOF’s valid signatures. These signatures are grouped into a single rule for the BOF. This is my control group to compare the Top 10 to. For islands larger than the max length, Pick 10 uses the same score heuristic to find an optimal run of instructions within the island. 
• Top 10 selects up to 10 signatures scored highest by the rule generator’s instruction information density heuristic.
• All contains one signature from each island in each BOF. This is the full pool of signatures that Pick 10 and Top 10 draw from. All shows how many false positives lurk within our programs.

For each of these groups, I ran the experiment with different match conditions: Any (of them) means if one signature in any rule matches contents in a file, it’s a match. 2 (of them) means at least two signatures within the same rule must agree to trigger a file match.

My data counts the number of unique goodware files matched. Even if a single file triggers multiple rules or signatures, it is counted as a single false positive file match in this table.

For this experiment, I focused on the 10-16b length signatures. This experiment, and the ones that follow, use the blind evaluation data.

Here, we see that individual signature vs. individual signature–the score heuristic selects better candidates than random selection. But, in aggregate, the real false-positive reduction hero is signature consensus. Both the random signatures and score-heuristic selected signatures hit 0 false positives when 6-7 signatures are required to agree.

> Does the compiler matter?

The test data set includes 41 MSVC-compiled BOFs from REDMED-X’s OperatorKit. I took those out and reran the test experiment with just the MinGW compiled BOFs.

Here, we see a drastic drop in false positives with the heuristic selected signatures. Out of a pool of ~2,000 signatures that generate ~3,500 false positive goodware file matches, the score selected ~550 signatures (the top 25%) that yielded only 14 false positives. Said again, the score picked 1 out of 4 candidate signatures, and ended up with <1% of the false positives. More importantly, this test reached zero false positives with a threshold of two signatures.

I separated the compiler here, because Crystal Palace (today) explicitly supports and encourages MinGW as the compiler of choice. These numbers better represent how I expect the generated rules to work with Crystal Palace outputs.

> How do signature lengths affect false positives?

I played around with the length of signatures (in bytes too). I kept the same window size in each of these runs, but slid it by two bytes each time.

In this data: shorter signatures result in more false positives. Longer signatures, usually, result in fewer false positives. But, with a caveat! The data is noisy and a slightly longer signature length can generate more false positives than a shorter one. What I take from this is that length alone isn’t the singular tool to reduce false positives. But, sufficiently long signatures converge to zero false positives at a 2-3 signature agreement threshold.

> How does signature quantity affect false positives?

The last thing I wanted to ask the data is how do the number of signatures affect potential false positives? Here, I stuck with the default 10-16b window, generated top X rules, and recorded their false positives.

> What about the MSVC false positives?

I did not look at MSVC output when I first created the score heuristic. But, I was very curious about what caused the spike in false positives. And, I decided to investigate this further.

I dumped the yara-x output to a file and I sorted the rule matches by count. Here’s what that yielded:

Notice that the false positive matches are not evenly distributed. There’s one dominant super-matcher signature and a few others that stand out. I took a look at $r12_go (note, there were multiple, so I had to narrow it down) and $r9_go. I saw the same story in both:

These instructions spill a pointer onto the stack. They score low in the existing heuristic, because I penalize complex instructions that use RSP/RBP as the base register. But, I wanted to see if I could improve my system knowing this information. I updated the score heuristic to penalize RAX/EAX and I made the RSP/RBP base register penalty stronger. Sadly, this means the test data is no longer blind 😦 Oh well! Here’s the re-run of the score heuristic vs. chance experiment with these changes:

I’d like to draw your attention to the Pick 10 and All numbers in this experiment vs. the first. They’re improved. We’ve shaved nearly 1,000 false positives in our signature set. This is the effect of the improved score heuristic selecting an optimal run of instructions within longer islands. But, even with this improvement across the board, the Top 10 signature selection improved enough to converge to 0 false positives with fewer agreeing signatures than Pick 10.

As a sanity check, I removed the MSVC BOFs and re-ran the GCC-only test. I wanted to see if these changes hurt our GCC-only numbers. They didn’t.

I investigated the false positives from the updated score heuristic. I didn’t see a single outlier super-matcher. But, I did see a cluster of signatures with high-matches. I looked at the top one and saw information dense instructions setting up arguments for the RegOpenKeyExA API. At this point, our top signature is zeroing in on something interesting our program is doing and not compiler book keeping. I call that a win.

Migration Notes

None

Closing Thoughts

I ran these experiments to validate (and improve) the rule generator’s score heuristic. But, I also wanted to document the rule generation parameters (e.g., signature agreement, number of signatures, and length) to show how those affect false positives. In these experiments, signature agreement showed itself as the high-leverage tool to reduce false positives.

I don’t expect these numbers to land a cover spot in Detection Engineer Magazine. Rather, my goal is to document the physics of content signatures as they relate to Crystal Palace’s PIC and PICO contexts. One take-away is that signatures are drawn from a program’s fingerprint. And, pulling from functions across the program, it’s possible to get a unique fingerprint when enough pieces are expected to agree. And, while program randomization can help, note this: a 4b anchor and 6-10 predictable bytes nearby is a signature.

Tradecraft Garden is a model to develop, release, and demonstrate evasion research that is ground-truth focused and use-case agnostic. The first pillar was to package techniques into standardized artifacts–ground truth that also works as vendor-actionable unit tests. Tools to generate high-quality content signatures is another pillar. Both are efforts to buy good will with other parts of the industry and defuse narratives bad faith actors wield to malign researchers for doing their job.

The above is not incompatible with red teaming. I believe two things: (a) it’s possible to [economically] keep a public and known implementation alive against low-leverage defenses (e.g., content signatures) and (b) security testers provide the most value working within that space of what’s recently known and new, but not fully defended and democratized across the security profession yet.

If you’re with me on point (b), I can help on point (a). I have ideas to empower you to play with these fingerprints and apply your own transform recipes via Crystal Palace. +mutate ain’t it. But these ideas are empty without a way to measure and observe the effect.

The rule generator had to come first.

For a full list of what’s new, check out the release notes.

Happy New Year. I’ve got another Crystal Palace and Tradecraft Garden update for you. My focus this development cycle was making Crystal Palace’s binary transformation framework more robust. I think this is also a good opportunity to brain dump some technical details on this piece of our tradecraft and capability separation stack.

But before we do that, here are the new features:

+regdance randomizes non-volatile registers in some functions.

+blockparty shuffles the order of blocks within a function.

+shatter is a variant of +blockparty. It shuffles the order of blocks program wide.

The above are +options you can use with make pic, make object, etc.

Crystal Palace’s binary transforms are now friendly to MinGW’s -O1 optimizations. Tradecraft Garden’s examples are now compiled with -O1.

Now, let’s dive deep into the binary transformation framework.

What is bin2bin?

Crystal Palace’s binary transformation framework is a program rewriting tool. It’s called bin2bin [1, 2, 3] because we accept a program binary as input, we make changes to it, and our output is a working program binary.

I have a strong aversion to bin2bin tools. My user experience is that they work with their test cases, but break in mysterious ways during production use. While this system will always have limitations, because bin2bin has fundamental limitations, my goal is something that’s robust and predictable—so long as programs stay within what’s supported.

Importantly, while Crystal Palace has a built-in bin2bin framework–it is a linker first. Its job is to compose programs from pieces. But, it’s a linker that can rewrite its programs! Crystal Palace uses this super-power to:

• Turn x86 and x64 programs into “just works” PIC
• Find and remove unused functions at link time.
• Provide some byte-content signature resilience via +regdance, +shatter, etc.
• Weave merged tradecraft into capability with the attach and redirect aspect-oriented programming primitives

What about LLVM?

An alternative to bin2bin, if you are working with all of the source code (or have a source code-derived LLVM bitcode file), is to write compiler plugins to rewrite a program before executable code is emitted. This is fertile ground for offensive security research:

• Austin Hudson’s Orchestrating Modern Implants with LLVM (Fortra booth presentation at BlackHat 2025) is a good survey of the LLVM offensive security space.
  
• DittoBytes by Tijme Gommers is a metamorphic cross-compiler that relies on LLVM plugins to compile PIC-friendly C into something unique with each run.
  
• LLVM-Yx-CallObfuscator by Alejandro González is an LLVM plugin to transparently apply stack spoofing and indirect syscalls to Windows x64 native calls at compile time, driven by a configuration file.

Working from a source code-derived intermediate representation is a high-leverage and safe place to transform a program. Compiler passes are better suited for rewriting programs. A bin2bin tool doesn’t have the same program knowledge that the compiler works from. This means where there’s overlap, some things we do from a bin2bin context will approximate what’s possible via a compiler pass. This will come through when we case study +regdance.

But, with bin2bin we’re also free to deviate from some of the structure assumptions and hierarchy that are baked into a compiler backend. +shatter, discussed later, is an example of what’s possible here.

The above said, I want to share my rationale for bin2bin with Crystal Palace. The goal of Crystal Palace and Tradecraft Garden is to separate capability from tradecraft. More directly: there’s a need to split ops capability development and tradecraft research as disciplines and communities. But, the two have to come together for various use cases too. That’s where Crystal Palace comes in. It’s an end-user tool. My vision is that an operator can edit a .spec to make tradecraft choices for a capability they are about to use. For this model to work, the flexibility needs to exist as close as possible to time-of-use. And, that’s likely after the pieces (possibly proprietary) are compiled. The ability to shuffle registers and play with program structure at time-of-use is just a cool bonus.

How does Crystal Palace’s bin2bin work?

Crystal Palace’s binary transformation framework is based on the fantastic iced. Iced is a disassembler, instruction decoder, and assembler for the x86 architecture (16-bit, 32-bit, and 64-bit). The project has ports for Rust, .NET, Lua, Java, and Python.

I like that Iced is self-contained. It’s a single .jar file and I was able to merge it into crystalpalace.jar. This makes for a low friction and accessible user experience.

In the next sections, we’ll go through the binary transformation framework in detail. But, at a high-level:

• Disassemble: COFF -> Instructions
• Lift: Instructions -> Intermediate Representation
• Transform: Intermediate Representation -> Iced’s Code Assembler
• Lower: Iced’s Code Assembler -> Object Code -> Updated COFF

The process starts and ends with the COFF. The COFF and object code in it are Crystal Palace’s unit of truth about the program. There is no other meta-information. Each pass of the BTF pipeline expects a COFF as input and it returns the updated COFF as output.

Disassemble

The disassemble step turns object code from a COFF into a linked list of decoded instructions, encapsulated in Iced Instruction objects. This process is also where I match symbols and relocations from the COFF to individual instructions in the program. Symbols are things like: “this is where function X begins”. Relocations are compiler-generated hints for unknown addresses/offsets that the linker and (typically) operating system loader must resolve before the program is truly complete and ready to run. My PIC development crash course goes into more detail on this.

When Crystal Palace works on a program, it does so function by function. The Code class breaks the disassembled program up into linked lists grouped by function for us. I initially did this for the link-time optimization feature.

The link-time optimization is pretty simple: walk the program, from every potential entry point, and find the functions that are called or referenced. After the walk, delete the function -> list mappings that weren’t found in the walk. Pass the remaining functions to the lift/transform/lower pipeline and voila—working optimized program.

See also:

• src/crystalpalace/btf/Code.java
• src/crystalpalace/btf/Modify.java
• src/crystalpalace/btf/pass/CallWalk.java
• src/crystalpalace/btf/pass/mutate/LinkTimeOptimizer.java

Lift

Lifting is analyzing the disassembled program to elevate it from low-level object code into a safe-to-manipulate intermediate representation (IR).

This is the most critical piece of the binary transformation framework. It’s where the safety, robustness, and creative freedom comes from. Lifting includes several whole-program analysis tasks.

Crystal Palace groups the lift/transform/lower code into “vertical” classes for each analysis and its associated bookkeeping. This organization lets me reason about each analysis and its lift, transform, and lower tasks in isolation.

Rebuilder.java is the heart of the lift, transform, and lower pipeline.

See also:

• src/crystalpalace/btf/Rebuilder.java
• src/crystalpalace/btf/lttl/*.java

Transform

The transform step acts on the map of functions -> instructions and the lifting-generated analysis.

Transform walks the program, function by function, to create our rebuilt program. Iced’s CodeAssembler class manages the in-progress rebuilt program state. This API provides the same conveniences one would expect from a CLI assembler, like the ability to declare a label and let the assembler translate that to offsets at assemble time.

The transform walk is where the BTF pass changes stuff in the rebuilt program. This is where the bin2bin features become a framework. The implementation has interfaces to make different kinds of modifications. It can:

• Pre-walk a function and change the instruction order or edit instruction meta-information before the rebuild walk. +regdance, +blockparty, and +shatter build on this.
• Inspect symbols referenced by an instruction and swap them for something else. This is what redirect builds on.
• Replace individual instructions with a sequence of one or more instructions that do something that’s logically equivalent.

Lower

The last step of this pipeline is to lower the program back to machine code. It’s during this process that we ask Iced to assemble the program we built via its CodeAssembler API. There are also a few post-assemble passes needed to patch specific details in this rebuilt object code. Lowering is where the BTF updates the symbols and relocations in the input COFF to match the rebuilt program.

A Day in the Lift, Transform, and Lower

The above describes the high-level architecture of Crystal Palace’s binary transformation framework. Now, let’s go deeper and look at the common lift, transform, and lower actions that are part of each BTF pass.

Jumps

One of the most important tasks for a bin2bin is to deal with branch targets. In object code, a branch target is a fixed offset to some instruction elsewhere in the program. If our bin2bin doesn’t universally detect and fix these offsets, any change that affects the size of the program, even by one byte, will break the rebuilt program.

To handle branches, the jumps module walks the program and identifies branching instructions. Thankfully, Iced provides APIs to determine if an instruction is part of a branching group, which saves me from writing manual detection logic.

For each branch target, the jumps module pre-generates a label. This elevates the branch destination from a brittle fixed offset (e.g., “jump +50 bytes”) to an abstract reference (e.g., “jump to Label A”). This abstraction is critical: it decouples the control flow from the physical byte layout.

During the transform walk, jumps identifies each branch instruction again. Instead of reproducing the original instruction with its fixed offset, jumps emits a branch pointing to our pre-generated label.

When the transform walk encounters an instruction that is a target of a branch, it places the corresponding label at that point in the new program. This happens before any replace logic acts, ensuring the label anchors correctly even if the instructions following it are changed.

One of the cool features of Crystal Palace’s jumps module is the ability to “heal” 0-byte jumps. That is, if Crystal Palace detects an unconditional jump to the next instruction—it’ll opt to not emit the jump instruction. This is useful for features like +blockparty which randomize the order of blocks in a function. Sometimes, something that required a jump won’t require a jump from its new position.

See also:

• src/crystalpalace/btf/lttl/Jumps.java.

Local Calls

Crystal Palace treats calls, branches, and references to local functions as a special case, different from other branches. The local calls module is the single place to act on label redirecting logic. This is the foundation of the redirect feature in Crystal Palace.

The lifting step pre-generates a label for each function.

During transform, local calls identifies the beginning of a function and plomps its label down before the function’s instructions are emitted.

The local calls module acts on instructions whose offset refers to a function or other symbol from the COFF:

• Calls are emitted with a reference to a label rather than the original offset.
  
• Function jumps are emitted with a reference to the function label rather than the original fixed offset. MinGW’s -O1 does not use jumps in place of calls. But -O2 and -Os do.
  
• RIP-relative instructions are emitted with the function’s label as the target.

RIP-relative instructions refer to data relative to the instruction pointer. Any RIP-relative instruction not associated with a relocation (e.g., a string or Win32 API IAT entry) is handled here.

This module attempts to cross-reference the RIP-relative offset to a symbol. If there’s no symbol, the RIP-relative instruction code fails with an error. Similarly, if the local calls module detects a RIP-relative instruction that it wasn’t programmed to re-emit, it will also throw an error.

This strictness can cause problems for hand-written assembly embedded in a program. If hand-written assembly uses LEA for something within itself (that is not a symbol in the COFF), this code will raise an error. While I could probably work around this, for now, I encourage users to generate any hand-written assembly separately and use linkfunc to append it to their program.

One of the design goals of Crystal Palace is to detect situations it wants to handle but that I didn’t anticipate, and give a hard error at those points. I’d rather Crystal Palace raise a deliberate, process-stopping error than silently accept something unexpected and have the resulting program crash later.

At the end of the lowering phase, this module updates the symbols to match the functions and offsets in the rebuilt program.

See also:

• src/crystalpalace/btf/lttl/LocalCalls.java

Danger Zones

One of the perils of bin2bin transformation is corrupting the RFLAGS register. This is where ALU instructions dump meta-information about the last mathematical operation. Conditional branching instructions key off these flags.

The risk is real: if I replace an instruction with a sequence that changes RFLAGS around, I can corrupt the comparison logic in the program I’m modifying. Not fun!

To mitigate this, Crystal Palace tracks danger zones. It identifies instructions that modify flags and subsequent instructions that read them. Any instruction occurring between that write and read sits in a danger zone.

Different parts of the BTF handle these zones differently:

• The code mutator (an optional operation) skips mutations in these zones.
• The PIC ergonomics features (like dfr, fixbss, and fixptrs) throw a hard error.

I could use this meta-information to preserve the RFLAGS register in these situations, but for now, I prefer to fire an error. It’s safer and creates one less code path to test. Modifications within danger zones are rare with -O1, but when they do occur, they are logic bugs waiting to happen. That makes this analysis essential.

See also:

• src/crystalpalace/btf/lttl/Zones.java

Relocations

Earlier, I mentioned relocations are compiler-generated hints. They are the unknowns in our object code. Having access to these hints is a huge boon for us. Thanks to relocations, we know if an instruction is accessing something in .rdata or .bss. The attach, dfr, fixbss, and fixptrs features all act on instructions with associated relocations.

Like branch targets, relocations are associated with specific offsets in our object code, and we have to sync these offsets with our program’s changes.

The relocations lifter finds all of the relocations in the program. For each relocation, it:

• Pre-generates a label.
• Tracks the offset of the relocation within the associated instruction.
• Ties the original relocation information with this information.

The BTF pipeline doesn’t do anything with relocations on its own. The default behavior is to re-emit these instructions with the pre-generated label marking where in the new program these instructions live. However, any passes (e.g., dfr, fixbss) that modify an instruction with relocations have to take special care.

If a relocation-referencing instruction is changed, the pass needs to associate the relocation label with the new instruction and set the right offset to the relocation within that new instruction. Some passes “swallow” relocations because the new logic renders them unnecessary.

During lowering, the relocations module walks each relocation, finds its new location (thanks to the instruction label and fixed offset into the instruction), and patches in the relocation value from the input program. It’s here the relocations table is regenerated and the COFF is updated.

Confusingly, the relocation value itself is also an offset—but it is an offset into the section or symbol data the relocation is a hint for. When I say “fixed offset into the instruction,” I am referring to the physical location where that relocation value lives.

See also:

• src/crystalpalace/btf/lttl/RelocationFix.java
• src/crystalpalace/btf/lttl/Relocations.java

> It works, except when it doesn’t

There’s some room for improvement here. Right now, when I change an instruction, I rely on an explicit offset to mark where the relocation lives inside the instruction. For example, if I put down a MOV instruction to dump an immediate into a register, I assume the instruction is five bytes and the relocation begins at offset 1.

The above works, but it also led to a bug that took some work to track down. During testing, MinGW generated an instruction with an extra prefix byte. When I pushed that program through my binary transform pipeline, the program broke, and I had no clue why.

Iced’s assembler removed the prefix because it was redundant. These optimizations aren’t strange—Iced silently encodes jump instructions to the most size-efficient form for the target.

But, this specific removal was a disaster. Suddenly, the relocation offset was out of sync. Because the instruction had shrunk by one byte, the relocation was pointing to where the value used to be, not where it actually was.

I hadn’t seen this until I got lucky and my test crashed. If this happens with another instruction, I may move to a scheme that matches relocations not to a byte offset, but to an abstract position (e.g., Displacement, Immediate 1, Immediate 2) and uses that to calculate the byte offset dynamically during the rebuild.

This is an example of the tension between doing something that works right now and holds well in most situations–with an occasional exception that I manually deal with–versus engineering a lifting pass and a post-rebuild lowering pass to enforce an always-sane final result.

New Features

Somewhere in here, this is a release blog post.

I’d like to use these new features as a case study for the framework I just described. You might notice I’m downplaying the “why” behind these additions. That’s intentional. What’s implemented right now is only half the story; the rest is coming in a future update.

For now, these new features serve as a good example of what individual passes built on the BTF foundation look like.

Reg Dance

+regdance is Crystal Palace’s take on a popular compiler pass that randomizes register allocation. Because I’ve implemented this in a bin2bin context, I made several conservative choices to protect the integrity of the transformed program.

+regdance uses a lifting pass to determine which non-volatile registers each function pushes to the stack. Non-volatile registers are saved and restored by any function that tampers with their values. This makes them safe to use even if our function makes a call (or if we insert a call to a helper function).

On x64, non-volatile registers include R12-R15, RSI, RDI, RBX, and RBP. However, there are caveats. Sometimes, RSI and RDI are used as mandatory operands for specific instructions (e.g., x64 string instructions). To create a safe randomization set, I walk the function and remove non-volatile registers used in a “fixed” way. My implementation also excludes RBP, though I may lift this restriction in a future release.

Once I’ve identified the “safe-to-randomize” registers, I create a map to shuffle the set (e.g., R12 maps to RSI, R13 maps to RBX, etc.).

During transform, +regdance walks the operands for each instruction. If the operand is a register in our randomization set, it performs the swap. I also check and swap displacement and index registers. The logic normalizes each register to its root to check the set (e.g., ESI -> RSI) and the swapped register is converted to the correct sub-register width. This transformation is done without logic specific to any instruction.

When the randomized register set is big enough, this feature offers enough variance to make it worthwhile. A randomized set of N registers yields N! potential permutations.

• 3 Registers: 6 permutations
• 4 Registers: 24 permutations
• 5 Registers: 120 permutations
• 7 Registers: 5,040 permutations

That best case requires a hairball of a function; 0-5 registers is typical. If I allow RBP into the mix later, that will unlock more variance. This feature skips randomization if the set contains fewer than three registers.

This is where compilers have the advantage. A compiler pass can work with more of the register set, potentially mixing volatile and non-volatile registers. This yields significantly more permutations. Because Crystal Palace works from a bin2bin context, I’m limited by the need to manage the risks of modifying a compiled program.

There’s one other design choice to note: this implementation avoids modifying the function prologue and epilogue. This means +regdance limits itself to the registers the function was already using. I do this to preserve the push and pop contents at the function boundaries. Prologues and epilogues are deterministic and common compiler outputs. Altering them creates an anomaly that can stand out. I like to avoid these anomalies where I can.

See also:

• src/crystalpalace/btf/lttl/SavedRegContext.java
• src/crystalpalace/btf/pass/mutate/RegDance.java

Block Party

While +regdance is a bin2bin attempt to approximate a common compiler obfuscation, +blockparty stands on more neutral ground. +blockparty is a feature to shuffle basic blocks within each function.

A basic block is a sequence of instructions with one entry point and one exit point. It is the fundamental unit of analysis for optimizers, analysis tools, and program editing tools.

One of the Crystal Palace lifting analyses splits the whole program into blocks, grouping them by function. To find blocks in a stream of instructions, I rely on the leaders algorithm. It’s a straightforward walk. The first instruction of a function is the beginning of a block. If an instruction is a jump target, it is the beginning of a block. If an instruction is a branch, the next instruction is the beginning of a new block. Some implementations treat calls as block boundaries, but mine does not.

+blockparty inserts itself into the BTF pipeline as a pre-walk filter on a function’s instructions. This filter retrieves all the blocks for a function, keeps the first block static to preserve the function entry, and shuffles the rest. It then dumps these reordered instructions into a new list for the transform walk.

During transform, Crystal Palace checks if the processed instruction is the end of a fall-through block. It then peeks at the next instruction in the walk. If the next instruction is not the original fall-through target, the BTF dynamically emits a jump instruction to connect the just-ended block to its correct destination.

See also:

• src/crystalpalace/btf/lttl/Blocks.java
• src/crystalpalace/btf/mutate/BlockParty.java

Shatter

One of the fun things in this framework is the ability to play with whole program structure. An application of this power is +shatter. The +shatter feature is like +blockparty, but it randomizes blocks across the entire program.

When I built +blockparty and +shatter, I wasn’t thinking about an effect on Ghidra or other analysis engines. That isn’t needed for the use cases I care about. Instead, I am thinking about the assumptions baked into how content signatures are derived and how memory scanners work. +shatter plays with the concept of code locality. What is predictably contiguous becomes limited to the basic block itself.

What I didn’t do with +shatter is opt to dynamically split blocks further. I considered splitting blocks after a fixed number of instructions. However, I have another idea for a complementary primitive that I’ll look at for the next release.

See also:

• src/crystalpalace/btf/pass/mutate/Shatter.java

-O1 Support (MinGW32 Compiler Optimizations)

The last major feature in this release is support for -O1. This falls into the “I had to do it sometime” category.

A program compiled with -O0 looks drastically different from a program compiled with optimizations. An -O0 binary treats the stack as the source of truth, resulting in a flood of instructions to keep local variables synced on the stack. Almost nothing in production ships with -O0. -O1 is the baseline for production code.

That said, supporting a new optimization level isn’t trivial for a bin2bin tool. Different compiler flags and optimization levels generate different patterns of instructions.

Crystal Palace’s PIC ergonomic features (dfr, fixbss, fixptrs) are not instruction agnostic. I have to anticipate exactly which instructions the compiler will select when your program calls a function, references a function, or interacts with data in .rdata or .bss. Crystal Palace maintains specific transformations for each of these patterns. If an unanticipated instruction appears, Crystal Palace won’t silently generate a broken binary. Instead, it recognizes the gap and raises an explicit error.

> Dirty Leaves Made My Code Fall

Compiler optimizations do weird things. One of the x64 ABI requirements is that the stack is 16 byte aligned before a call. Certain instructions (e.g., SIMD instructions) will crash the program if the stack isn’t 16b aligned. A call, by the way, breaks 16b alignment when it pushes the return address onto the stack. In a -O0 program, every function fixes the stack alignment in the prologue. In a -O1 context, the compiler… takes liberties.

I ran a test where I added a SIMD movaps “crash canary” to dfr and fixbss in my tests:

#ifdef WIN_X64
	__asm__ __volatile__(
        	"sub $0x10, %%rsp\n\t"
        	"movaps %%xmm0, (%%rsp)\n\t"
        	"add $0x10, %%rsp"
        	::: "memory"
	);
#endif

I wanted to see if any of my transformations created an unaligned stack. Sure enough, two of my tests crashed. I was very confused, because the same transforms worked in the other tests.

With -O1 enabled, the compiler opts out of aligning the stack in the prologues of some leaf functions. A leaf is a function that doesn’t make any calls. This is OK, because if the function doesn’t make any calls (or use instructions that require alignment), why waste bytes and cycles to adjust the stack in the prologue and epilogue?

But, if we dynamically insert a function call (e.g., dfr acting on a reference, anything fixbss)—well… we’re no longer a leaf function. The unaligned stack is now a problem. This problem required creating an analysis pass to find dirty leaves. A dirty leaf is a leaf function with an unaligned stack.

The problem is that some leaf functions preserve registers in their prologue. Sometimes, the preserved registers align the stack. Other times, they don’t. The dirty leaf analysis walks the function’s instructions and determines if, accounting for the various stack operations, the stack is aligned. This informs which value dfr and fixbss expand the stack to when inserting their calls.

See also:

• src/crystalpalace/btf/lttl/DirtyLeaves.java

> Fighting the Compiler

If you compile your programs with -O1, expect that you will fight the compiler more. For example, the compiler might see a small function that you intend as a redirect join point and decide to inline its contents instead of calling it. Or, if it’s empty, just omit the call altogether. I encountered this surprise removal with the Tradecraft Garden Hooking example. In fight-the-compiler situations __attribute__((optimize("O0")) disables optimizations for a specific function. That didn’t help my hooking example though. Here’s how I dealt with the inlining and elimination of my empty setupHooks join point:

/*
 * This is an empty function, but we will use redirect to LAYER setupHooks from our modules on top of this.
 *
 * NOTE: gcc with -O1 likes to inline some functions and an empty or minimal function is a prime candidate for
 * inlining. I'm using noinline to prevent that tragedy, because if a function is inlined, we can't redirect it
 */
void __attribute__((noinline)) setupHooks(char * srchooks, char * dsthooks, DLLDATA * data, char * dstdll) {
	/*
	 * And, in the fighting the optimizer department, -O1 likes to also not call a function it believes has
	 * no side-effects. So, we stick this here to say GCC LEAVE MY EMPTY FUNCTION ALONE!
	 */
	__asm__ __volatile__("");
}

What about -Os and other compiler optimizations?

If you’re going to use Crystal Palace to turn a COFF into PIC, compile your code with -O0 or -O1. This is what’s most likely to work with fixbss, dfr, and fixptrs.

For situations where you’re not turning a COFF into PIC, things are more relaxed. A potential use case of Crystal Palace is to merge + attach tradecraft with Beacon Object Files before they’re run. But, some popular BOFs (e.g., the Situational Awareness commands) are compiled with -Os. For this reason, there’s some -Os support in Crystal Palace. For example, attach and redirect are able to act on jumps to functions. Function jumps don’t show up in -O0 or -O1 code.

Down the road, I imagine sticking with -O1 as the supported optimization level. I can meet -Os halfway in some cases. -O2 or -O3 are probably not going to happen.

Migration Notes

None.

Closing Thoughts

The theme for this release is robustness. This effort was driven by the pain of supporting -O1 optimization. I ran into a lot of situations with -O1 that I simply didn’t see with -O0. While this post focused on x64, the x86 transforms received a rigorous overhaul too.

This release significantly refactored and updated the binary transformation framework. The architecture now strictly separates vertical lift/transform/lower concerns, making it easier to add new “verticals” as needed. It also provides cleaner interfaces to design new passes with.

As a developer, any effort that tames internal complexity and makes it clean and extensible is a win. It means every future feature sits on a reasoned and workable foundation. That’s where we’re at now.

Enjoy the release!

For a full list of what’s new, check out the release notes.

What’s more relaxing than a beautiful fall day, a crisp breeze, a glass of Sangria, and music from the local orchestra? Of course, I expect you answered: writing position-independent code projects that separate capability from tradecraft. If you didn’t answer that way, you’re wrong.

In the last six months, Tradecraft Garden has covered a lot of ground. This project started as a linker to make it easier to write position-independent code DLL loaders and it has rapidly evolved into an Aspect Oriented Programming tool to weave tradecraft into PIC and PICO capabilities. It can still write position-independent code DLL loaders too (modular and self-incepting DLL loaders, at that)—but there’s a lot more potential here.

One of the needs in the current model, is that while we can separate tradecraft from capability in C—the linker script forces us to define our architecture and tradecraft as one monolithic thing. Separating base architecture and tradecraft, within the specification files themselves, is the theme of this release.

Build Templates with %variables

This release introduces %variables into the Crystal Palace specification language. These are user-defined strings passed in at the beginning of the program. %variables are usable anywhere you would use a “string” argument in Crystal Palace’s specification language.

For example:

load %foo

This command will resolve %foo and load its contents. Easy enough, right?

We also have string concatenation with the <> operator too. So:

load %foo <> “.x64.o”

This will resolve %foo and append .x64.o to it.

With %variables comes the need to better understand what a script is doing. The new echo command prints its arguments to STDOUT (CLI) or to a SpecLogger object (API):

echo “I am looking at: “ %hooks

%variables evolve the Crystal Palace specification file language from a collection of commands into a build templating language. That is, a specification file may now define the architecture of a loader or capability with the information about specific tradecraft getting added later.

Simple Loader – Execution Guardrails uses these new features. The loader is now agnostic to the follow-on specification file it encrypts and packs. The %STAGE2 variable is a stand-in for that file. You can pair this stage with one of the other examples from the Tradecraft Garden (including a COFF loader or just straight PIC).

Populating %variables (“The Glue”)

For this base architecture and specific tradecraft separation to work, we need a glue. That is a means to specify %variables.

Specifying %variables via the Java API is easy. Put a “%variable” key into the environment map with a “string” value.

You may also specify %var=”value” arguments via the ./link and ./piclink CLI tools too.

If you want to keep a variable configuration in a file, add @file.spec to your program’s CLI. This will read file.spec and use its commands to populate variables before the main linker script is run. And yes, we have new commands to set %variables from a Crystal Palace .spec file.

setg sets a variable within the global scope for this build session:

setg “%bar” “0xAABBCCDD”

Crystal Palace has a concept of scope for variables too. You will almost always want global variables in these configuration files. But, local scope exists for variables that are visible only within the current label’s execution context. Use set to set a local variable:

set “%foo” “file.spec”

With any commands that set or update %variables, quote the variable name to prevent Crystal Palace from evaluating the variable to its contents before command execution.

And, pack is a way to marshal %variables (and other strings) into a $VARIABLE byte array.

pack $VAR “template” “arg1” %arg2 …

The Perl programmer in me can’t resist a good pack command. pack accepts a variable, template string, and list of arguments that correspond to the characters in the template string. Think of the template as a condensed C struct definition. Each character specifies how pack will interpret the argument string and what type it will marshal the value to.

While I see these commands as configuration tools, they are generic Crystal Palace commands. You can use them anywhere.

Layering and Chaining

While straight variable substitution is handy, sometimes, we want to mix and match modules of an unknown quantity. That’s where the next feature helps.

Crystal Palace’s foreach command expects a comma-separated list of items as its argument.

foreach %libs: mergelib %_

The foreach command walks the provided list and calls another Crystal Palace command with %_ set to the current element of the list. %libs needs to exist, but an empty value is OK. The goal of foreach is to act as a placeholder for layered tradecraft that’s dynamically brought into a base architecture.

The next command is a list shift and execute tool. next expects a “%variable” name argument and it expects %variable is a comma-separated list of values. If the list is empty, next does nothing. If the list is not empty, next removes %variable’s first item and runs the specified command with %_ set to that element.

next “%NEXT”: run %_

The goal of next is to support chaining tradecraft together, giving cooperating modules a mean to pass execution through each other.

Modular Specification File Contracts

Crystal Palace’s main modularity tool is to create separate .spec files and use run to execute their commands in another file. This release gives us more modularity options.

The run command now accepts positional arguments. And, it passes them on to the child script as %1, %2, %3, etc.

run “file.spec” “arg1” %arg2

The positional arguments of “file.spec” are local to that run of that file. If file.spec runs another .spec file, the positional arguments are local to that specification file’s runs. The local scope is necessary to prevent our .spec files from stepping on each other’s arguments.

This release also adds callable labels to specification files too. Think of them as local runnable files, user-defined commands, or Crystal Palace functions. To create a callable label use:

name.x64:

Then, list your commands like normal. That’s it. These labels are callable with a dot name syntax and accept positional arguments too:

.name “arg1” “arg2”

The nice thing about this feature is we now have a choice or whether to split a function into its own .spec file or let it co-exist inside of the current .spec file. And, while this is nice, that’s not why I chose to build this feature. The real payoff is the call command.

call runs a callable label from another specification file:

call “file.spec” "name" “arg1” “arg2”

call is an encapsulation tool. That is, our base specification defines the architecture of our capability or loader. %variables become the placeholder for our tradecraft implementation. And, callable labels and call let us present the pieces of a tradecraft in a single file, with a common interface (callable labels), that our base architecture expects to act on.

Simple Loader – Hooking demonstrates this idea. It defines a base architecture for hooking a DLL and a modular contract for hooking tradecraft modules. XORhooks demonstrates this contract. Stack Cutting is now a module that composes on top of this base loader. What’s really cool? You can layer them together.. See the Simple Loader – Hooking notes for more on this.

File Paths

One of the mundane, but important details in this scheme is file path resolution. Crystal Palace commands treat file paths as relative to the current .spec file. With %variables, things get messy, because we might specify a file path in one place (e.g., the CLI, @config.spec, an argument to run/call) and it gets used elsewhere. The resolve command brings some predictability to this.

resolve “%files”

resolve will walk through %files (assuming it’s a comma-separated list of files), canonicalize each entry to a filename [relative to the current .spec], and set %files to these full paths. This gives you control over when this path resolution happens and which .spec context its relative to.

The -r CLI option will resolve file paths in a %key=”value” argument provided that way.

Migration Notes

1. The link and piclink shell scripts changed in this version. You’ll want to update to the latest from the Crystal Palace distribution or source archive.
   
   
2. I’ve updated the CLI syntax for piclink and link to accept % and $ sigils for %VAR and $DATAKEY values specified on the command-line. The old behavior of KEY=[bytes] to set $KEY still works, but going forward, the documentation and other materials will use explicit sigils. You may want to update your scripts to use explicit sigils too.
   
   
3. Several of the methods in crystalpalace.spec.LinkerSpec were deprecated. I cleaned up the API to make it easier to share arguments between a configuration LinkSpec and the main LinkSpec. https://tradecraftgarden.org/docs.html#javaapi

Closing Thoughts

This release introduced several commands and features to change how Crystal Palace specification files work together.

The combination of %variables and the ability to set those via the Java API or CLI allow our users to combine a base specification with specific tradecraft choices later on. This turns a base PIC into a re-usable component.

Callable labels and call allow us to encapsulate tradecraft modules into a single file with different touch points (e.g., initialization, apply hooks) available via a common convention. Pair this with foreach and we have a means to specify tradecraft modules in one %variable and use them at the right-spots within the base project.

The goal of this release is to move Tradecraft Garden projects from singular monolithic examples, that each redefine everything, into reusable components to compose tradecraft cocktails with.

To see the full list of what’s new, check out the release notes.

It’s 2025 and apparently, I’m still a Java programmer. One of the things I never liked about Java’s culture, going back many years ago, was the tendency to hype frameworks that seemed to over-engineer everything. One of the hot trends I never understood, was Aspect-Oriented Programming. I now have a healthy respect for AOP’s core ideas, as there’s real overlap with Tradecraft Garden’s goals and the Crystal Palace effort.

Aspect-Oriented Programming

Aspect-Oriented Programming is a paradigm to add functionality to a base program that normally needs code in a lot of places, but to do it from one place. The classic example is logging. A base program might not have any logging built-in at all. Aspect-Oriented Programming is a way to take this cross-code need and uniformly apply it to different points of interest in the program. In some AOP models (as we’ll discuss here) it’s possible to add features without changing the base program at all.

Aspect-Oriented Programming ideas and design patterns are absolutely relevant to separating capability and tradecraft, whether use-case and tool agnostic (as I’m working to do) or to make a C2 modular and flexible.

Here’s a quick run-down of Aspect-Oriented Programming vocabulary:

A cross-cutting concern is functionality one needs to apply into many places in a base program.

Join Points are specific instrumentation opportunities or places in the program one can attach an Advice to. These are the opportunities to get into the flow of the program.

An Advice is code that implements cross-cutting functionality.

A Pointcut is a mechanism to define (and even dynamically select) Join Points to insert Advice into. Pointcut refers to both the mechanism and a specific query to choose Join Points.

An Aspect is a module that packages Advices, Pointcut mechanisms, and Pointcut selectors.

The process of adding Aspects to a program is called Weaving. There are different methods of weaving. Some AOP frameworks process source code directly. Some managed runtime AOPs dynamically generate object proxies. Some AOPs rely on binary transformations like what I’m doing with Crystal Palace. LLVM plugins that dynamically add tradecraft at compile-time is AOP and Weaving too.

Hooking and other instrumentation techniques are a form of weaving. What separates AOP weaving from dynamic instrumentation like Frida, is AOP weaved functionality is part of production use rather than a temporary and risky intrusion into running code.

Crystal Palace PIC and AOP

Crystal Palace’s PIC service modules are an example of Aspect-Oriented Programming. Every PIC needs to resolve functions and the specific method is often painfully tangled with the program. This is true for using (or awkwardly avoiding) global variables too. These are cross-cutting concerns.

In Crystal Palace, Win32 API resolutions are a PIC Join Point. dfr attaches function resolution advice (the resolver) to these join points. dfr demonstrates a selective Pointcut feature too. Crystal Palace dynamically selects DFR advice for each Win32 API using its module as criteria. The end result is that a PIC capability exists blissfully agnostic to the service module that it’s paired with. This is possible because Crystal Palace weaves these Advices into the program through its binary transformation framework..

My point summoning all of this isn’t to flex with arcane enterprise programming jargon from 20+ years ago. Rather, it’s to show that there’s a body of work on these ideas that pre-dates a niche profession’s 2025 needs. And, to highlight that others used this paradigm to separate tightly coupled and disparately spread functionality into something architecturally clean, centralized, and swappable. This exists.

Attach, Redirect, Protect, Preserve, and Optout

In the recent Arranging the PIC Parterre, Daniel Duggan speculated:

“CP’s ability to weave helper functions inline with a merged capability provides a lot of exciting potential. A feature that I think would be really useful is changing how an API call is performed after it’s been resolved… but being able to rewrite DFR functions to push execution through a similar proxy, but without having to do explicit hooking, would be awesome.”

I fully agree. And today, I’ve got another update to Crystal Palace and Tradecraft Garden. This update brings weaving-enabled AOP primitives to PIC and PICOs.

One cross-cutting concern is Win32 API calls. Each Win32 API call is an opportunity to choose something equivalent, but stealthier, or to decorate the call with some sort of evasive action (e.g., prepping a fake call stack). To attach Advice (tradecraft) to a Win32 API call, we have the attach command:

attach “MODULE$Function” “_Hook1”

attach disassembles our program, finds references to MODULE$Function (M$F’er), and switches instructions and relocations to use _Hook1. This is weaving.

Crystal Palace applies these changes in a context-aware way. For example, M$F’er calls and references in _Hook1 are not updated. This means you can M$F’er from _Hook1 and access the original functionality.

M$F’er advices stack too. Let’s add this command after the above:

attach “MODULE$Function” “_Hook2”

This attach updates _Hook1’s M$F’er reference to _Hook2. _Hook2’s use of the Win32 API is untouched. A _Hook3 would update _Hook2’s reference to the API. Crystal Palace tracks this chain and knows which functions get which hooks. Each hook decides whether to call the target API and continue the chain. Hooks execute in a first-attached first-executed order.

Crystal Palace’s model to add hooks to a capability is to merge the hooks COFF with the capability COFF. That’s the merge verb introduced a few releases ago.

The updated Stack Cutting project in the Tradecraft Garden demonstrates attach. This IAT hooking demo now uses attach to incept some of the PIC loader’s Win32 API calls and push them through the stack cutting call proxy. I mean, why not?

redirect is another primitive, similar to attach. redirect targets the program’s local function calls:

redirect "function" "_hook"

The semantics of redirect are like attach. Calls and references to the target function within the hook aren’t touched. And, hooks stack too. Calls to function() within _hook and its successors execute the rest of the chain.

While redirect is awesome, don’t use it in place of the obvious. If you wish to lay functionality over a base program with a 1:1 mapping–good ol’ fashioned modular C is the right tool here. Declare an undefined function in a base module, use it, and merge the chosen implementation later.

One design pattern redirect enables is Chain of Responsibility. Imagine a C2 agent ships with a processinject() function. Its implementation is print an “I failed” error. With redirect, an end-user could stack processinject() advices onto this function in a desired handling order. If a processinject() advice is not applicable to the context (or it fails) it calls the next processinject(). On down the chain until one succeeds or the original “I failed” is reached. merge brings processinject() advices in dynamically. Maybe a big library with a bunch of them. With link-time optimization enabled, the unused functions go away. This same pattern could apply to communication modules or any number of things. That’s the power here.

If attach or redirect are used on a non-existing Join Point (e.g., the function or Win32 API doesn’t exist)—the command will do nothing. If link-time optimization is enabled, Advices not attached to something will get removed when the PICO or PIC is exported.

These powerful cross-program hooking tools require ways to isolate parts of the program from these hooks. That’s what protect, preserve, and opt out are for.

protect isolates the listed functions from all attach and redirect hooks. dprintf is opted into this automatically. Use this tool to protect debugging tools and other sensitive code.

protect "function1, function2, etc."

preserve protects a specific target (local function or Win32 API) from attach and redirect hooks in the listed function contexts. Use preserve functions that need direct access to the target function or its pointer.

preserve "target|MODULE$Function" "function1, function2"

optout prevents specific hooks from taking effect within a function. Use optout to isolate a tradecraft setup function from its own hooks. This makes it possible for other tradecraft to modify the setup function later.

optout "function" "hook1, hook2, hook3"

When I started this work, I had ambitions to explore a many to 1 call proxy for attach and redirect. I thought I could come up with a scheme that used %rax/%eax to keep the original function pointer. But, as I thought on this further, I didn’t like it. My thought is that I would need a many to 1 proxy for each number of arguments I expect to proxy (e.g., proxy2, proxy3, etc.). I also didn’t have a means to have Advices follow function pointers. I opted to abandon this approach and go with tractable 1:1 mappings.

I really like this implementation of attach and redirect. Nothing feels janky about it. The program output after attach and redirect is indistinguishable from the original program calling the hook function. In some cases, attach simplifies the instructions some (e.g., it detects load/call to pre-call fetch a Win32 API’s pointer from an IAT slot and simplifies this to call hook).

Right-sized IAT Hooking

One of the tradecraft and capability separation models I cater to is the PIC loader paired with a DLL (or PICO) capability. Here, Win32 APIs are an of-interest Join Point. And, our method to apply Aspects/tradecraft to Win32 API calls is to hook these APIs during the load process.

This Crystal Palace update adds some features to help with the above. addhook registers a MODULE$Function hook with Crystal Palace.

addhook “MODULE$Function” “hook”

Specify as many of these as you like. Crystal Palace won’t throw an error if a MODULE$Function hook isn’t used.

These registered hooks are used by the __resolve_hook() linker intrinsic (defined in tcg.h):

FARPROC __resolve_hook(DWORD functionHash);

A linker intrinsic is a pseudo-function that expands into linker generated code later in the process. __resolve_hook() generates code to turn a Function ror13 hash into a hook.

One of the problems with IAT hooks, is we don’t know which capability (or variation) they’re going to get attached to. And, so we run the risk of specifying too many hooks and having a bloated loader/tradecraft layer or specifying too few, in the name of code economy. This release helps with this problem too:

filterhooks $DLL

The filterhooks command walks the imports of a specified $DLL or $OBJECT and removes registered hooks that aren’t needed in this capability context. What this means is our dynamically generated __resolve_hook() function only maps hashes to hooks that are needed by $DLL or $OBJECT. Pair this with link-time optimization and the unused hooks are removed when the final program is generated. Right-sized IAT hooking!

The Simple Loader (Hooking) and Stack Cutting examples demonstrate these IAT hooking features.

Tips for Hooking

Here are some tips to write addhook and attach hook functions, compatible with the original API call:

1. hook should accept the same number and type of arguments as the Win32 API you’re attaching to.
   
2. hook should have the same decorators (e.g., WINAPI) as the Win32 API you’re attaching to. These set things like the calling convention (e.g., __cdecl vs. __stdcall). If the hook and API don’t match here, it’ll bite ya—especially on x86.
   
3. Don’t decorate hooks with __declspec(dllimport) or something that aliases it (e.g., WINBASEAPI, DECLSPEC_IMPORT, etc.). Crystal Palace won’t treat these symbols like local functions.
   
4. Beware: x86 __stdcall convention function symbols have @## after the function name. Crystal Palace expects full function symbols in most places. The ## is the size (in bytes) of arguments pushed onto the stack. Multiply the number of arguments by four and you’ve guessed the ## value. If you forget @## in a symbol, Crystal Palace will throw an error–BUT it’ll also suggest which full symbol name it thinks you meant.

PICO Function Exports

This release adds PICO function exports and a PICO API to get their function pointers.

exportfunc exports a function and assigns it a tag intrinsic:

exportfunc “function” "__tag_function"

This process generates a random integer tag for the function. This tag makes the exported function discoverable via the PICO’s loading directives.

We don’t know this hidden tag value. That’s where __tag_function() comes in. This pseudo-function is replaced with the hidden tag at link time. __tag_function() is available globally to any PIC/PICO exported after exportfunc is used.

Here’s the prototype to declare __tag_function:

int __tag_function();

Use this intrinsic with PicoGetExport to get a pointer to the exported function:

PICOMAIN_FUNC pFunction = PicoGetExport(picoSrc, picoDst, __tag_function());

The purpose of the tag scheme is to make dynamic linking safer. Originally, I had a manual user-assigned tag scheme. And, even I, illustrious developer of this cockamamie tool, found I couldn’t keep an integer synced between two files. I chased a crash because I forgot exportfunc too. If __tag_function() resolves–we know that exportfunc was used on a valid PICO function during this linking session.

Simple Loader (Hooking) merges two PICOs to save a memory allocation and relies on exportfunc to call code in the merged PICO. Simple Loader (Hooking) and Stack Cutting use exportfunc to make post-merge tradecraft setup APIs available between a hooks module and base loader in their shared architecture.

Migration Notes

(1) I’ve changed the function signatures of findFunctionByHash and findModuleByHash in tcg.h to use the right types. You’ll need to update your DFR resolvers to keep the compiler happy:

FARPROC resolve(DWORD modHash, DWORD funcHash) {
	HANDLE hModule = findModuleByHash(modHash);
	return findFunctionByHash(hModule, funcHash);
}

(2) I’ve removed reladdr from Crystal Palace and revoked permission for linked contents to use partial pointers. fixptrs is now required for x86 PIC doing anything interesting.

Closing Thoughts

I led this post with Aspect-Oriented Programming for good reason. Aspect-Oriented Programming is an instrumentation-enabled programming paradigm. AOP does not replace modular C programming. Instead, it’s a complement to layer cross-program changes onto a base program. Evasion tradecraft is a cross-cutting program concern that benefits from AOP-style tools.

While Crystal Palace continues to serve the PIC loader + DLL capability problem set, I think this technology’s most exciting when using PICOs (usable as PIC or with a loader) as an AOP-friendly canvas to compose fully realized tradecraft demonstrations onto.

To see what’s new, check out the release notes.

The goal of Tradecraft Garden is to separate evasion tradecraft from C2. Part of this effort involves looking for logical lines of separation. And, with PIC, I think we’ve just found one of them.

Two weeks ago, I introduced several features that brought a unified convention model for Crystal Palace PIC and its BOF-like PICOs. This release continues that effort by fixing some bugs and expanding on these features.

Dynamic Function Resolution, Revisited

Last release, I added a means for Crystal Palace PIC to call Win32 APIs using the Dynamic Function Resolution convention. The implementation has Crystal Palace disassemble the program, find any calls to a MODULE$Function Win32 API, and dynamically insert a call to a user-provided resolver (specified, in the specification file) to turn that call into a ready-to-use pointer.

Part of where I’m going with this work, is I’d like one set of conventions to write PICOs and PIC–with the same program working as-is in either context. When I introduced PIC DFR, I realized… shit… I painted myself into a corner here.

PICO loaders have a convention to act on libraries that are not loaded in the current process yet. The current DFR model for PIC doesn’t. I ran into this problem when recording my PIC ergonomics video. I had to debug why a call to User32$MessageBoxA crashed. No User32 library. 😦 The solution was to add LoadLibraryA(“User32”) at the beginning of the program.

This release solves the above problem. Crystal Palace specification files can now specify multiple Dynamic Function Resolution resolvers and either associate a resolver with a specific set of modules OR set a default resolver.

Now, it’s possible to do this:

dfr “resolve” “ror13” “KERNEL32, NTDLL”

And Crystal Palace will use the resolve() function with the ror13 module and function arguments to resolve APIs tied to Kernel32 or NTDLL.

And, for everything else, we can set a default resolver:

dfr “resolve_ext” “strings”

The above is the same syntax introduced in the last release. Any API not matched to another resolver will fall back to the default resolver. And, it’s perfectly OK for the default resolver to use KERNEL32 and NTDLL APIs to aid its work (since they’re resolved in a different resolver):

char * resolve_ext(char * mod, char * func) {
    HANDLE hModule = KERNEL32$GetModuleHandleA(mod);
    if (hModule == NULL)
        hModule = LoadLibraryA(mod);
 
    return (char *)GetProcAddress(hModule, func);
}

Say yes to the .bss (PIC Global Variables)

One of the ass-pains that inspired Crystal Palace was my attempt to implement Page Streaming as a DLL loader without access to global variables to keep state. Clearly, there’s a lot we can do in PIC without global variables—but it’s nice to have the option when it’s needed.

Crystal Palace’s fixbss command is a way to bring (uninitialized) global variables to Crystal Palace position-independent code. Like fixptrs and dfr, this command relies on a binary transform and a helper function. When a fixbss function is provided, Crystal Palace will disassemble your program, find instructions that reference .bss data (uninitialized global variables), and dynamically insert a call to your function. This function must reliably return the same pointer to read/write memory where the .bss data can live in memory. The beautiful part of restoring just the .bss section, is we don’t have to worry about copying over any initial data. We just need read/write memory of a suitable size that is initialized (or already set to) zeroes.

Now, the question becomes… how to implement our fixbss function? This is a tradecraft question and there are certainly different creative ways to do this.

The Simple PIC Tradecraft Garden example demonstrates one way. Its specification file defines getBSS as our .bss fixing function.

fixbss “getBSS”

Simple PIC implements getBSS by looking for a data cave. What is a data cave? It’s unused space within a loaded library or program we can stash data into. Simple PIC’s getBSS uses the slack space between a read/write mapped section’s real size and it’s rounded-up to the nearest page virtual size. We simply walk a few modules (in my example, I walk the current program and Kernel32), find their mapped .data section, and check if the slack space is large enough to accommodate our program’s .bss section. This space is already read/write, it’s predictable to find with a walk, and it’s initialized to zero. Perfect for our demonstration. But, beware—my implementation is not friendly to multiple PICs in the same process using this technique.

Other caveats apply. Crystal Palace only transforms certain common instruction forms (here: load address, load, store, and store a constant for byte/word/dword/qword types) with this feature. As soon as you start doing esoteric stuff or enabling optimizations—you may run into instruction forms Crystal Palace can’t handle.

While I think transparent availability of globals in PIC is a cool trick, I want to clarify something important. This is not a push to always use transformed PIC. My goal is more parity between PIC and PICOs. In situations where I’m allocating or repurposing eXecutable memory in the current process for a capability… I think the better choice is a loaded PICO (globals, strings, Win32 API, etc. without binary transforms). What we get with this parity is code re-use between PIC and PICOs, a common set of skills to write PIC and PICOs, and flexibility to choose the right output for the needs of the situation. That’s why I’ve made this work part of the Crystal Palace effort.

Remap

This release adds a symbol remapping command (e.g., remap “old” “new”). This is a dumb primitive to simply rename a symbol in your COFFs symbol table.

One use of symbol remapping is to aid those of you who dislike the Dynamic Function Resolution convention. Simply create a .spec file of APIs you might use and fill it with:

x86:
  remap “__imp__Function@8” “__imp__MODULE$Function@8”
  remap “__imp__VirtualAlloc@16” “__imp__KERNEL32$VirtualAlloc@16"

x64:
  remap “__imp_Function” “__imp_MODULE$Function”
  remap “__imp_VirtualAlloc” “__imp_KERNEL32$VirtualAlloc

Remap won’t complain if a function you intend to remap doesn’t exist.

The above isn’t the only use of remap. The remap command is also a way to build one binary and, in the context of a specification file, remap one of several stand-by implementations of an expected function to the expected name. This is better described with an example.

Tradecraft Garden’s Simple Object and DLL loader demonstrated (with too much complexity) what it looks like to write a loader that works for a PICO or a DLL. The remap command gives us a tool to simplify this example some.

Rather than have two Makefiles (one for a DLL loader, another for an Object loader)—we instead compile one loader binary. And, our loader binary as-built has no go() function defined. Instead, it has go_dll and go_object.

With remap, our specification file can remap “go_object” “go” when we have an object target. And, we can also remap “go_dll” “go” when we have a DLL target.

What about the extra unneeded function? Use make pic +optimize and let the link-time optimizer get rid of the unused function. The end result is starting with one binary, we’re able to use our .spec file context to tailor that program down to exactly what’s needed for the situation.

Migration Notes

None.

Closing Thoughts

With these new features introduced, let’s revisit this logical line of separation thing.

One of the responsibilities of a DLL loader is to bootstrap the needed execution “stuff” to allow loading a DLL. That is finding Win32 APIs, allocating memory, etc. These bootstrapping behaviors are a detection opportunity and an area for exploring/finding alternate techniques.

Today, it’s easy to think of a PIC program as a monolithic thing that must do everything, including its own bootstrapping. But, with Crystal Palace we now have a clear line between bootstrapping and capability within PIC itself.

The bootstrapping functionality for our PIC loaders is the stuff that Crystal Palace’s helper functions implement: the x86 pointer fixing, the .bss fixing to get global variables back, and our strategy to satisfy the contract of dynamic function resolution. The choices made for each of these bootstrapping chores is a tradecraft choice and it makes sense to keep these bootstrapping cocktails separate of and agnostic to the follow-on PIC. We can do this now.

The new Simple PIC example in the Tradecraft Garden demonstrates this separation well. I’ve implemented a PIC bootstrapping cocktail as something I call a service module. This service module is scoped to the functionality our PIC capability needs to restore key language features and start doing real work in a Win32 process space. It handles bootstrapping like a loader, but it’s not a loader—because it doesn’t load anything.

Crystal Palace’s model to pair a service module with a capability is to merge the two programs into one and dynamically weave calls to the different helper functions into the end-capability to make everything work as expected. [I intend to explore what else this approach can buy us.]

The Simple PIC project merges its service module with an arbitrary PICO to make a functional PIC program. This separation makes the code easier to digest, it makes the follow-on loader agnostic to these bootstrapping choices, and it containerizes an important set of discrete tradecraft choices (e.g., we could have an arsenal of PIC bootstrappers to choose from and they could stand-alone as self-contained units of study).

Thoughtful containerization, finding these lines of separation, is the name of the game here. This is all part of an effort to reframe offensive security research as a systemic security science. And, I believe componentization of the attack chain is a needed step to enable this.

To see what’s new, check out the release notes.

Enjoy the release.

When I started work on Crystal Palace, my initial thought was to see how much I could ease development of position-independent code DLL capability loaders using the tools and manipulations possible with a linker. The initial Tradecraft Garden examples were built with these primitives.

Crystal Palace doesn’t just merge and append COFFs though. It’s a powerful binary transformation framework as well. That is, Crystal Palace has the ability to disassemble a compiled program, turn it into an abstract form, manipulate it, and put it back together. This technology is the foundation of Crystal Palace’s code mutation, link-time optimization, and function disco features.

Before we go further, I’d like to shout out Austin Hudson’s Orchestrating Modern Implants with LLVM Fortra booth presentation at BlackHat 2025. One of the LLVM uses he described was transforming non-PIC x86 programs to working PIC. It’s a cool talk and it inspired me to look at binary transformations to make Crystal Palace PIC more ergonomic. Which gets to the new features…

This release adds features to transform x86 and x64 programs, written to PICO conventions, into working position-independent code. While these binary transformations are opt-in (you can still manually copy and paste ror13 hashes from elsewhere, if you really want to), they greatly simplify writing PIC and I’m all-in with them. All of the examples in the Tradecraft Garden were simplified with these new tools.

And, taking full advantage of unified conventions for x86 PIC, x64 PIC, and x86/x64 PICOs—this release introduces a Crystal Palace concept of shared libraries to aid modularity, code re-use, and open up opportunities to participate in the ground truth eco-system this project seeks to build.

Dynamic Function Resolution for PIC

One of the defining features of Cobalt Strike BOFs and Crystal Palace PICOs are Dynamic Function Resolution (DFR). That is, calling Win32 APIs as MODULE$Function to give their loaders the needed hints to resolve the right function pointer.

Crystal Palace now has Dynamic Function Resolution for x86 and x64 PIC. Because PIC has no loader, acting on this convention requires a different approach. Here, the binary transformation framework helps. Crystal Palace walks your program, finds instructions that reference __imp_MODULE$Function symbols, and dynamically inserts code to call a user-provided resolver function. This new code replaces the original instruction that would have expected a patch from the loader.

To opt into this feature, specify a DFR resolver in your Crystal Palace specification file:

dfr “resolver” “method”

There are two resolver methods right now: ror13 and strings. The method dictates the arguments generated and passed to the resolver function.

The ror13 method will turn MODULE and Function into ror13 hashes and pass them as arguments to your resolver function. The strings method pushes strings onto the stack and calls your resolver with pointers to these strings. Most Tradecraft Garden Simple Loaders demonstrate the ror13 method. Simple Loader – Pointer Patching (which patches-in a pre-existing GetProcAddress/GetModuleHandle) demonstrates the strings method.

With this feature, this goes away:

And, we get this instead:

Crystal Palace’s PIC DFR convention expects you’re resolving Win32 APIs from already loaded libraries. If you’re writing a full-fledged capability as PIC, make sure you load any needed libraries at the beginning of your program.

If you’re worried that the above introduces unwelcome fixed constants into your program, fear not. Crystal Palace’s code mutation, when enabled with “make pic +mutate”, will rewrite these constants for you.

Fixing x86 PIC Pointers

One of the barriers to unified code for x86 PIC and x64 PIC is the addressing model. x86 programs reference data using a model known as direct addressing, that is they expect to know the full address of any data they work with. Crystal Palace PIC, so far, has worked around x86’s direct addressing model with hacks. That is, Crystal Palace patches in an offset to any referenced data and expects, somehow, that the PIC’s C code takes special steps to turn that offset into a full pointer. These hacks are why Tradecraft Garden was full of #ifdef macros like this:

But, thanks to another opt-in transform—we can get away from the above:

fixptrs  “_caller”

The fixptrs command accepts the name of a caller function. This is a simple contract. The caller function’s job is simply to return its return address. And, the above becomes this:

When fixptrs is set, Crystal Palace will walk your x86 PIC, find any data references, and rewrite the instructions to create a full pointer. (The caller function aids this process.) This means you don’t have to rely on #ifdef hacks and manually calculated instruction offsets to referenced linked data or function pointers in x86 PIC.

This also opens another door. Crystal Palace’s “make pic” now appends .rdata to x86 and x64 PIC programs. Thanks to the fixptrs feature, x86 instruction references to .rdata now work too—giving x86 PIC access to string constants without any special handling in your C code.

The above makes “make pic64” redundant and I’ve removed “make pic64” from Crystal Palace. “make pic64” was an opt-in way to append .rdata to x64 PIC programs and (thanks indirect addressing) get access to string constants from x64 PIC.

While the above is a lot of fun, there are some caveats. x86 references to .rdata, especially with compiler optimizations enabled, generate a lot of possible instruction forms. Crystal Palace only has strategies for the most common forms. When a novel instruction form is encountered, Crystal Palace will catch it, and fail with an error stating it can’t fix the pointer. This is a good hint to either disable optimizations in your x86 PIC or… at least… to disable optimizations within the offending function.

What should go() first?

In position-independent code, your entry point must live at position 0 of your program. Tradecraft Garden used to satisfy this requirement by specifying a go() function at the top of a program, before anything else is included, and having it call the real entry point:

Now, you can declare your entry point as go. And, with make pic +gofirst—Crystal Palace will move this function to position 0 of your PIC.

This is a minor ergonomic feature for developers and another way to make PIC work more like PICOs. Like all of the above features, it’s opt-in via your Crystal Palace specification file.

Shared Libraries

With the above work, Crystal Palace now has shared conventions for x86 PIC, x64 PIC, and x86/x64 PICOs. In practice, this means a compiled object written to these conventions should “just work” in an x86, x64 PIC or PICO context. And, this paves the way for Crystal Palace shared libraries.

Crystal Palace shared libraries are zip files with compiled objects that use these common conventions to offer easy code re-use between PIC and PICO projects. Note: Crystal Palace PIC does not support read/write global variables, where PICOs do. Shared libraries that wish to work with PIC and PICOs should not use read/write global variables either.

The first Crystal Palace shared library is LibTCG, the Tradecraft Garden Library. LibTCG is all of the common functionality in the Tradecraft Garden examples now. It offers DLL parsing and loading, PICO running, printf debugging, and Export Address Table API resolution. LibTCG replaces all of the duplicate #include header files that implemented this functionality in the previous iterations of the Tradecraft Garden examples.

Use Crystal Palace’s mergelib "lib.x64.zip" command to merge all of the objects from a Crystal Palace shared library into a PIC or PICO.

Now, you may have some concerns about the above in the context of offensive security use cases. The first concern is size. Naturally, a shared library will come with a lot of stuff your current program doesn’t need—making it artificially larger than it would be. Well, you can still load and merge individual objects if you like. But, there’s another solution to this problem too: link-time optimization. Crystal Palace’s link-time optimization walks your program, starting at the entry point go, and builds a set of all called/referenced functions. It then rewrites your program to keep the used stuff and get rid of the unused stuff. So, that’s one solution.

Of course, incorporating a shared library means a static content fingerprinting playground. But, that’s why we have code mutation. And, you can use function disco to shuffle functions and effectively interweave imported content with your bespoke content. It’s up to you. Further, if a shared library has a stable API—there’s nothing to say you can’t maintain a private version of that library and keep it for your projects while letting the generic fingerprinted version demonstrate functionality publicly.

Shared Libraries also fill an eco-system gap in Tradecraft Garden’s model. Up until now, I struggled with how I (or others) might expose one-off tradecraft ideas or variations of existing ideas—without writing a bespoke loader for each. Crystal Palace’s shared libraries are path to package and document one-off or like ideas into something easy to incorporate and use from both PIC and PICOs.

License Change

When I initially released the Tradecraft Garden, I chose the BSD license for Crystal Palace. This was a deliberate choice to welcome this component’s integration and use in commercial and open source projects.

Separately, I chose the GPLv2 for Tradecraft Garden’s example loaders. I liked the idea of the GPLv2 as a way to keep the derived tradecraft open. My goal isn’t just an open source eco-system though. I want something that welcomes security conversation-aligned commercial players to co-create value with this commons. A permissive license better serves my goal to create this security conversation-aligned eco-system and more opportunities for offensive security research.

So, in the spirit of weeding the garden and cleaning things up, I’m relicensing the Tradecraft Garden example loaders under the BSD license. (And, for those of you who’ve built on the previous code, I’ve released an updated package with those materials under a BSD license—which you’re welcome to use if you wish for the permissive freedoms). For anyone building open source on this tech, I encourage you to use a permissive license (e.g., BSD, MIT, Apache 2.0).

Migration Path

Here are the migration notes for projects updating to the latest release of Crystal Palace:

This release deprecates “make pic64”. Use make pic instead.

The Makefile for LibTCG requires zip in your WSL environment. Use sudo apt-get install zip to install it

The rest of the features are opt-in and won’t break existing code and specification files. But, I recommend looking at these new conventions as they are the future of Tradecraft Garden:

1. Use “make pic +gofirst” in all of your PIC programs and rename the intended entry point to go()
2. Move away from explicit ROR13 hashes and port your PIC programs to use Dynamic Function Resolution
3. Opt into the x86 pointer fixing with fixptrs and get rid of the manual #ifdef hacks and pointer offsetting required before.
4. Ditch the original Tradecraft Garden common functionality headers and move over to the Tradecraft Garden library. You just need to #include “tcg.h” and use mergelib to include libtcg.x86.zip (or libtcg.x64.zip) in your program.

To see what’s new, check out the release notes.

Enjoy the release.