TOCORATOR

████████╗ ██████╗  ██████╗ ██████╗ ██████╗  █████╗ ████████╗ ██████╗ ██████╗
╚══██╔══╝██╔═══██╗██╔════╝██╔═══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗
   ██║   ██║   ██║██║     ██║   ██║██████╔╝███████║   ██║   ██║   ██║██████╔╝
   ██║   ██║   ██║██║     ██║   ██║██╔══██╗██╔══██║   ██║   ██║   ██║██╔══██╗
   ██║   ╚██████╔╝╚██████╗╚██████╔╝██║  ██║██║  ██║   ██║   ╚██████╔╝██║  ██║
   ╚═╝    ╚═════╝  ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝

by dimareverse

Statically extract the payload embedded in Nuitka onefile binaries. Fully static — the target is never executed. Ideal for software analysis and malware triage.

---

What it does

Nuitka's --onefile mode bundles a whole Python distribution (the compiled program, python3xx.dll, every .pyd, data files…) into a single executable. The bootstrap binary unpacks that payload at runtime into a temp directory.

TOCORATOR parses that payload directly from the file, with zero execution:

• fancy TUI (menu, colored boxes, progress bar, hexdump inspector)
• plain CLI (--list, --info, batch-friendly)
• payload auto-discovery in 4 known locations
• automatic layout detection (compression / checksums / archive mode / name encoding)
• integrity report: CRC32 verification, JSON manifest with per-entry CRC32
• detects DLL-mode dists (no .exe inside — by design) and generates a runnable RUN_APP.pyw launcher that mimics what the Nuitka bootstrap does
• tells you what a non-Nuitka file actually is (PyInstaller, .NET, native Qt/MinGW app…)

From extracted payload to Python source

TOCORATOR stops at extraction. What you do next depends on the target:

• Full source recovery: feed the extracted files to HEXPYRION — the new-generation Nuitka decompiler, with markedly better performance (speed) and accuracy, maximum universality and excellent scalability (--ndx --dev-only <binary> -o OUT).
• Alternative onefile extractor: extremecoders-re/nuitka-extractor.
• Worst case — Themida/WinLicense-protected builds: follow the nuitka-themida-unpacker pipeline, where the whole process is documented step by step. ⚠️ That pipeline requires running the sample: make sure you are inside a protected, isolated environment (disposable VM, no network, no shared folders) before you start.

Quick start

pip install zstandard pefile     # pefile is optional but recommended
python tocorator.py              # interactive TUI
python tocorator.py app.exe      # TUI with target preloaded

# scriptable CLI (same engine)
python nuitka_onefile_extractor.py app.exe                 # extract
python nuitka_onefile_extractor.py app.exe --list          # list TOC only
python nuitka_onefile_extractor.py app.exe --info          # metadata only
python nuitka_onefile_extractor.py app.exe --dump-payload payload.bin

Set TOCORATOR_FAST=1 to skip the TUI animations. NO_COLOR=1 disables colors.

Where it looks for the payload

#	Location	Notes
1	PE resource RCDATA #27	Nuitka ≥ 2.6 and Commercial 4.x on Windows
2	PE overlay	classic appended payload
3	u64 size trailer at EOF	classic ELF layout
4	raw scan for the KAX/KAY header	payload merged into a section / stripped builds

The payload format (reverse-engineered)

header:  "KA" + flag        'Y' = zstd, 'X' = stored
entries (repeated):
    name<NUL>               utf-16le on PE targets, utf-8 elsewhere
    [flags: u8]             non-Windows builds only (1=exec, 2=symlink)
    size: u64               uncompressed size
    [crc32: u32]            only if the build stored checksums (0 is avoided → stored as 1)
    [csize: u32]            only in --onefile-as-archive + compressed builds
    data                    raw bytes, or an independent zstd frame (archive mode)
terminator: empty name

Two container modes exist for compressed builds:

• single stream (default): the whole TOC + all files flow through one zstd stream (multi-threaded compression may emit several concatenated frames — TOCORATOR consumes them all);
• archive (--onefile-as-archive): the TOC is stored in plain text and each file is its own zstd frame prefixed by a u32 compressed size.

Layout variants are auto-detected and cross-validated (plausible names, in-bounds sizes, TOC terminator position, CRC32 when present, first-frame decompression in archive mode) before anything is written to disk.

Verification & safety

• entry CRC32 checked when the build stores one; a _tocorator_manifest.json (order, sizes, computed CRC32) is written next to the extracted files
• extracted PEs can be sanity-checked independently (header parse, PE CheckSum field when non-zero)
• path traversal is blocked: entry names are sanitized before writing
• the target file is only ever opened for reading — never executed

Tested byte-exact via full round-trip (pack → extract → compare) on all four layout modes, including odd-sized files, unicode names, multi-frame streams and a real 689-entry application payload.

Compatibility & honest limitations

✅ Covered: Nuitka onefile builds of the KA format era (2020 → today), open source and Commercial 4.x, Windows PE and Linux ELF layout, all compression / checksum / archive variants listed above.

❌ NOT covered:

• encrypted payloads (Nuitka Commercial optional feature) — static extraction without the key is out of scope;
• pre-2020 experimental onefile builds;
• binaries re-packed by external protectors (VMProtect/Themida/…);
• future format changes (the parser is version-agnostic by auto-detection, but no one can promise a format Nuitka hasn't shipped yet).

If discovery fails on something that is a Nuitka onefile, open an issue with the --scan output (no need to attach the binary).

Repository layout

tocorator.py                  fancy TUI (menu, progress bar, hexdump, …)
nuitka_onefile_extractor.py   engine + scriptable CLI (importable: core API)
requirements.txt

Disclaimer

This tool is for analyzing software you own or are authorized to analyze (malware triage, software audit, recovery of your own builds). Extracted payloads are still potentially malicious code: handle them in a VM, never run them on your host. No warranty, see LICENSE.

---

TOCORATOR — by dimareverse