disrobe: static software recovery

Recover source, unpack payloads, and trace the evidence back to the input.

disrobe is a Rust command-line suite for examining compiled and obfuscated software. It decompiles supported bytecode and native code, reverses source obfuscation, extracts frozen applications and embedded frontends, and unpacks supported packers, archives, and firmware containers. Recovery reports identify the input, the stages that ran, the artifacts they produced, and the conditions that prevented further recovery.

The default path never executes the sample. One opt-in PyArmor v6/v7 fallback does execute it and requires --allow-dynamic; use that path only inside an isolated sandbox. Start with the forensics and malware-safety posture when handling untrusted material.

Watch or download the full video · Read the transcript. Twenty CLI commands cover unpacking, source recovery, Android resources, indicators, reports, artifact verification, and project setup in 2 minutes 12 seconds. The transcript includes the recorded build's complete command inventory.

Try it in your browser: the disrobe playground. Decompile a .pyc, scan a pickle for malicious reduce callables, and summarize a .wasm module, all client-side, with the core passes compiled to WebAssembly. Nothing is uploaded.

The live catalog spans 15 ecosystems: Python, JavaScript and TypeScript, WebAssembly, JVM and Android, .NET, native PE/ELF/Mach-O/NE, Go, Lua, PHP, Ruby, Erlang and Elixir on BEAM, Swift and Objective-C, ActionScript 3, mobile runtimes, and shell languages. The implemented native-packer tier currently lists Donut, sRDI, UPX, ASPack, Petite, MPRESS, FSG, PECompact, Yoda's Crypter, NSPack, MEW, kkrunchy. Run disrobe catalog [ecosystem] for the per-family recovery tier compiled into your binary.

Guarantees and boundaries

• No model runs in the recovery path. Metadata bundles are deterministic structured data for downstream tools.
• Output ordering and serialization are checked by hashing three fixture recoveries across Linux, macOS, Windows, and batch runs with one and four workers.
• The main CLI ships as one Rust binary. In-house paths launch no external program. Commands with optional backends invoke an installed tool only when you name it with --backend.
• The shared artifact layer can store recovered state in a content-addressed .dr envelope with an rkyv payload, postcard sidecar, and BLAKE3 root. Chain runs record topology and per-stage provenance separately.
• Python's normalized opcode-structure agreement is 95.18% on a fixed 574-module CPython 3.14 core population (17396 of 18276 code objects), excluding idlelib and turtledemo. Its pinned 200-module subset reaches 97.66% (6139 of 6286). See the comparison rules.

Start with an artifact

After installation, replace sample.bin with the file you want to examine:

disrobe auto sample.bin --out recovered/ --capture-stages
disrobe context --out recovered/
disrobe report recovered/ --format html > recovery.html

auto selects recovery passes from the file's bytes. context summarizes their outcomes; the HTML report brings the artifact inventory, evidence, and recovery limits into one document. --capture-stages retains intermediate bytes so you can inspect a layer or pass it to another tool. The quickstart explains the output and direct commands.

Choose a recovery path

disrobe passes lists direct command families and the automatic recovery routes included in the current build, with their ecosystems and support tiers. Direct commands also provide recon, taint analysis, and optional external decompilers. Electron and Tauri frontends use webview.carve; Wails can use Go's embedded-filesystem route. Use disrobe --help for commands and disrobe catalog [ecosystem] for recognized families.

In-house recovery remains available without optional toolchains. JVM, Android, .NET, and native commands can also use installed tools such as CFR, Vineflower, jadx, ILSpy, de4dot, or Ghidra where their command-specific backend policy allows it. disrobe doctor reports what is installed; it does not make an unavailable backend part of an in-house result.

Measured recovery

Every figure below comes from a committed test gate or a local measurement harness. strong figures are graded against an independent oracle; coverage-self-reported figures state the inspected population and count disrobe's own output. The full per-value sourcing lives in xtask/data/recovery.json.

Open the full-size recovery chart.

Colour identifies the comparison method. A filled mark denotes a CI gate on its documented triggers; a hollow mark denotes a local measurement. Each descriptor lists its inputs and prerequisites.

Recovery reports include support tiers and per-stage outcomes. Native-virtualized code, runtime-only keys, and RSA-wrapped capsule keys remain detect-only when the required information is absent from the input.

Recovery limits

An unsupported instruction, ambiguous signature, or unavailable runtime key can stop a recovery stage. Its report names the reason and retains the recovered structure available up to that point. Supplying additional artifacts, such as a matching runtime or name map, can make another recovery path available. See reading a result for outcomes and error codes.

Where to start

• First run: Installation, then Quickstart.
• The design: Architecture overview, then the five-rung IR ladder.
• One language: its language guide.
• The full family list: the supported families catalog, or disrobe catalog [ecosystem].
• Triage of stripped code or recovered source: queryable IR and capabilities and recon, prowl, and indicators.
• Embedding: Use it as a library, or the browser playground first.
• An exact command or flag: the CLI command reference.
• Untrusted samples: Forensics and malware-safety posture, before anything else.

Installation

Install disrobe from GitHub Releases or build the CLI from source. GitHub Releases is the canonical distribution point for the standalone binary; the Python bindings are a separate integration.

Prebuilt binaries (recommended)

Each tagged release includes prebuilt binaries for the common targets, alongside SHA256SUMS, a cosign keyless signature bundle per archive, a GitHub build-provenance attestation, and a CycloneDX SBOM. See SECURITY.md for artifact verification.

1. Download the archive for your platform from the Releases page.

2. Verify the checksum:

   sha256sum -c SHA256SUMS        # Linux / macOS
   

3. (Optional) verify the cosign signature against the Sigstore transparency log:

   cosign verify-blob \
     --certificate-identity-regexp '^https://github.com/1-3-7/disrobe/' \
     --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
     --bundle    disrobe-<version>-<target>.tar.zst.cosign.bundle \
     disrobe-<version>-<target>.tar.zst
   

4. Extract and place disrobe (disrobe.exe on Windows) anywhere on your PATH.

Build from source

The workspace declares Rust 1.95 as its minimum supported version. Use the repository's selected Rust toolchain and a linker/C toolchain for your target; native dependencies also compile during the build. On Windows with the MSVC target, install the Visual C++ build tools and Windows SDK. Optional analysis backends and the language runtimes used by grading tests are separate prerequisites.

git clone https://github.com/1-3-7/disrobe
cd disrobe
cargo build --locked --release -p disrobe-cli --bin disrobe
./target/release/disrobe --version

The binary lands at target/release/disrobe; copy it onto your PATH.

Per-OS notes

• Windows: the binary is disrobe.exe.
• Linux: the musl build is fully static; the glibc build needs a matching glibc.
• macOS: x86-64 and ARM64 (Apple silicon) archives are published separately. Gatekeeper may quarantine an unsigned download; clear it with xattr -d com.apple.quarantine disrobe.

The dependency boundary

The required tools depend on whether you are building the CLI, selecting an external backend, or reproducing a measurement.

The per-ecosystem list for the last two rows is in evidence/README.md.

Slim build

The CLI's default features select the full build. For a smaller artifact, the slim build keeps the always-on core and drops optional passes. A command can remain visible in help while its implementation reports that the corresponding feature was not compiled in:

cargo build -p disrobe-cli --release --no-default-features
# same build, shorter
cargo build-slim

Slim excludes optional language passes and their dependencies, including native, Python, WebView, and the embedded JavaScript and WebAssembly toolchains. Core byte inspection and static string extraction remain available. It also excludes optional service and collection surfaces. The dependency-tree gate enforces the expected crate graph for the selected features.

Binary size and command availability depend on the target, source revision and selected features. Compare builds of the same revision with the same compiler and profile before claiming a size reduction. Some commands are omitted from help; others, including wasm, remain declared and report the missing feature when invoked:

$ disrobe wasm decompile app.wasm
Error: the `wasm` pass is not compiled into this binary (slim build); rebuild with default features (feature `wasm`)

Layer specific passes back onto a slim base with --features, for example --no-default-features --features native,py,webview or --no-default-features --features wasm,jvm.

Git history scanning uses the git-history feature, which the full build includes. In a slim build, frisk --git reports that this feature is required; use --features git-history to enable it.

Verifying the install

disrobe --version          # print the version
disrobe passes             # direct families plus auto-chain pass IDs
disrobe --help             # full subcommand surface
disrobe <pass> --help      # drill into any pass, e.g. `disrobe py --help`

Optional external backends

Disrobe includes its own recovery engines for native code and the supported bytecode languages. External backends add rendering and analysis paths: Ghidra for native decompilation; CFR, Vineflower, Procyon, and JADX for JVM and Android inputs; ILSpy, dnSpy, dnSpyEx, and de4dot for .NET. Backend selection is command-specific. JVM and .NET decompilation invoke an installed tool only when --backend names it; the JVM and .NET disrobe auto passes use their in-process engines. Recompilation checks have separate compiler/interpreter prerequisites, as listed above.

Probe what is installed and what is missing:

disrobe doctor                 # probe 46 to 51 external tools depending on the platform
disrobe doctor --auto-install  # install every missing tool that has a known install action

A missing tool with no install action (a commercial tool, a tool that ships bundled with another tool, a platform-exclusive tool, or a tool preinstalled by the operating system) is not silently dropped. --auto-install records it as a skip with a typed reason, in both text and --json output.

Install a single tool through your platform's native package manager (winget / brew / apt / dnf / pacman / apk). disrobe never installs itself this way; it only fetches the optional backends:

disrobe install --list         # list every known tool + per-platform package name
disrobe install ghidra
disrobe install upx

Heavyweight dependencies that ship as upstream release archives rather than OS packages (Ghidra, for instance) have a dedicated installer:

disrobe install-deps ghidra
disrobe install-deps --all

Shell completions and man pages

disrobe completions bash --install        # also: zsh, fish, powershell, elvish
disrobe man --out ./man                   # one .1 page per subcommand

Quickstart

This walkthrough takes a local file through automatic recovery, inspects the result, and shows how to select a direct command when you know the format. Replace the example filenames with your own inputs.

Check the installation

Follow installation, then confirm which binary and optional tools are available:

disrobe --version
disrobe doctor

doctor reports installed, missing, and stale external tools. The in-house recovery paths do not require all of them. Install a tool when the command or verification step you need requires it; see optional backends.

For a first run, use a file you own or a trusted compiled fixture. For an untrusted sample, read the handling guidance first. The default recovery path does not execute the input.

Auto-detect and chain

disrobe auto suspect.exe --out recovered/ --capture-stages
disrobe context --out recovered/
disrobe report recovered/ --format html > recovery.html

auto identifies the input and selects a recovery chain from the available passes. Open recovery.html for the artifact inventory, evidence, and stage outcomes. context gives a shorter terminal view of the passes that ran, their confidence tiers, the final verdict, and provenance.

The output directory contains chain.json, recovery.json, anti-analysis.json, and report.json. Use these structured reports when another tool needs the topology, recovery status, or forensic summary. Check the input identity and any incomplete or failed stages before treating the recovered files as a complete account of the input. See reading a result for the status vocabulary and next steps.

The selected passes depend on the bytes recovered at each stage:

Read the pass list and the recovery report for the route and support tier actually selected. A missing key or unsupported variant can end a branch before source recovery.

Use --capture-stages to mirror the exact bytes written by each executed pass under <out>/NN-<pass>/ and link the terminal stage or stages under <out>/final/. These are exact stage records; a decompiler's source output is not a byte-identical copy of the compiled input. Cap the chain depth with --max-depth (default 8).

Per-language one-liners

Choose a direct command when you know the format or want to inspect one layer of a chain. The output path in each example identifies the source file, extracted tree, or report to inspect next. Run disrobe <command> --help before relying on a backend or emit that is not shown here.

Python bytecode and frozen applications

Decompile a .pyc, inspect its instructions, clean obfuscated source, or extract an application bundle:

disrobe py decompile module.pyc --out recovered/
disrobe py disasm module.pyc --out trace.txt
disrobe py deob obfuscated.py --out clean.py --cleanup
disrobe pyinstaller extract onefile.exe --out out/
disrobe pyarmor unpack protected.py --out out/
disrobe nuitka extract app.exe --out out/

Python's default round-trip check needs a matching interpreter. Read its result before relying on the emitted source; a missing interpreter leaves the comparison unperformed. Python recovery describes the comparison and version limits.

PyArmor v6/v7 may require the dynamic-hook fallback. That path executes the sample and is disabled unless you add --allow-dynamic. Use it only inside an isolated sandbox with no network or sensitive mounts. PyArmor v8/v9 and --allow-bcc remain static.

JavaScript, WebAssembly, and embedded frontends

Clean a bundle, split its modules, lift WebAssembly, or extract a desktop application's frontend:

disrobe js deob bundle.min.js --out clean.js
disrobe js unbundle app.bundle.js --out src/
disrobe wasm decompile module.wasm --target rust --out lifted.rs
disrobe webview desktop.exe --out frontend/

JVM, Android, and .NET

These examples request installed external backends. Check doctor and the command's reported backend: availability and fallback behavior are command-specific. The corresponding auto passes use in-house recovery.

disrobe jvm decompile app.apk --backend jadx --out src/
disrobe dotnet decompile App.dll --backend ilspy --out src/

Native executables and Go

Unpack an executable or recover symbols and Go runtime metadata:

disrobe native unpack packed.exe --out unpacked.bin
disrobe native symbols app.exe --out symbols.json
disrobe go recover app --out symbols.json
disrobe catalog native

For source recovery and architecture limits, see the native decompiler. A symbol report and recovered function bodies answer different questions; inspect the artifact the selected command actually emits.

Mobile runtimes and other bytecode

Recover the supported source or structural view for the input:

disrobe hermes decompile index.android.bundle --out surface/
disrobe flutter dump libapp.so --out layout.json
disrobe lua decompile script.luac --out script.lua
disrobe ruby decompile app.rb
disrobe php decode payload.php --out out/payload-php/
disrobe beam parse module.beam

Use the catalog to inspect each family's Recover, Partial, or Detect-only support tier:

disrobe catalog python

Extract indicators from recovered files

frisk scans local files offline for secrets, endpoints, and indicators, with source locations:

disrobe frisk recovered/ --format json > frisk.json

Network enrichment is a separate step. prowl queries the selected public archives and feeds for a domain or URL; use a target you intend to disclose to those providers. indicators merges the local and network reports and can print a deduplicated target list:

disrobe prowl example.com --subs --sources wayback,urlscan,crtsh --format json > prowl.json
disrobe indicators frisk.json prowl.json --targets-only > targets.txt

Secret values remain visible by default in recon reports. See recon, redaction, and indicators before sharing them.

Structured output

The global --json, --ndjson, and --sarif flags select machine-readable output where a command supports those formats. For example, scan can emit SARIF 2.1.0 for GitHub code scanning:

disrobe scan firmware.bin --sarif > findings.sarif

Inspecting a run

To revisit a chain run without rerunning recovery:

disrobe context --out recovered/

If a stage failed, use its reported DR- error code with disrobe explain. A registered entry describes the cause and the input or prerequisite that may resolve it. Reading a result also covers stalls, caps, cycles, and verification failures.

If you created or received a .dr envelope, inspect its metadata and verify its integrity separately:

disrobe envelope inspect module.dr
disrobe verify module.dr

Generating a metadata sidecar

Commands that implement metadata bundles accept --metadata-pack-1 through --metadata-pack-4. --llm is a compatibility alias for pack 4; it does not run a model.

disrobe py decompile module.pyc --out recovered/ --metadata-pack-4 --llm-briefs

See metadata sidecar and provenance for the full category and pack model.

Reading a result

Start by confirming the input identity, then inspect the recovered artifacts and the stages that stopped. The reports let you connect a result to the bytes supplied and decide whether another pass, tool, or input can help. A source file, a symbol list, and a detection report provide different evidence; the output's presence alone does not establish complete recovery.

What a run leaves behind

disrobe auto and disrobe chain write four documents into the output directory, and a fifth, run.json, when --timings is given.

Use disrobe context for a terminal summary of recovery.json:

disrobe auto sample.bin --out ./out/sample --capture-stages
disrobe context --out ./out/sample

The summary prints the input identity, overall verdict, tier histogram, and stage rows. This recorded run on the repository's corpus/webview/tauri/wvfix.exe fixture used version 0.10.5; its timings describe that run:

  schema:    disrobe.recovery/v1
  tool:      0.10.5
  verdict:   FanOutPartial
  total_ms:  468
  tiers:     exact=0 semantic=1 partial=0 skeleton=11 (total 12)
  passes:
    webview.carve                advanced   skeleton  53ms
    terminal                     incomplete skeleton  -

disrobe report ./out/sample renders the same run as text, markdown, JSON, or a self-contained HTML page, and adds a recovery score, the artifact inventory, and the detect-only and skeleton caveats. See run reports.

Pass --capture-stages on any run you expect to debug. It mirrors the exact bytes written by each stage to ./out/sample/NN-<pass>/output.bin and links the terminal stages under ./out/sample/final/, which lets you re-enter the pipeline at the stage that stopped. Exact capture does not mean a decompiler's source output is byte-identical to the compiled input. Without capture you have the verdicts but not the stage bytes.

Support, confidence, and status

Read these labels together: the family's supported recovery, the confidence assigned to this stage, and the stage's execution status.

A support tier describes a family, not a run. It is the standing claim about how far recovery goes for that packer or obfuscator, and it comes from the catalog or disrobe catalog <ecosystem>: Recover, Partial, or Detect-only.

A confidence tier describes one stage of one run. It comes from recovery.json, and the four values, ranked, are exact, semantic, partial, skeleton. A family at support tier Recover can still produce a skeleton stage on your sample. Check the pass's output and verification result to determine which bodies or structures were recovered.

Stage status is a third axis, with five values:

The chain stopped early

Symptom. Chain verdict Stalled in the text view, "stalled" in JSON. The last disrobe context row is named terminal, with status incomplete and confidence skeleton:

  verdict:   Stalled
  tiers:     exact=0 semantic=0 partial=0 skeleton=1 (total 1)
  passes:
    terminal                     incomplete skeleton  -

Meaning. No detector result for that stage's bytes met the selection floor of 0.5. The runner stopped because it could not select a pass with sufficient confidence. No pass executed at that node, so the terminal row has no pass name to attribute a recovery to. A stall does not establish that the input is unrecoverable.

chain.json's stats.rejected_passes counts candidates dropped below the floor across the run. A nonzero count records low-confidence detections somewhere in the run; it does not identify the stalled artifact by itself.

Next. Identify the stalled bytes, then select a supported pass explicitly if its input requirements match. The stage path below is an example; use the path from your capture.

disrobe detect ./out/sample/final/02-pyinstaller-extract/output.bin
disrobe identify ./out/sample/final/02-pyinstaller-extract/output.bin
disrobe chain sample.bin --chain 'pyinstaller.extract,pyarmor.unpack,py.decompile' --out ./out/sample-explicit

An explicit --chain bypasses detector selection for the passes you name, so a family that scored 0.4 still gets its pass run. It does not supply missing keys or make an unsupported input valid. Chain pass IDs are dotted and comma-separated (pyinstaller.extract, pyarmor.unpack, py.decompile, native.packer-unpack, binfmt.container, and the rest), and a trailing ,* hands the remaining depth back to auto-detection. disrobe passes lists the chain IDs available in your binary after its direct-command summary. An unknown ID fails with DR-CLI-0298 and lists the registered IDs.

When auto recovers nothing it already prints a note on stderr naming the format it thinks it saw and the command group to try:

note: auto recovered no files and could not identify the format. Run `disrobe detect <file>` to identify it, then the matching subcommand.

The chain hit a cap

Symptom. Verdict CapReached, or "cap-reached" in JSON, on a branch that still had unprocessed output.

Meaning. One of two bounds stopped the branch: the depth cap, eight passes by default, or the cumulative-output budget of 512 MiB across the whole run. Both bound work on nested archives and repeatedly emitted output; see depth and cycle safety. A cap records unfinished processing. Inspect the completed stages and their captured output before deciding how to continue.

Next. If the report identifies the depth cap, increase it within the supported limit. Otherwise, split the work and re-enter on the captured child you need to examine. Substitute its actual capture path in the second command:

disrobe auto sample.bin --max-depth 16 --out ./out/sample --capture-stages
disrobe auto ./out/sample/final/03-binfmt-container/output.bin --out ./out/sample-inner

Sixteen is the ceiling for --max-depth; above it the spec is rejected. The cap is also settable per project as max_depth under [execution] in .disrobe.toml. The byte budget is fixed and not exposed as a flag, so a run that exhausts it has to be split.

The chain saw the same bytes twice

Symptom. Verdict Cycle.

Meaning. A stage produced bytes already seen earlier in the chain. Each stage output is content-hashed with BLAKE3, and a repeat stops the branch instead of looping. Usually this is a pass that did not change its input, or an archive that contains itself.

Next. Compare input_blake3 and output_blake3 across the nodes in chain.json to find the stage that repeated, then run that stage's pass directly on the captured bytes to see what it did and did not change.

A body came back as a skeleton

Symptom. Confidence skeleton on a stage that did execute, or a nonzero skeleton count in the histogram.

Meaning. The chain assigns semantic to a stage that completed with source output and partial to one that completed with a byte payload. Everything else is skeleton, so at chain level the tier tells you the stage did not produce a recognized recovery, not how much of each body survived. For that, read the pass's own output. Passes that recover bodies separate the levels explicitly rather than mixing them: disrobe nuitka decompile writes real source lifted from frozen bytecode into frozen/ and typed signatures of native-compiled modules into skeleton/, and labels each in its disrobe.nuitka.recovery-manifest/v1 sidecar (decompiled-from-bytecode against signatures-only-native-compiled), so no signature is ever presented as a recovered body.

Check whether the report identifies a missing lifter operation or data absent from the artifact, such as a runtime-only decryption key. A different recovery engine may handle the former. The latter requires additional material; retrying the same bytes cannot supply it.

Next. Check the family's standing support tier, then read the code the pass emitted.

disrobe catalog python
disrobe explain DR-PYARM-0013

Names and signatures can still locate modules or functions for further analysis. Keep their signatures-only status with the result so a consumer does not treat them as recovered implementations.

A pass reported a refusal

Symptom. Status failed on a stage, with a DR- code in the message. In chain.json that node's verdict is "error" and the message is in its error field.

Meaning. A pass can return an error for a processing failure or a deliberate refusal, so failed alone does not distinguish them. Read the code and full message. A refusal should identify the unsupported condition or missing evidence; retain that limitation with any recovered artifacts.

Next. Look up the DR-<DOMAIN>-<NNNN> code. For registered entries, explain prints the description, causes, and fixes:

disrobe explain DR-PYARM-0013
disrobe explain pyarm-13          # short form, zero-padded for you
disrobe explain pyarmor-13 --json # long domain aliases also resolve

DR-PYARM-0013
  title:       PyArmor v3/v4/v5 capsule walled on the RSA-wrapped key
  description: v3-v5 capsule structure and metadata parse, but the bytecode AES key is
               RSA-wrapped with a private key the author never ships, so the plaintext is
               not in the artifact and cannot be recovered statically.
  common fixes:
    - supply the cleartext capsule key if you hold it; structure, version, and metadata
      still parse without it

This entry separates what parsed from what is absent and names the additional input recovery requires. Not every code in the binary has a registered entry; the domains that carry entries are CLI, PYARM, PYINST, PYFRZ, NUITKA, SDEF, PYDEOB, JSDEOB, WASMDEOB, MARSHAL, and BINFMT. An unregistered code returns DR-CLI-0102 and asks you to file an issue with the full message you saw.

The absent-data case

Some failures identify a prerequisite you can supply: a missing PyArmor runtime extension, a wrapper altered by another obfuscator, or a .pyc without the interpreter needed for verification. Supplying that prerequisite allows the affected step to run; its result still needs inspection.

Other cases require data outside the supplied artifact: a key that exists only at run time, state held in a live process, or a payload fetched from the network on execution. Static recovery of the supplied bytes cannot reconstruct that missing material. The catalog marks these detect-only cases per family and identifies the missing input.

Record the missing input when handing the result to another analyst. A detect-only result with an absent-data reason calls for additional evidence; a stall, cap, or lifter gap calls for a different recovery step.

The recovery did not verify

Symptom. disrobe py decompile prints a roundtrip: line that is not perfect.

Meaning. By default, Python decompilation attempts to recompile the emitted source on a matching interpreter and compare the code objects. The label reports the comparison or why it did not run:

For no-interpreter, install the matching interpreter and rerun the command. For skipped, remove --no-roundtrip to enable the comparison. Neither status reports a comparison result.

The semantic label refers to the documented opcode normalization, not an execution comparison. Read the Python comparison rules before using it as evidence about behavior.

The emit you asked for is not there

Symptom. An --emit kind wrote a small JSON document instead of an artifact.

Meaning. Commands that implement the standardized emit contract return either the requested artifact or a stub with "applicable": false, "schema": "disrobe.emit.stub/v0", and a reason. The shared parser recognizes fifteen emit labels, but support is command-specific and auto accepts only recovery. See standardized emits.

Next. Run the pass the reason names. disrobe auto --emit accepts only recovery, which echoes recovery.json to stdout under --json; for structured emits, drive the per-language subcommand directly.

disrobe auto sample.bin --emit recovery --json --out ./out/sample
disrobe py decompile ./out/sample/final/02-pyarmor-unpack/output.bin --emit source,disasm,report

Before you conclude anything

Anything you read out of a run is a claim about the bytes you supplied. Confirm the input identity in recovery.json matches the sample you meant to analyze: the blake3 and size fields are there so a report can be tied back to an artifact, and so two runs can be compared. disrobe diff and disrobe guard verify compare chain.json documents stage by stage when you need to prove two runs agree. For handling of the sample itself, read forensics and malware-safety posture.

Architecture overview

disrobe is a workspace of focused Rust crates exposed through one CLI. Direct commands run a selected operation; auto composes registered passes by detecting each stage's output. The IR ladder describes available representations, and the optional .dr envelope stores an artifact with its integrity hash.

Crate map

The workspace splits into shared cores and dedicated ecosystem or recovery-surface crates:

The Pass trait

Every chain pass implements one trait (Pass in disrobe-core, re-exported as chain::detector::Pass): it exposes an ID, a Detector, an output kind, and a run method that transforms an Artifact. The trait does not require adjacent rung transitions; unpackers can return another raw artifact. The chain runner re-detects the current bytes after each stage and selects a registered pass using detector confidence and precedence. This lets a supported PyInstaller -> PyArmor -> .pyc decompile input run through one disrobe auto invocation.

The CLI also has a standardized emit vocabulary, but it is not part of the Pass trait and support varies by command. A command wired to the emit helper writes an applicable: false stub when a requested kind does not apply. auto accepts only the recovery emit. See Standardized emits.

The four pillars

1. The five-rung IR ladder: the representations available to recovery and analysis passes.
2. Passes and pass selection: what each pass registers and how the chain runner picks between them.
3. The chain runner: auto-detection, stage mirrors, depth and cycle caps.
4. The .dr envelope: the content-addressed wire format that makes caching deterministic.

Determinism is a design constraint, not a feature

The recovery architecture is designed for reproducible output. No model runs in the decompile path, and recovery output does not depend on randomness. Opt-in redaction uses the first 96 bits of the value's unsalted SHA-256 digest, so the same value receives the same sentinel across runs. Values shorter than 16 characters reveal no source characters. Longer values reveal only the first two and last two characters. Run documents record no duration, worker count, or clock, so two runs over one input write identical bytes; --timings records durations and clocks separately in run.json. The .dr envelope is content-addressed with BLAKE3 rather than timestamp-addressed, so a cache hit identifies the same bytes. This makes disrobe output usable as a forensic baseline and as a disrobe diff input across versions.

The committed cross-platform gate exercises three real fixtures. Each of the test job's Linux, macOS, and Windows legs runs the CLI against those fixtures, and the downstream determinism-cross-platform job hashes the recovered output with BLAKE3 and fails if the operating systems disagree. A companion check runs the same fixtures through the batch path at --jobs 1 and --jobs 4 and compares the two output directories byte for byte. These checks establish determinism for that population; they do not turn three fixtures into a claim about every input. See crates/disrobe-cli/tests/determinism_cross_platform.rs and the determinism-cross-platform job in .github/workflows/ci.yml.

The five-rung IR ladder

Disrobe uses five intermediate representations, from original bytes to rendered source. A recovery can use several rungs or stop at one. Unpackers commonly transform raw bytes into another raw artifact; passes do not have to visit each rung in order.

Open the full-size IR diagram.

The shared disrobe-ir enum defines Rung::{Raw, Disasm, Mir, Hir, Surface}. Individual backends choose the representations needed for their supported inputs.

Raw: file bytes

The input bytes and recovered container members. Format detection, extraction, unpacking, and decryption operate here. A byte comparison can grade a recovered member when its original is available; a successful extraction alone does not establish byte identity.

Disasm: instructions

Decoded operations with their offsets, operands, and labels. Commands such as disrobe py disasm, disrobe beam disasm, and disrobe as3 disasm expose instruction listings directly. The supported decoder and input format determine which bytes can be represented.

MIR: basic blocks

Normalized operations and control flow: blocks, branches, stack effects, and values. This representation gives structural recovery a common vocabulary without requiring the original source syntax.

HIR: program structure

Recovered loops, conditions, expressions, and other source constructs. Available names and types come from the input's metadata and the backend's analysis. Missing information can limit the structure a pass recovers.

Surface: readable source

Rendered text in the selected output language, such as Python, Java, C#, Lua, Erlang, WAT, C, Rust, or TypeScript. Some backends produce pseudo-source. Consult the language guide and recovery report before treating an output as compilable or behaviorally equivalent to its input.

Python's published comparison recompiles output and compares normalized opcode structure. It excludes jump targets and most operands, so agreement measures that structure rather than program equivalence. See the comparison rules and measured population.

Composition and storage

The chain runner uses detectors to select passes and re-inspects each stage's output. The shared artifact envelope carries the representation and integrity metadata. Rung names describe what an artifact contains; they do not determine the next pass by themselves.

The transcode registry is keyed by (from_version, from_rung, to_version, to_rung). disrobe envelope migrate-check <from.dr> <to.dr> checks whether a registered migration path satisfies the required capabilities.

Confidence tiers

Recovery producers map their evidence to four tiers in disrobe-core:

