Volexity's donut-decryptor locates Donut loader shellcode in suspect files, decrypts the embedded DONUT_INSTANCE and dumps any DONUT_MODULE payload — a malware-analysis utility for authorized defensive research.
| Tool | volexity/donut-decryptor — a Python configuration and module extractor for the donut binary obfuscator |
| Category | Malware analysis / static config extraction (Python, BSD-3-Clause) |
| Primary Use | Parsing Donut loader shellcode in captured samples, decrypting the embedded DONUT_INSTANCE config and dumping any DONUT_MODULE payload to disk for triage |
| Safe Use | Intended for incident responders, malware analysts, and authorized security teams dissecting malicious samples inside controlled lab environments, sandboxes, and isolated analysis VMs |
| Telemetry Note | Purely offline static analysis — it touches no network infrastructure; defenders benefit directly because extracted Donut configs and modules feed YARA/Sigma detection and threat-intel reporting |
donut-decryptor is Volexity's contribution to one of the more persistent pain points in modern malware triage: the donut obfuscator (TheWover's open-source loader) is used both by red teams and by criminal actors precisely because it wraps arbitrary payloads — shellcode, DLLs, EXEs — in an encrypted, position-independent shellcode blob that neutralizes naive static inspection. This tool attacks that problem from the defender's side. It scans candidate files for known signatures of the Donut loader shellcode, and when it gets a hit, it walks the binary structure to locate, decrypt, and extract the embedded DONUT_INSTANCE configuration block. Where a DONUT_MODULE is present, it decrypts that too and dumps it to disk for follow-on analysis.
Architecturally, the tool mirrors the loader it dissects. Donut's shellcode is self-describing at runtime: it decrypts its own DONUT_INSTANCE and DONUT_MODULE structures in memory before executing the payload. A static extractor has to reimplement that decryption logic without ever running the sample — a meaningful safety property, since the malicious code inside is never executed. The README frames this as signature-driven detection followed by structural parsing, which implies the maintainers maintain a mapping between loader shellcode patterns and the offsets/entropy markers needed to find the encrypted instance data. That mapping is currently hardcoded in the project; the TODO list openly notes a plan to move loader/instance mapping to a YAML configuration file, which would make it far easier for analysts to adapt to new Donut builds without touching Python code.
The workflow is deliberately simple. Installation follows standard pip conventions — drop into the repo root and run python -m pip install ., which registers a donut-decryptor command-line script on your path. From there, donut-decryptor --help documents the invocation surface, and the tool accepts file arguments to check against its signature set. This is the shape of a classic batch-triage utility: point it at a directory of suspicious binaries pulled from an IR engagement, and it will tell you which ones are Donut-wrapped and what configuration they carry. That configuration data — the DONUT_INSTANCE — is typically where the operationally interesting facts live, since it encodes how the loader was told to behave.
The engineering hygiene visible in the repo is worth calling out because it signals reliability for a tool you'll trust with hostile input. The project uses Hatch for project management, Ruff for linting and formatting, and mypy for type checking, with a coherent task matrix (hatch run test, hatch run test-cov for coverage, and hatch run lint:style, lint:fmt, lint:typing, lint:all for the quality gates). For a malware-analysis utility, a tested, typed codebase matters: parsing attacker-controlled binaries is exactly the scenario where sloppy offset arithmetic or unhandled exceptions will bite you mid-engagement. The presence of a real test suite with coverage tracking suggests the maintainers treat the parser's correctness as a first-class concern.
The repo also ships practical validation material. The samples directory contains 7z archives, password-protected with the standard analyst convention password infected, each holding a Donut-wrapped binary that the script can decode. This is a well-understood defensive practice — the password both deters accidental execution and signals to mail scanners and archive tooling that the contents are known malware. Analysts using the repo get an immediate regression corpus: if a code change breaks parsing of any known Donut variant, the bundled samples will surface it. It also gives newcomers a safe way to learn the tool's output format without needing their own case material.
The TODO list is candid about current limitations, and it's the most instructive part of the README for understanding coverage boundaries. Donut can emit its loader in multiple output formats — hex strings, C-string/Ruby, Python, C#, and PowerShell — and the detection rules and instance parsing do not yet handle all of these alternatives. In practice that means analysts may encounter Donut samples delivered as, say, a PowerShell byte-array that the current signatures won't catch until it is converted back to raw binary. Anyone incorporating donut-decryptor into an automated pipeline should normalize or de-encode candidate files into raw shellcode form first, then run the extractor against the normalized artifacts.
Context matters here: Volexity is a threat-intelligence and incident-response firm, and the tool's design reflects IR realities. Config extractors like this sit at the front of the analysis chain — immediately after initial triage identifies a sample as likely Donut, and immediately before deeper reverse engineering of the recovered DONUT_MODULE. Recovering the inner payload is the high-value step, because it converts an opaque encrypted blob into the actual implant, loader, or second-stage executable that attribution, detection engineering, and IOC generation all depend on. With 141 stars and a BSD-3-Clause license, the project is comfortably usable in commercial tooling and internal IR platforms without licensing friction.
There's also a broader ecosystem angle. Donut itself is a legitimate dual-use red-team tool, published openly and used widely in authorized adversary simulation. Its abuse by criminal actors is what makes a decoder like this necessary, and the cat-and-mouse between loader updates and signature updates is the ongoing maintenance burden. The proposed YAML-based signature mapping is exactly the right evolutionary step, because it decouples analyst knowledge (new loader byte patterns, new offsets) from the extraction engine, letting the community contribute detection coverage the way YARA rule sets evolve. Watch the commit cadence on that item if you're deciding whether to build pipeline integrations against the current CLI contract.
Operationally, treat donut-decryptor as an offline, host-based static analysis step inside a controlled lab or sandbox VM. It executes no shellcode and contacts no network resources, which reduces the risk envelope considerably compared to dynamic detonation, but the input files remain live malware — standard analyst handling rules apply, including keeping the bundled infected-password archives sealed until needed and running extraction inside an isolated VM with snapshots. The dumped DONUT_MODULE output is itself a live malicious binary and inherits the same handling requirements as the original sample.
For defenders, the secondary value of this tool is detection engineering. The decrypted configuration and loader artifacts recovered from Donut samples feed directly into YARA rules targeting loader stubs, into scanning for Donut's distinctive entropy patterns, and into threat reports documenting actor tradecraft. Because the tool decrypts statically, the extracted DONUT_INSTANCE fields give precise ground truth about how a specific sample was configured, which is exactly the fidelity needed to distinguish one actor's Donut build from another's — a recurring attribution problem given how many groups share the same public loader.
In sum, donut-decryptor is a focused, well-engineered utility that does one job — unwrapping Donut — and documents its own gaps honestly. Its pip-based install, clean CLI, tested Python codebase, and bundled sample corpus make it a low-friction addition to any malware-analysis toolkit, while the format-coverage TODO and planned YAML signature refactor mark the roadmap for where coverage will grow. For authorized analysts facing Donut-wrapped payloads in real incidents, it shortens the path from encrypted blob to actionable intelligence considerably.
volexity/donut-decryptor.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.