Skip to content
Sustainable shellcode evasion
Python Assembly
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Update the INSTALL file with the new repo URL Dec 4, 2019


Crimson Forge

Crimson Forge intends to provide sustainable evasion capabilities for native code on the x86 and AMD64 architectures. It achieves this by rewriting the input code utilizing the following two techniques:

Shuffling: Instructions are shuffled into a new order at the basic block level. This is a reliable technique and does not modify the size of resulting binary.

Alterations: Instructions are swapped with functional equivalents, effectively de-optimizing them. New instructions are inserted into the same graph used by the Shuffling technique, allowing them to be reordered as well.

Due to the nature of the re-writing, it is not necessary for processed shellcode to exist within writeable memory. This eliminates a very common pattern which is identified as malicious by many AV and EDR systems.


See the for installation instructions.

Getting Started

Once installed, utilize the primary command line interface at ./crimson-forge. The help menu documents each of the options. Basic usage includes specifying an architecture (e.g. amd64 or x86), providing an input file, and specifying an output file. By default both the input and output files are expected to be raw shellcode, not executable files such EXEs. Use the --format and --output-format options to specify the input and output data formats respectively. Note that the --output-format option can be specified multiple times. Additionally, arguments can be defined in a file one per line and passed using the syntax ./crimson-forge @file/with/args.txt. See data/common-arguments.txt as an example.

Known Limitations

Unstaged Payloads: Unstaged payloads as generated by the Metasploit Framework are currently not functional due to the constraints on the file format.

Tainted References: Certain payloads retrieve references to their location in memory and then apply a static offset to it. Crimson Forge has no way to identify the significance of the static offset which will change when Alterations are applied. Crimson Forge will attempt to identify instances where this occurs and will disable Alterations altogether to ensure a functional output is produced. However, disabling Alterations limits the capability to generate unique binaries.

Encoded Payloads: All encoding modules within the Metasploit Framework require the shellcode to be placed in memory with Read, Write and Execute (RWX) permissions. This defeats the purpose of Crimson Forge. See also Tainted References.

Overlapping Instructions: In certain, theoretical scenarios instructions may overlap with one another. This would be the case where one instruction jumps or calls an address within another instruction. This would cause the block-level analysis to be misaligned.

The following example would result in a jump into the body of the move instruction resulting in the flow of execution being jmp $+3, inc eax rather than what is stated.

jmp  $+3
mov  eax, 0xc0ff0000

Technical Documentation

The existing technical documentation of the internal API is able to be built with Sphinx. Build the documentation with the following command:

sphinx-build -a -E -v -b html docs/source docs/html


Crimson Forge was originally designed and developed by RSM US LLP in Q1 of 2019 as part of an offensive security research and development initiative.

You can’t perform that action at this time.