These are producer-reported classifications. In particular, semantic can mean that a full body was lifted without an independent execution comparison. Read the accompanying evidence and result documents for the limits of a recovery.

Passes and pass selection

A pass is the unit of work in disrobe. Chain passes implement a shared trait and register a detector that scores how confidently each one recognizes a given input. Ecosystem crates may expose one or more passes plus direct APIs. disrobe auto picks the next pass by comparing detector verdicts, not by matching capability descriptors between passes; see Pass selection below.

Commands and auto-chain passes

The CLI has two related surfaces:

• Direct commands are the operations shown by disrobe --help. They include ecosystem command families such as py, native, and jvm, plus analysis commands such as scan, frisk, query, taint, and webview.
• Chain passes implement the shared Pass trait and can be selected by disrobe auto. Their IDs are not necessarily CLI subcommand names.

disrobe passes prints both layers. Its first block summarizes direct recovery families. Its second block is the authoritative list of chain pass IDs reachable from disrobe auto in that binary, with an ecosystem and full, partial, or detect-only tier. The standard CLI build at this revision reports:

The standard CLI enables automatic webview recovery: Electron and Tauri use webview.carve, while Wails uses go.classify with Go support enabled. disrobe webview also provides direct frontend extraction. Build features can change the chain registry; disrobe passes lists the routes in the binary you are running.

native.image-classify handles structurally valid PE, ELF, and Mach-O images when no more specific ecosystem detector wins. Its partial tier includes identity, signatures, recovered symbols, and bounded pseudo-source reports on supported architectures. The native decompiler provides the direct source-recovery options and architecture limits.

The direct JavaScript catalog currently carries 11 bundler families. The WebAssembly catalog carries 3 families whose transformation runs through wasm deob (Jscrambler-WASM, Wobfuscator and Wasmixer); Tigress-via-Emscripten and wasm-name-obfuscator are classification-only there, and the Tigress unflattener is a library helper no recovery path calls. These catalog counts describe direct command capability and do not add chain pass IDs.

Pass selection

Rather than hard-coding which pass follows which, every pass registers a Detector (chain::detector::Detector in disrobe-core) that inspects the current bytes and, if it recognizes them, returns a DetectVerdict: a pass ID, a format tag, a family (obfuscator-wrapper, packer-archive, interpreter-bytecode, source, container, native-format, or unknown), a confidence score, and a specificity rank.

PassRegistry::run_all (chain/registry.rs) runs every registered detector against the bytes. Six extraction-first passes (nuitka.extract, pyinstaller.extract, pyfreeze.extract, pyarmor.unpack, binfmt.container, sourcedefender.decrypt) are tried before the rest, and the sweep stops early the moment one of them returns a High-band verdict (confidence >= 0.90) with specificity <= 30. A raw confidence buckets into ConfidenceBand::Low (< 0.70), Medium (0.70-0.89), or High (>= 0.90).

A SelectionPolicy then picks the winner among whatever verdicts came back: candidates below its minimum confidence (0.5 by default) are dropped, and the survivors are ranked by precedence::compare (chain/precedence.rs), which breaks ties in order: confidence band, then raw confidence, then the lower specificity value, then a fixed family-precedence table (obfuscator-wrapper beats packer-archive beats interpreter-bytecode beats source beats container beats native-format beats unknown), then the lexically smaller pass ID.

The chain driver (chain/state_machine.rs) runs this selection once per queued artifact, executes the winning pass, and re-runs detection on its output to decide what happens next. A branch ends when no verdict clears the minimum confidence (Stalled), when the same output bytes reappear (Cycle), or when the depth cap or cumulative-output budget is exceeded (CapReached). This is why disrobe auto can detect that a PyInstaller archive contains a PyArmor-protected module and route it through the unpack-then-decompile chain without any per-combination glue code.

Standardized emits

The CLI's shared emit parser recognizes these fifteen labels:

source  disasm  ast  cfg  ir  manifest  sourcemap  symbols  strings
imports  signatures  fingerprints  report  recovery  provenancemap

Commands opt into this contract individually. Where a command accepts --emit, pass a comma-separated subset such as --emit source,disasm,report. A supporting command writes an explicit stub when the requested kind does not apply:

{
  "schema": "disrobe.emit.stub/v0",
  "pass": "beam-lift",
  "emit_kind": "fingerprints",
  "applicable": false,
  "reason": "not implemented for the beam pass in this build"
}

Support is not universal. auto accepts only --emit recovery, and commands that do not expose --emit use their own output contract. --all-emits is also command-specific. Check disrobe <command> --help before building a consumer around an emit.

Error codes

Many diagnostics carry a DR-<DOMAIN>-<NNNN> code. The curated error registry provides explanations for registered codes:

disrobe explain DR-PYARM-0007
disrobe explain CLI-1            # short form also works

The chain runner

The chain runner detects each artifact, runs a matching recovery pass, and routes its output to the next pass. It backs both disrobe auto (automatic selection) and disrobe chain (an explicit pipeline).

Auto-detection

disrobe auto suspect.exe --out recovered/
disrobe auto suspect.exe --out shareable/ --redact

disrobe auto fingerprints the input, picks the highest-confidence pass, runs it, then re-fingerprints the output and repeats until no further pass clears the confidence threshold or the depth cap is hit. disrobe passes prints the auto-chain pass IDs compiled into the current binary, with each pass ecosystem and support tier. Use that output instead of a copied count. Direct commands such as scan, frisk, taint, and webview are separate surfaces and do not become auto-chain passes merely because the CLI can run them. See Pass selection for exactly how the next pass is chosen.

