donut - Generates x86, x64, or AMD64+x86 position-independ

项目说明

![Issues]()
![Contributors]()
![Stars]()
![Forks]()
![License]()
![Chat]()
![Github All Releases]()
![Twitter URL]()

!Alt text

<p>Current : <a href="

<h2>Table of contents</h2>

<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#how">How It Works</a></li>
<li><a href="#build">Building</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#subproj">Subprojects</a></li>
<li><a href="#dev">De with Donut</a></li>
<li><a href="#qad">Questions and Discussions</a></li>
<li><a href="#disclaimer">Disclaimer</a></li>
</ol>

<h2 id="intro">1. Introduction</h2>

<p><strong>Donut</strong> is a position-independent 代码 that enables in-memory execution of , JScript, EXE, DLL files and dotNET assemblies. A module created by Donut can either be staged from a HTTP 服务端 or embedded directly in the loader itself. The module is optionally encrypted using the <a href=" block cipher and a 128-bit randomly generated key. After the file is loaded and executed in memory, the original reference is erased to deter memory scanners. The generator and loader support the following features:</p>

<ul>
<li>Compression of input files with aPLib and LZNT1, Xpress, Xpress Huffman .</li>
<li>Using entropy for API hashes and generation of strings.</li>
<li>128-bit symmetric encryption of files.</li>
<li>O native PE headers.</li>
<li>Storing native PEs in MEM_IMAGE memory.</li>
<li>Patching Antimalware Scan Interface (AMSI) and Windows Lockdown Policy (WLDP).</li>
<li>Patching Event Tracing for Windows (ETW).</li>
<li>Patching command line for EXE files.</li>
<li>Patching exit-related API to avoid termination of host process.</li>
<li>Multiple output formats: C, Ruby, Python, PowerShell, Base64, C#, Hexadecimal, and UUID string.</li>
</ul>

<p>There are dynamic and static libraries for both Linux and Windows that can be integrated into your own projects. There's also a python module which you can read more about in <a href=" and using the Python extension.</a></p>

<h2 id="how">2. How It Works</h2>

<p>Donut contains indi loaders for each supported file type. For dotNET EXE/DLL assemblies, Donut uses the Unmanaged CLR Hosting API to load the Common Language Runtime. Once the CLR is loaded into the host process, a new Application Domain is created to allow for running Assemblies in disposable AppDomains. When the AppDomain is ready, the dotNET Assembly is loaded via the AppDomain.Load_3 method. Finally, the Entry Point for EXEs or public method for DLLs specified by the user is invoked with any additional parameters. Refer to MSDN for documentation on the <a href=" CLR Hosting API.</a> For a standalone example of a CLR Host, refer to <a href=" here.</a></p>

<p> and JScript files are executed using the IActi interface. There's also minimal support for some of the methods provided by the Windows Script Host (wscript/cscript). For a standalone example, refer to <a href=" here.</a> For a more detailed description, read: <a href=" Execution of Ja, , JScript and XSL</a></p>

<p>Unmanaged or native EXE/DLL files are executed using a custom PE loader with support for Delayed Imports, TLS and patching the command line. Only files with relocation information are supported. Read <a href=" Execution of DLL</a> for more information.</p>

<p>The loader can disable AMSI and WLDP to help evade detection of malicious files executed in-memory. For more information, read <a href=" Red Teams Bypass AMSI and WLDP for .NET Dynamic 代码</a>. It also supports decompression of files in memory using aPLib or the RtlDecompressBuffer API. Read <a href=" Compression</a> for more information.</p>

<p>As of v1.0, ETW is also bypassed. Like with AMSI/WLDP, this a modular system that allows you to swap out the default bypass with your own. The default bypass is derived from research by XPN. Read <a href=" your .NET - ETW</a> for more information.</p>

