Metadata-Version: 2.4
Name: donut-decryptor
Version: 0.1.0
Summary: Decryptor for files containing Donut shellcode
Project-URL: Documentation, https://github.com/volexity/donut-decryptor/blob/main/README.md
Project-URL: Issues, https://github.com/volexity/donut-decryptor/issues
Project-URL: Source, https://github.com/volexity/donut-decryptor
Author-email: Volexity <threatintel@volexity.com>
License-Expression: BSD-3-Clause
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: aplib~=0.6
Requires-Dist: chaskey~=0.0.4
Requires-Dist: lznt1~=0.2
Requires-Dist: yara-python~=4.5
Description-Content-Type: text/markdown

# donut_decryptor

A configuration and module extractor for the [donut binary obfuscator](https://github.com/TheWover/donut)

## 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:

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

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

```bash
donut-decryptor --help
```

## Development

This project uses [Hatch](https://hatch.pypa.io/) for project management, [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy-lang.org/) for type checking.

### Setup

Install Hatch:

```bash
pip install hatch
```

### Running Tests

```bash
hatch run test
hatch run test-cov  # with coverage
```

### Linting and Formatting

```bash
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.