--redact replaces secret values in machine output, printed paths and messages, the generated reports (chain.json, recovery.json, anti-analysis.json, report.json, report.sarif, and run.json), and every extracted file that looks like JSON: a .json name, or content that starts with { or [ after an optional byte-order mark and whitespace. The values come from a recon scan of the input and of every extracted file, from the secret values listed in extracted recon.json, secret-scan, and mobile reports, and from a rescan of each document. An extracted JSON file that contains a secret is rewritten as indented JSON; one that does not parse, or exceeds the redactor's depth, node, or string limits, has its text scrubbed instead; one larger than 64 MiB is not written, and a DR-CLI-0366 line on stderr names it. Other recovered source, extracted binaries, and the raw stage copies that --capture-stages writes are not altered. disrobe chain applies the same redaction when .disrobe.toml sets output.redact = true. Raw report values remain the default.

Representative routes include native.packer-unpack -> go.classify for a UPX-packed Go executable and pyinstaller.extract -> pyarmor.unpack -> py.decompile when the extracted Python wrapper and available runtime/key material support those stages. APKs reach jvm.classify; Electron ASAR archives reach webview.carve, whose recognized JavaScript children can continue through js.deob. See the quickstart route table for their outputs and registered passes for the complete list.

Explicit chains

When you want to pin the pipeline rather than auto-detect:

disrobe chain input.bin --chain 'pyarmor.unpack,py.decompile' --out recovered/
disrobe chain input.bin --chain 'auto:8' --out recovered/        # auto-detect, depth 8
disrobe chain input.bin --chain 'auto:8' --chain-pin pyarmor.unpack --out recovered/

Explicit chains use comma-separated pass IDs from disrobe passes. With --chain auto[:N], --chain-pin fixes a pass prefix before automatic selection continues; it does not select package versions.

Layered payload recovery

disrobe unwraps obfuscated and packed payloads recursively. A structural check gates every step (compression magic, a loadable marshal object, a valid parse, a validated crib), so a decode never advances on garbage, and every decompression is bomb-bounded.

Depth and cycle safety

Adversarial input can try to make a chain recurse forever (an archive nested inside itself, a packer that re-emits its own signature). The chain runner defends against this:

• Depth cap. --max-depth (default 8) bounds how many passes can run in one chain.
• Cycle detection. Each stage's output is content-hashed (BLAKE3); if a stage produces bytes already seen earlier in the chain, the runner stops rather than looping.

Output layout

auto and chain write into the --out directory:

out/
├── extracted/
│   ├── lib/app.dll          # a fan-out member, at its path inside the container
│   └── recovered/
│       ├── app.py           # recovered source, named after its input with the language's extension
│       └── chain-node-4.cs  # a source whose input had no name
├── chain.json
└── recovery.json

• Recovered source. Every stage that ends a branch with recovered source writes it under extracted/recovered/. The file keeps the directory and stem of the member it came from, and takes the extension of its language: .py for Python, .cs for C#, .java for Java, .m for Objective-C and MATLAB. A source whose input had no name is written as chain-node-<id>.
• Existing output. --out must be empty or absent. A directory that already holds files is refused with DR-CLI-0913, because the new run's reports would cite files the run did not write. --force accepts such a directory and first deletes the earlier run's extracted/. DR-CLI-0912 reports a directory that cannot be read or cleared.
• Batch runs. A directory run gives each input its own output directory, named after the input's relative path. Inputs whose names would give the same directory get numbered suffixes (app-1, app-2), so no two inputs share one.

Verdicts

Every node in chain.json carries a verdict, and the run carries one overall verdict computed from the branches that end in a leaf.

A member of a container that no pass claims is not-applicable on its own node and does not count against the run: a ZIP holding one .pyc and a README is complete once the .pyc decompiles. A directory run classifies each file from its verdict as recovered (grade ok), incomplete, not applicable or failed, and manifest.json counts each class.

Stage mirrors

Pass --capture-stages to materialize the exact bytes written by every executed pass. This records each stage faithfully; it does not mean decompiled source is byte-identical to the compiled input.

recovered/
├── 01-pyinstaller/        # exact recorded output of pass 1
├── 02-pyarmor/            # exact recorded output of pass 2
├── 03-py-decompile/       # exact recorded output of pass 3
├── final/                 # terminal stage(s), linked
│   └── 03-py-decompile/   # symlink, or a recursive copy when symlinks are unavailable
├── chain.json             # the chain topology descriptor
└── recovery.json          # per-pass status and confidence histogram

The final/ link prefers a symlink and falls back to a recursive copy, so final/ always resolves to the terminal artifact regardless of platform and privilege. On Windows without the symlink privilege or Developer Mode, final/ is a copy.

chain.json: the topology descriptor

chain.json records the executed pipeline: each pass, its version, the input and output BLAKE3 hashes, the rung transition, byte sizes, and the per-stage verdict. It is the document disrobe diff and disrobe guard verify operate on (see Diff and guard tooling).

Each node includes a metadata object whose keys and values are strings. The object is empty when the stage has no metadata. Registered keys use lowercase dotted namespaces. Serialized keys remain in deterministic lexical order.

anti.recovered_techniques is a published metadata key. Its value is a nonempty comma-separated list of technique labels with no empty elements, embedded commas, or whitespace around delimiters. The encoded value is limited to 4,096 UTF-8 bytes. An absent key means that the stage reported no recovered technique metadata. An empty or malformed value is an error, not an absent value. The CLI reports malformed metadata as DR-CLI-0299 before it derives anti-analysis evidence or writes the final chain output.

recovery.json: the provenance sidecar

recovery.json is the per-run report: each pass's status and a confidence-tier histogram. Summarize it without reading raw JSON:

disrobe context --out recovered/

run.json: timings on request

chain.json, recovery.json, report.json, and report.sarif record no duration, no worker count, and no clock, so two runs over one input write identical bytes. Pass --timings to auto or chain to also write run.json (schema disrobe.run/v1): the start and end clocks, the worker count, the tool version, the run's duration, and each node's duration in milliseconds keyed by node id. Node 0, the input, covers the whole run; a node that ran a pass holds that pass's run time; any other node holds the time spent on it. disrobe context prints run.json when the directory holds one.

This prints per-pass status, confidence tiers, the overall verdict, and provenance, which is the human-facing view of what the chain actually managed to recover and how much to trust it.

The .dr envelope

The .dr envelope is disrobe's content-addressed IR wire format. A caller can persist a supported artifact as one, inspect or verify it without running a recovery pass, and pass it to consumers that accept its rung. The chain runner uses disrobe-core::Artifact between stages and writes separate chain.json and recovery.json records; it does not require every stage to become a .dr file.

Anatomy

A .dr envelope has three parts:

1. Hot payload (rkyv). The primary typed IR data, serialized with rkyv 0.8. The mmap reader validates the header, declared lengths, and root hash before exposing the archived payload for zero-copy access.
2. Cold sidecar (postcard). Secondary metadata serialized with postcard, kept out of the hot path so the common case stays fast.
3. BLAKE3 root hash. A content hash over both the hot and cold bytes. Equal roots identify equal payload and sidecar bytes. The root does not include the header fields, so it is not by itself a claim that two complete envelope files are byte-identical.

The fixed header also carries the schema version, IR rung (see the ladder), flags, hot and cold lengths, and root hash. The postcard sidecar stores the producer, producer version, capability set, and string provenance map. MBA outputs that use the peephole table record its deterministic rule-pack content ID in provenance and in the corresponding chain artifact record; this identifies the exact table and audit data used for that result.

Why content-addressed, not timestamp-addressed

The root binds the typed payload and sidecar to their bytes rather than to a path or timestamp. disrobe envelope verify recomputes that root and rejects a mismatch. Cache entries use a separate key derived from the operation, input bytes, and effective configuration, and the cache reader validates its own stored checksum before returning a hit.

Working with envelopes

# Create an envelope from a source file
disrobe envelope create source.bin --out source.dr

# Inspect: version, rung, capabilities, provenance, root hash
disrobe envelope inspect source.dr

# Verify the BLAKE3 root against the payload
disrobe envelope verify source.dr
disrobe verify source.dr               # convenience alias

# Structurally diff two envelopes
disrobe envelope diff a.dr b.dr        # version, rung, flags, root hash, producer, capabilities, provenance

# Validate one envelope against another envelope's version and rung
disrobe envelope migrate-check source.dr target.dr

migrate-check answers a precise question: can the source envelope be transcoded to the target envelope's (version, rung) through a registered path while every Requires capability remains satisfiable? It validates the proposed transition; it does not rewrite either input.

Transcoding across schema versions

disrobe-ir carries a transcode registry keyed on (from_version, from_rung, to_version, to_rung). Identity transcodes are registered for every current rung. A non-identity transition succeeds only when the caller requests a registered path and its capability requirements remain satisfiable; no implicit rung change occurs.

Hardening

The envelope decoder parses a content-addressed binary format and is treated as a security-sensitive surface. Adversarial envelopes that attempt read-past-end, integer overflow, or BLAKE3-mismatch acceptance are in scope for the security policy. The decoder lives in crates/disrobe-ir/src/envelope.rs and is fuzzed.

Metadata sidecar and provenance

disrobe can emit a structured metadata bundle beside recovered output. The bundle carries call graph, types, control flow, capability surface, decompile provenance, and round-trip verdicts in one schema-conforming sidecar. It is deterministic data derived from the same pass results as the human output; no model runs in the recovery path.

Turning it on

disrobe py decompile module.pyc --out recovered/ --metadata-pack-4
disrobe py decompile module.pyc --out recovered/ --metadata-pack-4 --llm-briefs

--llm remains as a compatibility alias for the full Pack-4 selection. Prefer --metadata-pack-4 in new scripts. --llm-briefs additionally renders AGENTS.md and SKILL.md reconstruction briefs next to the bundle.

By default the bundle is written next to the primary output as <stem>.disrobe.llm.json. Override with --metadata-out <path> and choose the format with --metadata-format json|jsonl|cbor|msgpack.

The sidecar example shows workspace initialization, recovery and recompilation of add.py, and the resulting Pack-4 bundle. It includes the commands, generated-file hashes, and reconstruction briefs.

The four packs

Packs are cumulative presets over the 18 categories:

The 18 categories

Each category can also be toggled individually:

ast  disasm  cfg  dfg  symbols  strings  types  imports  constants  signatures
provenance  roundtrip-verdict  source-map  manifest-cat  decryption-keys
confidence  opcode-coverage  pii-map

Fine-tune any pack:

disrobe py decompile m.pyc --metadata-pack-3 --metadata-exclude ast,symbols
disrobe py decompile m.pyc --metadata-include cfg,types,provenance

Which commands write a bundle

The metadata flags are declared on the root parser, so every subcommand accepts them, but only these commands act on them. Every other subcommand ignores the flags and writes no bundle, and disrobe auto rejects them with DR-CLI-0843 because the chain engine writes a single chain.json instead.

Every command in this table also contributes pii-map when requested. A dedicated pass (disrobe-llm-metadata-pii) scans the raw input bytes for PII-bearing indicators and secret findings, independent of which language command ran, so pii-map behaves like cfg/dfg rather than like the per-language categories above: one shared scan wired into the bundle writer, not a per-command implementation. It reports applicable: false with a reason when it finds nothing, distinct from an unimplemented category.

Control flow and data flow

The cfg and dfg categories are summaries of the normalized IR, so a command produces them only for an input that reaches the Mir rung. These input families reach it:

• Native PE, ELF and Mach-O binaries, through the disassembler.
• WebAssembly modules, JVM class files, Dalvik .dex, managed .NET PE, SWF and raw ABC, Ruby YARB bytecode, Lua chunks, BEAM modules, and CPython .pyc, each through its own lifter.
• Any Disasm-rung or Mir-rung .dr envelope.

Both categories are emitted as one entry describing the whole module. function names the unit, blocks carries every basic block with the label of the function it belongs to, and edges carries from and to block indices with a kind of fallthrough, branch_true, branch_false or jump. A functions array carries the per-function address, export flag, cyclomatic complexity and block count. The dfg value reports memory defs, the uses each def reaches, and unreached_reads for reads no write reaches.

An input that never reaches Mir gets applicable: false and a reason naming the missing rung. A module that reaches Mir but produces no findings gets applicable: true with an empty array. Consumers can distinguish an unavailable analysis from a completed analysis with no findings.

Auth-gated categories

The decryption-keys category exposes recovered keys and IVs and is gated: passing --decryption-keys without --i-have-authorization fails with DR-CLI-0420. Other legally sensitive recovery paths document their own authorization gate where the CLI exposes one. The pii-map category itself carries no such gate: it emits only a placeholder and a location for each finding, never the matched value, so it adds no secret material of its own. Other categories such as strings and ast still report full recovered text by design, so a pack-4 bundle as a whole is not a scrubbed artifact.

Schema and reproducible output

Every bundle names its shape in schema (disrobe.metadata.llm.v2) and schema_version (2.0.0) and validates against schemas/disrobe-metadata-llm-v2.json. Each pipeline step and each provenance chain entry names a pass, its version, and the rungs it read and wrote. They record no durations.

The only timestamp is the top-level generated_at, and it appears only when SOURCE_DATE_EPOCH is set. It holds that Unix time as an RFC 3339 UTC timestamp with millisecond precision: SOURCE_DATE_EPOCH=1700000000 gives 2023-11-14T22:13:20.000Z. Without the variable the bundle carries no clock, so repeating a command on the same host with the same input and flags writes byte-identical bundles. A value that is not a whole number of seconds, or that falls after 9999-12-31T23:59:59Z, fails the command with DR-CLI-0318 and no bundle is written. The AGENTS.md brief lists a generated row only when the bundle carries generated_at.

Version 2 removed the per-step duration_ms and made generated_at optional, so a consumer written for disrobe.metadata.llm.v1 must stop requiring either field.

Provenance sidecars

Independently of the metadata bundle, a chain run records its stages and recovery results:

• recovery.json: per-pass status and the confidence-tier histogram. Summarize with disrobe context --out <dir>.
• chain.json: stage identities, input and output hashes, detector choices, and verdicts.

Neither file carries a clock or a duration. With --timings, the run also writes run.json, which holds the start and end clocks, the job count, the tool version, and each node's duration; disrobe context prints it.

See Reading a result for the full output contract. A line-level provenance map is not a guaranteed output of every chain run.

The .disrobe/ workspace

Scaffold a full agent workspace in the current directory:

disrobe init                    # scaffold .disrobe/
disrobe init --ide claude       # also generate IDE-specific settings (claude, cursor, windsurf, aider)

This lays down an AGENTS.md forensic-framing template, per-symbol annotation schemas under .disrobe/annotations/, skill packs under .disrobe/skills/, slash commands, and a settings file (see Diff and guard tooling for what its hook does and does not do). Maintain it with:

disrobe annot refresh           # rebuild .disrobe/annotations/<stem>.annot.json
disrobe rename oldName newName --note "why"   # append-only rename record
disrobe context --out recovered/              # summarize the recovery report

Supported families catalog

This is the authoritative per-ecosystem list of every packer, obfuscator, protector, freezer, and bundler disrobe recognizes, with the support tier for each. The live CLI view is disrobe catalog [ecosystem]; a default build, which turns the full feature on, reports 169 families across 15 ecosystems, and the totals on this page are the full ones. Most catalogs sit behind a cargo feature, so a build with features trimmed registers fewer catalogs and reports a smaller total.

cargo run -p xtask -- regen --check re-derives the headline total, the native tier split, and the per-pass counts in the tables below from the tables the binary itself carries (Packer in crates/disrobe-pass-native/src/packers/mod.rs, CATALOG_COUNT in each pass chain_detector.rs, Protector::ALL in crates/disrobe-pass-dotnet/src/protectors.rs, and RaspVendor in crates/disrobe-pass-jvm/src/rasp.rs), so a family added to the binary without this page moving with it fails that check. Three rows count something no catalog table holds, Freezers / packagers, Freezers / packagers (experimental, unvalidated), and JS bundlers (unbundler); for those the check compares the published count against the family list beside it, which keeps the two halves of a row consistent but proves neither against the binary.

disrobe catalog
disrobe catalog native
disrobe catalog python --json

Three words describe how far recovery goes for a family, the same three the README uses:

• Recover: real recovered output (source, bytes, or structure), measured against an independent oracle where one exists.
• Partial: the layer is identified and what is intact is extracted or peeled, with the residual stated.
• Detect-only: identification plus a stated reason the rest cannot be recovered statically.

A wall identifies a required input that is absent, such as a runtime key or network-fetched payload. Every wall is detect-only, and detect-only also covers families identified without static recovery. See recovery limits and reading a result for how to interpret these reports.

disrobe catalog prints the same three tiers with the SupportQuality labels the binary carries (crates/disrobe-core/src/chain/obfuscator_catalog.rs), where full is the Recover tier: [full], [partial], [detect-only].

The disrobe auto chain at the bottom is what stitches these together: it fingerprints the input, runs the matching pass, re-fingerprints the output, and repeats until nothing else applies.

Native packers and protectors (29)

The Packer enum carries 29 variants across five UnpackerStatus tiers (12 + 6 + 3 + 6 + 2 = 29). The native chain detector catalog advertises 27 of them; the two CLR-layer crypters route to the .NET pass, so disrobe catalog native lists 27.

The tier names below are the in-tree UnpackerStatus values, so the split is exactly what the binary advertises. crates/disrobe-pass-native/src/packers/mod.rs test published_tier_counts_match_this_enum asserts every count in the table below against unpacker_status, so a variant cannot be added or moved between tiers without this page failing. The family names in each row are written by cargo run -p xtask -- regen from the same enum, and regen --check fails when a row names a family the binary does not carry, omits one it does, or files one under the wrong tier. Only the Implemented tier reaches an unpack routine, and the same check fails when a family in that row has no dispatch arm in crates/disrobe-pass-native/src/chain_detector.rs or when a family outside it has one.

Donut and sRDI are shellcode loaders, so what the Implemented tier recovers for them is the embedded payload rather than a decompressed image. Donut recovery is graded on one Binject/go-donut instance (Chaskey-encrypted, LZNT1 and uncompressed modules); XPRESS and XPRESS-Huffman modules are reported as undecoded, and no instance built by the original C generator is in the corpus.

The recover tier is scored byte-for-byte against real committed originals: UPX .text and .pdata are bit-identical (the whole loaded image about 96%, the residual being loader-rebuilt relocations and IAT the OS resolves at run time), ASPack and PECompact rebuild the decompressed image with the reconstructed IAT at least 98% byte-identical, and Yoda's Crypter .rsrc is byte-identical with its .text decrypted to full plaintext. NSPack, FSG and Petite each reproduce from a clean checkout with one committed packed-and-original pair apiece. For the NSPack pair the gate holds the whole loaded image at or above 94.1% and the .text, .rdata and .data span at or above 99.3%. A per-section gate scores those three decoders over a wider span that also counts .rsrc: NSPack 57721 of 60060 bytes, FSG 55263 of 60060, and Petite 86986 of 89648. .text and .data are byte-identical for all three, and NSPack's .rdata is byte-identical as well, because its import lookup and address tables are rebuilt from the module record the stub carries rather than left for the loader. Their shared residual is the resource directory, now recovering 2333 of 4672 bytes for NSPack and 1552 of 4672 for FSG once the original tree is placed at its own RVA, and relocations are scored separately as loader-rebuilt. Larger local-only samples score lower on the whole-image measure, and no figure is published for them because those samples are not committed and nothing pins them, so the numbers above describe the committed pairs rather than the families. kkrunchy is byte-exact against committed fixtures and does reproduce. The full breakdown is in the native guide.

Python

Jawbreaker's b16/b32/b64 loader shell is decoded statically, but a payload it fetches from a remote paste at run time is absent from the file. ObfuXtreme's AES-CBC/b85/xor static body is recovered; its runtime-payload segment is not in the artifact. python-obfuscator (PyPI), pyobfus, and Pypacker are detect plus partial-peel. Compiled Cython extensions (.pyd / .so) have their Python-visible surface (function and class names, docstrings, signatures) recovered from the module's symbol tables, with a structural fallback when the binary is stripped. See the Python guide.

JavaScript / TypeScript / WebAssembly

The JS and WebAssembly guides cover each pipeline.

JVM / Android / .NET

On .NET, ConfuserEx2 constant decryption is reversed on a real committed sample, the Eazfuscator VM tier is devirtualized at 67 of 67 instructions across six bodies against an in-repo EazVM virtualizer of our own, and the KoiVM VM tier is devirtualized on a sample produced by the real KoiVM tool (6 of 6 bodies lifted to CIL). ILProtector, MaxToCode, and the Themida/.NET wrapper derive their per-method key in a native loader absent from the artifact, so those bodies are runtime-key walled. See the JVM and Android and .NET guides.

Detection covers every family in that row. String decryption is a narrower claim and it rests on different evidence per family. It is graded against a committed assembly the protector's own tool produced for ConfuserEx2, Obfuscar, BitMono. For SmartAssembly, Spices.Net, Skater, .NET Reactor, Eazfuscator.NET, CryptoObfuscator the decoder implements the published algorithm and is graded against a fixture built to that algorithm; no assembly produced by those products is committed, so each of those families is detected and its decryption modelled, not confirmed against a real protected assembly. String recovery stops at detection for Themida (.NET wrapper), ILProtector, MaxToCode, whose keys live in a native loader the artifact does not carry.

Lua

The Lua chain catalog is 16 entries: 14 obfuscator families plus the Luau and GLua dialect detectors.

IronBrew2 2.7.0 is reversed on real committed output in standard and MAX mode, validated by a real-lua execution differential. MoonSec-shape recovery runs against a synthetic bootstrap of our own design pending a real sample. The Lua guide walks the devirtualizer.

Shell

Full VBA p-code decompile (264-opcode table, VBA5/6/7) with VBA-stomping detection rounds out the shell pass, alongside Excel 4.0 (XLM) macro-formula recovery (BIFF8 and BIFF12 Ptg decode, shared-formula resolution, and Auto_Open resolution in BIFF8 workbooks) and PDF maldoc analysis (embedded JavaScript, launch and embedded-file actions, both xref forms, RC4/AESV2 empty-password decrypt). See the shell guide.

PHP

Stacked eval-chain obfuscation (FOPO and the base64/gzinflate/rot13/XOR layer set) and Phar archives are peeled and walked in the same pass. See the PHP guide.

Other runtimes

The disrobe auto chain

disrobe auto is the front door to the pass registry compiled into the current binary. It fingerprints the input, picks the highest-confidence pass, runs it, re-fingerprints the output, and repeats until no further pass clears the confidence threshold or the depth cap is hit. disrobe passes prints that registry. Some cataloged operations are reachable only through direct commands; disrobe --help is the authority for those surfaces.

disrobe auto suspect.exe --out recovered/                 # detect + chain the whole pipeline
disrobe auto suspect.exe --out recovered/ --capture-stages # keep the exact output written by each stage
disrobe auto firmware-dir/ --out out/ --batch-max-depth 6

Representative chains:

• PE -> UPX -> rust-demangle
• PyInstaller -> PyArmor -> .pyc decompile
• APK -> dex -> Java + manifest
• Electron .asar -> unbundle -> source
• .NET PE -> in-house CIL decompile -> C#

Compiled webview frontends also have a direct static recovery path:

disrobe webview desktop.exe --out frontend/

The standard CLI also recovers supported Electron and Tauri layouts through webview.carve in auto; Wails uses go.classify. See Webview desktop frontends for the output paths and package extraction workflow.

With --capture-stages, stage outputs land in out/01-*/, out/02-*/, ..., out/final/. The full mechanism, including the depth cap, cycle detection, and the chain.json topology descriptor, is in The chain runner.

Anti-analysis defeat

disrobe analyzes samples statically by default. It recognizes obfuscation and anti-analysis patterns, recovers the available code and data, and reports missing runtime keys or unsupported transformations.

Signature defeat

Identification never trusts a single magic byte. A zeroed or flipped magic, renamed UPX0/UPX1 sections, or a corrupt UPX! marker is re-identified from internal self-consistency:

• PE through e_lfanew to the COFF and optional headers.
• ELF / Mach-O by header offsets that close against the file length.
• ZIP by its end-of-central-directory anchor.
• DEX by section-offset consistency.
• Classfile by a constant-pool walk.
• wasm by the LEB section stream.

A real UPX executable with a flipped MZ and renamed sections still unpacks byte-identically, because the structural PackHeader (method id, self-consistent compressed and uncompressed lengths, plausible version) is the signal a scrambler cannot remove without breaking the stub's own ability to self-extract.

Code-signing verification

Malware often ships with a broken, expired, self-signed, or mismatched Authenticode signature to look trustworthy at a glance. For a signed PE, disrobe native identify verifies the signature end to end rather than trusting its presence: it recomputes the Authenticode hash and compares it to the claimed digest, walks the PKCS#7/CMS certificate chain to an embedded bundle of trusted code-signing roots, requires the code-signing extended key usage on the leaf, and cryptographically verifies any RFC 3161 timestamp before letting it extend validity. The result is a single verdict (Valid, HashMismatch, Expired, SelfSigned, UntrustedChain, WrongKeyUsage, and the rest), so a tampered .text, a forged timestamp, or a chain that does not reach a trusted root is surfaced instead of silently accepted. The native guide lists the signed-fixture and osslsigncode cross-checks behind it.

String and data encryption

Recovery stops when a required key exists only in a system property, environment variable, clock value, random source, or runtime table.

Control-flow obfuscation

• BlackObfuscator DEX flattening is recognized: the String.hashCode()-keyed dispatcher and its const-string block names are used to annotate the recovered block order. The flattened method body remains in the emitted source.
• OLLVM-style control-flow flattening is deflattened on native, and the result is reported as a cover rather than as an equivalence. disrobe enumerates every state the dispatcher can select out of the sample's own compare tree or jump table, resolves the state transition out of each case region by value-set analysis over the state variable, and reports which states the recovered program reaches. A state it cannot reach stays in the denominator and carries a named reason. The deobf.json sidecar publishes the whole cover: the state list, the recovered state-to-state edge set, the case regions with their block spans, and one reason per uncovered state. Its fully_recovered flag is true only when all three of these hold: every dispatcher state is reached, no reached state has an unresolved transition, and the recovered edge set passes its consistency check. It is not a claim that the recovered program and the flattened one agree on every input. Bogus control flow and instruction substitution are reversed on the same path.
• Proven-dead conditional arms are folded on the AArch64 native decompile path by a symbolic devirtualizer that runs before structuring (on by default, disabled with --no-devirt). The fold is transactional: on any proof miss or budget exhaustion it reverts to the original function, so it replaces a construct only with a proven-equivalent one and adds no edges.
• Obfuscator-planted out-of-range exception entries that poison the JVM control-flow graph are dropped before structuring.
• Flattened JS dispatchers are collapsed back to structured control flow.

Anti-disassembly and MBA

The JVM, Dalvik, and CIL decoders tolerate broken StackMapTable, fake exception ranges, and illegal-but-verifiable bytecode. On native, jump-into-the-middle desync, overlapping instructions, and opaque predicates are resolved in-tree. A mixed-boolean-arithmetic simplifier, wired through the JS and WebAssembly decoders as well, collapses MBA expressions back to their algebraic form through a layered stack: linear signature solving, nonlinear reduction modulo the null-polynomial ideal, e-graph equality saturation over proven ring identities, bounded enumerative synthesis for opaque leaves, and permutation-polynomial inversion. Each layer is sound or abstains, and a rewrite is emitted only after equivalence is proven over the full bitvector domain, so an expression the stack cannot prove is left untouched rather than approximated.

Indirect dispatch is resolved before the SMT tier is ever consulted. A strided-interval value-set analysis reads the masked, compare-guarded, or position-independent index bound off the path constraints and enumerates the jump table to a concrete target set that over-approximates, and usually equals, the reachable targets. It abstains when the table is writable or the index is unbounded, and defers to the solver only for a disequality residual, rather than narrowing past what it can justify. The over-approximation property is unit-tested and graded against a real gcc-compiled switch; it is not proved for every input. The value-set tier carries no solver dependency and compiles without one.

Every SMT verdict the simplifier and the devirtualizer depend on is independently checked before it is trusted. A SAT verdict is re-evaluated against the model the solver returned; an UNSAT verdict is reconfirmed by BDD bit-blasting, or, for the multiply-heavy opaque predicates the bit-blaster cannot settle, by a finite-difference polynomial certificate. A verdict that fails its own check, or a solver that panics or exhausts its budget, degrades to abstain, so a solver bug the independent check catches costs a recovery rather than producing a wrong answer. The external differential runs against pinned Z3 4.16.0 in CI and includes a seeded wrong rewrite as its control. The same harness supports Bitwuzla for local runs, but CI does not provision it. A defect shared by both the solver and its checker is outside what the differential can rule out.

Bytecode virtualization

Overlay inflation

The PE overlay carve computes the true end of the executable image and isolates any trailing archive (gzip, xz, zstd, bzip2, tar, 7z, cab, rar) into its own segment, so padding cannot mask an appended payload.

Symbol stripping

ProGuard/R8 mappings are replayed into name-restoration.json with overload matching; the emitted Java names are unchanged. Go type and stdlib names are recovered from surviving pclntab/moduledata on stripped binaries, Rust/C++/Swift/Itanium symbols are demangled, and structure is recovered from DWARF. garble's hashed user names remain unresolved without the required naming information; the report retains the structure and metadata that can be recovered.

What grades each capability

The table links each capability to its compiler, runtime, verifier, or repository test. Partial and Detect-only rows identify the remaining recovery limits.

Warning the analyst before anything runs

disrobe also flags the evasion a sample attempts. disrobe behavior and disrobe capabilities surface al-khaser / Pafish-class anti-debug, anti-VM, anti-sandbox, and timing checks, mapped to MITRE ATT&CK and MBC, with a confidence grade per technique. This is detection only: disrobe never executes the sample on its default path and never implements any of these techniques itself.

Runtime-keyed protection

With a matching pyarmor_runtime, the static path supports the variants listed in the Python guide. The 72-of-72 structural result covers the manifest's v8/v9 default-trial wrappers: each decodes to a complete header-anchored root CodeObject. That measurement does not grade source recovery, original .pyc identity, or semantic equivalence. Some v6/v7 variants require the opt-in, sandboxed dynamic-capture path. For ionCube, SourceGuardian, Zend Guard, ILProtector, and MaxToCode, a required key may reside in a native loader or live process outside the artifact. Disrobe reports the missing key and leaves that content unrecovered.

See the forensics and malware-safety posture for how the default static path stays safe on untrusted input.

Queryable IR and capabilities

disrobe query and disrobe capabilities turn a stripped binary into something you can interrogate. Both run over the same symbol-independent IR the native disassembler builds (disrobe-query and disrobe-capabilities), and both accept a raw binary or a .dr envelope.

disrobe query: ask the IR a question

disrobe query app.exe functions                 # discovered functions, complexity, exports
disrobe query app.exe calls-to malloc           # call sites to a target
disrobe query app.exe xrefs-to sekret           # references to a symbol or address
disrobe query app.exe string-decoders           # decoder-shaped functions (loops + byte arith)
disrobe query app.exe complexity-over 20        # functions over a cyclomatic threshold
disrobe query app.exe capability network        # instructions tied to a capability
disrobe query classes implementors 'Lpkg/Root;' # concrete JVM/DEX implementors

The query layer is built on the same function discovery the disassembler uses (call-target and prologue scanning), so it works without a symbol table. It accepts a .dr envelope at the Disasm or Mir rung; an envelope at any other rung is rejected with an explicit unsupported-rung error rather than silently returning empty or wrong results. The seven verbs are:

Every query honors the global --json flag, so the output drops straight into a script.

implementors accepts a single .class or .dex file, or a directory containing .class and .dex files. JVM descriptors such as Lpkg/Type; use nonempty components and allow Unicode, hyphens, and control characters except ., ;, [, and /. DEX descriptors follow the file version's SimpleName grammar: ASCII letters and digits, $, -, _, and the format's declared Unicode ranges are valid in every position; DEX 040 additionally admits its declared space characters. Controls, parentheses, and code points outside those ranges are rejected. Target descriptors are limited to 1,048,576 UTF-8 bytes. Quote descriptors at a shell prompt because the terminator is a semicolon. Text output escapes control characters; JSON preserves accepted descriptors. Results and proof paths are sorted by descriptor. The result records missing targets, duplicate definitions, malformed edges, cycles, rejected directory artifacts, and every traversal budget that produced a partial result. A rejected .class or .dex in a directory does not discard valid siblings. Malformed, missing-definition, and rejected-artifact identities are capped independently by count and byte length, with typed truncation diagnostics. APK and JAR containers are not query inputs, and DEX 041 container-relative layouts are rejected explicitly.

Navigation through MCP

The MCP companion exposes the same module model through call_graph, xrefs, function_summary, and neighborhood. These tools use ids derived from the module source hash and function address rather than function names, so duplicate names remain addressable. Direct-call outcomes distinguish an exact function start, an address inside one function, an ambiguous overlap, a non-function symbol, and an unresolved address. Calls without a direct target remain explicit indirect-call records.

call_graph, xrefs, and neighborhood paginate deterministically. Each cursor binds the source hash and request parameters, and a cursor from another module or neighborhood is rejected. A content-derived discriminator keeps distinct same-address function records addressable without depending on their position in the module. Graph construction has fixed function, instruction, call, cross-reference, candidate-work, and retained-memory ceilings before response pagination. Neighborhood traversal records visited ids and bounds both depth and retained records, so recursion and mutual recursion terminate without dropping their cycle edges.

disrobe capabilities: behavior to ATT&CK

disrobe capabilities app.exe
disrobe capabilities app.exe --json

disrobe capabilities runs a rule engine over the same IR and reports the behaviors it matched, each mapped to MITRE ATT&CK techniques and Malware Behavior Catalog (MBC) IDs. Every match carries the instruction offsets that triggered it as per-rule evidence, so a finding can be traced to the exact bytes rather than taken on faith.

The report names the detected format, the match count, and the per-rule evidence. The MCP server also offers a behavior summary, which uses a separate byte-analysis API; its results are not interchangeable with this IR rule report.

Where the IR comes from

The native disassembler (an in-tree iced-x86 decoder, detailed in the native guide) discovers functions, partitions them into basic blocks, and records each instruction's register, memory, and rflags effects. The query and capability layers read that structure rather than the original symbols, which is why a stripped binary answers the same questions a symbol-rich one does. Pointing either tool at a .dr envelope reuses a cached disassembly instead of re-decoding the bytes.

Recon, prowl, and indicators

disrobe frisk scans files, directories, APKs, and recovered source trees for secrets and indicators. Findings include cloud keys, service tokens, private keys, API routes, storage buckets, URLs, domains, IP addresses, emails, .onion addresses, and webhooks. Android manifest analysis reports deep links, exported components, content-provider authorities, and dangerous permissions. Findings carry source locations so you can inspect the surrounding content.

Usage

disrobe frisk app/                                  # walk a directory or recovered source tree
disrobe frisk app.apk                               # APK manifest exposure + secrets + IOCs
disrobe frisk recovered/ --format json              # text, json, or sarif
disrobe frisk recovered/ --format sarif > frisk.sarif
disrobe frisk app/ --pattern rules.txt              # custom rule pack: name=regex per line
disrobe frisk app/ --suppress example.com           # drop findings whose value contains a substring
disrobe frisk app/ --emit-baseline > baseline.json  # snapshot current findings
disrobe frisk app/ --baseline baseline.json         # report only new findings
disrobe frisk app/ --entropy                        # include high-entropy generic-secret findings
disrobe frisk app/ --redact --format sarif          # replace secret values in shareable output

frisk is offline. Network enrichment is explicit through prowl, and schema merging is explicit through indicators.

Secret values remain visible by default. Pass --redact, or set output.redact = true, to replace detected secret values throughout text, JSON, SARIF, and HTML reports. Redaction runs after suppression and baseline filtering. It preserves finding counts, locations, and offsets.

Each token contains the first 96 bits of the unsalted SHA-256 digest. The same secret therefore receives the same token across runs. A 96-bit identifier makes an accidental collision improbable. Redaction returns an error when renamed JSON object keys would collide. Values shorter than 16 characters reveal no source characters. Longer values include only the first two and last two characters. Because the digest is unsalted, anyone who holds or can guess a candidate value can compute its token and confirm whether that value appears in a report, so a token hides a secret only from readers who cannot enumerate it. Literal replacement processes longer matches first so an overlapping shorter value cannot expose part of a longer value.

Redaction scrubs finding values, previews, messages, paths, URI user information, and nested serialized fields. Nested JSON traversal stops at 64 levels, 1,048,576 values, or 64 MiB of string data. The command returns an error instead of emitting a partially redacted document when a limit is exceeded or redacted object keys would collide.

Decoded string layers

A secret hidden behind an encoding is still a secret, so frisk does not scan only the literal bytes. It peels base58, base62, base45, base91, base92, base122, Ascii85, Z85, uuencode, xxencode, yEnc, percent-encoding, HTML entities, and Punycode recursively, with decompression-bomb caps at every level, and rescans each recovered layer for the same secrets and IOCs. A finding inside a decoded layer reports the position in the file that carried it.

Wide strings

frisk and ioc read UTF-16 text in both byte orders on every input. No flag turns wide scanning on or off, and no flag selects a byte order.

A wide run is four or more ASCII characters, each held in a two-byte code unit whose other byte is zero. Eight bytes is therefore the shortest run that can be reported. A run may start at any byte offset, odd or even. The indicator scan accepts printable ASCII, tab, line feed, and carriage return inside a run. The endpoint and .onion pass accepts printable ASCII only. A code unit outside the accepted set ends the run, and the scan resumes at the next position rather than stopping.

The endpoint and .onion pass in disrobe frisk reads at most 65536 wide runs per file for each byte order, and stops a single run at 65536 bytes. The indicator scan stops after 100000 indicators for one input, wide and plain findings together.

What a wide scan reports

The indicator layer reads wide runs in both byte orders. URLs, domains, IPv4 and IPv6 addresses, emails, and wallet addresses surface from wide text in both commands. disrobe ioc also reports Windows paths, registry keys, and Unix paths found in wide text. disrobe frisk keeps those three only when the value matches a persistence indicator. The endpoint rules and the .onion rule run over each wide run as well.

Secret rules and --pattern rule packs do not read wide runs. They match the file's own bytes and its lossy UTF-8 text. A credential stored only as UTF-16 is reported only when the secret rule matches the raw bytes. frisk and ioc read UTF-16 only, and neither reads UTF-32.

disrobe frisk anchors every finding taken from a wide run to the file offset, line, and column where the run starts, not to a position inside the decoded text. disrobe ioc reports the run's file offset plus the index of the match inside the decoded run, so the offset is exact for a match at the start of a run and approximate for a match further in.

The opposite reading of the same bytes starts one byte later and produces a different value. Both readings can therefore report a finding over one run. Read the rule id suffix, or the encoding value, to see which reading produced a given finding.

Byte order in the output

disrobe ioc sample.bin --format json | jq '.indicators[] | select(.encoding == "utf16_be")'
disrobe frisk recovered/ --format json | jq '.findings[] | select(.rule_id | endswith("-UTF16BE"))'

In disrobe frisk, the suffix is part of the fingerprint that --emit-baseline and --baseline compare. A wide finding and its plain-text twin are two separate entries in a baseline.

Finding categories

Every finding carries a category, a rule id, the matched value, a severity, and a file:line:column (or byte offset for non-text input).

Flags

Custom rule packs

A rule pack is one name=regex per line:

# rules.txt
internal-host=https://[a-z0-9.-]+\.corp\.example\.com
deploy-token=DEPLOY_[A-Z0-9]{32}

disrobe frisk recovered/ --pattern rules.txt --format json

Baselines

Snapshot the current findings, then report only new ones on later runs, so a CI gate fires only when a fresh secret or endpoint appears:

disrobe frisk app/ --emit-baseline > frisk-baseline.json
disrobe frisk app/ --baseline frisk-baseline.json --format sarif > new-findings.sarif

Network harvest with prowl

disrobe prowl example.com --subs --sources wayback,commoncrawl,urlscan --format json > prowl.json
disrobe prowl --targets-file targets.txt --proxy http://127.0.0.1:8080 --timeout 20
disrobe prowl --recon-input frisk.json --ioc domain,ipv4,email
disrobe prowl keyring set virustotal

disrobe prowl queries public archives and threat-intel feeds and writes disrobe.prowl/v0. The source labels are:

Important flags:

Key resolution order is flags, provider environment variables, OS keyring, then the permissions-checked TOML config. Use disrobe prowl keyring set|get|rm|list <provider> to manage stored keys.

Indicator bundles

disrobe frisk recovered/ --format json > frisk.json
disrobe ioc sample.bin --format json > ioc.json
disrobe prowl --recon-input frisk.json --format json > prowl.json
disrobe indicators frisk.json ioc.json prowl.json --format json > indicators.json
disrobe indicators frisk.json prowl.json --targets-only > targets.txt

disrobe indicators ingests disrobe.recon/v0, disrobe.ioc/v0, and disrobe.prowl/v0, deduplicates indicators by class and value, preserves each value's source provenance, and emits disrobe.indicators/v0. --targets-only prints network indicators ready for prowl --targets-file.

String reader

disrobe_core::recon::string_emu holds the wide-run reader behind the endpoint and .onion pass in disrobe frisk. It reads UTF-16LE and UTF-16BE runs from the input bytes and reports each run's encoding and offset.

Python

disrobe disassembles and decompiles Python bytecode across CPython 3.8-3.15 and the alternative runtimes, peels source-level obfuscators, and unwraps freezers and protectors back to .pyc.

The Python decompiler is implemented in Rust. The command uses this engine; pycdc, PyLingual, decompyle3, and uncompyle6 appear in comparison benchmarks.

At a glance

Commands

disrobe py decompile module.pyc --out recovered/
disrobe py decompile module.pyc --out recovered/ --backend native    # accepted for explicitness; native is the only backend
disrobe py decompile module.pyc --out recovered/ --emit source,disasm,ast
disrobe py disasm module.pyc --out trace.txt
disrobe py deob obfuscated.py --out clean.py
disrobe py deob obfuscated.py --out clean.py --cleanup

decompile runs the in-tree engine: a frame-tree pre-pass, per-version opcode dispatch, then round-trip verification. --backend native is accepted for explicitness; no external Python decompiler backend is exposed by this command.

disasm writes a faithful per-instruction trace across every supported interpreter dialect. This is the Disasm rung: lossless, offset-preserving, no structural reconstruction.

deob peels source-level obfuscator wrappers (Kramer/Specter, Berserker, Jawbreaker, BlankOBF, PlusOBF, pyobfuscate.com, PyObfuscator (mauricelambert), python-obfuscator (PyPI), ObfuXtreme, Manglify, Oxyry, pyminifier, online obfuscator family, Xindex, pyobfus, Pypacker, Patchwork) with an AST-evaluator backend. --cleanup runs a ruff-AST constant-fold and dead-branch-elimination pass afterward.

Freezers and packagers

disrobe pyinstaller extract onefile.exe --out out/       # PyInstaller 2.x .. 6.20+, AES-CTR/CFB decrypt
disrobe pyinstaller detect onefile.exe                   # cookie, Python version, TOC offsets, no extract
disrobe pyfreeze extract app.exe --out out/              # cx_Freeze / py2exe / shiv / pex / PyOxidizer (experimental, unvalidated) / Briefcase
disrobe nuitka detect app.exe                            # flavor + Python version
disrobe nuitka extract app.exe --out out/                # --onefile payload (zstd)
disrobe nuitka symbols app.exe                           # impl_* + module-init scan on --standalone builds
disrobe py sourcedefender app.pye --out app.msgpack      # SourceDefender .pye decrypt

PyArmor

disrobe pyarmor unpack protected.py --out out/
disrobe pyarmor unpack protected.py --out out/ --allow-bcc
disrobe pyarmor unpack protected.py --out out/ --allow-dynamic --dynamic-timeout 60

unpack extracts a decrypted payload and can reconstruct a .pyc; reconstructed output is not claimed byte-identical to an original .pyc. The published 72/72 result is narrower: it covers manifest-named v8/v9 default-trial wrappers and requires one complete header-anchored root CodeObject, not source recovery, emitted .pyc identity, semantic or execution equivalence, or external agreement. v6/v7 can optionally use a dynamic-hook fallback that runs the obfuscated wrapper in a watched subprocess to capture marshal streams; this is opt-in and unsafe on untrusted input.

The --allow-dynamic path executes the sample. Only enable it on trusted samples or inside an isolated sandbox. See Forensics and malware-safety posture.

Other useful flags: --mode auto|standard|super, --target 3.11 (rewrite emitted .pyc magic), --allow-bcc, --strict, and --all-emits.

BCC input is refused with DR-PYARM-0050 unless --allow-bcc is set. With that opt-in, the pass lifts extracted native blobs statically in tree; it does not execute them or invoke Ghidra. Windows x86-64 uses the Microsoft x64 ABI, Linux x86-64 uses the System V ABI, and Darwin ARM64 uses AAPCS64. A function that depends on the PyArmor or CPython runtime dispatch remains an unmodeled record with native disassembly and a typed reason.

The dedicated command writes bcc/bcc-recovery.json, bcc/bcc-pseudo-c.c, and bcc/bcc-recovered.py beneath --out. Path-aware PyArmor extraction through disrobe auto writes the same three byte-identical artifacts. The canonical JSON schema is disrobe.pyarmor.bcc.recovery/v1; it embeds disrobe.pyarmor.bcc.function_map/1 and represents modeled, unmodeled, and refused blob outcomes. The recovered Python file is a deterministic source skeleton derived from the same publication, not a claim of source identity or execution equivalence.

--strict returns DR-PYARM-0052 when unpacking produces no .pyc, records a fallback reason, or records a marshal decode error. It does not add a separate failure condition for incomplete BCC lifting.

End to end

A real-world Python sample is often frozen, then protected, then compiled. disrobe auto chains the whole stack:

disrobe auto suspect.exe --out recovered/    # PyInstaller -> PyArmor -> .pyc decompile

Coverage and fidelity

How the in-house engine works

The engine reconstructs nested source constructs from the CPython 3.11+ exception table before walking instructions. Its round-trip checker recompiles recovered source when a matching interpreter is available, then compares the resulting code objects. Reports distinguish exact matches, normalized matches, code differences, compilation failures, and an unavailable interpreter. A normalized match is evidence about the compared representation, not a proof of identical behavior.

Measured opcode structure

The benchmark compiles each original module and its recovered source with CPython 3.14.5 at optimization level zero. It compares normalized opcode streams and three argument-count fields for each original code object. Normalization removes or merges selected instructions and omits jump targets and most operands. The comparison excludes __annotate__ code objects and does not penalize additional recovered code objects. These results measure opcode structure, not bytecode identity or program equivalence.

The fixed core population contains 574 modules and excludes idlelib and turtledemo: 17396 of 18276 code objects agree, or 95.18%. Its pinned 200-module subset yields 6139 of 6286 (97.66%). The committed module lists define both populations.

full_stdlib_recompile_gate.rs measures the 574-module population on explicit invocation. CI runs a 115-module subset and runs the 200-module gate on tags and scheduled builds, with a 97.66% regression threshold for the latter.

The recorded run includes the executable and interpreter hashes, comparison rules, exact counts, and reproduction command. Its unmatched objects identify all 880 code differences, missing objects, and collisions by module, qualified name, and occurrence.

Per-interpreter bands

Each band uses the same normalized opcode-structure comparison and pinned module list, compiling both sources on the listed interpreter. Modules absent from that interpreter are excluded. The different denominators prevent a direct ranking between bands.

The recorded results and interpreter versions are in xtask/data/recovery.json.

The 3.10, 3.12, and 3.13 bands run on each push to main. Tag builds and weekly scheduled builds also run the remaining band gates. The dedicated 3.10, 3.12, 3.13, 3.14, and 3.15 checks require their pinned interpreters. The 3.8 and 3.9 counts were measured on Windows x86-64; their gates run in the weekly test job, which installs both interpreters, and skip when the interpreter is absent.

The 3.14 row reads differently from the rest: it reports the pinned 200-module subset of the accepted 574-module measurement; both use the same source hashes and comparison rules.

Cython compiled extensions

A Cython module compiles to a native .pyd / .so, but the module still exposes the surface CPython needs to import it. The disrobe-binfmt Cython reader (disrobe_binfmt::containers::cython) recovers that surface from the compiled ELF, PE, or Mach-O: function names, qualified names, docstrings, calling-convention flags, per-class method groupings, and the original .pyx / .pxd source filenames. It walks the PyMethodDef and PyTypeObject tables through the module's symbols when they survive, and falls back to a bounded structural scan of the readable data sections for PyMethodDef-shaped records when the binary is stripped, resolving data pointers through both static section relocations and ELF dynamic relocations.

Recovery is graded against real compiled Cython fixtures (unstripped, stripped, and separately linked) with a known ground-truth .pyx: the expected functions recover with their exact docstrings and signatures, and the report records whether each name came from a symbol or from the structural fallback (real_cython.rs).

disrobe auto claims a Cython extension through the python.cython-surface pass and writes two files: <module>.pyi, a stub that declares every recovered function, class and method with its parameters, defaults, Python-typed annotations and docstring, and cython-surface.json, the full recovered record. The stub of the committed fixture is parsed by CPython's ast and compared with the authored .pyx (cython_stub_reference.rs): every function and method is declared with the authored parameter names and defaults, and a dropped default turns the comparison red. A stripped module keeps every function and method name, grouped under its class by the qualified signature Cython embeds; parameters come only from those embedded signatures, and a class whose type table did not survive stripping has no __init__ declaration.

Limits

• The pyc-zipper real-output grader covers 30 pinned outputs against CPython 3.12. Compressed payloads recover their opcode structure; obfuscation can permanently delete variable names and line information. Twenty-five source recoveries print the same bytes as the authored programs; the five generator cases retain named partial status. Eighteen outputs also have broken loaders in the tool itself, recorded separately from static recovery.
• The pyobfus real-output grader covers 15 generated sources. Recovery removes the generator header and preserves the body exactly, including generated names, literals and reflection lookups. All 15 re-execute like the authored inputs. Original identifier names are unavailable, so recovery remains partial; three other requested cases failed in the tool and produced no fixtures.
• A Cython module's Python source is gone once compiled. Only the import surface described above is recoverable, not the .pyx bodies.
• PyArmor v6/v7 may need the opt-in dynamic-hook fallback, which executes the sample. The manifest-named v8/v9 default-trial result is a pure-static structural decoding check only; it does not establish recovery for other variants.

JavaScript / TypeScript

disrobe reverses supported JavaScript and TypeScript obfuscation, extracts modules from recognized bundle layouts, and inspects packaged JavaScript runtimes. Recovery uses static parsers and bounded transformations.

At a glance

Commands

disrobe js deob bundle.min.js --out clean.js --full --rename-scope-aware
disrobe js deob legacy.js --out clean.js --legacy auto --unminify
disrobe js unbundle app.bundle.js --out src/
disrobe js unbundle app.bundle.js --out src/ --emit sourcemap
disrobe js v8 app.jsc
disrobe js v8 app.asar --json-out report.json
disrobe auto app.asar --out recovered/        # Electron and Node packaging chains run end to end
disrobe auto app.exe --out recovered/         # deno compile executable
disrobe auto modules.eszip --out recovered/   # bare eszip archive
disrobe webview desktop.exe --out frontend/    # Electron, Tauri, or Wails assets

Use js v8 to inspect a packaged JavaScript runtime and webview to recover the shipped frontend tree from a desktop binary. The standard CLI also routes supported desktop layouts through auto. See Webview desktop frontends.

The default deob path runs string-array recovery and writes a detection.json sidecar naming the matched family. --full runs the complete obfuscator.io reversal pipeline and records per-stage statistics in a pipeline.json (string-array call sites inlined, dispatch blocks collapsed, opaque predicates folded, packed blocks expanded). --legacy jsobfu|jscrambler-free|auto targets the older families; --unminify adds constant folding and the AST unminify rules (!0 to true, void 0 to undefined where undefined is not shadowed, bracket to dot access, string concatenation).

For Rust callers, AstRuleId::AsyncRestore is a selector-compatibility no-op: Babel-style async wrappers are preserved. Any call carrying an exact Babel async-helper specifier quarantines the entire AST and preset-env pass, without assuming the callee is CommonJS require. AstRuleId::ArgumentSpread and AstRuleId::TemplateLiteral are disabled-by-default selector-compatibility no-ops, with stable zero-valued report counters. AstRuleId::RegeneratorRestore is a disabled-by-default selector-compatibility no-op with a stable zero-valued report counter; regenerator state machines are preserved. undo_preset_env keeps helpers_removed empty and its spread, class, and async counters at zero; it currently reports only AST-proven optional-chain and nullish-coalescing restoration.

unbundle auto-detects the bundler runtime from its markers (the full table above) or forces one with --target auto|webpack|webpack4|webpack5|vite|rollup|esbuild|turbopack|bun. Modules land as separate files with chunk and module identifiers preserved, plus a manifest.json. --emit sourcemap synthesizes per-chunk v3 source maps and decodes embedded data-url maps.

Coverage and fidelity

js v8 classifies the artifact and prints real detection: bytenode header layout and Node version for .jsc, SEA flags and code length, nexe/nw.js payload geometry, or the .asar entry listing.

For .jsc, Disrobe detects the serializer version across Node 18-24, recovers user strings and every serialized bytecode array, and disrobe auto reports each function's Ignition disassembly with registers named as node --print-bytecode names them, together with a JavaScript lift of it (lifted_js). Each function states lift_complete and its reversible, lossy and runtime-opaque line counts; an instruction without a lift rule is kept as a comment and its accumulator reads as __unlifted_<op>, so an incomplete lift fails when run instead of computing a wrong value. The path runs locally without a patched V8 binary or an external decompiler. Branches and loops lower to a for (;;) switch (__pc) dispatcher over the bytecode offsets, so a lifted function keeps its control flow; functions with jump tables, generators, try/catch, for-in or constant-pool jump offsets keep their jumps as comments and are not complete. It does not rebuild the original source: functions are named function_<index> in serialization order, and loops are not restructured into for or while.

Deno

disrobe auto recognizes the data section deno compile embeds in the executable and extracts each module as its own output file. The section is found by its d3n0l4nd markers and a complete structural parse, not by the host executable format; only Windows x64 executables have been checked. Two section layouts are parsed:

• Deno 2.x module store, checked against Deno 2.9.7 output. Local files come out of the embedded virtual file system at their paths relative to the program root, with the source bytes Deno stored, which for TypeScript is the original TypeScript. Remote modules, such as https: imports cached at compile time, come out at a path built from the specifier without its scheme; only synthetic payloads cover them. For the checked program the output matches the authored sources byte for byte.
• Deno 1.x section, a 40-byte d3n0l4nd header followed by an eszip, checked against Deno 1.46.3 output. Modules come out as the eszip stores them: JavaScript and JSON verbatim, TypeScript as Deno's transpiled JavaScript with its source map written beside it as <module>.map. The map's sourcesContent carries the original TypeScript.

A bare eszip file (versions ESZIP_V2, ESZIP2.1, ESZIP2.2 and ESZIP2.3) is extracted the same way; a real archive has been checked only for ESZIP2.2 from Deno 1.46.3. SHA-256 checksums are verified when the archive carries them, and a module whose checksum does not match is dropped.

Limits

• Deno 2.x payloads also hold the transpiled JavaScript and source map of each TypeScript module; auto writes only the original source. Symlinks in the embedded file system are parsed but not written.

• Deno 1.x executables that bundle npm packages keep those packages in a separate directory after the eszip. auto does not extract it and records a refusal saying so.

• Only Deno 1.46.3 and 2.9.7 output has been checked. Other releases, including earlier 1.x releases that wrote a different section layout, are recognized only if their section matches one of the two layouts; a section that differs fails to parse and the input is not reported as a Deno executable.

• .jsc internalized identifiers (most variable and property names, for example console and log) are serialized as references into V8's read-only snapshot heap, not as inline bytes in the .jsc. Resolving them needs the exact V8 binary's RO heap. disrobe reports that as a lossy-internalized-roots boundary and does not decode past it.

• TypeScript async recovery assumes the global Promise is the built-in one when the module runs. A module that visibly rebinds Promise is left compiled; a replacement installed by another script (for example zone.js) is outside a single-file check. State-machine shapes the rule cannot prove equivalent, such as terser's conditional instruction returns, also stay compiled.

• For V8 snapshots disrobe reports a SnapshotDeserializeWall: the format prevents full bytecode recovery, so it scrapes the string pool (tunable via --scrape-min) and states the boundary; it does not decode past it.

Webview desktop frontends

disrobe webview statically recovers the frontend files embedded in Electron, Tauri, and Wails desktop applications. It writes HTML, JavaScript, CSS, source maps, fonts, images, WebAssembly modules, and other asset bytes under an output directory without starting the application.

disrobe webview desktop.exe --out frontend/
disrobe --json webview desktop.exe --out frontend/ > webview.json

The text result names the detected family and each recovered path, byte size, and compression method. JSON output uses the disrobe.webview.carve/v1 schema and includes the input path, family, output directory, asset count, externally unpacked paths, and per-asset records.

Supported layouts

The embedded-map decoder handles uncompressed entries plus Brotli, zstd, and gzip. Mixed encodings are decoded per entry. It bounds the number of scan candidates, table probes, paths, recursion depth, output bytes, and compression expansion before allocating or writing output.

Recovered paths pass through the same path sanitizer used by the container layer. A single leading / on a non-empty key is treated as bundle-root-relative. Traversal components, UNC paths, drive prefixes, and other escaping names fail instead of writing outside --out.

Automatic recovery and packages

disrobe auto detects supported webview layouts and writes their frontend assets under extracted/. Electron and Tauri use webview.carve; JavaScript and WebAssembly children can continue through their respective analysis passes. With Go support enabled, Wails uses go.classify, retaining both Go analysis metadata and the frontend under extracted/embed/frontend/dist/.

disrobe auto desktop.exe --out recovered/

webview accepts one file. If the application image is still inside an archive, installer, disk image, or application bundle, extract that container first and pass the recovered executable to webview:

disrobe extract desktop-package.bin --out package/
disrobe webview package/path/to/application.exe --out frontend/

The standard CLI enables this route through its chain feature. disrobe passes lists the routes included in a custom build.

Evidence and limits

Committed Tauri v1, Tauri v2, and Wails v2 builds are compared against their complete source asset trees in crates/disrobe-pass-webview/tests/real_toolchain.rs and crates/disrobe-cli/tests/cli_webview_carve.rs. These tests compare the full path set and every file's bytes through the library and automatic CLI routes. Electron CLI tests cover direct extraction and automatic recovery with one and four workers. The electron_oracle test also compares extraction with the real @electron/asar CLI.

The graded host-format matrix covers PE32+, 32-bit and 64-bit ELF in both byte orders, thin Mach-O, and universal Mach-O. PE32 remains declared but unobserved; the shared 32-bit read path is graded on ELF32 in both byte orders. Real committed desktop builds cover the current Tauri and Wails layouts; constructed fixtures exercise the wider host and compression matrix.

Static recovery cannot return assets that a development build reads from disk or a server at run time because those bytes are absent from the executable. Wails v3 remains ungraded while it is prerelease. Tauri resource-section storage is also ungraded because the tested released toolchains emit record arrays instead. These cases are not included in the byte-identity claim.

WebAssembly

disrobe parses WebAssembly modules, lifts them to four target surfaces, reverses Wasm-specific obfuscators, and decodes the Component Model and GC type graphs.

At a glance

Commands

disrobe wasm decompile module.wasm --target rust --out lifted.rs
disrobe wasm decompile module.wasm --target ts   --out lifted.ts
disrobe wasm decompile module.wasm --target wat  --out lifted.wat
disrobe wasm decompile module.wasm --target c    --out lifted.c
disrobe wasm decompile module.wasm --target json --out summary.json
disrobe wasm deob module.wasm --out clean.wat --emit-wasm clean.wasm
disrobe wasm component module.wasm        # parse the Component Model envelope -> world / adapter manifest
disrobe wasm types module.wasm            # recover the GC type graph (struct / array / ref types)

decompile lifts to Rust, TypeScript, WAT, or C pseudo-source, or a JSON summary.

deob writes the recovered module as WAT to --out. Add --emit-wasm to write the recovered binary as well. Two JSON files land beside the WAT with its extension replaced, so --out clean.wat produces clean.summary.json and clean.recovery.json. The recovery report holds the per-transformation counts, including the unflattening counts described below.

Coverage and fidelity

The committed corpus contains 40 .wat files. wasm-tools 1.250.0 parses 38 of them into 133 functions containing 1034 instructions. Disrobe lowers all 1034 instructions across all 133 functions, with no instruction-inventory disagreements. Coverage includes the MVP instruction set and the SIMD, atomics, bulk-memory, table/element, reference, and tail-call proposals.

The per-function reference inventory is stored in tests/golden/external_wasm_op_inventory.json, keyed by each fixture's BLAKE3. Instructions count as covered only when their function's recovered WAT reassembles; failed output remains in the denominator. Both tools reject the remaining 2 files, whose reference error text is also pinned.

This coverage measure records successful lowering and reassembly, with an external denominator and a self-reported numerator. The execution comparison below grades behavior separately. Regenerate the reference inventory with:

cargo test -p disrobe-pass-wasm-deob --test external_op_denominator -- --ignored regenerate_external_inventory

Regeneration requires wasm-tools 1.250.0. Routine coverage checks use the committed inventory.

All 57 of the 57 execution-eligible functions match the original under Wasmtime over the test's input battery. Eligibility requires a numeric or nullable-reference ABI that can be isolated per function or exercised within a faithful whole module. The semantic_differential test compares return values and trap parity; the first 4096 bytes of linear memory also match in all 6 memory cases.

Both sides run with the same limits: 2 MiB per linear memory or GC heap, at most eight linear memories and eight tables, and 1,024 elements per table. Each call receives two million fuel units; an epoch watchdog bounds the comparison. Imported functions trap instead of calling the host.

wasm deob runs three family passes before the generic folds. It strips Jscrambler-WASM integrity imports, rewrites Wobfuscator's imported arithmetic operators (op_add, op_xor and the like) back into instructions and drops an import only when nothing else references it, and inlines Wasmixer's fragmented functions. It does not recover Wobfuscator's eval op-table and does not unwrap the Wasmixer XOR decrypt stub: rewriting encrypted data would make the stub decrypt it a second time at run time. Tigress-via-Emscripten is detected from its Emscripten-marked exports, but wasm deob does not run its separate dispatcher-unflattening or _Z name helper.

The generic folds keep the module's behaviour. A branch folds only when its condition is a constant expression, or a call into functions that read no mutable global and no memory and do not trap. A call_indirect becomes a direct call only when the table slot is an immediate constant, the table is neither exported, imported nor written at run time, and the target's type matches the call's type. The recovered module is validated before it is written; a module that fails validation is reported as DR-WASMDEOB-0006 instead.

Control-flow unflattening

wasm deob rebuilds control-flow-flattened dispatchers as structured control flow. It recognizes a function that writes a constant start state, enters a loop, selects a case with a br_table on that state, and branches back to the loop head. Each case ends by writing the next state as a constant. The rewriter reads any module, not only one that matches a detected obfuscator family, and it is separate from the Tigress-via-Emscripten helper named above.

The dispatch state can live in three places. A local holds it, read straight into the br_table or copied into a temporary at the loop head. A mutable global holds it, on the condition that the module does not export it and no other function reads or writes it. A linear-memory slot holds it, read at the loop head by a non-atomic i32.load at a fixed offset from a base local and written back by a non-atomic i32.store to the same memory and offset.

Two routes rewrite a recognized dispatcher. The first route applies when the state lives in a local and every case names one successor. It replays the case bodies in execution order, and wraps a repeating tail in a loop. The second route rebuilds the state graph as nested if/else and loop blocks. It takes each case that chooses between two successors, and it takes every dispatcher whose state lives in a global or a memory slot. Both routes remove the br_table from the rewritten function and stop the state cell from carrying dispatch state. flattened_functions_restructured counts a function either route rewrote. flattened_conditional_restructured counts the second route.

The rewrite is graded by execution. For each fixture pair, tests/cff_conditional_reloop.rs first confirms that the flattened module agrees with a separately written module that computes the same function without a dispatcher, over a fixed argument battery under wasmtime. It then requires the rewritten module to agree with that same reference on return value and trap for every argument in the battery. A mutant fixture that swaps the two successors of one conditional transition must disagree with the reference, so a wrong edge cannot pass the battery.

disrobe refuses a dispatcher whose shape it cannot resolve. A refused dispatcher stays as it is, the module still validates and behaves as before, and flattened_dispatchers_walled records it. Set DISROBE_DEBUG=wasm-deob to read the reason on stderr:

• state cell is observable outside the dispatcher. The state global is exported or imported, another function reads or writes it, or code after the dispatch loop reads the state cell. A module that carries a function with more nested instruction sequences than the scan bound reports this same reason for every global-state dispatcher in it, because the scan then treats no global as private.
• state transition is not a resolvable constant edge. A case does not end in a constant state write, hides that write behind a branch, or reads the state cell in its own work or condition.
• state graph has no sound structured form. The state graph has no equivalent shape built from if/else and loop. A cycle entered at two different states or a state the entry cannot reach can land here.

An ordinary compiler can emit a shape outside the supported set. rustc 1.96.1 targeting wasm32-unknown-unknown at -C opt-level=0 lowers a hand-written match over a state variable into a next-state temporary. The rewriter admits the recorded dispatcher when it can resolve that temporary's constant edges; its mutation controls remain walled when those edges change. The committed tests/fixtures/cff_rustc_temp_state.obf.wasm and its Rust source record that case, and the rewritten output validates and behaves the same as the input under wasmtime.

disrobe auto reaches the same rewriter through the wasm chain pass. That pass writes wasm.recovered.wasm and the real counts in wasm.recovery.json when a transformation changed the module. A module whose only finding is a refused dispatcher changes nothing, so its wasm.recovery.json carries zeros. Read a refusal from wasm deob or from DISROBE_DEBUG=wasm-deob, not from the chain sidecar.

Limits

• Two corpus modules are skipped on wat-parse or signature-extraction failure, so the op-coverage figure covers the supported subset, not all of wasm.
• Functions outside the execution-eligible set are op-coverage-only; their behavior is not compared against the original.
• The Component Model envelope, memory64, and the GC type graph are parsed and decoded by dedicated scanners. Their per-instruction semantics are not all lifted to source. Threads are different: all 67 threads-proposal atomic operators lift to C, Rust, and TypeScript, and the runtime tests grade shared-memory contention, wait and notify, fence, and memory growth under a wall-clock deadline.
• Tigress-via-Emscripten is detected and classified only. Its standalone dispatcher-unflattening and name helpers are not on the wasm deob run path.
• wasm-name-obfuscator destroys the original debug names. The library's strip_obfuscated_names helper removes recognized generated name sections and preserves other custom sections; it cannot restore those names. Its real-output grader compares all 30 pinned outputs with clean wasm-tools references. The helper is separate from the wasm deob pipeline, which detects and classifies this family.
• Control-flow unflattening runs only while the module stays under the intra-function folding budget. Above that budget the recovery report sets intra_function_folding_skipped and no dispatcher is rewritten.
• A state cell read with an atomic i32 load is not recognized, so wasm deob leaves that function as it stands.
• flattened_dispatchers_walled counts dispatchers the rewriter recognized and then refused. A shape it never recognized is not counted, and only the three reasons above are printed.

JVM and Android

disrobe decompiles JVM classfiles and Android DEX through a unified command, adding protector analysis, ProGuard/R8 mapping reports, and chain auto-detection, with headless wrappers for FOSS decompilers selected by the format's default routing or --backend.

At a glance

Commands

disrobe jvm decompile App.class --emit source --out src/          # write the in-house Java source
disrobe jvm decompile app.jar --backend vineflower --out src/
disrobe jvm dex2-jar classes.dex --out classes/  # in-house .class tree + classes.jar
disrobe jvm decompile classes.dex --backend dex2-jar --out external/  # installed d2j-dex2jar
disrobe jvm decompile app.apk --backend jadx --out src/
disrobe jvm decompile classes.dex --backend jadx --out src/
disrobe jvm decompile classes.dex --format ghidra --out recovered/
disrobe jvm decompile app.jar --mapping mapping.txt --out src/   # write name-restoration.json
disrobe jvm extract app.apk --out classes/    # extract a .jar / .apk + dump classfile inventory
disrobe jvm backends                          # report available JVM/Android backends on PATH
disrobe jvm jni app.apk                       # link native methods against the apk's own .so files
disrobe jvm jni App.class --native libnative.so --json
disrobe jvm jni module.aar                    # nested classes.jar against jni/<abi>/*.so
disrobe jvm jni base.apk --native split.apk    # cross-split link against an APK Set member
disrobe apk app.apk                           # also prints the JNI link table for the embedded dex/.so pair
disrobe auto app.apk --out recovered/         # recursively process recognized payloads
disrobe auto classes.dex --format json --out recovered/

Every format writes in-house source by default: Dalvik source for .dex and .apk, per-class source for .jar and .class. An external backend runs only when --backend names it: cfr, vineflower, procyon, jd or krakatau for class and jar files, jadx or dex2-jar for DEX and APK input. A named backend that is not installed, or that does not apply to the input format, fails with an error. disrobe validates the classfile itself (format 1.0.2-25) and recovers records, sealed types, and pattern matching where the selected backend supports them, plus Kotlin and Scala idioms.

disrobe jvm dex2-jar is the in-house DEX-to-class translator. It writes a deterministic class tree and classes.jar without an external executable. disrobe jvm decompile <dex> --backend dex2-jar is different: it invokes an installed d2j-dex2jar backend and keeps that backend's contract and output separate from the in-house translator.

The in-house translator carries InnerClasses, EnclosingMethod, and generic Signature attributes from DEX system annotations. The Dalvik renderer uses ownership metadata to group nested classes; a $ in a name alone does not establish nesting. Invalid annotation metadata is reported without rejecting an otherwise parseable DEX.

For a standalone DEX, jvm decompile --format ghidra|ida|json writes descriptor-keyed class, method, and field entries beside the normal output. auto accepts the same formats when the original input itself reaches a successful jvm.classify node and writes the sidecar under exports/dalvik/. It does not reuse a DEX extracted from an APK or another container. Each entry keeps the original owner, original member name, descriptor, and replacement as separate values. When the current recovery path has not changed a name, the original and replacement stay identical. The Ghidra and IDAPython scripts resolve the original logical identity in the loaded DEX database before renaming the database object; they do not assign virtual addresses to Dalvik identifiers. IDAPython class renames require IDA 9.4 or later because that release introduced the loader's persistent DEX type-rename store. Method and field renames use the older DEX record APIs.

Coverage and fidelity

Classfile

The in-house classfile decompiler is gated against real javac: on the EdgeCases corpus, the asserted floor is 131 of 131 decompiled methods (100%) recompiling error-free on JDK 25. Its emitted source carries enum types with their constant bodies, declaration and member annotations, enhanced-for loops over arrays and iterables, and multi-catch clauses, each recompile-checked on the same corpus (foreach_multicatch_recovery.rs). CI provisions a JDK so this gate runs there.

Dalvik

The Dalvik lifter's recovered bodies are graded by the real JVM bytecode verifier rather than by the lifter's own output: a committed gate assembles the recovered classes from the committed dex corpus, loads them under -Xverify:all, and asserts that the recovered classes pass the verifier; 100% of verifier-presented classes pass (118 of 118, 0 lifter verify failures; the other 37 of 155 classes are link-skipped because they reference supertypes the harness does not bundle, Kotlin's Function1 among them, which is a test-harness limit and not a lifter defect). A live-range-splitting pass recovers method bodies whose registers carry conflicting JVM types across control-flow joins; 317 re-hosted bodies verify clean under the same gate. The committed-corpus verifier floor and the EdgeCases recompile floor are asserted by committed test gates.

The in-house Dalvik decompiler, the default for disrobe jvm decompile on .dex and .apk, is graded on the same corpus against the real EdgeCases.java source rather than its own output. A value computed in one basic block and consumed in another (an array length, or a wide argument to a call such as Math.abs or charAt) is materialized into a local at its real use site instead of being dropped across the block boundary, so all eight leaf methods reconstruct their call sites with full fidelity while every method's signature, control flow, and operators recover (dalvik_decompile_oracle.rs).

The same source path reverses core-library desugaring emitted by D8 9.1.31 with desugar_jdk_libs_configuration 2.1.5. It restores marker-confirmed public API types in the j$/time, j$/util, and j$/nio namespaces, receiver-first $-EL calls, $-CC interface static calls, and exact supported Desugar* retarget helpers. The committed minimum-API-21 DEX covers time, streams, functions, Optional, concurrent, and NIO APIs. A minimum-API-34 DEX built from the same Java source provides the original call-shape reference. The test recompiles every recovered compilation unit with Java 11, then executes every recovered API probe method through an independent harness. Unknown configuration identifiers, application-owned j$/ classes, wrapper conversions, API flips, unknown helpers, and malformed receiver shapes remain unreversed instead of being renamed by prefix.

Containers

auto opens four container formats and passes their members to the class and DEX passes. An ODEX yields its embedded classes.dex. An OAT file yields its single DEX, found through the oatdata symbol and the OAT header; when the DEX lives in a separate .vdex, which is the usual layout on current ART, the OAT file yields only its manifest and a refusal, because VDEX is not read. A .jmod yields every entry at its archive path, and a jimage (lib/modules) yields every stored resource as module/parent/name; compressed jimage resources are refused rather than emitted, because no jimage decompressor is implemented. Each container also writes jvm-container.json. The jmod reader shares the zip limits (65,536 entries, 256 MiB per entry, 1 GiB in total) and the jimage reader enforces the same totals. tests/jvm_container_chain.rs grades a committed jmod against jmod extract and the grading JDK's own lib/modules against jimage extract, byte for byte.

Obfuscator analysis and recovery

For JVM classfiles, disrobe peels supported protector string patterns before in-house source emission. On Dalvik, it lifts a DexGuard-style flattened method from the rewired control-flow graph when every dispatcher edge resolves to a constant successor and the state register is read only by its dispatcher; otherwise the method keeps a note naming why it was not rewired. BlackObfuscator dispatchers are analyzed. --mapping parses ProGuard/R8 mappings and writes recovered class and member names to name-restoration.json; it does not rewrite emitted Java source. disrobe registers detection and routing for 10 obfuscator and protector families: ProGuard/R8, Zelix KlassMaster, Allatori, Stringer, DashO, DexGuard, BlackObfuscator, yGuard, SkidSuite2, and JBCO (the last three detect-only, identified by marker strings and, for JBCO, its jsr/ret control flow).

On the Android side it also applies eight runtime application self-protection (RASP) fingerprint rules: Promon SHIELD, Guardsquare DexGuard RASP and ThreatCast, Appdome, OneSpan, Arxan/Digital.ai, Zimperium zShield, and Licel DexProtector. For APK signatures, disrobe inventories v1 signing material, verifies v2, v3, and v3.1 content digests, and parses v4 .idsig files to match their APK digest to a computed v2 or v3 content digest.

String-encryption protectors are decrypted by emulating each class's decrypt method on the encrypted constants rather than by guessing a key, so Allatori and DashO style decrypt(String) and decrypt(int, String) routines are recovered statically. The evaluator runs <clinit> for a per-class static key, constructs the receiver and runs <init> for an instance decrypt keyed on a field, synthesizes the calling frame for a caller/stack-trace-keyed key, and covers the long-accumulator arithmetic, getfield/putfield, and switch-dispatched keystreams these routines emit, all under a hard step cap. With disrobe jvm decompile --mapping mapping.txt, ProGuard and R8 names are written to name-restoration.json, with overloaded methods disambiguated by descriptor argument count; emitted Java identifiers are unchanged.

On the Android side, the BlackObfuscator analyzer recognizes the String.hashCode() keyed dispatcher, matches each block's const-string block-name to its switch case, and reports the recovered linear block order in the decompiled output. The method body remains rendered from the flattened graph; the annotation records the recovered order rather than replacing that body. Separately, obfuscator-planted out-of-range exception-table entries are dropped before classfile structuring so they cannot poison the control-flow graph, and jsr/ret subroutines are inlined into a linear stream.

DexGuard hides string constants in an encrypted static String[] decrypted at run time through java.lang.reflect.Method.invoke rather than a direct call. The key and ciphertext are present in the dex; only the dispatch is reflective. disrobe runs a constrained Dalvik register machine over the dex's own routine: it executes the class <clinit> to rebuild the encrypted table, then runs the decrypt(int) body for each index (read the table element, apply the per-char transform against the embedded key, rebuild the string) and emits the plaintext, with the Class.getDeclaredMethod + Method.invoke call sites resolved to their concrete target. disrobe jvm decompile app.dex surfaces the recovered strings and resolved sites in the manifest.

JNI linking

disrobe jvm jni and disrobe apk link each declared native method to its C implementation across the DEX or classfile to native library boundary. Static binding computes the short and the long JNI symbol from the class name, method name, and descriptor, escaping _, ;, [, $, and non-ASCII characters as the JNI specification requires, and matches both against the library's exported symbols. A JNINativeMethod array that the compiler placed in the library's read-only data is recovered from the file: the tool walks candidate name, signature, and fnPtr triples, applies the ELF dynamic relocations to their pointer fields, and resolves each function address to its symbol. It reads the table, not the RegisterNatives call, so the recovery does not depend on how the call reaches the JNIEnv function table, and it finds no table that the program assembles in memory at run time. The output is the typed link table plus a JNIEXPORT ... JNICALL C prototype per native method.

An APK whose zip carries both the DEX and the native library links them without the caller naming either side; --native supplies the library for a bare .class, .jar, or .dex input. An AAR unzips its nested classes.jar and scans jni/<abi>/*.so, the AAR layout, rather than an APK's lib/<abi>/. An APK Set (.apks), or a base APK plus split APKs passed with --native, merges every split's DEX and native libraries into one input set, so a native method declared in the base DEX can resolve against a symbol that exists only in a config split. A raw .oat file locates its single embedded DEX through the OAT header's oat_dex_files_offset; a multi-dex .oat is refused, because the per-entry record stride changes between ART releases and is not documented. disrobe auto performs the same link and writes jni-link.json when both sides are in one container.

A native method with no matching symbol in any library is reported unresolved rather than dropped, and dynamic_only counts it. A symbol exported by more than one library is reported ambiguous rather than bound to the first. Each resolving library's ABI directory name is carried on its entry, so a multi-ABI APK states which .so a symbol came from.

The tests below run in cargo xtask prepush when disrobe-pass-jvm or disrobe-cli changes, and in the weekly scheduled CI run on Linux, macOS, and Windows; no JNI test runs on every push. "Real" means the input came from a real compiler or tool; "synthetic" means the test built the bytes itself.

Not graded by any test: AAB input, a Windows .dll or macOS .dylib passed with --native, the JNI table that disrobe apk prints, ambiguous symbols, a real dex2oat .oat, and an NDK-built library or the NDK's jni.h.

Only two things are absent from the static artifact and therefore unrecoverable: a fnPtr computed at runtime rather than stored as a relocatable pointer, and a FindClass target name built dynamically rather than passed as a string literal. The native function body at a recovered address is not this surface's job; it goes to the native pseudo-C decompiler.

Limits

Disrobe reports lowering 83662 / 83943 methods with code items across three SHA-256-pinned FOSS APKs, or 99.7%. This counts emitted bodies. The APKs contain 89,516 declared methods, including 5,573 abstract, native, and interface-instance declarations without bodies.

The JVM check selects non-stub methods by a deterministic hash of each method name and re-hosts their bodies in isolated carriers. Of the bodies presented, 2988 of 2998 pass -Xverify:all without being invoked. Another 5,421 sampled bodies are ungraded: 1,407 constructors, 1,730 invokespecial receivers, 2,141 unresolved dependencies, and 143 other exclusions. The recovery chart's data records the full candidate and sample populations.

The two measureContentWidth bodies excluded by the sampling rules are ungraded and do not contribute to the accepted count. Verdicts are pinned by method name under crates/disrobe-pass-jvm/tests/golden/dalvik_body_attest/. These measurements use local APKs; CI checks the published counts and the separate committed-DEX corpus.

• Runtime-keyed string schemes (system property, environment, clock, secure random, or a live cross-class table, as Stringer sometimes uses) are flagged as walled instead of faked.
• A DexGuard routine that derives its key from runtime-only state (a system property, the environment, the clock, or a secure random) is reported as runtime-keyed rather than guessed.
• DexGuard-style reflection-string recovery is validated against a benign sample implementing that technique, not output produced by the commercial DexGuard tool. The sample is a hand-written .java compiled by real javac and dexed by real d8; the plaintext reference is the stdout of the same program run under a real JVM.
• yGuard, SkidSuite2, and JBCO are detect-only on the protector-specific recovery path. The JBCO real-output grader covers five pinned Soot 4.7.1 outputs: ordinary classfile recovery recompiles Sample.names.jar to identical behaviour, while four outputs remain named partials. Four other runner invocations failed in the tool and produced no fixtures.

.NET / CIL

disrobe parses .NET PE and CLR metadata, decompiles CIL to C#, F#, and VB pseudo-source, registers detection and routing for 23 protector families, and probes ReadyToRun and Native AOT images.

At a glance

Other registered families produce reports identifying the protector and the static recovery available for that input. Bodies that require an unavailable runtime key remain encrypted.

Commands

disrobe dotnet decompile App.dll --backend ilspy --out src/
disrobe dotnet decompile App.exe --backend dnspy-ex --out src/
disrobe dotnet decompile App.single-file.exe --out recovered/
disrobe dotnet decompile App.dll --backend de4dot --out src/
disrobe dotnet analyze App.dll
disrobe dotnet native-aot App.native.exe --out aot.json
disrobe dotnet backends                  # report available .NET backends on PATH
disrobe auto App.exe --out recovered/     # static protector peel + in-house CIL-to-C#

decompile always runs the in-house CIL renderer. --backend ilspy|dnspy|dnspy-ex|de4dot also runs that external decompiler; a named backend that is not installed fails with an error. disrobe auto stays on the registered in-house pass and does not launch those backends. analyze reports the PE and CLR summary, protector detection, and whether ReadyToRun (R2R) or Native AOT is detected. Use dotnet native-aot for the detailed AOT report and recovered method bodies.

Coverage and fidelity

Single-file bundles

A .NET single-file deployment packs application files into a host executable. A self-contained deployment can also carry native runtime components. The bundle reader (disrobe_binfmt::containers::dotnet_bundle) finds the bundle marker inside a PE, ELF or Mach-O host, reads the manifest, and returns each embedded member under its sanitized relative path. It inflates a deflate-compressed member and returns a stored member as it lies. Members are managed assemblies, native libraries, deps.json, runtimeconfig.json and symbol files. The reader also parses deps.json into a typed manifest rather than only carving it, so the runtime assembly list and the library table are readable as data.

disrobe extract writes the members to disk, and disrobe auto routes them onward with no dedicated flag: an embedded managed assembly reaches the CIL pass on its own. disrobe dotnet decompile accepts the same bundle as a direct input. It stages all recovered output beside the destination and publishes the directory only after extraction and every managed assembly decompilation succeed. members/ holds every embedded file. assemblies/<relative-path>/ holds the normal manifest and pseudo-source for each managed assembly. bundle.manifest.json records the bundle version, bundle ID, quota accounting, and managed assembly list. The command refuses a non-empty destination and refuses more than 512 managed assemblies before invoking any rendering backend.

The format defines exactly three manifest major versions, and the reader accepts those three and refuses any other by number. Major 1 is what .NET Core 3.x wrote, major 2 is .NET 5, and major 6 is .NET 6 and later. Major 1 has no deps or runtimeconfig block and records every entry as type Unknown. Compression exists only from major 6.

Coverage is graded against bundles the real .NET tooling produced, in corpus/binfmt/dotnet-single-file. Each extracted assembly is compared byte for byte with the assembly the compiler emitted before bundling. The committed set spans all three major versions, PE, ELF and Mach-O hosts, every one of the six entry types, and a bundle that mixes compressed and stored entries. A declared member size that runs past the buffer, a path that escapes the output directory, a duplicate path and a decompression bomb are each refused.

A universal (fat) Mach-O host is not supported. Its header-offset field is relative to the slice rather than to the file, so the reader sees an implausible version and refuses the file instead of reading the wrong offset.

Native AOT images

The AOT report recovers metadata names, type and method attribution, method boundaries, and pseudo-C bodies. That coverage is measured on x86_64 PE executables published by the .NET Native AOT toolchain. The ELF and Mach-O fixtures are hand-assembled: each is a small assembly source linked by ld.lld or ld64.lld into an image that holds a ReadyToRun header and two metadata names. On those two formats the tests grade header location, layout-profile selection, and name recovery only; no ELF or Mach-O image built by the .NET toolchain is committed, and type, method, and body recovery on them is unmeasured. The parser reads layout metadata from the image; recovery on aarch64, arm, and x86 remains outside the measured population.

Obfuscator reversal

disrobe registers detection rules for 23 protector families. Recovery depth varies by protector and by what is statically present in the artifact. The per-family evidence below states what artifact is graded, what data is recovered, and where static recovery stops.

Detection and string decryption are separate claims, and the evidence behind the second one differs by family. String decryption evidence below states which families are graded on an assembly the protector itself produced and which are graded on a fixture we build to the published algorithm.

Reversed on a real committed sample (plaintext recovered from the artifact, plaintext-absent oracle):

• ConfuserEx2: in-house recovery reverses the constants protection (the documented FOSS "Ki.Constants" block-XOR / LZMA-validated algorithm) on a real committed SampleConstants.confuserex2.dll, with a test whose fixture holds only ciphertext plus the real decryptor and asserts plaintext not present anywhere in it. The encrypted-resource layer is carved byte-exact but walled on the runtime key. Control-flow flattening is deflattened in-house: disrobe rebuilds the original control-flow graph from the while(true)/switch dispatcher and recovers the switch-key encoding. The deflattening evidence comes from two protector lines and differs in strength:

  • ConfuserEx 1.x (yck1509/ConfuserEx, ctrl flow protection): on the NormalPredicate sample all 6 flattened methods recover the clean build's control-flow graph with every opcode and operand in place; on the x86Predicate sample (the native decoder stub emulated through the in-house x86 interpreter) and the ExpressionPredicate sample (the inverse expression folded symbolically) all 8 methods each recover the clean control-flow graph.
  • ConfuserEx2 1.6.0: in the gauntlet sample the flattened Process method deflattens with no unresolved block, 11 of its 12 block signatures match the clean build, and every call-result pop survives. In HelloAppLegacy.confuserex2.dll every flattened method (the static constructor and the injected constant decoder) deflattens with no unresolved block and no edge to a missing block; that check has no clean baseline to compare against.

  For de4dot's runtime-VM string and anti-tamper handling, confirm de4dot is available with disrobe dotnet backends, then use disrobe dotnet decompile App.exe --backend de4dot. disrobe auto does not invoke that external backend.

In-assembly-decryptor recovery, graded by round-trip against the pre-encryption original. This list is grouped by how recovery works, not by who produced the sample, so a family in it also appears in String decryption evidence below: the round-trip proves the decoder inverts the encryption, and the table below states whether the encrypted input came from the protector's own tool or from a fixture built to its published algorithm.

• Eazfuscator.NET: locates a static char[]/byte[] string-decryptor method and emulates its CIL over the encrypted #US literal table to recover the plaintext strings. The graded decryptor is a generic single-key XOR loop inside a synthetic PE that the test assembles itself; neither Eazfuscator.NET's own string algorithm nor its output is part of that grade, which is why the family also sits in the modelled row below. The VM tier is devirtualized against an in-repo EazVM virtualizer of our own: the committed assembly is encoded by that virtualizer, not the shipping Eazfuscator.NET product. disrobe reads the embedded resource, recovers the per-build opcode map from the in-assembly dispatch table by fingerprinting each handler, decrypts the position-keyed instruction stream, and lifts every virtualized method body back to CIL. It then applies width-checked MBA simplification to supported straight-line int32 expressions before grading the result against the clean DLL. The ordered instruction comparison resolves branch targets to instruction indexes, and 67 of 67 instructions match in sequence across six bodies (100%). A second gate evaluates the recovered bodies in the product's bounded CIL emulator with the arguments Main passes and requires the six values the clean assembly prints. It also checks both sides of every recovered branch against the C# source, and a mutation of each branch must change a result. No assembly runs. For the committed seeded build, the randomized opcode map is recovered from the assembly rather than read from its sidecar.
• KoiVM (ConfuserEx VM): detects the #Koi stream and VMDispatcher markers, identifies dispatch handlers, decodes each method's instruction stream, and lifts all six virtualized bodies to CIL. The committed fixture was produced by the TheProxyRE KoiVM fork through its public Virtualizer API over a benign test program. Recovery is compared with the separately compiled KoiSample.clean.exe and manually derived operations: Add and Square recover fully, and aggregate structural recovery has a 75% CI floor. The unobfuscated control produces no KoiVM summary.
• SmartAssembly (embedded assemblies): the mode-1 chunked raw-DEFLATE resource that carries a merged or embedded dependent assembly is decompressed back to the original assembly bytes, graded byte-for-byte against a committed Roslyn-built fixture. The sample recovers 1 / 1 embedded resource. The payload inside it is a real assembly; the mode-1 framing around it is built to the published algorithm, not taken from a SmartAssembly build. Non-mode-1 carriers are marked Unknown and malformed mode-1 is Rejected; neither produces a decoded value. String encryption is a separate axis (below).
• .NET Reactor (encrypted-resource strings): the AES key and IV are read from the reachable encrypted-string resource and the string table is decrypted back to the original literals, graded against the runtime-validated originals of committed Roslyn-built fixtures carrying the .NET Reactor v4 static-string resource shape (astral-plane, embedded-nul, empty, and CJK strings all round-trip). No assembly produced by .NET Reactor is committed. An ambiguous or disconnected decoy key/IV tuple is Rejected as report-only, never guessed.
• ILProtector / MaxToCode: classified on in-repo structural fixtures by Invoke-stub and zero-RVA method enumeration, runtime-resource and .mtc/.text1 section location, and container-framing parse. For native-keyed configurations, the managed assembly does not carry the per-method key used by the runtime loader, so the encrypted bodies remain report-only.
• Obfuscar: dedicated in-house peeler (NameMaker odometer classification plus HideStrings recovery: the hidden ldstr literals are read back to their original bytes from the in-assembly FieldRVA carrier through the generated accessor, 15 / 15 on the gauntlet sample).

Babel, Dotfuscator (Pro), Goliath, DeepSea, and Agile.NET have detection and classification support. Babel reports the string-recovery prerequisite: a matching protected/plain sample or a verified decoder chain. The other paths report watermarks, identifier characteristics, and encrypted-resource details. They can also use the generic static decoder for supported pure transforms.

String decryption evidence

Which families disrobe decrypts strings for, and what each claim is graded against:

The second row tests algorithm implementations against known plaintexts encrypted by repository fixtures. Product versions and per-build variants are outside that comparison; the corpus contains no redistributable product-produced sample for those families. The Eazfuscator.NET entry is weaker than the others in that row: its graded decoder is a generic XOR decryptor on a synthetic fixture, not an implementation of the product's string algorithm.

crates/disrobe-pass-dotnet/src/protectors.rs carries this split as Protector::string_evidence, and the tables above are regenerated from it. cargo run -p xtask -- regen --check fails if a family claims a committed sample the tree does not carry, or claims one whose MANIFEST.toml does not record the tool that produced it, or sits in the modelled row without being published there.

Limits

Recovery stops at these boundaries:

• Themida / .NET wrapper: native VM bodies are outside the current recovery scope; disrobe does not ship a native-VM devirtualizer.
• ArmDot: detected and reported, but no static devirtualizer ships.
• ILProtector / MaxToCode native-keyed configurations: when the per-method key is computed inside the native stub, the original CIL is not statically present.
• Obfuscar renames: original identifiers require the separate Mapping.txt; the PE contains no name map.

Protector reports identify the missing key or handler stream when those bytes are unavailable in the artifact.

Native (PE / ELF / Mach-O / NE)

disrobe includes native decompilation for x86-64, AArch64, ARM32, and MIPS32, alongside symbol recovery, disassembly, identification, patching, fingerprinting, and diffing. It can export recovered information to Ghidra and IDA, and drive Ghidra headlessly. Architecture-specific output and limits are described in the decompile guide.

Two adjacent surfaces have their own pages: native decompile for the in-tree decompiler and the Ghidra backend, and native unpacking for packers, protectors, and bytecode-VM devirtualization.

At a glance

Commands

disrobe native symbols app.exe --out symbols.json            # symbols, sections, imports, debug info, RTTI

disrobe native disasm app.exe --out app.asm                   # recovered per-function listing
disrobe native disasm app.exe --emit cfg-dot --out cfg.dot    # per-function basic-block CFG
disrobe native disasm app.exe --emit json --out disasm.json   # structured instruction stream
disrobe native disasm --raw shellcode.bin --base 0x1000 --bits 64 --syntax intel   # linear sweep
disrobe native callgraph app.exe --out callgraph.dot          # whole-program call graph

disrobe native patch app.exe --at 0x1400 --bytes 0x90,0x90 --out patched.exe   # rewrite + revalidate
disrobe native patch app.exe --nop-range 0x1400:0x1410 --out patched.exe        # nop a span
disrobe native sigmaker app.exe --at 0x1400                                     # wildcarded signature
disrobe native diff old.exe new.exe                                             # match functions across builds

disrobe native identify app.exe --out identity.json           # compiler, packer, protector, signature verdict

disrobe query app.exe functions                         # discovered functions, complexity, exports
disrobe query app.exe calls-to malloc                   # call sites to a target
disrobe query app.exe xrefs-to sekret                   # references to a symbol
disrobe query app.exe string-decoders                   # decoder-shaped functions (loops + byte arith)
disrobe query app.exe complexity-over 20                # functions over a cyclomatic threshold
disrobe query app.exe capability network                # instructions tied to a capability
disrobe capabilities app.exe                            # MITRE ATT&CK + MBC behavior report

disrobe strings app.exe                                 # static strings + decoder-execution recovery

disrobe native entropy app.exe                           # ASCII heat-strip + byte histogram + packed-region runs
disrobe native entropy app.exe --format svg --svg map.svg # dark-theme SVG entropy map with section overlays
disrobe native entropy app.exe --format json --out e.json # the disrobe.native.entropy/v0 document
disrobe native signatures app.exe --out sigs.json        # AES T-tables, SHA/MD5 IV+K, ChaCha20 sigma
disrobe native signatures app.exe --flirt db.sig         # match against an IDA FLIRT database
disrobe native fingerprint app.exe                       # crypto + FLIRT + string-xref sidecar
disrobe native graph app.exe --out imports.dot           # import/export table as Graphviz DOT
disrobe native sbom app.exe --out app.cyclonedx.json     # CycloneDX 1.5 SBOM from cargo-auditable metadata

Coverage and fidelity

Symbol recovery and dumping

native symbols dumps symbols, sections, segments, imports, and debug info from PE, ELF, Mach-O, and 16-bit NE files. It demangles and restores Rust and C++ symbols across x86 / ARM / RISC-V / MIPS / PowerPC / SPARC / eBPF / AVR, reading DWARF, PDB, and STABS debug formats. For C++ binaries it recovers the class hierarchy from the in-memory RTTI and vtable layout: ABI, each class's inheritance kind, direct base classes (virtual flagged), virtual-method slot counts, and detected STL templates.

New Executable structure

The NE parser accepts the little-endian segmented container used by Windows 3.x and OS/2 1.x. It validates the 64-byte header, segment and resource ranges, entry bundles, resident and nonresident names, module references, imported names, relocation records, and non-additive relocation chains. It lowers segment-relative entry addresses, exports, and imported names into the same native model used by behavior, IOC, HTML-report, and native-symbol surfaces. The identify surface classifies both variants. The registered native.ne-structure pass gives detect and auto the validated structure. It does not claim 16-bit disassembly or decompilation.

NE names use an OEM code page rather than UTF-8. Printable ASCII bytes other than backslash render directly. Backslash and every other byte render as \xNN, which keeps the representation unambiguous without guessing a host code page or dropping malformed text.

Disassembly, call graph, and CFG

An in-tree iced-x86 disassembler discovers functions without symbols (call-target and prologue scanning), partitions each into basic blocks, builds the whole-program call graph, and renders the per-function listing or, with --emit cfg-dot, the basic-block CFG. --raw disassembles a flat code blob with no container, and --syntax intel|at&t|nasm|masm selects the dialect for raw output. Each decoded instruction carries its register, memory, and rflags read/write effects, and the native layer can re-encode and relocate instruction blocks (the engine behind native patch).

Patching, signatures, and binary diff

native patch rewrites bytes at a virtual address (or nops a VA span), maps the VA to a file offset, applies the edit, and revalidates the image. native sigmaker generates a wildcarded byte signature from the function at an address (immediates and displacements masked via the instruction decoder), then uniqueness-tests it across the image. native diff matches functions across two binaries by content, relocation-invariant, and control-flow-graph fingerprints and reports the added, removed, and changed functions. All three work on stripped input through the in-tree function discovery.

Queryable IR and capabilities

disrobe query runs a queryable-IR layer over the disassembled code (functions, calls-to, xrefs-to, string-decoders, complexity-over, capability), symbol-independent and driven by the same function discovery. disrobe capabilities runs a rule engine over that IR and reports matched behaviors mapped to MITRE ATT&CK techniques and Malware Behavior Catalog (MBC) IDs, with the matching instruction offsets as per-rule evidence. Both accept a stripped binary directly or a .dr envelope.

Emulation-driven string recovery

Beyond a static scan, disrobe strings locates decoder-shaped functions and drives each through the in-house x86 emulator, recovering the plaintext that only exists after the decoder runs. Emulation-recovered strings are deduplicated against the static set and reported with the decoder and buffer addresses, so a single-byte or multi-byte XOR/sub stack-string scheme yields the decoded text without executing the sample natively.

Identifying the compiler, packer, and protector

An in-house multi-signal signature engine fingerprints what built and protected a binary through self-consistency-based identification, then routes each finding to the disrobe pass that handles it. It detects compilers and toolchains (Go, Rust, MSVC, GCC, Clang, MinGW, Delphi, Nim, Zig, Crystal, Swift, GHC, .NET, Nuitka), packers (UPX, ASPack, PECompact, FSG, MEW, MPRESS, Petite, NSPack, kkrunchy), protectors (Themida, VMProtect, Enigma, Obsidium, Armadillo, ConfuserEx, .NET Reactor, Eazfuscator), installers (NSIS, Inno Setup, InstallShield, AutoIt, PyInstaller, Electron, Bun), linkers (MSVC link via the Rich header, GNU ld, LLD), and code-signing. Every hit carries a support route: a Go binary points at disrobe go recover, a packed PE at disrobe native unpack, a .NET assembly at disrobe dotnet decompile, an installer at disrobe auto.

Unpacking and byte-level recovery

disrobe native unpack is graded per section against a committed original rather than by whether the output merely parses. Three families ship one packed-and-original pair each, so their figures reproduce from a clean checkout:

.text and .data are byte-identical for all three, and NSPack's .rdata is byte-identical as well, so the decompressors themselves are exact and the residual is placement and fixups rather than lost payload. The content denominator is the original's own section span and is asserted by equality, so a recovery that emits fewer bytes scores worse instead of shrinking what it is measured against. The byte-identical sections are held as a membership list rather than a count, so a section that stops recovering exactly drops out of the list instead of being masked by another section improving. Two spans are reported and they are not interchangeable: the per-section total above counts .rsrc, while an older whole-image gate measures NSPack over .text, .rdata and .data only and reads 99.36% for the same fixture. Relocations are classified as loader-rebuilt and scored separately, because the OS resolves them at load time.

The residuals have specific causes worth knowing when reading a recovered image. FSG's .rdata gap is the import descriptor region: the stub's block-destination table names one aPLib stream per original section, all four are decoded, and the descriptor block is decoded then deliberately withheld from the recovered image because the stub writes it over original .rdata content at run time. NSPack's .rdata reaches byte identity instead, because its import lookup and address tables are rebuilt from the module record the stub carries rather than left for the loader to resolve. The .rsrc gap is shared across families, at 1552 / 4672 for FSG and 2333 / 4672 for NSPack, and it narrowed once the original resource-directory tree is placed at its own RVA rather than wherever the decompressed image left it; what remains is the part each stub reconstructs at run time. Larger uncommitted vendor samples score lower on the whole-image measure for the same two reasons, and no figure is published for them because those samples are not committed and nothing pins them. kkrunchy and kkrunchy classic recover their payload byte-exactly against committed fixtures.

An absent fixture is never a silent pass. A missing committed fixture always fails the test and names its path. A missing uncommitted vendor sample fails the same way unless tests/optional.toml lists the local packer samples, which it does because CI never has them; the run then writes a not-measured record naming the absent file. A fixture that is present but unreadable is a hard failure in every mode, because that is how a quarantined or truncated sample would otherwise stop grading unnoticed (committed_packer_byte_recovery.rs, fsg_unpack.rs, nspack_byte_recovery.rs, petite_unpack.rs, kkrunchy_unpack.rs).

Authenticode verification

For a signed PE, identify verifies the Authenticode signature rather than only noting its presence. It recomputes the SHA-1/256/384/512 digest over the Authenticode hash range (the file minus the checksum field, the certificate-table directory entry, and the certificate table itself) and compares it to the digest the signature claims. It walks the PKCS#7/CMS signer chain (RSA PKCS#1 v1.5 and ECDSA P-256/P-384) up to an embedded bundle of eight trusted code-signing roots, and requires the code-signing extended key usage on the leaf certificate. It verifies any RFC 3161 timestamp, both its own signer chain and its message imprint, before trusting that timestamp to extend validity. Without a verified timestamp, certificate validity is judged at the time SOURCE_DATE_EPOCH names, or at the current time when the variable is unset; a value that is not a whole number of seconds fails the command with DR-CLI-0318 rather than falling back to the clock. The outcome is a single verdict, one of Valid, NoSignature, HashMismatch, Expired, SelfSigned, UntrustedChain, WrongKeyUsage, UnsupportedAlgorithm, or MalformedSignature, written into identity.json with the computed and claimed hashes, the certificate chain, and the timestamp. The verdicts are graded against real signed PE fixtures carrying injected defects: a flipped .text byte, a forged timestamp, a wrong-EKU leaf, and self-signed and expired chains, each asserted to its expected verdict. The computed digest is cross-checked against osslsigncode where it is installed, and live Microsoft-signed System32 binaries reach Valid against the embedded roots (authenticode_oracle.rs).

Delphi and C++Builder RTTI

For a Delphi or C++Builder binary, the native Delphi analyzer (disrobe_pass_native::delphi::analyze) recovers the published object model from the compiled RTTI. It locates virtual method table anchors across the three ABI eras (pre-2009 32-bit, Delphi 2009+ 32-bit, and 64-bit), accepting a class only when its table is self-consistent, and recovers each class's name, parent, instance size, published properties with the ancestor that introduced each, published methods, published fields with their declared class, dynamic method and message handlers, and implemented interface identifiers. Enumeration member names, ordinal ranges and set element types come from the referenced type records. Compiled-in string literals are recovered from the reference-count header across the pre-2009, code page and 64-bit layouts, accepted only when the declared length lands exactly on the terminator. The unit initialization table is reached by following the entry point stub, giving the unit count and each unit's initialization and finalization address, and is refused unless every address lands in an executable section. Each class is tagged as runtime library or author code from its RTTI unit name, so an analyst can read only the author's classes. The compiler release is named only when independent signals agree: the table layout era, a linked runtime package name, dotted unit scope names, and build toolchain path strings. When they disagree the report says so rather than choosing one. It also decodes the binary DFM form resources (TPF0) back to their textual object ... end representation.

Form decoding is compared byte for byte against form streams and renderings both produced by the Free Pascal RTL converters, over five committed cases covering collections, nested collections, child objects, binary data blocks, value lists, sets, control characters and 64-bit integers; the converter source and a regeneration script ship beside the fixtures. Float rendering is excluded and remains ungraded, because the reference renderer's float format differs from Delphi's. The virtual method table and published table walks are graded against the documented layout rather than against a Delphi-compiled binary, so they catch a regression but not an error shared between the reader and the specification transcription. Each table is rejected whole unless every entry validates, so a wrong layout yields nothing rather than invented names. False-positive controls confirm no class, field, dynamic method, interface, type record or string literal is produced from real kernel32.dll, ntdll.dll, user32.dll or shell32.dll.

Nim, Zig, Crystal, and D binaries

These four compilers erase the source, so recovery works from each binary's own tables rather than from anything resembling the original file. disrobe detects the toolchain, demangles its name scheme, and recovers the symbol and metadata surface the compiler left behind. Where DWARF survives, aggregate members come back with full types, including multi-dimensional array dimensions and const/volatile qualifiers, so a field reads as const u8[4] or u8[2][3] rather than an opaque blob. A stripped D PE, which carries neither DWARF nor a name table, is a wall: the format is identified and nothing further is claimed.

Function bodies are carved and lifted to pseudo-C and pseudo-Rust. The figures below come from committed binaries built by the real compilers, and each count is pinned exactly in body_equivalence.rs, so a change in either direction fails the test.

These counts measure how many bodies the pass emits, not whether they are correct. Two tests grade the output against independent references. body_recovery_oracle.rs compiles every pseudo-C body recovered from the Nim and Zig ELF files, the Crystal PE, and a D PE with a real C compiler (-fsyntax-only -std=c11), and every pseudo-Rust body with rustc --emit=metadata; it requires at least 492 C and 487 Rust bodies to pass. This grade is compile-only: it shows that each body stands alone as valid source, not that it computes what the original did. body_equivalence.rs compiles 14 recovered pseudo-C bodies from Zig 0.16.0, Nim 2.0.8, and Crystal 1.20.2 builds, runs them on at least 115 input rows, and compares each result with a model of the function transcribed from the original source; each binary must also match its build record (source hash, toolchain, and build command). Both tests run in the weekly scheduled CI run on Linux, macOS, and Windows, not on every push.

Entropy map and byte histogram

disrobe native entropy slides a 4 KB window across the file computing Shannon entropy (bits/byte) to locate packed, compressed, or encrypted regions, and renders the profile three ways via --format text|json|svg:

• text (default): a Unicode heat-strip sparkline (one glyph per 4 KB block, taller = higher entropy), a 16-bucket ASCII byte-frequency bar chart, and a list of contiguous high-entropy runs (entropy >= 7.0 bits/byte) with their file offsets, the candidate packed or encrypted regions. Pass --out <path> to also drop the JSON document.
• svg: a self-contained neutral-gray entropy map with no external dependency. Each block is a column colored on a calm-gray to amber to red ramp, with PE/ELF/Mach-O section boundaries (parsed from the file's own section table) overlaid as labeled dashed markers and a color legend. Written to ./out/<stem>.entropy.svg or the explicit --svg <path> (which implies SVG rendering). The SVG is byte-stable for a given input (no clock or RNG) and all section names are XML-escaped.
• json: the machine-readable disrobe.native.entropy/v0 document: per-block entropy, the sparkline/heat-strip strings, the 16-bucket histogram, the detected high-entropy runs, and the section spans.

The reusable rendering logic lives in disrobe_pass_native::entropy_viz (entropy_sparkline, byte_histogram, histogram_ascii_16, high_entropy_runs, render_entropy_svg) so other tools can embed it.

Limits

• No committed benchmark compares the in-tree decompiler with Ghidra or IDA, so this guide states no ranking against them. What it does state: disrobe hands either one clean, unpacked, symbol-rich input, and can drive Ghidra headlessly. See native decompile for the in-tree decompiler, its two grading levels, and the Ghidra backend.
• Themida and VMProtect support covers detection and section carving. See native unpacking for the available outputs and recovery limits.
• Authenticode chain validation walks to an embedded bundle of eight trusted code-signing roots and covers RSA PKCS#1 v1.5 and ECDSA P-256/P-384. Anything outside that lands as UnsupportedAlgorithm or UntrustedChain rather than a pass.
• The Delphi VMT walk accepts a class only when its VMT is self-consistent, so a partially-overwritten or hand-built table yields no class rather than a guessed one.

Native decompile

disrobe's x86-64 decompiler emits C or Rust. Its AArch64, ARM32, and MIPS32 paths emit pseudo-C. These in-tree paths require no external decompiler. Ghidra is available as a separate headless backend.

For symbol recovery, disassembly, and identification see the native guide; for packers and VM protectors see native unpacking.

At a glance

Commands

disrobe native decompile app.exe --out decompiled/                 # x86-64 -> C, default backend
disrobe native decompile app.exe --format rust --out decompiled/   # x86-64 -> idiomatic Rust
disrobe native decompile app_arm64 --out decompiled/               # aarch64 -> pseudo-C, symbolic devirt on by default
disrobe native decompile app_arm64 --no-devirt --out decompiled/   # aarch64 without the symbolic devirtualizer
disrobe native decompile app.exe --backend ghidra --out decompiled/

Output lands at <out>/<stem>.c or <out>/<stem>.rs alongside a manifest.json (schema disrobe.native.decompile/v1) listing which functions recovered, which did not and why, and the emitted symbol name for each. x86-64 output also carries the types.json sidecar.

Coverage and fidelity

Call resolution and structure

--backend native (the default) uses the in-tree decompiler. For linked AArch64 ELF inputs, a validated direct same-image call resolves its callee's real name and integer arity only when the sibling target is unambiguous. Indirect, external, malformed, unsupported, and ambiguous calls abstain. Relocatable AArch64 objects fail before output because section-qualified function identity is not yet carried through the CLI. Dense switch dispatch is recovered from the binary's own jump table. A function with no validated outgoing calls uses per-function recovery. AArch64 uses object-context recovery first, with the NIR lift and image-backed recovery available as narrower fallbacks.

AArch64 scalar floating point

The AArch64 lifter recognizes all 32 scalar floating-point registers through their h, s, and d views. Half-precision values use IEEE binary16 bits in the shared register model. The C emitter uses _Float16; the internal Rust emitter uses u16 at function boundaries because stable Rust does not provide an f16 primitive, then converts those bits through bounded binary16 helpers. Arithmetic, fused multiply-add, minimum and maximum, square root, rounding, integer conversion, precision conversion, comparison, selection, base-register scalar loads, scalar stores, and image-backed s and d literal-pool loads use the declared operand width. Literal-pool recovery reads only the encoded width from a mapped image range and refuses missing or truncated data. The scalar path models the default IEEE floating-point environment. A function that reads or writes FPCR refuses recovery because its rounding, flush-to-zero, default-NaN, or alternative-half controls can change scalar results. Ambient FPCR state established outside the function cannot be inferred, so output that depends on an externally selected nondefault state is not claimed as bit-exact. q and v operands remain vector operations and do not enter the scalar path.

x86-64 type recovery

Types are inferred from the access shape rather than left as raw registers. A pointer walked at several fixed offsets recovers as a struct with named fields (p->field_8), a base indexed by a scaled register recovers as an array (a[i]), and offsets read at conflicting widths recover as a union. The calling convention is inferred per function, including x86 thiscall (implicit this in ecx) and vectorcall (SSE/AVX register arguments), so the recovered signature matches how the function is actually called.

Alongside the source, native decompile writes a types.json sidecar (schema disrobe.native.types/v1) recording the recovered integer width and signedness of each frame slot. The disrobe-typerec crate reads those signals straight from instruction semantics, subregister access, movsx/movzx, div/idiv, sar/shr, and signed against unsigned compares, and resolves them over a lattice with union-find. A frame slot the compiler reused for two variables is split back into distinct objects by a region-typed memory-SSA and live-range pass, so a reused slot recovers as two types instead of one blurred type that loses the signedness of both, and the same crate grades the struct, array, and union shapes the decompiler recovers from those access paths.

When a recovered call reaches a known library or OS function, resolved through the PE import table or ELF relocations to a curated libc, kernel32, and ws2_32 prototype database, that function's parameter and return types are propagated backward into the caller's locals through the same region memory-SSA and written into types.json as api_slots, each carrying its library!function provenance so an API-derived type is distinguishable from an inferred one; an unresolved import, an ordinal-only import, or a call whose backpropagated type conflicts abstains rather than guessing, and those API-derived caller-local types are graded on a stripped-versus-unstripped clang corpus against the unstripped DWARF, recovering pointer, integer-width, and sign with zero wrong types.

Graded against an unstripped sibling's DWARF on an -O0 corpus, integer width and struct field offset and per-field width recover at recall 1.0, live-range splitting lifts signedness recall from 0.25 to 1.0 on the slot-reuse cases, and mutation checks confirm the grader rejects seeded-wrong widths, signs, field offsets, and merged or invented fields instead of passing everything.

AArch64 symbolic devirtualizer

On the AArch64 path a symbolic devirtualizer runs before structuring, on by default in a full build and disabled with --no-devirt. It folds conditional arms it can prove dead against the path constraints, then hands the simplified function to the structurer. The fold is transactional: on any proof miss or budget exhaustion it reverts to the original function, so it replaces a construct only with a proven-equivalent one and adds no edges. Per-function fold counts and status land in the decompile manifest.json under devirt.

Auto-vectorized loops

Auto-vectorized loops are recovered to their scalar meaning: the C backend recognizes SSE/AVX reduction and pointer-walk map kernels that gcc and clang emit at -O2/-O3 and lowers them back to the equivalent scalar loop, tracing each argument to its pristine ABI register so a compiler's entry-sequence register swap does not misattribute the length to the output pointer. Reassociation-unsafe floating-point vector loops are rejected rather than lowered to a wrong scalar form.

x86-64 constant division and modulo

A compiler replaces a division by a constant with a multiply by a magic number, a shift, and a sign correction. The x86-64 path recognizes that sequence and emits the division again. C output uses / and %. Rust output uses wrapping_div and wrapping_rem. The recognized forms are a magic multiply whose product fits a single register, a wide multiply through the one-operand mul or imul, the add-form that carries an implicit high bit, the pre-shift form used for an even divisor, and the signed corrections taken from the sign of the dividend, of the product, or of the quotient. A dividend narrower than 64 bits must be zero-extended into an unsigned form or sign-extended into a signed form. An extension that does not match the form refuses the rewrite.

The divisor is not read out of the magic number. A candidate divisor is accepted only when the multiply and shift reproduce the exact quotient for every dividend in range. A multiply-shift pair that computes a fixed-point scale fails that check and stays a multiply and shift, so a scale is never renamed as a division. A perturbed shift amount, a perturbed multiplier, and a 32-bit magic applied to a 64-bit dividend fail the same range check.

The modulo is recovered from the tail that follows the quotient. Inside a bounded window after the matched sequence, the recovery tracks copies, additions, subtractions, multiplication by a constant, left shifts, and lea with a scale, then emits % for the register that ends up holding dividend - quotient * divisor. When the quotient is still live after that tail, the division and the modulo both emit.

The rewrite replaces straight-line code only. A back edge that targets the first instruction of the matched sequence, or any address before it, refuses the rewrite. A division inside a loop therefore keeps its multiply-and-shift form whenever the loop jumps back to or above the start of the matched sequence. Any other control transfer that lands inside the sequence refuses it as well. A store or a read-modify-write inside the sequence refuses it. Every register the sequence writes, other than the quotient and the copies of the dividend that outlive it, must be dead afterward.

The one-operand imul lifts as a signed wide multiply, so a signed 64-by-64 high-half product emits as __int128 in C and as i128 with wrapping_mul in Rust instead of taking the unsigned form.

Set DISROBE_DEBUG=native to print the address and the recovered divisor of each rewritten sequence.

Grading

C output is graded by execution-differential recompilation against real gcc or clang, and x86-64 Rust output against rustc, never against disrobe's own prior output. The AArch64 pseudo-C lift is held to the C bar against real clang machine code at -O0, -O1, -O2, -O3, and -Os. Its scalar floating-point battery compares raw result bits for register and stack parameters across directed IEEE edge patterns and seeded random inputs. It canonicalizes a comparison only when both results are NaNs, and reports how many comparisons passed on that canonicalization. The struct, array, and union recovery is asserted on recompiled-and-executed fixtures rather than by inspection. The vectorized-loop recovery is held to the same C bar: the recovered scalar loop is recompiled and its output compared bit-for-bit against the original compiled kernel across a spread of input lengths, and on Linux at least one gcc -O3 pointer-walk reduction must recover and execute-prove (simd_devirt_oracle.rs).

Constant-division recovery is held to the same C bar. It is measured over divisors 1 through 1024 plus sampled values up to 4294967295, at -O1, -O2, and -Os, for 32-bit and 64-bit dividends, with whichever of gcc, clang, and cc is on PATH, and a recovered divisor that differs from the one in the source is a failure. Recovered functions are recompiled and executed against the compiled original over a fixed spread of inputs, and that execution grading covers the loop bodies and the signed 128-bit high-half products as well as the plain division and modulo cases. Whole-program recovery is graded on its own, so the rewrite is proven reachable through recover_program and not only through a single leaf function (pseudo_c_const_division_oracle.rs).

Ghidra backend

--backend ghidra runs Ghidra headlessly (install it with disrobe install-deps ghidra) and returns pseudo-C alongside the standardized emits.

Limits

• AArch64 function discovery is symbol-table-based today (the linear-sweep function finder is x86-only), so a stripped AArch64 binary surfaces fewer functions than its unstripped sibling, which enumerates and decompiles in full.
• On the AArch64 path, control-flow-flattening deflatten and jump-table edge rewrite are noted as deferred in the devirt manifest section.
• AArch64 Rust emission is unsupported. --format rust fails before native recovery writes output.
• On x86-64, where the byte stream carries no sign signal for a frame slot, the types.json sidecar reports it as unknown rather than guessing.
• An unresolved import, an ordinal-only import, or a call whose backpropagated type conflicts abstains rather than guessing an API-derived type.
• Reassociation-unsafe floating-point vector loops are rejected rather than lowered to a wrong scalar form.
• Constant-division recovery is x86-64 only. The AArch64 path does not rewrite a magic multiply back into a division.
• Constant-division recovery starts from a magic multiply, so a divisor the compiler lowered to a plain shift stays a shift in the output.
• A magic multiply-shift sequence whose divisor the range check cannot confirm, including a fixed-point scale, is left as a multiply and a shift rather than rewritten.
• A constant division is left alone when a back edge targets the first instruction of the matched sequence or an earlier address, when another control transfer lands inside the sequence, or when the sequence writes to memory.
• --backend ghidra runs the optional external decompiler on the input.

Native unpacking and devirtualization

disrobe detects the runtime packer on a PE / ELF / Mach-O and unpacks it, driving stub-based packers through an in-house x86 emulator, and lifts bytecode-VM protected code back to IR and pseudo-code.

For symbol recovery, disassembly, identification, and forensics see the native guide; for the in-tree decompiler see native decompile.

At a glance

Commands

disrobe native unpack packed.exe --out unpacked.bin
disrobe native devirt protected.exe --out recovered/

native devirt writes the recovered listing, the pseudo-code, and a devirt.manifest.json (schema disrobe.native.devirt/v1) into the output directory.

Coverage and fidelity

Packers

In-house decoders cover UPX (.text and .pdata byte-identical, ~96% whole loaded image), MPRESS, Petite, MEW, ASPack, and PECompact, plus NSPack, FSG and Petite, each of which ships a committed original and packed pair so its byte-recovery figure re-derives from a clean checkout; kkrunchy and kkrunchy classic ship committed fixtures and recover their payload at a pinned 100.00% floor from a clean checkout.

On committed samples ASPack and PECompact rebuild the decompressed section image at its load RVA: the section report confirms the recovered .text byte-identical and the import table >=98% byte-identical to the original, both gated in CI, while the packed .text of near-random entropy and zero resolvable calls drops to ~6.2-6.5 with hundreds of disassembler-resolvable intra-code calls. Because the whole rebuild is a loaded-memory image rather than a disk-aligned file, the bench marks whole-output byte-identity n/a. MEW rebuilds a flat image of the committed Sysinternals samples, read as the entropy drop to ~4.2-4.9 and tens of thousands of decoded instructions.

Yoda's Crypter is recovered by driving its unpack stub through the in-house x86 stub emulator: the stream decryptor runs to the original entry point inside the emulator, then the reconstructed sections are read back and sliced byte-for-byte, so its .rsrc recovers byte-identical and its .text decrypts to full plaintext. The same emulator drives ASProtect, Morphine, nPack, NeoLite, PolyCryptor, Warzone Crypter, which sit one tier lower: the emulator is validated against spec-built stubs, and no vendor-packed sample in the corpus proves recovery on a real one.

Per-fixture recovery scores are pinned in corpus/native/packers/MANIFEST.toml.

Bytecode-VM devirtualization

disrobe native devirt targets the bytecode-VM tier rather than the compression tier. It locates the interpreter, fingerprints each handler's micro-op behaviorally by probing it through the in-tree x86 emulator (so a per-build handler permutation does not break the lift), recovers the handler-to-opcode table, reconstructs the VM CFG, and lifts the handler bytecode to a re-executable IR plus pseudo-code.

The lifter is validated end-to-end on a self-authored Tigress-shape bytecode VM: the recovered IR re-executes to the same outputs as the original across arithmetic, loop, and branch programs, lifted from machine code alone (vm_devirt_oracle.rs).

Limits

• FSG, NSPack, and Petite each ship one committed packed-and-original pair, and the published figures for them are measured on those pairs alone. Their larger samples, and the extra MPRESS and UPX megafiles beside them, are kept out of the tree on size or license; every such path is marked local in corpus/native/packers/MANIFEST.toml with a recipe for rebuilding or refetching it, and no figure is published for any of them, because nothing in a checkout re-derives one.
• Yoda's Protector is classified as detect-and-carve. Its original-assisted comparison carve reports surviving sections. On the committed fixtures, the .yP emulator derives the image-resident RC4 key but halts before CryptDecrypt; replaying that key directly over the carved on-disk sections does not recover plaintext because they contain an RC4-encrypted compressed stream. No single-input route emits a recovered image for this family.
• On UPX and NSPack the whole-image residual is the loader-rebuilt zone (bound import address table and base relocations): those addresses are resolved by the OS loader at run time and are not present in the packed stream, not a decoder gap.
• On VMProtect and Themida images, disrobe auto writes each protected section (.vmp*, .themida, .winlice) verbatim as carved/NN-<name>.bin, and the packer manifest records recovery_mode: detect-and-carve with each section's address, sizes and permissions. A section without file bytes, or an image with none, is refused with DR-NAT-0909. A .winlice image handled by the Themida carver is reported as WinLicense. The carve does not reconstruct the original code, and native unpack remains detect-only.
• The direct Enigma Protector, WinLicense, PELock, PE-Protector, Armadillo, and Obsidium packer routes are detect-only and emit no recovered image. WinLicense can reach a carve only when the Themida route recognizes its .winlice section.
• The generic VM lifter is validated on the Tigress-shape VM. disrobe ships no per-family devirtualizer that lifts these commercial protector families back to source.

Go

disrobe recovers symbols from stripped and garbled Go binaries across PE, ELF, and Mach-O by parsing the Go runtime's own metadata tables.

At a glance

Commands

disrobe go recover app --out app-go.json
disrobe go info app
disrobe auto packed-app --out recovered/    # unpack the UPX layer first, then recover the Go symbols

recover writes the full analysis JSON (default ./out/<stem>-go.json); info prints the fingerprint without writing anything. Output shape (illustrative):

go recover: OK
  input:        app
  image kind:   elf
  ptr size:     8
  pclntab ver:  go1.20
  buildversion: go1.26.3
  funcs:        ...
  packages:     ...
  garble:       None
  embed.FS:     used=true directives=...
  wrote:        ./out/app-go.json

info adds the stripped-binary fingerprint: whether the symbol table was stripped, how many functions were still recovered from pclntab, and the stdlib-name ratio that feeds the garble grading.

UPX-on-Go chains automatically: disrobe auto unpacks the UPX layer first, then recovers the Go symbols underneath.

Coverage and fidelity

The garble report separates a real wall from a tooling boundary. garble -literals is handled separately from names. Simple rodata schemes are recovered by pairing adjacent key/data blobs and applying the inverse XOR/ADD/SUB or repeating-key operation. Full-key literals are recovered when their code and ciphertext are present: the thunk scanner follows bounded x86-64 init thunks or inline materializers, emulates the decrypt path, and accepts only UTF-8/readable plaintext. The tests assert the source strings are absent as cleartext before requiring byte-exact recovery, so the oracle is not circular.

An embed.FS map is located through the layout the Go compiler is required to emit rather than by matching a pattern. The compiler writes the slice header and the file records into one symbol and sets the records pointer to that symbol plus three pointer-sized words, so the header points at itself and the length equals the capacity. Discovery keys on that identity, which also fixes the record count from the header instead of reading records until one fails to parse. Ordering is not assumed: real compiler output places frontend/dist/style.css before frontend/dist/assets/, so a scanner that requires a sorted run rejects every genuine map.

Each file record carries the first sixteen bytes of a digest the compiler computed over the member contents, and the pass recomputes it. Members at or below 1024 bytes take a one-shot form and larger members take a streaming form, a boundary measured from real toolchain output rather than assumed. The toolchain generation is identified by which construction verifies the records, so no digest depends on trusting the version string an image reports, and a map whose members are all above the boundary is reported as unable to distinguish two generations rather than being assigned one. Recovery is graded against the exact files each fixture was built from, across PE, ELF, and Mach-O at both pointer widths, both byte orders, and both position-dependent and position-independent links. Go's internal linker materializes the record pointers even in a position-independent image, so the same discovery path serves both. A directory record, a zero-length member, and a member whose contents are not valid UTF-8 are all covered.

The pass is validated against a go1.26.3 fixture, and the test suite gates type-name recovery at >= 85% on that fixture; 838 of 838 type names (100%) are recovered at HEAD, a count the gate now pins by equality, since the typelinks and moduledata tables survive -s -w stripping. Big-endian recovery has its own oracle: a cross-built stripped linux/s390x binary is parsed as a big-endian ELF and its named type and itab pairs are recovered by back-searching the metadata tables, graded against the build (go_bigendian_recovery.rs).

Limits

• The deliverable is symbols, types, and embedded data, not source bodies.
• garble's hashed user identifiers are reported as a name_recovery_wall when the required build seed or name mapping is unavailable. The pass does not infer original names from the hashes. Surviving standard-library names in pclntab are recovered.
• The remaining limits on literal recovery are concrete: missing bytes, runtime-only key material, unsupported architectures, exhausted budgets, or ambiguous short plaintext.

Lua

disrobe decompiles compiled Lua chunks across every common dialect, peels the major Lua obfuscators, and devirtualizes custom-VM wrappers back to runnable Lua source.

At a glance

Commands

disrobe lua decompile script.luac --out script.lua
disrobe lua detect script.luac
disrobe lua deobfuscate obfuscated.lua --out clean.lua
disrobe lua deobfuscate vmified.lua --family prometheus --out clean.lua
disrobe lua deobfuscate dumped.lua --family moonsec-v3 --i-have-authorization
disrobe lua opcode-map --canonical vanilla.luau --client client.luau --build-id 2026-08-24 --out 2026-08-24.json
disrobe lua decompile client.luau --opcode-map 2026-08-24.json --build-id 2026-08-24 --out recovered.lua

Build-keyed Luau opcode maps

lua opcode-map imports only observations proven by a supplied canonical/client pair. The pair must use the same supported bytecode version, have the same prototype tree and instruction counts, and retain every non-opcode and auxiliary instruction word. The map records the explicit client build identifier and bytecode version. lua decompile --opcode-map selects it only when both values match.

The importer accepts a conflict-free bijection for the opcode bytes it observes. It does not infer the remaining permutation. A missing entry causes decompilation to refuse at the instruction location; an incompatible, stale, or malformed map is not substituted with another build's map.

Opcode availability is validated against Luau's bytecode history at 367f9d83: version 3 adds FORGPREP and JUMPXEQK*, version 4 adds IDIV/IDIVK, version 5 adds SUBRK/DIVRK, version 6 adds FASTCALL3, version 9 adds userdata field access, version 10 adds NEWCLASSMEMBER, and version 11 adds CALLFB.

decompile writes the recovered source (default ./out/<stem>.lua) and a manifest.json recording the format, fidelity grade, and warnings. detect reports the dialect and header field summary (constant, proto, and code counts) without writing output. MoonSec v3 and IronBrew2 are commercial-tier wrappers; their peelers require the explicit --i-have-authorization flag.

Recovered Lua 5.x source wraps the main chunk in local function _main(...) and ends with return _main(...), so the file runs unchanged. Short-circuit conditions such as while a and (b or c) do, c and x or y value selection, elseif ladders with compound arms, and local x declarations that Lua 5.1 compiles to nothing are rebuilt as source. The re-execution grade compiles self-authored programs with luac -s (no debug names), decompiles the stripped bytecode, and requires the recovered file to print exactly what the original prints under the same interpreter and to create no global the original does not create (tests/reexec_diff_oracle.rs, Lua 5.1, 5.3 and 5.4 lanes). tests/generated_differential.rs applies the same check to seeded, generated programs on Lua 5.1 and 5.4.

Stripped bytecode carries no local names, so recovered locals are named from their register (v3) or role: numeric loop variables become i, j, k and generic loop variables k and v, unless a global or upvalue of that name is visible anywhere in the function, in which case the register name is kept. A temporary reused after its block ends is declared again with local rather than assigned as a global. A value that is read after its register is overwritten is kept in a local before the overwrite. while true do ... end loops left by break, and loops whose head runs statements before the test, are rebuilt as structured loops. Values selected by and/or chains, including (a or b) and c and chains whose operands are calls, are rebuilt as one expression or as a local assigned on every path; for a chain whose operands are calls, the Lua 5.1 and 5.3 output still contains a goto, which the Lua 5.1 parser rejects, so corpus/lua/behaviour/values.lua is graded on the Lua 5.4 lane only.

--family pins one peeler instead of letting auto choose. Auto-detection tries Prometheus first, so a Vmify container needs no flag. Pass --family prometheus when you want a file carrying no Prometheus signature to fail rather than fall through to another family.

Output shapes below are illustrative.

lua decompile: OK
  input:        script.luac
  format:       Lua54
  fidelity:     Lossless
  warnings:     0
  wrote:        ./out/script.lua
  manifest:     ./out/script.manifest.json

lua deobfuscate: OK
  family:       Auto
  detected:     Prometheus (confidence=0.97)
  passes run:   3
    - string_decode
    - bytecode_unwrap
    - emit
  recovered:    12 string(s)
  fully peeled: true
  residual:     0
  wrote:        ./out/obfuscated.peeled.lua

The deobfuscate report lists every pass that ran, recovered string constants, a fully peeled verdict, and any residual markers.

Coverage and fidelity

IronBrew2 and MoonSec ship their payload behind a custom register-VM: a permuted opcode-handler table and an embedded constant pool that a stock decompiler cannot read. The permutation is not stored in the loader; it is computed at load time inside the obfuscated bootstrap, then used to dispatch handlers and key the constant decryptor. disrobe reconstructs it the same way the loader does.

For IronBrew2 2.7.0, the devirtualizer parses the bootstrap's dispatch chain to derive the encoded -> canonical permutation and the XOR key, decodes the constant pool, and lifts the VM bytecode back to runnable Lua. The committed corpus/lua/ironbrew2 set carries real obfuscated bootstraps for five programs in both standard and MAX mode; each must produce byte-identical output to the original under a real lua binary (tests/ironbrew2_real_oracle.rs).

MAX mode adds three layers on top of standard: a control-flow-flattened dispatch (a nested binary search over the opcode enum, which the same handler walker un-flattens), comparison-polarity number-mutation (the EQ handler tests ~= and jumps on equality, captured as the literal operator plus jump direction), and fused super-operator handlers (one VM step covering several real ops, whose hoisted scratch locals are stripped after classification).

Prometheus Vmify

The Prometheus Vmify step rewrites a chunk into a register machine held inside one container function. Every original function becomes a numbered entry point in a shared dispatch tree, and every call becomes a jump through that tree. disrobe reads the container, rebuilds a control-flow graph for each entry point, and re-emits structured Lua. The pass appears as prometheus-vmify-container-devirt in the passes run list. Vmify applied over its own output is unwrapped layer by layer, up to four layers in one call. A chunk that needed more than one layer also carries a prometheus-vmify-nested-devirt-<n>-layers entry naming the layer count.

Vmify does not keep a captured variable as a Lua upvalue. It moves the variable into a store table shared by the whole chunk, hands each closure a list of slot indices into that store, and uses a reference count to decide when a slot is cleared. disrobe fingerprints the allocator and the release helper by their statement shape, which is how it tells the capture store apart from any other table in the chunk. It then gives each allocation one Lua local, named __vu0, __vu1, and so on in allocation order, and declares it once in the scope that allocates it. Every read and write of that slot is rewritten to the same local, both in the allocating function and in each closure that receives the slot, so the recovered closure captures the variable by reference the way the original source did.

The committed corpus/lua/prometheus/vmify_upvalue pair holds real Prometheus Vmify output for a counter factory whose inner function captures a local. The gate first requires that no Prometheus layer is left in the recovered source, then runs it under a real lua 5.1 binary and requires the output the clean file prints (tests/reexec_diff_oracle.rs). The obfuscated file itself is never run.

The Prometheus Weak preset (Vmify, ConstantArray and WrapInFunction) is graded on the Lua megafile. All 171 functions in its dispatch tree come back structured with no dispatch fallback, and 630 of the 630 reached handlers are lifted. The recovered program then runs under real Lua 5.1 and 5.4 against a driver that calls every export, and it must print the same 116 lines as the clean source (tests/real_prometheus_megafile.rs). A mutation that drops trailing nil results from calls turns that grade red.

Set DISROBE_DEBUG=lua to trace the capture analysis. It emits prometheus_vmify.box_model, naming the registers the capture helpers resolved to, and prometheus_vmify.captured_variables, the number of captured variables bound in the run.

The Hercules real-output grader covers 15 pinned outputs from Hercules 2.0.1. Fourteen recover to source that prints the same bytes as the authored programs under Lua 5.4. The remaining branches.maximum fixture reports its unrecovered VMGenerator layer. Each recovered case also has a changed-literal control that must differ from the original.

Limits

• Where fully peeled is false the report carries the residual marker names and the reason (runtime key, anti-tamper variant, unmodeled VM tier, or a refused Vmify recovery).
• When a MoonSec v3 constant-pool key is available only at runtime, disrobe returns fully_recovered: false with a runtime keys residual marker.
• The MoonSec emulate_perm_builder tests use a purpose-built bootstrap whose permutation is derived at runtime. These tests cover the table-builder algorithm; the corpus contains no captured MoonSec dump to establish end-to-end recovery.

Prometheus Vmify refusals

Vmify recovery refuses unsupported shapes instead of substituting placeholder functions for missing bodies. A refusal names its cause, and where the cause is a specific expression it names the byte offset of that expression in the text the layer was reading. The execution comparison below covers the committed Lua 5.1 Vmify fixtures.

A refusal takes one of two shapes.

• The whole container is refused. fully peeled is false, prometheus-vmify-container-devirt is absent from passes run, the output file holds the earlier peel stage rather than a devirtualized body, and a residual marker reads a Vmify container was found but recovery was refused rather than emitted partly wrong, followed by the reason.
• Some layers recovered and a further layer is refused. The recovered source is written, fully peeled is false, and a residual marker records how many layers recovered before the refusal, followed by the reason.

disrobe refuses these captured-variable shapes.

• A capture allocated on a cycle in the recovered control-flow graph, which is what a capture written inside a source loop becomes. Each iteration of such a loop captures a fresh variable, and one declaration at function scope would alias them into a single shared variable. The committed corpus/lua/prometheus/vmify_loop_capture pair is a loop that builds three closures over three different values, and disrobe refuses it. The cycle search runs under a step budget, and disrobe refuses when the search exceeds it.
• A chunk that creates a closure with a non-empty capture list, but whose reference-counted capture helpers do not match the shape disrobe fingerprints. The fingerprint accepts exactly one allocator and exactly one store bound to that allocator's reference-count table, so a chunk carrying more than one of either yields no model and no captured variable can be resolved to a real Lua variable. A chunk that captures nothing needs no model and is unaffected.
• A register that receives a second capture inside one recovered function, because the register cannot then carry one stable name.
• A capture allocator referenced anywhere other than a plain allocation assignment.
• A store slot read or written through anything other than a register the same function allocated a capture into, or an entry of the closure's own capture list indexed by a positive whole-number literal. An index past the end of the supplied capture list is also refused.
• A closure-creation call whose capture list is not a table constructor, or whose capture list carries a keyed entry. A keyed entry has no stable position to match against the closure body.
• A closure-creation call whose entry point is not a literal number, because the closure body cannot then be located in the dispatch tree.
• One dispatch leaf shared by two closures with different captured variables, which would bind one expression to two different recovered values.
• A recovered body that still names the container's own capture machinery, meaning the capture table, the store, the allocator, or a slot register. At least one access went unresolved in that case, so the body is refused rather than emitted.

Recovery is graded against Prometheus output built for Lua 5.1 with Vmify as the only step. Other target dialects and other step combinations are not graded.

PHP

disrobe peels PHP eval chains, evaluates supported decode loops and literal-key ciphers, and extracts Phar members. It also identifies ionCube, SourceGuardian, and Zend Guard envelopes, recovers statically available legacy layers, and reports when loader-resident keys keep a payload sealed. These operations run locally without uploading the input.

At a glance

Commands

disrobe php decode payload.php --out out/payload-php/
disrobe php decode payload.php --encoder ioncube --i-have-authorization
disrobe php deobfuscate obfuscated.php --out clean.php
disrobe php extract archive.phar --out extracted/

--encoder is auto (default), phar, ioncube, sourceguardian, or zendguard. Commercial encoders require the explicit --i-have-authorization flag. The output directory receives the decoded payload, a skeleton .php when an op_array was decompiled, and a manifest.json recording the encoder, version label, marker offset, ciphertext and plaintext byte counts, and the recovery stage.

Output shapes below are illustrative.

php decode: OK
  input:        payload.php
  encoder:      Ioncube
  out dir:      ./out/payload-php
  manifest:     ./out/payload-php/manifest.json

deobfuscate unwraps stacked eval() layers until the residue is plain PHP. The manifest counts each layer kind that was peeled and flags whether any eval remains in the residue.

php deobfuscate: OK
  input:        obfuscated.php
  layers:       3
  residual_eval:false
  wrote:        ./out/obfuscated.peeled.php
  manifest:     ./out/obfuscated.peeled.manifest.json

extract walks the Phar manifest and extracts every entry through a path-sanitizer (no .. escapes), writing a manifest.json with the entry count and API version.

php extract: OK
  input:        archive.phar
  entries:      14
  out dir:      ./out/archive-phar
  manifest:     ./out/archive-phar/manifest.json

Coverage and fidelity

Every recovery carries an explicit stage in its manifest: EvalChainPeeled, OpArrayDecompiled, StructuralOnly, or PlainSource, so a caller can tell a fully peeled payload from an envelope parse.

Limits

• ionCube, SourceGuardian, and Zend Guard keys live in the native loader, not the file. Those envelopes are detected and walled. A partial op_array skeleton is recovered only for legacy statically-keyed cases (Zend legacy XOR).
• When an encoder's key lives only in its runtime loader, the decode is graded StructuralOnly and the manifest carries the residual ciphertext length rather than pretending at plaintext.
• A decode loop whose key arrives at run time, from $_GET, $_POST, a header or the network, is not statically recoverable. The loop is left in place and no plaintext is produced.
• A helper declared inside a conditional or inside another function is not evaluated. Only a declaration at the top level of the file is, which matches where php makes a function callable before its own text.
• A helper taking a parameter by reference, or a variadic parameter, is not evaluated, because the interpreter models values rather than references.
• The interpreter reads a variable only when the file defines it. An undefined read, a call outside the pure-function allowlist, or any exceeded budget abstains and leaves the loop in place.
• An undefined constant abstains. A constant whose value comes from the file name, the request, or the environment is not resolved, because the value is not in the file.
• A cipher mode outside the listed AES set, including a stream or authenticated mode, is refused. The call is left in the source rather than decrypted by a different primitive.
• A division that does not divide exactly abstains. The interpreter models integer values only, so strlen($d) / 3 is not evaluated where php would produce a float.
• mcrypt_decrypt is not evaluated. The extension was removed in php 7.2, so a loader that calls it cannot be graded against a real interpreter.

Ruby

disrobe analyzes Ruby artifacts and recovers source from YARV and mruby bytecode. The YARV benchmark recompiles recovered source with MRI and measures opcode-name overlap.

At a glance

Commands

disrobe ruby decompile app.bin --out app-ruby.json
disrobe ruby detect app.bin

decompile sniffs the flavor, runs the matching analyzer, and writes the analysis JSON (default ./out/<stem>-ruby.json). For YARV, or for mruby when a body is recovered, it also writes a .rb source file beside the JSON; YARV output includes a disassembly trailer when available. detect reports the flavor and exits without writing output.

Coverage and fidelity

For MRI source the summary reports token and definition counts. For YARV it adds the IBF header fields, iseq and object counts, instruction count, decompile fidelity, and statement count. For mruby it reports the compiler version string, irep count, instruction count, and whether a body was recovered.

The benchmark compiles the original and recovered sources with MRI, then counts opcode names across their instruction sequences. For each name, the smaller of the two counts contributes to the numerator; the denominator contains every original opcode occurrence. The stored results are 79 of 79 for the greeter and 23648 of 23966 for the megafile.

This comparison ignores instruction order, operands, constants, branch targets, and instruction ownership. Additional recovered instructions do not reduce the score. MRI compiles both sources without executing either program, so the result measures opcode-name recall rather than behavioral equivalence.

Ruby2Exe and Ocra self-extracting packages are detected as their own flavors. Analysis records their embedded-payload offsets and lengths; for Ocra opcode streams it also parses contained file records.

Limits

• JRuby .class files are classified but not decompiled here. JVM-class material belongs to the JVM guide.
• TruffleRuby AOT images are classified but not decompiled here. Their native code belongs to the native guide.

BEAM (Erlang / Elixir)

disrobe parses BEAM IFF files, recovers Erlang or Elixir source when debug chunks survive, lifts to Core Erlang otherwise, and disassembles the Code chunk per instruction.

At a glance

Commands

disrobe beam parse module.beam --out ./out/module-beam.json
disrobe beam lift module.beam --out out/module-beam-lift/
disrobe beam disasm module.beam --out ./out/module-beam.disasm.json

Output shapes below are illustrative.

parse reports the module name, atom / export / import / fun counts, which optional chunks are present, and any unrecognized chunk names.

beam parse: OK
  module:       my_module
  atoms:        42
  exports:      8
  imports:      15
  funs:         3
  wrote:        ./out/module-beam.json

lift writes three files: <stem>.<ext> (recovered Erlang or Elixir source, extension derived from recovered_from), <stem>.surface.json (the surface record with provenance), and <stem>.core.json (lifted Core Erlang functions), plus a manifest.json linking them.

beam lift: OK
  module:       my_module
  core fns:     8
  recovered:    AbstractCode
  source:       ./out/module-beam-lift/module.erl
  surface:      ./out/module-beam-lift/module.surface.json
  core erlang:  ./out/module-beam-lift/module.core.json
  manifest:     ./out/module-beam-lift/manifest.json

disasm emits the per-instruction Code-chunk trace as JSON and a flat .txt listing beside it.

beam disasm: OK
  input:        module.beam
  instructions: 214
  wrote:        ./out/module-beam.disasm.json
  listing:      ./out/module-beam.disasm.txt

Coverage and fidelity

When a Dbgi chunk is present the original forms are recovered directly and labeled AbstractCode (Erlang) or ElixirDbgiForm (Elixir). Each lift records where its source came from in recovered_from, so a caller can tell a recovered original from a lift.

For stripped BEAM, 21 / 21 committed corpus entries recover to Core Erlang source that recompiles under Erlang/OTP 27.3.4, preserves the original export set, and returns the same result from the entry's committed test/0 battery. Each corpus entry is an Erlang module compiled from committed source; the gate removes both Dbgi and Docs before recovery so neither source path can participate.

The measurement covers each module's committed test/0 cases. erlc compiles the original and recovered source independently; the harness runs both with erl and compares exit status and stdout. A control replaces a recovered test/0 with one that raises, while preserving compilation and exports, and checks that the runtime comparison rejects it.

The Linux CI test leg pins OTP 27.3.4.15 and makes missing erlc or erl fatal. macOS and Windows retain explicit optional reporting when that toolchain is absent. Reproduce the Linux gate with:

DISROBE_REQUIRE_ERLANG=1 cargo test -p disrobe-pass-beam --test erlc_recompile_equivalence -- --nocapture

Limits

• Without a Dbgi chunk the original source is not in the file. The output is then a best-effort Core Erlang lift labeled CoreLifted, not the original text.
• An opcode beyond the known table fails with an explicit DR-BEAM-0012 error naming the offending opcode rather than silently skipping bytes.

Swift / Objective-C

disrobe extracts the type metadata the Objective-C and Swift runtimes leave in a native binary, demangles it, parses SwiftShield rename mappings into a lookup for downstream use, and rebuilds the dylibs a dyld shared cache bundles into standalone Mach-O images.

At a glance

Commands

disrobe swift classdump App.app/App --out dump.json
disrobe swift shield-undo map.txt --out renames.json
disrobe swift xor-decrypt blob.bin --key 0x55 --out strings.json

disrobe macho classdump universal.bin --out dump
disrobe macho dump App.app/App
disrobe macho fat universal.bin
disrobe macho dyldcache dyld_shared_cache_arm64e --out ./out/cache-dylibs
disrobe macho dyldcache dyld_shared_cache_arm64e --image /usr/lib/libobjc.A.dylib

classdump reconstructs the type interface from the two metadata sources the runtime leaves in the binary. Beside the JSON, it writes a .swift declaration file with recovered type signatures when reflection metadata yields declarations; source-level function bodies do not survive in this metadata.

shield-undo parses a SwiftShield mapping. SwiftShield renames symbols to high-entropy identifiers and emits an obf ==> original mapping in the .dSYM. disrobe writes that mapping as a lookup for downstream use; class-dump does not apply it automatically. xor-decrypt decodes printable strings from a single-byte XOR blob when the caller supplies --key. Its tests cover hand-authored model fixtures, not SwiftConfidential output.

macho dump reports the header, load commands, segments, sections, and any LC_ENCRYPTION_INFO or LC_ENCRYPTION_INFO_64 records. macho fat walks a fat binary and reports each slice's CPU type, subtype, and offset.

macho dyldcache rebuilds every dylib the cache bundles and writes each one under --out at a path taken from its install name. A split cache reads its .01, .02, ... and .symbols subcaches from the directory of the file you name. --image <install-name> (repeatable) extracts only the named images and fails, naming each one, when the cache holds no image by that name. An image that cannot be rebuilt is listed by install name with its reason, and a subcache that is missing is listed with the file names it looked for; the summary line then reads partial instead of OK. The command writes compact images; use disrobe auto when you want images with a rebuilt __LINKEDIT.

Output shape (illustrative):

swift classdump: OK
  input:        App
  cpu/bits:     arm64 / Bits64
  swift types:  24
  reflected:    18
  mangled syms: 312
  demangled:    312
  swift declarations: ./out/App-swift.swift
  wrote:        ./out/App-swift.json

Coverage and fidelity

The Objective-C side walks __objc_classlist, __objc_catlist, and __objc_protolist to recover classes, categories, protocols, ivars, properties, and method selectors with their type encodings. The Swift side parses the reflection sections (__swift5_types, __swift5_fieldmd, __swift5_proto) and demangles the symbols to recover type names, stored fields, and conformances.

The demangler recovers async functions, actor and distributed-actor entities, and opaque return types. It also recovers key-path and protocol-witness thunks, partial-apply forwarders, Objective-C bridging thunks, attached macro expansions, and cross-module protocol conformance descriptors and witness tables. Each arm is checked against a real swift-demangle run (arm_coverage.rs).

Objective-C calls compile to objc_msgSend, so a raw disassembly shows only indirect calls into the runtime. When the chain pipeline recovers native function bodies from a Mach-O (disrobe chain / disrobe auto over a Mach-O), each objc_msgSend, objc_msgSendSuper, objc_alloc, and objc_alloc_init call site is resolved back to its concrete selector, the receiver class where it is statically determinable, and a rendered Objective-C message expression such as [NSString stringWithUTF8String:x2]. The dispatch maps are built from the binary's __objc_selrefs and __objc_classrefs, the dyld bind opcodes, and the __stubs section, then a bounded per-call backward walk over an arm64 or x86-64 def-use model traces the selector and receiver into the call.

The resolution is graded on real clang-compiled fixtures for both arm64 and x86-64 stripped dylibs: every message send in the fixture recovers with the correct selector and receiver class and zero false positives, and the rendered expressions match the source (objc_dispatch_sends.rs).

dyld shared cache

A dyld shared cache packs many system dylibs into one file. disrobe claims a file that carries the dyld_v1 magic and whose header parses. A file that only starts with the magic is left to another pass.

The offset of the mapping table fixes which header layout the cache uses. disrobe names that layout legacy, local-symbols, slide-mappings, sub-caches, or relocated-images. It reads the image list from the legacy header fields when they are set, and from the relocated image fields otherwise. The cache report carries the layout beside the architecture, header size, UUID, platform, format version, the simulator and chained-fixups flags, the mapping, image, and sub-cache counts, the sub-cache entry kind, whether local symbols sit in a separate symbols file, one entry per slide region naming its version or the version number disrobe does not support, the mappings whose file range runs past the end of the file, the pairs of mappings whose address ranges overlap, and up to 4096 install names.

Each image is rebuilt from the mappings that cover its segment addresses, and its segment and section file offsets are rewritten to point at the recovered bytes. Compact output packs the segments back to back. Page-aligned output starts every segment on a 0x4000 boundary and replaces __LINKEDIT with one built for that image alone. A rebuilt __LINKEDIT holds a symbol table, an indirect symbol table, and a string table for that image, and it copies the image's dyld info blobs, chained-fixups blob, exports trie, function starts, and data-in-code table out of the cache file that holds them. The LC_CODE_SIGNATURE offset and size are set to zero, so a recovered image is unsigned. Dysymtab tables the image does not carry are zeroed instead of left pointing into the cache. Two runs over the same cache produce the same bytes.

The cache keeps each image's local symbol names in a run of its own. The legacy, local-symbols, and slide-mappings layouts use the narrow entry, which keys each run by the image's file offset in the primary file. The sub-caches and relocated-images layouts use the wide entry, which keys each run by the image's offset from the cache base, and they move the runs into a separate symbols file when the header carries a symbol-file UUID. disrobe reads both forms and appends the run for an image to the symbol table it builds for that image.

Slide info records the pointers the cache builder rewrote to cache addresses. disrobe reads versions 1, 2, 3, 4, and 5, and writes each pointer back to the value the image declares. An authenticated pointer is recorded with its key (IA, IB, DA, or DB), its diversity value, and its address-diversity bit, and the pointer in the recovered image holds the bare target. Each image records up to 65536 authenticated pointers and reports the full count beside a flag that states whether the list was cut. A slide-info version outside 1 to 5 stops the image, and the error names the version it found.

The cache container in the tests is written to the header layouts above, and the image inside it is a compiled Swift dylib committed to the corpus. Recovery is graded against that original file's segment bytes, symbol table, exported symbols, and function starts (dyld_cache_reconstruction.rs, dyld_cache_chain.rs). Slide info is graded end to end through a rebuilt image for versions 3 and 5, and at the page walk that decodes them for versions 1, 2, and 4.

Sibling cache files

A cache can declare sibling files that hold the rest of its mappings. disrobe locates them by computing names from the primary file you named. For sub-cache N it looks for <primary>.N, and for a single-digit index it also looks for the zero-padded <primary>.0N. For the unmapped local symbols it looks for <primary>.symbols. A file suffix declared inside the cache is never used as a path. Such a suffix is rejected before any file is opened when it holds .., a path separator, :, one of *, ?, ", <, >, |, or a byte outside graphic ASCII.

A missing .symbols file does not stop recovery. Each image keeps exactly the symbol table it declares, and the run continues.

A missing numbered sibling does stop recovery, because the segments it holds are unreachable. The chain refuses, and the error names the sibling it looked for, how many images it could not reach, and the segment that was out of reach for each one.

Recovered dylibs in the chain

disrobe auto and disrobe chain detect the cache, write the cache report as JSON, and emit each recovered dylib as a child artifact that continues through the chain. Both commands pass the input path down, which is how the sibling files are found. Children are page-aligned images with a rebuilt __LINKEDIT. A child keeps its install name as its relative path, with the leading separator and any . or .. component dropped. Every character outside graphic ASCII becomes _, and so does each of :, *, ?, ", <, >, and |. An install name that leaves nothing after that becomes dyld-cache-image.

disrobe auto dyld_shared_cache_arm64e --out ./out/cache-chain

The chain refuses a split cache when it has no path to compute sibling names from. It refuses in the same way when the path it is given is not a readable file.

Limits

• Swift and Objective-C compile to native machine code. Source-level function bodies are not part of the runtime metadata; native code can still be analyzed by the native pass. This pass recovers the metadata the runtimes need at run time.
• A dispatch site whose selector or class cannot be traced within the backward-walk window is left unannotated rather than guessed, so a spurious annotation counts as a soundness failure.
• disrobe macho dyldcache writes compact images. It does not rebuild __LINKEDIT, so a compact image keeps the symbol table offsets the cache gave it.
• The chain handles a cache of at most 256 images. A cache above that count is refused whole, and the error points at disrobe macho dyldcache, which carries the limits above.
• One rebuilt image is capped at 512 MiB, one whole-cache run at 1 GiB, and one cache family at 12 GiB across its files. A cache that needs more than a cap is refused rather than truncated.
• A recovered image is unsigned. disrobe clears the LC_CODE_SIGNATURE offset and size whenever it rebuilds __LINKEDIT.
• FairPlay-encrypted regions (App Store DRM) are reported detect-only via LC_ENCRYPTION_INFO. Without the decryption key, the pass cannot recover class metadata from those encrypted regions.

ActionScript 3 / Flash

disrobe parses SWF files, disassembles their embedded ActionScript 3 bytecode (AVM2), and lifts method bodies back to readable AS3 pseudocode via operand-stack abstract interpretation.

At a glance

Commands

disrobe as3 disasm movie.swf --out out/
disrobe as3 tags movie.swf

disasm walks every DoABC and DoABCDefine tag, emits a per-instruction AVM2 listing as <label>.disasm.txt beside the JSON, and reconstructs class skeletons with lifted method bodies as <label>.source.as3. tags lists every tag in the SWF: TagCode, byte offset, and payload size.

Output shape (illustrative):

as3 disasm: OK
  input:        movie.swf
  swf version:  10
  abc blocks:   2
  classes:      6
  methods:      24
  instructions: 512
  source files: 2
  disasm files: 2
  out dir:      ./out
  manifest:     ./out/manifest.json

Coverage and fidelity

The source lifter reconstructs class skeletons with expressions, calls, loops, conditionals, forward lookupswitch regions, exception regions, and residual goto control flow by abstractly interpreting the operand stack. At each tracked forward lookupswitch join, it compares the stack height and values from every predecessor. Equal-height predecessors preserve an identical value or produce a named merge value and mark the method partial. Conflicting heights keep the raw control-flow form instead of selecting a value from the last case visited. A /// DR-AS3-PARTIAL: line identifies an unsupported opcode, opaque operand, dropped code, or internal control-flow residue detected by the lifter. The same line also marks a method or constructor body that failed to lift, followed by the lift error, for example an expression nested deeper than the lifter depth cap; such a body contains only that line. Absence of that line means only that these internal checks found none; it does not establish independent semantic or reference equivalence.

disrobe fingerprints commercial AS3 obfuscators (secureSWF, DoSWF, Kindi, Irrfuscator, swfLock) and flags techniques: string encryption, name mangling, control-flow flattening, register and stack shuffle, string-pool-rebuild candidates. Each finding carries a confidence score.

Limits

• Obfuscator handling is detection only. No decryption, pool rebuild, or unflattening is performed.
• ABC erases local variable names (non-parameter slots surface as loc{n}) and the compiler erases generics before ABC. Both are hard ceilings.
• FFDec is the mature full Flash decompiler and goes further on source-level recovery; disrobe covers SWF parsing and AVM2 disassembly as part of its chain pass, not as a Flash-decompiler replacement.

Mobile (Hermes / Flutter)

disrobe detects the runtime inside a mobile package, extracts React Native and other bundles, lifts Hermes bytecode to a JavaScript surface, and recovers Dart source or disassembles the ARM64 AOT snapshot from Flutter artifacts.

At a glance

Commands

disrobe mobile detect app.apk
disrobe mobile extract app.apk --out bundles/
disrobe mobile hermes index.android.bundle --out disasm/
disrobe mobile flutter libapp.so --out layout.json

disrobe hermes decompile index.android.bundle --out surface/
disrobe hermes disasm index.android.bundle --out disasm/
disrobe hermes info index.android.bundle

disrobe flutter dump libapp.so --out layout.json
disrobe flutter dump libflutter.so --format json --engine-symbol-map engine-symbols.json
disrobe flutter decompile libapp.so --out estimate.json
disrobe flutter kernel app.dill --out kernel.json
disrobe flutter disasm libapp.so --emit-listing
disrobe flutter map obfuscation_map.json --out map.json
disrobe flutter inventory libapp.so --out inventory.json
disrobe flutter inventory-standalone vm_data vm_instructions isolate_data isolate_instructions --out inventory.json

mobile detect classifies the package; mobile extract pulls bundles out of the container. It writes a manifest.json for React Native, Flutter, Cordova/Capacitor, NativeScript, and Xamarin extraction; Android APK/Dex and Android bundle paths write child files directly without a manifest.

hermes decompile lifts each function back to pseudo-JavaScript. hermes disasm emits a per-function summary without a JS surface. Pass --function <INDEX_OR_NAME> to select a zero-based index or exact function name, and add --json to receive the same instruction list as a structured document. Duplicate names require an index. hermes info prints the version, function count, string count, and identifier count.

flutter dump reports the four Dart snapshot sections and their sizes. With --format, an optional --engine-symbol-map accepts the versioned disrobe.flutter.engine-symbol-map JSON format. Disrobe applies those names only when the map's GNU build ID matches the ELF input and every address lies inside an image segment. The parser caps the map at 1 MiB and 10,000 unique addresses. flutter map parses a Flutter obfuscation_map.json into a typed original-to-obfuscated lookup.

{
  "format": "disrobe.flutter.engine-symbol-map",
  "version": 1,
  "identity": {
    "kind": "elf-build-id",
    "value": "b71885094a73117bf90d3cfa05824129"
  },
  "symbols": [
    { "address": 4096, "name": "Dart_Invoke" }
  ]
}

address is an unsigned virtual address in the input image, not a file offset or image-relative offset. Addresses must be unique. A validated external entry replaces a symbol-table entry at the same address; all other local symbols remain. JSON exports record the map path, format, and matched build ID in provenance. The same map can be supplied to a single-file automatic run with disrobe auto <input> --format json --engine-symbol-map <map>.

Output shapes below are illustrative.

hermes decompile: OK
  input:        index.android.bundle
  hermes ver:   96
  functions:    8
  with body:    8
  identifiers:  24
  strings:      12
  opcode cov:   100.0% (312 reconstructed / 0 fallback)
  if/loop/try:  3/2/1
  source:       ./out/index.android.bundle-hermes/index.android.bundle.js
  manifest:     ./out/index.android.bundle-hermes/manifest.json

flutter kernel: OK
  input:        app.dill
  format ver:   130
  libraries:    3
  classes:      8
  procedures:   21
  fields:       14
  bodies:       21 recovered (byte-exact Dart source from the kernel source table)
  strings:      112
  wrote:        ./out/app-dart-kernel.json
  dart source:  ./out/app-dart-kernel.recovered.dart

Coverage and fidelity

decompile reads the header of Hermes bytecode versions v60 through v96 against the documented layout. Lifting each function back to pseudo-JavaScript is graded against builds of one sample by the real Hermes compiler at v62, v71, v74, v76, v83, v84, v89, and v96, each through the same JavaScript-engine behavior comparison; other versions in the v60-v96 band parse but are not graded against a real compiler. On a hermesc-built HBC v96 sample (8 functions, CI-gated) every function lifts at 0 fallback opcodes. A non-redistributable 66 MiB production bundle parsed the 122,633-function table with no parse failure (measured locally, not CI-gated).

Two distinct recovery paths cover two distinct Flutter artifacts.

Corpus provenance: self-authored sample. disrobe_sample/ is self-authored: Flutter stable SDK, bundled Dart SDK 3.12.2 (windows_x64), kernel format version 130/132, gen_snapshot android-arm64-release in product mode with no DWARF. Its source, disrobe_aot_sample.dart, exercises:

• Classes with final fields, a const constructor, a computed getter, and an instance method that returns a new instance of its own class
• A top-level recursive function and sequential if/return control flow
• Nullable types with ?? and ?., string interpolation, a for-in loop over a List, and a non-capturing lambda passed to .where()

It does not exercise async or generator functions, a user-defined generic class or function, a closure that captures an enclosing variable, extension methods, mixins, Future/Stream chains, or build_runner-generated code, so recovery of those constructs is untested.

Corpus provenance: obfuscated builds. pinned_graph_fixture/ is a second self-authored source built three times by the real flutter build apk --release toolchain (Flutter 3.44.6, Dart 3.12.2): plain, with every class and field renamed, and with --obfuscate --split-debug-info=build/symbols. The obfuscated build is graded, not merely present: obfuscated_flutter_build_reports_structure_only and obfuscated_auto_mode_never_claims_source_names require the declaration graph to report StructureOnly with opaque names and never claim a source name it does not have.

A real third-party sample, local only. crates/disrobe-pass-mobile/tests/real_flutter_rustdesk.rs fetches RustDesk 1.4.9's arm64-v8a release APK (AGPL-3.0, 26,871,021 bytes, sha256 pinned in the test and in corpus/mobile/flutter/MANIFEST.toml) and extracts lib/arm64-v8a/libapp.so and libflutter.so from the zip in memory; the APK itself is never committed. Reproduce it with:

mkdir -p "$TMPDIR/disrobe-scratch/rustdesk-flutter-cache"
curl -sSL -o "$TMPDIR/disrobe-scratch/rustdesk-flutter-cache/rustdesk-1.4.9-aarch64-signed.apk" \
  "https://github.com/rustdesk/rustdesk/releases/download/1.4.9/rustdesk-1.4.9-aarch64-signed.apk"
cargo test -p disrobe-pass-mobile --test real_flutter_rustdesk

This result is [local]: no CI job populates the cache, so tests/optional.toml lists the sample and a run without it writes a not-measured record instead of passing; without that entry an absent cache fails the test by name. On this real build the RAW static path recovers

10,351 class-name strings, 28,952 method-name strings, and 1,489 library URIs, each cross-checked against an independent whole-file package:*.dart string scan that finds 1,271 of its own. Every one of those counts is pinned by equality in the test, so a figure that moves fails the gate rather than drifting silently. RustDesk's Dart snapshot falls outside the pinned Dart 3.12.2 android-arm64 product tuple, so the declaration-graph path (flutter inventory) reports unsupported-version on it rather than guessing at a cluster layout it has no pin for.

Dart kernel (.dill / kernel_blob.bin). A kernel is the serialized Dart AST. disrobe parses the kernel binary format (magic 0x90abcdef): the footer component index, the string table, per-library class and procedure offset tables, and the embedded UriSource table. From the source table it recovers byte-exact original Dart bodies, sliced per procedure by the kernel file offsets. The recovered .dart source file is always written beside the JSON without needing --emit-source.

ARM64 AOT snapshot (libapp.so). The AOT snapshot is ordinary AArch64 machine code. disrobe locates the four _kDart*Snapshot* symbols, recovers class and method names from the isolate-data string table, scans frame prologues to bound functions, and disassembles each body to readable instructions with resolved direct-call and branch targets. flutter decompile also recovers the class table estimate, library URIs, and a string pool from the isolate image.

Beyond the disassembly, the release ARM64 path recovers class membership and method-to-class attribution, and lifts each function to nested if/else/while pseudocode through the shared structurer. That lift is gated by a source-free CFG round-trip: when the recovered structure does not round-trip to the same control-flow graph, the function falls back to a flat call list rather than presenting a shape the graph does not support.

Each call in that pseudocode carries its reconstructed argument list. disrobe tracks the Dart argument registers, the Dart stack slots that hold arguments past the register file, and the caller's frame slots across the call sequence, then renders each argument as an expression: an immediate, a null or boolean read from the null register, a value produced by an earlier call, a field load by offset, or an object-pool entry. A tail call renders the same way, as a returned call. Pool entries are inlined as literals. On a pinned snapshot version disrobe deserializes the object pool per slot, so a call that loads a string, a double, an integer, a list, or a declared name reads that value back at the call site. Inlining is depth-bounded and size-bounded, and a cyclic pool reference stops at the placeholder. An argument the tracker cannot resolve renders as ?, and an argument produced by a control-flow merge always renders as ? rather than one branch's value. A call whose arguments cannot be recovered at all keeps the opaque (...) form.

Declaration graph (flutter inventory / flutter inventory-standalone). The clustered object graph inside the snapshot data blobs carries the full library, class, method, and field declarations, keyed to the exact Dart SDK snapshot version and feature tuple that serialized them. disrobe reads that graph directly for the pinned Dart 3.12.2 Android arm64 build (both the plain product tuple and the --split-debug-info DWARF tuple): every class, method with its parameter count, and instance field name, cross-checked on real flutter build apk --release output against the snapshot's own cluster-header totals. A snapshot compatibility hash outside the pinned set reports unsupported-version rather than guessing at cluster offsets.

Detected runtimes

disrobe mobile detect|extract routes the packaged JavaScript and .NET runtimes out of an .apk or .ipa: React Native Hermes, Flutter, Xamarin, Cordova, Capacitor, and NativeScript, each handed to the pass that reads it.

Limits

• The Hermes path is a structured lifter, not a full decompiler. Variadic call arguments are marked <arg?> where the Hermes frame-register layout is not modeled; unreconstructed opcodes appear in disasm form inline.
• Exact Dart source for an optimized AOT function is not byte-recoverable from the machine code (register allocation and inlining are lossy). Use the kernel path for source bodies.
• Instance field names are not recovered by the ARM64 disassembly path (flutter decompile / flutter disasm); they are only reachable through the declaration graph (flutter inventory), and only on a pinned Dart SDK snapshot version.
• The declaration graph path recovers names, not values or optimized-body source; it never guesses a cluster layout for a snapshot compatibility hash it does not have pinned.

Python pickle

disrobe analyzes pickles statically so you can audit what a stream would do on load before it ever touches a real interpreter. It never unpickles, never calls __reduce__, never executes a REDUCE opcode.

Pickle is a code-execution format wearing a data format's clothes. Unpickling a crafted stream runs arbitrary code through __reduce__ / REDUCE, which makes weaponized .pkl and .pt files a recurring ML supply-chain vector.

At a glance

Commands

disrobe pickle disasm model.pkl --out trace.txt
disrobe pickle decompile model.pkl --out graph.py
disrobe pickle safety model.pkl
disrobe pickle trace model.pkl
disrobe pickle polyglot suspicious.bin
disrobe pickle ml-detect model.bin

trace walks the opcode stream and reconstructs the object graph the same way a real unpickler would build it, but every operation is symbolic. A GLOBAL records a (module, name) reference without importing the module; a REDUCE records "this callable would be applied to these arguments" without calling it; the memo, stack, and STOP result are all inert values. The output is the full graph (objects, memo, resolved globals, reduce count) with nothing executed. decompile renders that graph back to equivalent Python assignments.

polyglot catches the trick of hiding a malicious pickle inside a zip, zip64, or tar that a model loader will open as an archive and then unpickle. ml-detect recognizes PyTorch, TorchScript, and numpy containers and lists every embedded pickle stream, so a multi-file .pt archive is enumerated rather than treated as one opaque blob.

The same static suite is available as a library. Nothing is ever unpickled.

from __future__ import annotations

from pathlib import Path

import disrobe
from disrobe import PickleSafety

payload: bytes = Path("model.pkl").read_bytes()
safety: PickleSafety = disrobe.pickle_safety(payload)

severity: str | None = safety.severity
finding_count: int = safety.finding_count
reduce_count: int | None = safety.reduce_count
listing: str = disrobe.pickle_disasm(payload)

Coverage and fidelity

The graph the symbolic VM builds is rendered back to re-executable Python, and the reduce protocol's listitems and dictitems extension streams are modeled, not dropped. That is what lets collections.deque, OrderedDict, and defaultdict reconstruct: a REDUCE that builds the container is followed by the item stream, which disrobe re-emits through extend/__setitem__ helpers so the rebuilt object is populated exactly as the original was, without ever running the pickle.

The reconstruction benchmark covers generated fixtures across protocols 0 through 5: primitives, containers, cyclic and shared references, __reduce__ objects, and the collection types above. CPython loads each original fixture and executes its reconstructed program; 470 / 470 reconstructed fixtures pass the comparison checks. These include type and value comparisons and identity checks for shared and cyclic container cases. These are trusted test fixtures. Disrobe's inspection and reconstruction commands do not execute their inputs.

disrobe pickle safety grades a stream into one of three severity tiers. Each finding is tagged with a confidence tier so a reviewer can tell a certain hit from an inference.

The report also surfaces the resolved import list, the REDUCE count, and the unused-memo count (a common obfuscation tell), so a triage decision does not require reading the raw opcodes.

Limits

• Nothing is executed, by design: a GLOBAL records a reference without importing the module and a REDUCE records an application without calling it. The report tells you what a load would do; it is not the loaded object.
• Reconstruction may require a runtime copyreg registry, out-of-band buffers, persistent IDs, or importable modules that the stream does not contain. The 470-fixture benchmark does not cover those dependencies.
• A pattern_inferred or context_dependent finding is a shape, not a signature match. Treat it as a lead for review rather than a verdict.

Shell / PowerShell

disrobe deobfuscates supported PowerShell, Bash, Batch, VBScript, and VBA patterns. Its recovery paths cover the families listed below, VBA source from Office documents, VBA p-code with stomp detection, Excel 4.0 (XLM) macro formulas, and PDF maldoc analysis.

At a glance

Commands

disrobe shell deob payload.ps1 --out recovered.ps1
disrobe shell detect payload.ps1
disrobe shell deob book.xls                    # Excel 4.0 macro-sheet formulas from BIFF8 or BIFF12
disrobe auto payload.ps1 --out recovered/      # detect the dialect and route obfuscated shell automatically

deob auto-detects the dialect and obfuscator family, applies the right reversal, and writes the recovered source plus a manifest.json. detect reports the dialect, family, confidence score, and detection markers without writing output.

Output shape (illustrative):

shell deob: OK
  input:        payload.ps1
  dialect:      PowerShell
  family:       InvokeObfuscationToken
  confidence:   0.94
  markers:      ["iex", "token-replace"]
  wrote:        ./out/payload.deob.ps1
  manifest:     ./out/payload.deob.manifest.json

Coverage and fidelity

VBA source and p-code

From a .docm / .xlsm / .bin Office container, disrobe parses the dir stream (MS-OVBA), maps each module to its stream and TextOffset, and MS-OVBA-decompresses the CompressedSourceCode at that offset to emit the original .bas / .cls text per module (multi-chunk compression and CopyToken bit-count edges handled). Validated against real Word and Excel documents authored via COM, byte-for-byte against the known module text.

The p-code decoder covers a 264-opcode table across VBA5, VBA6, and VBA7 in 32-bit and 64-bit forms, with identifier resolution. Tests compare its disassembly with pcodedmp dumps. Accepted differences are limited to four pinned classes of pcodedmp 1.2.6 defects: a shifted identifier-table index, an unresolved object name, a truncated declaration parameter chain, and a missing user-defined type name.

Source recovery has a separate comparison against the authored .bas files, preserving line order, operators, and operand order. The two committed modules recover 71 of 71 lines for SourceProbe and 552 of 552 for EdgeCases. These counts are enforced by regression tests. VBA-stomping detection compares compiled p-code with stored source, flags divergence, and recovers the compiled behavior from p-code.

Excel 4.0 (XLM) macros

disrobe shell deob book.xls recovers Excel 4.0 macro-sheet formulas from a BIFF8 (.xls) or BIFF12 (.xlsb) workbook. It decodes the Ptg RPN token stream back to formula text over the full Ftab and Cetab function tables, resolves shared-formula masters to per-cell absolute references, and flags the built-in auto-run names (Auto_Open, Auto_Close, Auto_Activate, Auto_Deactivate) as execution entry points, so a =EXEC("...") or =FORMULA(...) macro reads back in full. A token the decoder does not recognize is emitted as an explicit unknown marker, not as a guessed formula. Recovery is graded against hand-built BIFF fixtures with known formulas, covering BIFF12's wider reference fields, shared-formula relative-to-absolute resolution, and the Auto_Open entry point (xlm_fixtures.rs).

Haxe HashLink, Perl, R, and Tcl

The same scriptlang pass covers four runtimes that ship compiled or packaged rather than as plain source.

HashLink (.hl). The register bytecode is parsed byte-exact: type table, functions, natives, globals, and constants. Function bodies disassemble with reconstructed signatures, and source class and method names are recovered and graded against the original .hx. Haxe compiled to JavaScript or SWF routes to the JS and Flash stacks instead.

Perl. A B::Concise op-tree is read back, and ByteLoader-encoded scripts are decoded.

R. .rds serialized objects round-trip.

Tcl. A starkit extracts byte-identically.

PDF maldoc analysis

The shell pass carries a PDF analyzer (disrobe_pass_shell::analyze_pdf) for document-borne malware. It loads a PDF through both cross-reference forms (the classic xref table and cross-reference streams), transparently decrypts a Standard-security-handler document that uses RC4 or AESV2 under an empty user password (authenticating against /U per the PDF algorithms, with no password supplied), then walks the catalog, name trees, page annotations, and form fields to recover embedded JavaScript and every Launch, URI, GoToR, SubmitForm, ImportData, and EmbeddedFile action with its resolved target. Hex-escaped names, split or concatenated JavaScript strings, and Flate / LZW / ASCII85 filter chains are decoded along the way, and every decompression is bomb-bounded. It is graded against hand-crafted PDF fixtures that plant a known marker behind each path (classic-table and xref-stream JavaScript, RC4 and AESV2 empty-password decrypt, a launch target, an embedded file, name-tree and additional-action scripts), plus an RC4 published-vector check and an empty-password authentication test (pdf_fixtures.rs).

Limits

The XLM decoder is graded three ways that do not share a reading of the specification. Workbooks authored by real Microsoft Excel 16.0 are decoded and compared against the formulas as authored, across 99 cells in both directions so that a missing cell and an unexpected extra cell each fail, with every fixture pinned by length and sha256; a control flips one byte of the real =SUM(1,2) Ptg stream and must be rejected. The function tables are graded against an independent decoder's published snapshot, agreeing on 476 shared Ftab ids and 396 shared Cetab ids, which is what catches the wrong-index case where every CALL and EXEC an analyst reads would be renamed. Third, XLMMacroDeobfuscator 0.2.7 reads the same committed workbooks at test time and its formula text is compared cell by cell against the recovery, agreeing on 44 cells across two workbooks once three formatting conventions are folded: the reference renders a whole number as 1.0, spaces its argument separators, and quotes sheet names. Folding is string-aware, so a comma or a quote inside a literal is left alone, and the folding rules cannot rewrite a function name, a cell reference or a digit. Two of the four committed workbooks are outside that leg because the reference cannot read them: it stops at a ptgFuncVar function id it does not carry, and it refuses the Ftab probe sheet that deliberately carries index 0x00FF. Both refusals are recorded as named constants with their exact message, so a refusal that changes is a deliberate edit rather than a silent pass, and neither workbook is counted as graded.

A fourth leg grades the function tables at formula level rather than at name-table level. Each of the 476 Ftab and 396 Cetab ids is set into a real Excel-authored workbook, at four call sites that already exist in that workbook plus two synthesized call sites shaped to take four or five arguments, and the resulting file is read back by XLMMacroDeobfuscator 0.2.7. Of the 476 Ftab ids, 359 come back named by the reference and agree with the recovery; the remaining 117 are ids the reference's own parser table does not carry a name for at all, so they stay graded only against the name-table leg. All 396 Cetab ids come back named and agree. One divergence is recorded: 0x005C is SERIES and 0x019E is SERIESSUM, and the reference names both SERIESSUM, folding two distinct entries onto one name. Two mutation tests demonstrate the leg catches a wrong index rather than passing regardless of one: shifting 0x006E (the index the committed workbook already calls through EXEC) to its neighbor is reported, and so is shifting 0x0125, an id only the tables exercise. Two further tests walk the BIFF8 record and Ptg-class space each committed workbook actually carries, and state a reason for every declared record type and Ptg class no committed workbook carries.

Of the four committed workbooks, real_xlm_excel16.xls and real_xlm_ptgspread.xls are graded against formulas read back from real Microsoft Excel 16.0, not retyped from the byte layout. bench_biff12.xlsb and ftab_probe.xls are real Excel-produced bytes whose expected formulas are authored to the specification rather than confirmed by an Excel readback; both fixtures are recorded that way in the manifest test data reads, and the ftab-index sweep above grades every function table entry those two carry independently of that distinction, since it writes its own probe workbooks rather than trusting either fixture's expected values.

Two limits remain. Specification-assembled fixtures still cover shapes Excel will not author, and for those the same reading of the specification produces both the bytes and the expectation, so they catch a decoder that contradicts the specification but not a misreading shared by both sides. Breadth over arbitrary real-world workbooks is not graded, because the Excel-authored coverage comes from one producer version.

The VBA line-recovery measurement covers the two committed modules described above. Unrecognized XLM Ptg tokens appear as explicit unknown markers in the recovered formula.

Containers and archives

Before disrobe can decompile anything, it often has to get inside a container. The disrobe-binfmt layer detects every format below. Most use the generic member-byte extractor; LUKS1 uses a dedicated raw-volume-key route and reports a typed key wall when no key is supplied. Auto-detection, recursive chaining through nested layers, and shared zip-slip and decompression-bomb guards remain in effect. A committed input drives 30 generic extractors to member bytes that match an independent extractor (bsdtar, 7-Zip or the format's own decompressor), and the tracked LUKS1 fixture separately proves byte-exact decryption into the VHD extractor.

At a glance

Supported formats

Commands

Most extraction happens implicitly inside disrobe auto, which detects a container, extracts it, and recurses into the contents. Archive-shaped inputs are also available directly:

disrobe py extract package.whl --out extracted/
disrobe auto firmware-dir/ --out extracted/ --batch-max-depth 6
disrobe extract crash.dmp --out carved/
disrobe extract volume.luks --luks1-raw-volume-key-file volume.key --out decrypted/
disrobe extract volume.luks --luks1-raw-volume-key-file - --out decrypted/

Directory inputs are batch-processed recursively; --batch-max-depth limits directory descent. Container nesting inside a detected artifact is governed by --max-depth (default 8).

For ZIP, TAR, ARC, RAR, ARJ, LZH, StuffIt, Inno Setup, InstallShield, RPM, AppImage, .NET single-file, EROFS, and UEFI firmware-volume inputs, disrobe extract and disrobe auto apply the same default quota policy and retain the same ordered, byte-identical archive members. Extractor-generated sidecars are tagged separately and remain direct-only; an archive-controlled name such as .disrobe-user.bin remains an archive member. When an independently indexed member has an unsafe path, exceeds a quota, or cannot be decoded, extraction skips it and continues with trustworthy siblings. The direct result records the ordered reasons in integrity_violations; the automatic chain writes the ordered prefix that fits the 64 KiB container.refusals bound. container.refusals_total, container.refusals_omitted, and container.refusals_truncated make any truncation explicit. A malformed directory or table that cannot identify the next member safely still refuses the whole container.

Coverage and fidelity

Windows crash dumps

disrobe extract crash.dmp (or disrobe auto crash.dmp) carves the loaded PE modules out of a Windows minidump. It parses the stream directory, reads the module and memory lists, and for each module rebuilds an in-memory PE image by copying whatever memory the dump actually captured into a buffer at the correct RVAs, rewriting each section's file-offset field to match its virtual address so downstream PE parsers read the result as a well-formed image. Coverage is reported per page: the summary records how many bytes were recovered, which ranges the dump truncated, and which it never captured, with a reason for each gap, so a partially captured module is never presented as complete. The carve is graded by wrapping a real on-disk PE into a minidump and confirming the carved .text comes back byte-identical (minidump_real_pe.rs); each carved module and a .disrobe-minidump.json coverage summary land in the output directory.

Deno eszip archives

The disrobe-binfmt eszip reader (disrobe_binfmt::containers::eszip) parses a Deno eszip module-graph archive, versions 2 through 2.3, including one embedded inside a deno compile standalone executable, and reconstructs the module graph: each module's specifier, kind, and source bytes, plus redirects and npm specifiers, with per-module source-hash verification that drops any module whose stored hash does not match. It is exercised by a build-then-parse round-trip that also confirms a corrupted source hash is rejected.

Safety guards

Every extractor shares the quota machinery in crates/disrobe-binfmt/src/quota.rs:

• Per-entry size cap and aggregate size cap defuse decompression bombs.
• Recursion-depth cap defuses container-in-container bombs.
• Zip-slip path sanitization (sanitize_entry_path): every entry path is sanitized so no extraction can escape the output directory, on every format.

Bypasses of any of these are treated as security issues; see the security policy.

Limits

Where a format's payload is not decoded in-tree, the table above names it per entry rather than implying full extraction:

• LUKS1 recovery is limited to aes-cbc-plain with a caller-supplied raw volume key. Passphrases and keyslot unlocking, XTS modes, and LUKS2 are not accepted by this route. A detected keyless LUKS1 header produces a successful typed wall. A detached LUKS1 header is refused until its separately stored encrypted payload is supplied. VeraCrypt and TrueCrypt may not be identifiable without a key, and headerless dm-crypt has no on-disk header to detect.
• RAR 2.9/3.x members carry their transforms as RARVM programs. disrobe identifies a program by exact length and CRC-32 and runs a native transform for the canonical delta, x86 e8, x86 e8/e9, itanium, rgb and audio programs. It does not interpret RARVM bytecode, so a member carrying any other program is refused by name. The corpus grades the delta and x86 e8/e9 transforms against a real archive. The plain x86 e8, itanium, rgb and audio transforms have no real archive in the corpus yet, so their output rests on the CRC-32 check every decoded member passes and on known-answer tests rather than on a graded fixture. The crate publishes this gap as RAR3_FILTERS_WITHOUT_REAL_ARTIFACT and RAR3_FILTER_COVERAGE_NOTE in disrobe_binfmt::containers::rar. Encrypted members (the RAR4 LHD_PASSWORD flag or a RAR5 file-encryption record), members split across volumes (the RAR4 LHD_SPLIT_BEFORE and LHD_SPLIT_AFTER flags or the RAR5 volume-continuation header flags), and solid state carried from an earlier entry are refused by name, and the other members still extract. A stored member whose packed size differs from its declared unpacked size, and any member whose recovered length differs from its header, is refused rather than written short.
• Cabinet (.cab and MSI-embedded) folders are decoded once each, in member-offset order, for stored, MSZIP, LZX, and LZMS folders, and each data block's checksum is verified when the cabinet sets one. Quantum folders, members that continue into another cabinet of a set, and members whose name appears more than once in the cabinet are refused by name.
• In a solid 7z block, a member refused for its path is still read past, so the members after it keep their own bytes.
• Inno Setup follows finite version profiles from the loader through both metadata blocks, file and data records, solid groups, filters, and checksums. Unsupported profiles and encrypted content without a secret refuse by name.
• ARC methods 10-11 are refused.
• StuffIt 5 containers are parsed and their forks decode in tree, but extraction still carves the archive verbatim rather than writing each fork, so disrobe auto recovers a StuffIt 5 archive as one blob. Classic StuffIt forks are unaffected and extract per fork.
• OTP-AES Airoha firmware is an information-theoretic wall and is carved verbatim.
• A minidump only contains the memory it captured. Truncated and never-captured ranges are reported with a reason per gap instead of being filled in.

Global flags

These flags are accepted on every subcommand (they are declared global = true on the root parser).

Output and verbosity

Execution control

Debug tracing

Debug tracing is sample-sensitive. Only values emitted through explicitly guarded key/value events pass through the masking guard. After trimming surrounding whitespace, it masks a value only when the value is at least 20 characters, contains only ASCII letters, digits, _, -, +, /, or =, and mixes at least two of uppercase letters, lowercase letters, and digits. When the guard triggers, it preserves the first four trimmed characters and emits …<redacted N chars>, using a single Unicode ellipsis and the full trimmed character count. Ordinary messages, unguarded values, labels, and byte previews do not pass through this guard and may expose sample-derived data in either format. Review debug logs before sharing them.

This does not change scanner output: scan and frisk report full matched values by default. Pass --redact to replace detected secrets with stable truncated SHA-256 tokens in shareable output. The same setting can be stored as output.redact = true in .disrobe.toml.

Metadata sidecar flags

The metadata bundle flags are also global. They are accepted everywhere, but only the commands listed in which commands write a bundle act on them; every other subcommand ignores them, and disrobe auto rejects them with DR-CLI-0843. See metadata sidecar and provenance for the complete pack/category model. Summary:

The authorization gate

--i-have-authorization is the explicit assertion used by legally sensitive paths that expose an authorization gate. The decryption-keys metadata category refuses without it (DR-CLI-0420); language-specific commercial-protector paths document their own gate behavior. Passing the flag is your assertion that you are authorized to analyze the input under the statutory framing in Legal.

Command reference

disrobe <command> --help is authoritative for the binary you are running; the surface changes with optional build features. This page maps the public command surface: how commands are shaped, the command groups and integrations, then every command by ecosystem. Output paths and --emit support are command-specific; the global flags page covers the options parsed at the top level.

Recovery support varies by format, version and backend. The language guides list supported variants and limitations; chain reports identify unsupported constructs in your input.

Command shape

Ecosystem command families nest an action:

disrobe <pass> <action> <input> [--out <path>] [flags]

Other operations take their arguments directly, for example auto, scan, query, taint, extract, webview and report. Unambiguous prefixes resolve: disrobe dec ... works when only one subcommand starts with dec.

disrobe --help                # every subcommand
disrobe <pass> --help         # actions and flags for one pass, e.g. `disrobe py --help`
disrobe passes                # direct recovery families plus auto-chain pass IDs
disrobe catalog [ecosystem]   # supported families and recovery tiers
disrobe explain DR-CLI-0030   # look up any error code

The standard recovery loop:

disrobe auto input.bin --out recovered/ --capture-stages
disrobe context --out recovered/

Output formats

The CLI accepts these global output flags. A command can reject a format that does not fit its output contract:

disrobe scan firmware.bin --sarif > findings.sarif

detect also supports JSON, NDJSON and SARIF. Its structured output includes each matching detector, confidence score and signature markers. SARIF records use note severity and identify the input file; a format detection alone does not establish a vulnerability.

Command groups

Public integrations

Nested commands are listed by ecosystem below. For measurements and their limits, start with the evidence index.

Python

JavaScript / WebAssembly

JVM / Android / .NET

Native

Other languages

Chain, envelope, and forensics

Workspace and meta

Run the examples

Watch the chaptered CLI walkthrough and read its command transcript. The recording shows native unpacking, indicator extraction, automatic recovery, Lua, WebAssembly, and recovered source.

The feature capture records twelve commands and their output. It extracts three known indicators with their byte offsets, round-trips two ZIP members, recovers all 73,160 original code bytes from a UPX-packed greeting, decodes an APK manifest, compares a recovered Lua greeting with its baseline, and verifies an envelope before and after a one-byte payload change.

From the repository root, reproduce it with a full CLI build, Python 3.14 and Lua 5.1:

node docs/demo/capture-features.mjs --binary /path/to/disrobe --python /path/to/python --lua /path/to/lua

The Wasm quickstart, Python project example, and service examples cover automatic recovery, project briefs and the MCP, HTTP, gRPC and LSP interfaces. Each record names its inputs and binary so results can be compared across builds.

The public-collection example retrieves four archived example.org URLs from the Common Crawl index. It queries one archive, caps output at ten URLs, and makes no requests to the archived pages.

Project configuration (.disrobe.toml)

disrobe reads an optional .disrobe.toml so a project can set its own defaults instead of repeating the same global flags on every invocation.

Resolution order

Values are merged from three layers, lowest precedence first:

1. Built-in defaults: what disrobe does with no config and no flags.
2. .disrobe.toml: the discovered or explicitly named config file.
3. CLI flags: anything you type on the command line.

A flag you actually pass always wins over the config file; a flag you leave off falls back to the config value, and only then to the built-in default. "Did the user pass this flag" is decided by clap's value source, so there is no ambiguity between --json being absent and being false.

Discovery

• With --config <PATH>, that file is loaded. A missing path is a hard error (DR-CLI-0332).
• Without --config, disrobe walks up from the current working directory looking for .disrobe.toml, exactly the way cargo finds Cargo.toml. The first one found wins. If none exists, the built-in defaults are used.

Malformed TOML (DR-CLI-0330) and unknown keys are hard errors: a typo fails fast instead of being silently ignored.

The config command

Schema

[output]
dir = "out"                  # default output directory for chain/auto runs
emit = ["source", "manifest"] # default --emit kinds where a pass accepts them
json = false                 # default machine-output toggles (CLI flags still override)
ndjson = false
sarif = false
color = "auto"               # auto | always | never
progress = "auto"            # auto | always | never
verbosity = "warn"           # warn | info | debug | trace
quiet = false

[execution]
threads = 8                  # worker pool size (default: detected CPU count)
force = false
in_place = false
no_cache = false
cache_dir = "/var/cache/disrobe"  # content-addressed .dr envelope cache (default: OS cache dir)
dry_run = false
seed = 42                    # RNG seed for non-deterministic backends
max_depth = 8                # default chain depth for `auto`

[backends]
py = "native"                # native (in-tree CPython 3.8..3.15 engine; the only supported value)
jvm = "cfr"                  # cfr | vineflower | procyon | jadx
dotnet = "ilspy"             # ilspy | dnspy | dnspyex | de4dot
wasm = "wat"                 # json | rust | ts | wat | c
lua = "native"

[passes]
enable = ["pyarmor.unpack", "py.decompile"]  # restrict chain runs to these passes
disable = ["native.packer-unpack"]           # never run these passes

All tables and all keys are optional. An empty file is valid and resolves to the built-in defaults.

Batch directory processing

disrobe auto accepts a directory as well as a single file. Point it at a directory and it walks the tree, runs the auto-chain on every file, writes each file's outputs under out/<relative-stem>/, and emits one aggregate out/manifest.json.

Single-file behavior is unchanged: disrobe auto <file> still writes chain.json + recovery.json into a single out dir.

Usage

disrobe auto ./samples
disrobe auto ./samples --out ./out/triage --include '**/*.pyc' --exclude '*_test.*' --jobs 4

If --out is omitted, batch output lands in ./out/<dir-name>-batch/.

Flags (batch-only)

The --max-depth <N> (default 8), --capture-stages, --emit recovery, --timings, and global flags continue to apply. --max-depth is the per-file chain depth; --batch-max-depth is the directory recursion depth.

Glob syntax

Globs match against the slash-normalized path relative to the root.

A bare pattern with no / (for example *.bin) also matches files in subdirectories, so the common "all .bin files" case works without writing **/.

manifest.json

Schema disrobe.batch.manifest/v2:

{
  "schema": "disrobe.batch.manifest/v2",
  "tool_version": "0.10.5",
  "root": "samples",
  "out_root": "out/samples-batch",
  "chain": "auto:8",
  "summary": { "processed": 12, "recovered": 9, "detect_only": 2, "errors": 1 },
  "entries": [
    {
      "input": "samples/app.pyc",
      "relative": "app.pyc",
      "size": 4096,
      "detected_format": "Python",
      "chain": ["py.decompile"],
      "verdict": "Complete",
      "recovery_score": 0.67,
      "output_dir": "out/samples-batch/app.pyc",
      "error": null
    }
  ]
}

• recovery_score is the mean per-pass confidence-tier rank across the chain, normalized to [0, 1] (skeleton 0, partial 0.33, semantic 0.67, exact 1.0), or null when no pass ran.
• A file that fails (unreadable, or its chain errors) is recorded with a non-null error and counted under summary.errors; one bad file never aborts the batch.
• Files with no pass in their chain are counted as detect_only.
• The manifest records no duration and no worker count, so --jobs 1 and --jobs 4 over one directory write the same bytes. --timings writes run.json beside the manifest, with the start and end clocks, the worker count, the whole run's duration, and each file's duration, and a run.json in each file's directory with that file's per-node durations.

The human-readable summary line mirrors the manifest: N processed, M recovered, K detect-only, E errors.

Run reports (disrobe report)

disrobe report consolidates a completed run into a single forensic summary: input identity, chain topology, per-stage verdicts and recovery scores, the layers that stopped short, the recovered-artifact inventory, a cited byte range and digest for every artifact the run read, and the steps that re-check each one. It is the read-side companion to auto and chain.

Usage

disrobe report ./out/sample-auto                 # a completed single-file run
disrobe report ./out/samples-batch               # a completed batch run
disrobe report ./malware.bin                     # raw input: runs auto first, then reports
disrobe report ./out/sample-auto --format markdown
disrobe report ./out/sample-auto --format html > report.html    # self-contained, offline
disrobe report ./out/sample-auto --format sarif > report.sarif

--out <DIR> chooses where a derived run is written when the target is a raw input or a raw directory. Without it the derived run lands in ./out/<stem>-auto/ or ./out/<name>-batch/ under the working directory. The flag has no effect when the target is already a completed run.

Target resolution

The single positional argument can be:

A run document that is missing, unreadable, or truncated stops the command with a typed error. Nothing is partly rendered.

The report a run writes

disrobe auto and disrobe chain write report.json into the output directory, beside chain.json, recovery.json, and anti-analysis.json. It holds the single-run document described below, so a run is citable without a second command. The document auto writes and the document disrobe report <out-dir> --format json prints are the same, except that the command's JSON adds a report_kind discriminator.

A batch run writes an aggregate report.json beside manifest.json; it is the same JSON document that disrobe report <batch-out> --format json prints. Each file also leaves its own single-run report.json in its per-file output directory.

Formats

--format text|json|markdown|html|sarif (default text). A global machine-output flag (--json, --ndjson, or --sarif) forces JSON output. --format sarif overrides that and renders SARIF.

• text: an aligned human report for the terminal.
• markdown: a report with tables, ready to paste into an issue or PR.
• json: the machine-readable disrobe.report/v2 document. It records no duration, no worker count, and no clock.
• html: a single self-contained HTML file (printed to stdout; redirect to a .html). CSS is inlined from the shared docs theme token file, with no JavaScript and no external/CDN reference, so it renders offline when double-clicked. Sections include input identity, a chain-topology flow, per-stage verdicts with generated recovery bars, a generated tier histogram, walls and failures, capabilities, recovered artifacts, the evidence table, the reproduction steps, and, when the input is still readable, defanged IOC plus behavior / MITRE ATT&CK tables. Every interpolated value is HTML-escaped, and the renderer uses no clock or randomness, so identical report data produces byte-stable HTML.
• sarif: a SARIF 2.1.0 log printed to stdout. See SARIF output.

Single-run report contents

• Input identity: path, size, BLAKE3, detected format chain, final format.
• Topology and verdict: linear or tree, and the overall chain verdict.
• Recovery score: the mean per-stage confidence-tier rank normalized to [0, 1], plus a tier label (skeleton / partial / semantic / exact).
• Tier histogram: exact / semantic / partial / skeleton counts.
• Per-stage table: index, pass id, confidence, score.
• Walls: every layer that stopped short, with the input it lacks.
• Capabilities: ATT&CK- and MBC-tagged rule matches with addresses and evidence scope. Text, JSON, markdown, HTML, and SARIF consume the same result.
• Failures: every layer that returned an error, with its message.
• Recovered-artifact inventory: the union of artifact names produced by the stages.
• Evidence: one cited entry per artifact the report read, with its digest and byte range.
• Reproduction: the command that rebuilds the report and the steps that re-check it.
• Notes: detect-only, skeleton-tier, and artifact-walk truncation caveats.

Batch report contents

• The aggregate counts (processed, recovered, detect-only, errors) and mean recovery score. The mean is null when no file carried a score.
• A per-file table: file, detected format, score, and status (recovered / detect-only / error).

A batch report aggregates per-file manifests and holds no analysis-target bytes. Its SARIF render therefore reports the STIX, MAEC, capability, and indicator blocks as unavailable, each with that reason.

Walls and failures

A wall is a layer that stopped because a named input is missing. A wall is not a failure and is never rendered as an error. Each wall records its kind, the node id, the stage index when the layer maps to one, the pass, the input format, the BLAKE3 and size of the artifact it could not advance, and a sentence naming what it lacked.

A layer that returned an error is recorded as a failure instead. A failure carries the node id, the stage index when the layer maps to one, the pass, the recorded message, and the BLAKE3 and size of its input.

When no individual node recorded a wall or a failure, the overall chain verdict still produces one wall against the root node if that verdict is stalled, cycle, cap-reached, dry-run, or fan-out-partial. A run that recovered nothing reports the wall rather than an empty success.

Evidence and digests

Every report cites the artifacts it read. An evidence entry carries a role, an artifact URI, a byte offset, a byte length, a BLAKE3 digest, and where that digest came from.

The roles are analysis-target, stage-input, stage-output, and recovered-artifact.

Only recovered artifacts read off disk carry recomputed-from-file. An artifact a dry run would have written, a file that is not on disk under the run directory, and a file that cannot be opened are each cited with unavailable and a reason rather than dropped from the report.

An artifact on disk is cited by a file:// URI, or by its percent-encoded relative path when the recorded path is relative. An intermediate the chain held in memory is cited as ni:///blake3;<digest>. That names the artifact a byte range indexes; it is not a file you can open.

Every evidence entry starts at byte offset 0 and spans the whole artifact. Sub-ranges inside the analysis target come from the indicator results in the SARIF render.

The recovered-artifact inventory combines the artifact names the stages recorded with the files under extracted/ in the run directory. That walk skips symbolic links, stops at directory depth 32, and stops after 4096 files. Either stop is recorded as a note in the report, naming what is not cited.

Reproduction steps

A single-run report carries the command that rebuilds it and the steps a third party follows to re-check it:

1. Hash the analysis target with BLAKE3 and compare it with input.blake3.
2. Hash each evidence entry marked recomputed-from-file and compare each digest with the recorded one.
3. Read each ni:///blake3; evidence entry as the digest of an intermediate the chain held in memory.
4. Re-run the reported command and compare the output.
5. Set SOURCE_DATE_EPOCH to a Unix timestamp to date the SARIF render and emit its STIX bundle; without it the render carries no clock.

When any entry carries no digest, a further step counts those entries and points at their unavailable_reason.

SARIF output

--format sarif prints a SARIF 2.1.0 log to stdout. Its $schema is the stable OASIS 2.1.0 Errata 01 URI, and the CLI test suite validates the emitted log against the matching schema vendored under crates/disrobe-cli/tests/schemas/.

run.artifacts is the artifact table. Each entry carries its URI, a description, the byte length when the report knows it, its SARIF roles, and a blake3 hash when the report has one. An entry with no digest carries no hash. The roles follow the evidence roles: the analysis target becomes analysisTarget, a recovered artifact becomes resultFile, and a stage input or output becomes unmodified.

Every result location names an artifact URI and its index in run.artifacts. A region cites a byte offset and a byte length. A span whose offset plus length would leave the artifact is dropped rather than cited, so a cited range always reads back inside the artifact it indexes.

Results carry one of these rule ids. A rule is declared in tool.driver.rules only when the run produced at least one result for it.

Only two results are reported as level: error with kind: fail: a failure, and a batch entry whose manifest recorded an error. A wall is level: none with kind: review, so a layer that stopped short never reaches a code-scanning gate as an error. A behavior is kind: review. An evidence entry whose digest is unavailable is kind: review. Every other evidence entry, every stage, every indicator, and every batch entry that ran is kind: informational.

An indicator result records the offset and length of the value inside the analysis target, and a range_within_target flag. When a recorded offset lies outside the target, the result is kept, the flag is false, and the message says the range lies outside the analysis target.

run.invocations[0].commandLine holds the reproduction command. executionSuccessful is false when a single run recorded a failure, or when a batch manifest recorded an error. endTimeUtc appears only when SOURCE_DATE_EPOCH is set, and then holds that date.

run.properties

STIX 2.1 requires created, modified, and valid_from on its objects, and a render without SOURCE_DATE_EPOCH carries no clock to put there, so the bundle is emitted only when the variable is set; every STIX date then equals it. The bundle carries an identity object for the tool and a malware-analysis object for the run. Its result field stays unknown, because disrobe performs static recovery and does not classify a sample. Identifiers are derived from the first 16 bytes of BLAKE3 over a stable seed, stamped with the RFC 9562 version 4 and variant bits, so repeated runs over one input produce one identifier.

URL, domain, IPv4, IPv6, email, and registry indicators become STIX indicator objects. Hash, ASN, wallet, path, secret, and other indicators have no STIX pattern object path. They are counted by class in standards.stix.unmapped_indicator_classes and stay in the SARIF results only.

The standards block records SARIF 2.1.0, STIX 2.1, MAEC 5.0, and CycloneDX 1.5, and names OpenIOC 1.1 and CybOX 2.x as excluded with a reason for each.

What the enriched blocks need

The STIX, MAEC, capability, and indicator blocks read the original analysis target. The report opens it at the path chain.json recorded, resolved against the working directory. Capability analysis is limited to 256 MiB and verifies the bytes against the recorded BLAKE3 before attaching results. If the chain document records no path, the sample has moved or changed, the target exceeds the limit, or you run the command from another directory, the affected block reports available: false and names the reason. The rest of the report still renders.

Determinism

Text, JSON, markdown, HTML, and SARIF output is byte-identical across renders of one run, and the documents a run writes are byte-identical at any --jobs value. No document records a duration, the worker count, or the time of the run; auto --timings writes those to run.json instead.

Without SOURCE_DATE_EPOCH the SARIF render holds no timestamp at all: generated_at, endTimeUtc, and the MAEC behavior timestamps are left out, the STIX block reports itself unavailable, and standards.timestamp.source reads none. Set SOURCE_DATE_EPOCH to a Unix timestamp to date the render: every timestamp in the document then holds that value, the STIX bundle is emitted, and standards.timestamp.source reads source-date-epoch. A value that is not a whole number of seconds is refused with DR-CLI-0318 rather than replaced by the clock.

Analysis-depth commands

A set of static-analysis primitives that make disrobe useful as a triage and reverse-engineering tool, not only a decompiler. Each one operates on raw bytes and (where relevant) on the strings/source a chain has already recovered, so they compose with the rest of the pipeline. None of them execute the sample.

Credential scan

disrobe scan firmware.bin
disrobe scan firmware.bin --json
disrobe scan firmware.bin --sarif > findings.sarif

disrobe scan scans the target's raw bytes for leaked credentials: cloud provider keys (AWS, GCP, Azure, GitHub, Stripe, and others), VCS tokens, JWTs, PEM and SSH private keys, and other high-confidence secret patterns.

Unlike disrobe ioc, scan focuses exclusively on secrets that represent an immediate credential exposure rather than general network or host indicators. Output is text (one finding per line) or SARIF 2.1.0.

Format identification

disrobe identify sample.exe
disrobe identify sample.exe --json

disrobe identify fingerprints what built or packed a PE, ELF, or Mach-O binary. It reports the compiler, linker, packer, protector, and installer if detected, with structural evidence and the disrobe pass that handles each detected layer. The output is the same as disrobe native identify but works as a top-level command without routing through the native subcommand tree.

Prowl harvest

disrobe prowl example.com --subs --sources wayback,commoncrawl,urlscan --format json > prowl.json
disrobe prowl --targets-file targets.txt --proxy http://127.0.0.1:8080 --max-urls 50000
disrobe prowl --recon-input frisk.json --ioc domain,ipv4,email
disrobe prowl keyring set virustotal

disrobe prowl is the explicit network recon command. It queries Wayback, Common Crawl, OTX, urlscan, crt.sh, URLhaus, ThreatFox, and VirusTotal. Inputs can be command-line targets, a targets file, stdin, or a prior disrobe recon/IOC JSON report. The output schema is disrobe.prowl/v0 and contains the requested targets, selected sources, URL records, IOC records, and per-provider status.

The source labels are wayback, commoncrawl, otx, urlscan, crtsh, urlhaus, threatfox, and virustotal (vt alias). API keys resolve in this order: --api-key provider=key, provider environment variable (PROWL_<PROVIDER>_API_KEY or the provider's conventional variable), OS keyring, then a permissions-checked TOML config. Required-key providers without a key are skipped with a provider status rather than failing the whole harvest.

Filters are bounded and deterministic: --blacklist drops extensions, --from/--to constrain Wayback dates, --mc/--fc include or exclude HTTP status codes, --mt/--ft include or exclude MIME substrings, --ioc keeps selected IOC classes, --fp collapses URLs that differ only by query values, and --no-iocs suppresses derived IOC extraction. --timeout, --concurrency, --per-host-rps, --max-pages, --max-urls, --max-iocs, and --retries cap network and memory use.

IOC extraction