<p>By default, the loader will o the PE headers of unmanaged PEs (from the base address to IMAGE_OPTIONAL_HEADER.SizeOfHeaders). If no decoy module is used (module o), then the PE headers will be zeroed. If a decoy module is used, the PE headers of the decoy module will be used to o those of the payload module. This is to deter detection by comparing the PE headers of modules in memory with the file backing them on disk. The user may request that all PE headers be preserved in their original state. This is helpful for scenarios when the payload module needs to access its PE headers, such as when looking up embedded PE resources.</p>

<p>For a detailed walkthrough using the generator and how Donut affects tradecraft, read <a href=" - Injecting .NET Assemblies as Shellcode</a>. For more information about the loader, read <a href=" .NET Assemblies From Memory</a>.</p>

<p>Those who wish to know more about the internals should refer to <a href=" notes.</a></p>

<h2 id="build">3. Building</h2>

<p>There are two types of build. If you want to debug Donut, please refer to <a href=" here</a>. If not, continue reading for the release build.</p>

<h3><strong>Clone</strong></h3>

<p>From a Windows command prompt or Linux terminal, clone the repository.</p>

<pre>
git clone
</pre>

<p>The next step depends on your operating system and what compiler you decide to use. Currently, the generator and loader template for Donut can be compiled successfully with both Microsoft Studio 2019 and MingGW-64. To use the libraries in your own C/C++ project, please refer to the <a href=" provided here.</a></p>

<h4><strong>Windows</strong></h4>

<p>To generate the loader template, dynamic library donut.dll, the static library donut.lib and the generator donut.exe. Start an x64 Microsoft Studio De Command Prompt, change to the directory where you cloned the Donut repository and enter the following:</p>

<pre>
nmake -f Makefile.msvc
</pre>

<p>To do the same, except using MinGW-64 on Windows or Linux, change to the directory where you cloned the Donut repository and enter the following:</p>

<pre>
make -f Makefile.mingw
</pre>

<h4><strong>Linux</strong></h4>

<p>To generate the dynamic library donut.so, the static library donut.a and the generator donut. Change to the directory where you cloned the Donut repository and simply type make.</p>

<h3>Python Module</h3>

<p>Donut can be installed and used as a Python module. To install from 源码 requires pip for Python3. First, ensure older of donut-shellcode are not installed by issuing the following command on Linux terminal or Microsoft Studio command prompt.</p>

<pre>
pip3 uninstall donut-shellcode
</pre>

<p>After you confirm older are no longer installed, issue the following command.</p>

<pre>
pip3 install .
</pre>

<p>You may also install Donut as a Python module by grabbing it from the PyPi repository.</p>

<pre>
pip3 install donut-shellcode
</pre>

<p>For more information, please refer to <a href=" and using the Python extension.</a></p>

<h3>Docker</h3>

<p>Building the docker container.</p>

<pre>
docker build -t donut .
</pre>

<p>Running donut.</p>

<pre>
docker run -it --rm -v "${PWD}:/workdir" donut -h
</pre>

<h3>Support Tools</h3>

<p>Donut includes several other executables that may be built separately. This include "hash.exe", "encrypt.exe","inject.exe", and "inject_local.exe". The first two are used in shellcode generation. The latter two are provided to assist with testing donut shellcode. "inject.exe" will inject a raw binary file (loader.bin) into a process by its PID or process name. "inject_local.exe" will inject a raw binary file into its own process.</p>

<p>To build these support executables separately you may use the MS. For example, to build "inject_local.exe" to test your donut shellcode, you may run.</p>

<pre>
nmake inject_local -f Makefile.msvc
</pre>

<h3>Releases</h3>

<p>Tags have been provided for each release of Donut that contain the compiled executables.</p>

<ul>
<li><a href=" TBD</a></li>
<li><a href=" Bear Claw</a></li>
<li><a href=" Apple Fritter</a></li>
<li><a href=" Initial Release</a></li>
</ul>

<p>Currently, there are two other generators a.</p>

