donut_decryptor

A configuration and module extractor for the donut binary obfuscator

Description

donut-decryptor checks file(s) for known signatures of the donut obfuscator's loader shellcode. If located, it will parse the shellcode to locate, decrypt, and extract the DONUT_INSTANCE structure embedded in the binary, and report pertinent configuration data. If a DONUT_MODULE is present in the binary it is decrypted and dumped to disk.

Installation

You can install donut-decryptor for usage by navigating to the root directory of the project and using pip:

cd /path/to/donut-decryptor
python -m pip install .

Following installation, a command-line script is available. For usage instructions use:

donut-decryptor --help

Development

This project uses Hatch for project management, Ruff for linting and formatting, and mypy for type checking.

Setup

Install Hatch:

pip install hatch

Running Tests

hatch run test
hatch run test-cov  # with coverage

Linting and Formatting

hatch run lint:style   # check style
hatch run lint:fmt     # format code and fix issues
hatch run lint:typing  # run mypy type checking
hatch run lint:all     # run all checks

Examples

The files present in the samples directory are 7z files password protected using the password `infected``, all of which contain donuts which can be decoded using this script.

TODO list

• Update detection rules and instance parsing for alternative output formats:
  • Hex
  • C-String/Ruby
  • Python
  • C#
  • Powershell
• Consider moving loader/instance mapping to a YAML configuration file.