Malduck

4.4.1 · active · verified Thu Apr 16

Malduck is a Python utility library designed for malware researchers, offering a comprehensive suite of tools for malware analysis. It provides functionalities for cryptography, compression, memory model objects (for PE/ELF/raw files and IDA dumps), a modular extraction engine for configuration, fixed integer types, and string operations. Currently at version 4.4.1, the project is actively maintained with frequent updates addressing bugfixes and introducing new features.

Common errors

```
YaraError: rules are not compatible with this version of YARA-Python
```
cause An incompatibility between the installed `malduck` version and your `yara-python` version, especially around `yara-python 4.3.0`.

fix If using Malduck v4.3.1, downgrade `yara-python` to `4.2.3` (`pip install "yara-python==4.2.3"`). If using a newer Malduck version, ensure `yara-python` is updated (`pip install --upgrade yara-python`).
```
AttributeError: module 'malduck.dnpe' has no attribute 'dnfile'
```
cause The `dnpe` module's typing or dependencies were incorrectly defined or fixed in a patch release.

fix Upgrade `malduck` to version 4.4.1 or later to get the fix: `pip install --upgrade malduck`.
```
TypeError: __init__() missing 1 required positional argument: 'parent' (or similar errors with Extractor decorators)
```
cause When defining custom extractor modules, the class or its methods are not correctly initialized or decorated according to `malduck.extractor` API changes in v4.0.0.

fix Ensure your custom `Extractor` class inherits from `malduck.Extractor` and its methods are decorated correctly (e.g., `@Extractor.string('rule_name')`). Consult the official Malduck extractor documentation for the correct method signatures and decorator usage for your specific version.

Warnings

breaking Minimum Python version changed from 3.6 to 3.8. Users on older Python versions will encounter installation or runtime errors.
Fix: Upgrade Python environment to 3.8 or newer. Malduck recommends Python 3.8+ due to EOL of older versions.
gotcha Compatibility issues with `yara-python` version 4.3.0. Malduck v4.3.1 strictly pinned `yara-python` to `4.2.3` but later versions fixed compatibility with `>=v4.3.0`.
Fix: For Malduck v4.3.1, manually install `yara-python==4.2.3`. For Malduck versions >=4.3.2, ensure `yara-python` is updated to a compatible version (e.g., `pip install --upgrade yara-python`).
breaking Extractor methods in `malduck.extractor` require explicit decorators (e.g., `@Extractor.extractor`, `@Extractor.string`) prior to v4.0.0. After v4.0.0, the decorator application order and arguments changed.
Fix: Review the `malduck.extractor` documentation for the specific version being used. Ensure extractor methods are correctly decorated as per the new API (e.g., `@Extractor.string("string_identifier")`).
gotcha The `pefile` dependency was bumped to `>=2022.5.30` in v4.3.0, and a `FastPE` patch for `pefile.PE` was removed. Older `pefile` versions might cause unexpected behavior or missing functionality.
Fix: Ensure `pefile` is updated to `2022.5.30` or newer: `pip install --upgrade pefile`.

Install

pip install malduck Install stable version

Imports

aes
```
from malduck import aes
```
aplib
```
from malduck import aplib
```
DWORD
```
from malduck import DWORD
```
Extractor
wrong:
```
from malduck.extractor import Extractor
```
correct:
```
from malduck import Extractor
```
Most core modules are directly importable from 'malduck' due to how it's structured, avoiding deeper submodule imports unless specifically needed.
procmempe
```
from malduck import procmempe
```
Yara
```
from malduck.yara import Yara
```

Quickstart

Demonstrates basic AES-CBC encryption and decryption using Malduck's built-in cryptography functions. This is a common task in malware analysis for handling encrypted configuration data.

from malduck import aes

key = b'\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10'
iv = b'\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f\x20'
plaintext = b'This is a secret message.'

ciphertext = aes.cbc.encrypt(key, iv, plaintext)
decrypted_text = aes.cbc.decrypt(key, iv, ciphertext)

print(f"Original Plaintext: {plaintext}")
print(f"Ciphertext (hex): {ciphertext.hex()}")
print(f"Decrypted Text: {decrypted_text}")

view raw JSON →