<ul>
<li><a href=" generator by n1xbyte</a></li>
<li><a href=" generator by awgh</a></li>
</ul>

<h2 id="usage">4. Usage</h2>

<p>The following table lists switches supported by the command line of the generator.</p>

<table border="1">
<tr>
<th>Switch</th>
<th>Argument</th>
<th>Description</th>
</tr>

<tr>
<td><strong>-a</strong></td>
<td><var>arch</var></td>
<td>Target architecture for loader : 1=x86, 2=amd64, 3=x86+amd64(default).</td>
</tr>

<tr>
<td><strong>-b</strong></td>
<td><var>level</var></td>
<td>Behavior for bypassing AMSI/WLDP : 1=None, 2=Abort on fail, 3=Continue on fail.(default)</td>
</tr>

<tr>
<td><strong>-k</strong></td>
<td><var>headers</var></td>
<td>Preserve PE headers. 1=O (default), 2=Keep all</td>
</tr>

<tr>
<td><strong>-j</strong></td>
<td><var>decoy</var></td>
<td>Optional path of decoy module for Module O.</td>
</tr>

<tr>
<td><strong>-c</strong></td>
<td><var>class</var></td>
<td>Optional class name. (required for .NET DLL) Can also include namespace: e.g <em>namespace.class</em></td>
</tr>

<tr>
<td><strong>-d</strong></td>
<td><var>name</var></td>
<td>AppDomain name to create for .NET. If entropy is enabled, one will be generated randomly.</td>
</tr>

<tr>
<td><strong>-e</strong></td>
<td><var>level</var></td>
<td>Entropy level. 1=None, 2=Generate random names, 3=Generate random names + use symmetric encryption (default)</td>
</tr>

<tr>
<td><strong>-f</strong></td>
<td><var>format</var></td>
<td>The output format of loader saved to file. 1=Binary (default), 2=Base64, 3=C, 4=Ruby, 5=Python, 6=PowerShell, 7=C#, 8=Hexadecimal</td>
</tr>

<tr>
<td><strong>-m</strong></td>
<td><var>name</var></td>
<td>Optional method or function for DLL. (a method is required for .NET DLL)</td>
</tr>

<tr>
<td><strong>-n</strong></td>
<td><var>name</var></td>
<td>Module name for HTTP staging. If entropy is enabled, one is generated randomly.</td>
</tr>

<tr>
<td><strong>-o</strong></td>
<td><var>path</var></td>
<td>Specifies where Donut should save the loader. Default is "loader.bin" in the current directory.</td>
</tr>

<tr>
<td><strong>-p</strong></td>
<td><var>parameters</var></td>
<td>Optional parameters/command line inside quotations for DLL method/function or EXE.</td>
</tr>

<tr>
<td><strong>-r</strong></td>
<td><var></var></td>
<td>CLR runtime . MetaHeader used by default or v4.0.30319 if none a.</td>
</tr>

<tr>
<td><strong>-s</strong></td>
<td><var>服务端</var></td>
<td>URL for the HTTP 服务端 that will host a Donut module. Credentials may be provided in the following format: <pre>
</tr>

<tr>
<td><strong>-t</strong></td>
<td></td>
<td>Run the entrypoint of an unmanaged/native EXE as a thread and wait for thread to end.</td>
</tr>

<tr>
<td><strong>-w</strong></td>
<td></td>
<td>Command line is passed to unmanaged DLL function in UNICODE format. (default is ANSI)</td>
</tr>

<tr>
<td><strong>-x</strong></td>
<td><var>option</var></td>
<td>Determines how the loader should exit. 1=exit thread (default), 2=exit process, 3=Do not exit or cleanup and block indefinitely</td>
</tr>

<tr>
<td><strong>-y</strong></td>
<td><var>addr</var></td>
<td>Creates a new thread for the loader and continues execution at an address that is an offset relative to the host process's executable. The value provided is the offset. This option supports loaders that wish to resume execution of the host process after donut completes execution.</td>
</tr>

<tr>
<td><strong>-z</strong></td>
<td><var>引擎</var></td>
<td>Pack/Compress the input file. 1=None, 2=aPLib, 3=LZNT1, 4=Xpress, 5=Xpress Huffman. Currently, the last three are only supported on Windows.</td>
</tr>
</table>

<h3 id="requirements">Payload Requirements</h2>

<p>There are some specific requirements that your payload must meet in order for Donut to successfully load it.</p>

<h3 id="requirements-dotnet">.NET Assemblies</h2>

<ul>
<li>The entry point method must only take strings as arguments, or take no arguments.</li>
<li>The entry point method must be marked as public and static.</li>
<li>The class containing the entry point method must be marked as public.</li>
<li>The Assembly must NOT be a Mixed Assembly (contain both managed and native 代码).</li>
<li>As such, the Assembly must NOT contain any Unmanaged Exports.</li>
</ul>

<h3 id="requirements-native">Native EXE/DLL</h2>

<ul>
<li>Binaries built with Cygwin are unsupported.</li>
</ul>

<p>Cygwin executables use initialization routines that expect the host process to be running from disk. If executing from memory, the host process will likely crash.</p>

<h3 id="requirements-dotnet">Unmanaged DLLs</h2>

<ul>
<li>A user-specified entry point method must only take a string as an argument, or take no arguments. We ha an <a href="
</ul>

<h2 id="subproj">5. Subprojects</h2>

<p>There are four companion projects provided with donut:</p>

<table border="1">
<tr>
<th>Tool</th>
<th>Description</th>
</tr>
<tr>
<td>DemoCreateProcess</td>
<td>A sample .NET Assembly to use in testing. Takes two command-line parameters that each specify a program to execute.</td>
</tr>
<tr>
<td>DonutTest</td>
<td>A simple C# shellcode injector to use in testing donut. The shellcode must be base64 encoded and copied in as a string.</td>
</tr>
<tr>
<td>ModuleMonitor</td>
<td>A proof-of-concept 工具 that detects CLR injection as it is done by tools such as Donut and Cobalt Strike's execute-assembly.</td>
</tr>
<tr>
<td>ProcessManager</td>
<td>A Process Discovery 工具 that offensi may use to determine what to inject into and defensi may use to determine what is running, what properties those processes have, and whether or not they have the CLR loaded. </td>
</tr>
</table>

<h2 id="dev">6. De with Donut</h2>

<p>You may want to add support for more types of payloads, change our feature set, or integrate Donut into your existing tooling. We ha <a href=" documentation</a>. Additional features are left as exercises to the reader. Our suggestions:</p>

<ul>
<li>Add en keying.</li>
<li>Make Donut polymorphic by obfuscating the loader every time shellcode is generated.</li>
<li>Integrate Donut as a module into your fa RAT/C2 框架.</li>
</ul>

<h2 id="qad">7. Questions and Discussion</h2>

<p>If you have any questions or comments about Donut. Join the #Donut channel in the <a href=" Gang Slack</a></p>

<h2 id="disclaimer">8. Disclaimer</h2>

<p>We are not responsible for any misuse of this software or technique. Donut is provided as a demonstration of CLR Injection and in-memory loading through shellcode in order to provide red teamers a way to emulate ad and defenders a frame of reference for building analytics and mitigations. This ine runs the risk of malware authors and threat actors misusing it. However, we believe that the net benefit outweighs the risk. Hopefully that is correct. In the event EDR or A are capable of detecting Donut or beha patterns, we will not update Donut to counter signatures or detection methods. To avoid being offended, please do not ask.</p>

项目信息

开发语言：C

Star 数：4714

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Generates x86, x64, or AMD64+x86 position-independent shellcode that loads .NET Assemblies, PE files, and other Windows payloads from memory and runs them with parameters展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。