Python bindings

Use Disrobe's recovery engines from Python to decompile bytecode, analyze native code, deobfuscate scripts, and extract packaged files. The disrobe module uses the same Rust implementations as the CLI and provides typed report objects. It supports Python 3.9+ through PyO3's stable ABI.

Most analysis calls leave file I/O to the caller. The optional Flutter engine-symbol cache reads and writes the directory passed as cache_dir. Build the bindings from source; wheels are not published to PyPI.

The WebAssembly example shows an addition function recovered as WAT. The 0.10.5 compatibility results cover 60 API checks for typed results, error payloads, artifact round trips, and CLI surface mappings.

Install

Install Python 3.9+, the repository's Rust toolchain, and the target's native compiler and linker. Windows MSVC builds require the Visual C++ build tools, Windows SDK, and a Python installation that includes python3.lib. See the source build prerequisites.

Create a virtual environment:

git clone https://github.com/1-3-7/disrobe
cd disrobe/bindings/python
python -m venv .venv

Activate it with source .venv/bin/activate on Linux or macOS, or .\.venv\Scripts\Activate.ps1 in Windows PowerShell. Then install the build tool and compile the extension into that environment:

python -m pip install "maturin>=1.5,<2.0"
maturin develop --release

For a redistributable wheel:

maturin build --release --out dist
python -m pip install --no-index --find-links dist disrobe

The pyproject.toml requires maturin>=1.5,<2.0, takes the version from the Rust workspace, sets module-name = "disrobe.disrobe", and points at crates/disrobe-python/Cargo.toml. On Windows the crate's build.rs searches PYO3_PYTHON, an active VIRTUAL_ENV, and standard install locations; set PYO3_PYTHON=<path-to-python.exe> if none is found. A py.typed marker and a .pyi stub provide type information for the documented report attributes.

from __future__ import annotations

import disrobe

version: str = disrobe.__version__

Report model

Analysis functions generally return concrete report classes. Some functions return text, bytes, collections, or tuples; the function table gives each return type. The stub's _Report base describes the serialization methods shared by report objects.

_Report

Reports compare equal when their underlying records are equal (== / !=).

_LlmReport

Subclasses _Report. Adds one property:

Metadata-wired passes: py_decompile, py_disasm, py_deob, pyarmor_detect, pyarmor_unpack. Functions that build a metadata bundle accept pack: Pack | None where Pack = Literal["pack-1", "pack-2", "pack-3", "pack-4"].

LlmBundle

A TypedDict mirroring the disrobe.metadata.llm.v2 on-disk schema. The type name is stable; the schema id changes only when the bundle shape breaks compatibility. The payload is deterministic metadata, not model output. Every top-level key except generated_at is always present, and the categories present depend on which pack was requested. Pipeline steps record no durations. generated_at appears only when SOURCE_DATE_EPOCH is set, as an RFC 3339 UTC timestamp; a value that is not a whole number of seconds up to 9999-12-31T23:59:59Z raises DisrobeError.

The LlmBundle name describes a type in the stub; it is not a runtime export. To retain a complete report and its metadata, serialize the report:

from __future__ import annotations

from pathlib import Path

import disrobe

pyc_bytes: bytes = Path("module.pyc").read_bytes()
report: disrobe.PyDisasmReport = disrobe.py_disasm(pyc_bytes, pack="pack-2")
metadata_json: str = report.to_json()

print(metadata_json)

Literal type aliases

These names are defined in the type stub, not exported by the runtime module. Pass the documented string values to functions; do not import the aliases at runtime.

Exception hierarchy

Invalid Python argument types can also raise standard Python exceptions.

Module-level functions: full surface

Auto chain

from __future__ import annotations

from pathlib import Path

import disrobe

chain: disrobe.ChainReport = disrobe.auto(Path("sample.bin").read_bytes(), max_depth=8)

passes: list[str] = chain.passes
verdict: disrobe.ChainVerdict | None = chain.verdict
grade: disrobe.ChainVerdictGrade | None = chain.verdict_grade
print(chain.node_count, chain.pass_count, passes, verdict, grade)

full_plan_json: str = chain.to_json()
print(full_plan_json)

auto runs the chain detector against raw bytes and returns a ChainReport carrying the full chain.json plan the CLI produces; it does not write stage outputs to disk. max_depth must be 1-16. Other values in the unsigned-byte range raise DisrobeError; values below 0 or above 255 raise OverflowError. The registered pass tree covers pyarmor, pyinstaller, nuitka, py-decompile, py-deob, container, js, jvm, dotnet, wasm, mobile, swift-objc, and the native packer detector.

The accessors read the disrobe.chain/v2 document. to_json() returns the complete plan, including per-node hashes, detector picks, and statistics. The document carries no clock and no duration, so one input gives the same JSON on every call.

The earlier terminated accessor was removed because the document has no termination field; read verdict and verdict_grade instead.

Generic dispatch

Language-keyed entry points that fan out to the per-language passes.

decompile

def decompile(language: str, source: str | bytes) -> CanonicalSource: ...

Wired families: python-bytecode/pyc (py-decompile), jvm-class/class/java/kotlin (JVM lifter), lua (register lifter), ruby (YARV/mruby recovery), php/php-bytecode (eval-chain peel/op-array skeleton), javascript/js/typescript/ts (unminify). Binary-only targets (go, swift, wasm) have no single source body; call their structural binding or parse instead.

from __future__ import annotations

from pathlib import Path

import disrobe

recovered: disrobe.CanonicalSource = disrobe.decompile(
    "python-bytecode", Path("module.pyc").read_bytes()
)

source: str | None = recovered.source
language: str | None = recovered.language
produced_by: str | None = recovered.produced_by
confidence: float | None = recovered.confidence

CanonicalSource accessors

disasm

def disasm(language: str, source: str | bytes) -> str: ...

Returns a rendered instruction listing as text. Wired: python/pyc, jvm-class/class, dex, beam, hermes, wasm, ruby/yarv/mruby, and php/php-bytecode. For Lua use decompile('lua', ...) or parse('lua', ...) instead.

parse

def parse(language: str, source: str | bytes) -> (
    dict[str, Any]
    | GoAnalysis
    | SwiftReport
    | JvmClass
    | RubyAnalysis
    | LuaDecompilation
    | PhpDecode
    | JsUnminify
): ...

Returns a typed report for structural-recovery languages: go -> GoAnalysis, swift/objc/objective-c -> SwiftReport, kotlin -> JvmClass, ruby -> RubyAnalysis, lua -> LuaDecompilation, php -> PhpDecode, javascript/js/typescript/ts -> JsUnminify. Container and bytecode formats (pyc, jvm-class, dex, wasm, hermes, beam) return a nested dict[str, Any] because their full parse records have no single typed shape.

For a classfile report with typed attributes, use the dedicated parser:

from __future__ import annotations

from pathlib import Path

import disrobe

class_bytes: bytes = Path("Hello.class").read_bytes()
parsed: disrobe.JvmClass = disrobe.jvm_parse_class(class_bytes)
method_count: int = parsed.method_count

print(method_count)

compile

def compile(language: str, source: str, *, version: str | None = None) -> bytes: ...

Implemented for Python only; returns raw marshal.dumps bytes (no .pyc header) via the host interpreter. lua, ruby, and php raise UnsupportedLanguage with a hint pointing at the CLI subcommand or toolchain.

from __future__ import annotations

import disrobe

blob: bytes = disrobe.compile("python", "x: int = 1 + 2\n")
listing: str = disrobe.disasm("python", "x: int = 1 + 2\n")

Custom pass plugin protocol

Register and compose named passes and output consumers in the host process.

Named passes can return different Python objects. Check a registry result before using operations specific to its expected type.

from __future__ import annotations

import disrobe


def reverse_bytes(data: bytes) -> bytes:
    return data[::-1]


def print_result(result: object, **context: object) -> None:
    print(result, context)


disrobe.register_pass("reverse", reverse_bytes)
disrobe.register_consumer("print", print_result)

try:
    output: object = disrobe.run_chain(["reverse", "reverse"], b"hello")
    if not isinstance(output, bytes):
        raise TypeError("the reverse chain must return bytes")

    restored: bytes = output
    disrobe.emit("print", restored, source="example")
finally:
    disrobe.unregister("reverse")
    disrobe.unregister("print")

Pass and OutputConsumer protocols

These protocols describe callables in the stub. They are not exported as runtime classes; register ordinary Python functions with the corresponding signatures.

Analysis

strings_extract

def strings_extract(data: bytes, *, min_len: int = 4, decode: bool = True) -> StringsReport: ...

Extracts ASCII and UTF-16 strings from a binary blob.

ioc_extract

def ioc_extract(data: bytes) -> IocReport: ...

Harvests indicators of compromise from bytes and recovered strings.

behavior_analyze

def behavior_analyze(data: bytes) -> BehaviorReport: ...

Behavioral summary by category with MITRE ATT&CK IDs.

identify

def identify(data: bytes) -> IdentifyReport: ...

Compiler/linker/packer/protector/installer fingerprint. A signed PE's Authenticode certificate validity is judged at the time SOURCE_DATE_EPOCH names, or at the current time when it is unset; a value that is not a whole number of seconds raises DisrobeError.

secret_scan

def secret_scan(data: bytes, *, redact: bool = False) -> SecretScanReport: ...

Set redact=True to replace detected values, previews, messages, and URI credentials with stable redaction tokens. The default report retains the matched values. Redaction preserves the finding count and byte offsets.

Leaked-credential scan over raw bytes.

capabilities

def capabilities(binary_bytes: bytes) -> Capabilities: ...

Capability rule-set matches for a native binary.

extract

def extract(data: bytes, out_dir: str) -> ExtractionResult: ...

Carves container/firmware members to out_dir.

extract_recursive

def extract_recursive(
    data: bytes, *, source_label: str = "inline", max_depth: int = 8
) -> OverlayReport: ...

Recursive multi-magic carve; classifies every chunk by entropy and nesting.

yara_parse / yara_generate

def yara_parse(ruleset_source: str) -> YaraReport: ...
def yara_generate(data: bytes, *, name: str | None = None) -> YaraReport: ...

Parse a YARA ruleset AST or generate a candidate rule from a binary blob.

from __future__ import annotations

from pathlib import Path

import disrobe

data: bytes = Path("suspect.bin").read_bytes()

strings: disrobe.StringsReport = disrobe.strings_extract(data, min_len=6)
string_count: int = strings.string_count

iocs: disrobe.IocReport = disrobe.ioc_extract(data)
indicator_count: int = iocs.indicator_count

behavior: disrobe.BehaviorReport = disrobe.behavior_analyze(data)
category_count: int = behavior.category_count

ident: disrobe.IdentifyReport = disrobe.identify(data)
fmt: str | None = ident.format
finding_count: int = ident.finding_count

caps: disrobe.Capabilities = disrobe.capabilities(data)
match_count: int = caps.match_count

overlay: disrobe.OverlayReport = disrobe.extract_recursive(data, max_depth=4)
chunks_total: int | None = overlay.chunks_total
bytes_carved: int | None = overlay.bytes_carved

rule: disrobe.YaraReport = disrobe.yara_generate(data, name="suspect")
rule_count: int = rule.rule_count

Analysis report classes

Native binary

Functions

from __future__ import annotations

from pathlib import Path

import disrobe

data: bytes = Path("binary.elf").read_bytes()

syms: disrobe.SymbolsReport = disrobe.native_symbols(data)
symbol_count: int = syms.symbol_count
section_count: int = syms.section_count
import_count: int = syms.import_count

disasm_payload: disrobe.DisasmPayload = disrobe.native_disasm(data)
function_count: int = disasm_payload.function_count
instruction_count: int = disasm_payload.instruction_count

entropy: disrobe.EntropyReport = disrobe.native_entropy(data)
mean: float | None = entropy.mean

sig: disrobe.SigmakerReport = disrobe.native_sigmaker(data, at=0x1000)
ida_pattern: str | None = sig.ida_pattern

patched_bytes: bytes
patch_report: disrobe.PatchReport
patched_bytes, patch_report = disrobe.native_patch(
    data, at=0x1234, nop_start=0x1234, nop_end=0x1240
)
bytes_written: int | None = patch_report.bytes_written
edit_count: int = patch_report.edit_count

code: bytes = Path("function.x86.bin").read_bytes()
deob: disrobe.NativeDeobfuscation = disrobe.native_deobfuscate(
    code, bits=64, base=0x400000
)
recovered_blocks: int | None = deob.recovered_blocks
covered_states: int | None = deob.covered_states
dispatcher_states: int | None = deob.dispatcher_states
fully_recovered: bool = deob.fully_recovered

Native report classes

Query IR

The query functions operate on a Disasm- or Mir-rung .dr envelope (raw bytes). See Editable IR objects for how to produce and consume .dr envelopes programmatically.

from __future__ import annotations

from pathlib import Path

import disrobe

dr: bytes = Path("module.dr").read_bytes()

functions: disrobe.FunctionList = disrobe.query_functions(dr)
fn_count: int = functions.count

callers: disrobe.QueryReport = disrobe.query_calls_to(dr, "malloc")
match_count: int = callers.match_count

complex_fns: disrobe.QueryReport = disrobe.query_complexity_over(dr, threshold=20)
graph: disrobe.CallGraph = disrobe.query_call_graph(dr)
edge_count: int = graph.edge_count

Query report classes

Envelope

envelope_create wraps a payload as a Raw-rung .dr envelope and returns the encoded bytes. envelope_verify decodes and verifies, returning an EnvelopeReport.

from __future__ import annotations

import disrobe

envelope: bytes = disrobe.envelope_create(
    b"payload",
    source_label="inline",
    produced_by="my-tool",
)
report: disrobe.EnvelopeReport = disrobe.envelope_verify(envelope)
ok: bool = report.verified
root_hash: str | None = report.root_hash
rung: str | None = report.rung
hot_bytes: int | None = report.hot_bytes
cold_bytes: int | None = report.cold_bytes
version: int | None = report.version

EnvelopeReport accessors

The sidecar DrEnvelope TypedDict (bindings/python/dr-envelope.pyi) mirrors the raw on-disk header shape: magic, version, rung, flags, hot_len, cold_len, root_hash.

Metadata renders

agents_md and skill_md render the AGENTS.md and SKILL.md reconstruction briefs for a report with metadata attached (or a bare bundle dict), returning a str. provenance extracts tool/selection/input metadata as a typed Provenance. Each accepts a typed report or its raw dict and returns the same result for both. Passing a report whose llm slot is None raises DisrobeError; passing any other kind of object raises TypeError.

from __future__ import annotations

from pathlib import Path

import disrobe

report: disrobe.PyDecompileReport = disrobe.py_decompile(
    Path("module.pyc").read_bytes(), pack="pack-2"
)

agents_brief: str = disrobe.agents_md(report)
skill_brief: str = disrobe.skill_md(report)

prov: disrobe.Provenance = disrobe.provenance(report)
generated_at: str | None = prov.generated_at
schema: str | None = prov.schema
schema_version: str | None = prov.schema_version

Provenance accessors

generated_at is None unless SOURCE_DATE_EPOCH was set when the bundle was built.

Python passes

See also Python decompiler for the full decompiler design.

py_decompile

Decompiles a .pyc with its header to source. Normalized opcode-structure agreement on the fixed 574-module CPython 3.14 core population is

200-module corpus is 97.66% (6139 of 6286, regression threshold 97.66%).

The 574-module population excludes idlelib and turtledemo. The structural comparison omits jump targets, most operands and __annotate__ code objects; see the comparison rules.

from __future__ import annotations

from pathlib import Path

import disrobe

report: disrobe.PyDecompileReport = disrobe.py_decompile(
    Path("module.pyc").read_bytes(), roundtrip=True
)

source: str | None = report.source
marshal_version: str | None = report.marshal_version
decompile_version: str | None = report.decompile_version
recovered_directly: bool = report.recovered_directly
fallback_reason: str | None = report.fallback_reason
status: disrobe.RoundtripStatus | None = report.roundtrip_status
roundtrip_detail: str | None = report.roundtrip_detail
interpreter_path: str | None = report.interpreter_path
interpreter_version: str | None = report.interpreter_version

if status == "perfect":
    print("recompiled bytecode matched")

Round-tripping (when roundtrip=True) invokes a matching host interpreter to compile the recovered source and compare bytecode. It does not execute the recovered program.

py_disasm

from __future__ import annotations

from pathlib import Path

import disrobe

result: disrobe.PyDisasmReport = disrobe.py_disasm(Path("module.pyc").read_bytes())

marshal_version: str | None = result.marshal_version
instruction_count: int = result.instruction_count
text: str | None = result.text

py_deob, py_deob_detect, py_deob_list_passes, py_deob_detect_pass

from __future__ import annotations

import disrobe

obfuscated: str = "exec(__import__('base64').b64decode('cHJpbnQoMSk='))\n"

deob: disrobe.PyDeobReport = disrobe.py_deob(obfuscated, cleanup=True)
peeled_source: str | None = deob.peeled_source
cleanup_source: str | None = deob.cleanup_source
layer_count: int = deob.layer_count

detection: disrobe.PyDeobDetection = disrobe.py_deob_detect(obfuscated)
match_count: int = detection.match_count

passes: list[disrobe.ObfuscatorPass] = disrobe.py_deob_list_passes()
first_id: str | None = passes[0].id if passes else None

if first_id is not None:
    per_pass: disrobe.PyDeobDetection = disrobe.py_deob_detect_pass(
        obfuscated, first_id
    )
    print(per_pass.match_count)

py_deob_detect_pass raises DisrobeError for an unknown pass_id.

Python pass report classes

PyArmor

pyarmor_detect

Parses a PyArmor wrapper from source text.

from __future__ import annotations

from pathlib import Path

import disrobe

detection: disrobe.PyarmorDetection = disrobe.pyarmor_detect(
    Path("wrapped.py").read_text(encoding="utf-8")
)
version: str | None = detection.version
protection: str | None = detection.protection
confidence: str | None = detection.confidence
serial: str | None = detection.serial
python_major: int | None = detection.python_major
python_minor: int | None = detection.python_minor
payload_offset: int | None = detection.payload_offset
payload_size: int | None = detection.payload_size

pyarmor_unpack

Accepts the binary payload extracted from a PyArmor wrapper: the bytes literal passed as the third argument of __pyarmor__, not the wrapper source. The earlier keyword wrapper_bytes= is accepted as an alias for payload; passing both raises TypeError.

Without runtime, v8/v9 payloads return detection metadata and status "detect-only". Pass the bytes of the matching pyarmor_runtime extension module as runtime to decrypt the payload statically; the runtime is parsed, not loaded or executed. A runtime the core cannot parse raises DisrobeError. The report describes the result and does not expose plaintext bytes. There is no --allow-dynamic equivalent.

The core static path, supplied with the matching runtime, decrypts each body and decodes one complete root CodeObject from its header-anchored marshal stream on the 72 / 72 manifest-named v8/v9 default-trial wrappers. That structural check does not compare source, emitted .pyc bytes, semantic or execution behavior, or external-tool output.

from __future__ import annotations

from pathlib import Path

import disrobe

unpacked: disrobe.PyarmorUnpack = disrobe.pyarmor_unpack(
    Path("payload.bin").read_bytes(),
    runtime=Path("pyarmor_runtime_000000/pyarmor_runtime.pyd").read_bytes(),
)

status: disrobe.PyarmorUnpackStatus | None = unpacked.status
pyarmor_version: str | None = unpacked.pyarmor_version
protection_kind: str | None = unpacked.protection_kind
plaintext_len: int | None = unpacked.plaintext_len
digest: str | None = unpacked.plaintext_blake3_hex
bcc_blob_count: int | None = unpacked.bcc_blob_count
inner_cipher_recovered_co: int | None = unpacked.inner_cipher_recovered_co

pyarmor_classify

from __future__ import annotations

from pathlib import Path

import disrobe

payload: bytes = Path("payload.bin").read_bytes()

classification: disrobe.PyarmorClassification = disrobe.pyarmor_classify(
    Path("wrapped.py").read_text(encoding="utf-8"), payload
)
script_type: str | None = classification.script_type
bootstrap_import: str | None = classification.bootstrap_import
disposition: str | None = classification.disposition
rft_enabled: bool = classification.rft_enabled
ecc_enabled: bool = classification.ecc_enabled

The sidecar PyarmorDetection TypedDict (bindings/python/pyarmor-detection.pyi) names the confidence and protection Literal values used in the raw dict.

PyArmor report classes

PyInstaller and Nuitka

pyinstaller_extract / pyinstaller_entry_bytes

from __future__ import annotations

from pathlib import Path

import disrobe

image: bytes = Path("app.exe").read_bytes()

archive: disrobe.PyInstallerArchive = disrobe.pyinstaller_extract(image)
entry_count: int = archive.entry_count
encrypted: bool = archive.encrypted
encryption_key_present: bool = archive.encryption_key_present
python_major: int | None = archive.python_major
python_minor: int | None = archive.python_minor

archive_json: str = archive.to_json()
print(archive_json)

Use an entry name from the archive report to recover its bytes:

from __future__ import annotations

from pathlib import Path

import disrobe

image: bytes = Path("app.exe").read_bytes()
entry_name: str = "main"
main_payload: bytes = disrobe.pyinstaller_entry_bytes(image, entry_name)
print(len(main_payload))

nuitka_detect / nuitka_extract

from __future__ import annotations

from pathlib import Path

import disrobe

image: bytes = Path("app.exe").read_bytes()

det: disrobe.NuitkaDetection = disrobe.nuitka_detect(image)
flavor: str | None = det.flavor
version: str | None = det.version
wheel_marker: str | None = det.wheel_marker
onefile_payload_offset: int | None = det.onefile_payload_offset
onefile_payload_compressed: bool = det.onefile_payload_compressed

extraction: disrobe.NuitkaExtraction = disrobe.nuitka_extract(image)
variant: str | None = extraction.variant

The sidecar FreezerManifest TypedDict (bindings/python/freezer-manifest.pyi) describes the manifest schema for cx-freeze/py2exe/shiv/pex/py-oxidizer/briefcase freezer families; reach it via report.raw.

PyInstaller/Nuitka report classes

Hermes (React Native)

All 8 functions in the committed hermesc-built HBC v96 sample lift at 100% op-coverage with 0 fallback ops. A 122,633-function production React Native bundle parses with no module-parse failure in the local scale harness.

from __future__ import annotations

from pathlib import Path

import disrobe

bundle: bytes = Path("index.android.bundle").read_bytes()

disasm_result: disrobe.HermesDisassembly = disrobe.hermes_disasm(bundle)
function_count: int = disasm_result.function_count
identifier_count: int = disasm_result.identifier_count
string_count: int = disasm_result.string_count

lift: disrobe.HermesLift = disrobe.hermes_lift(bundle)
function_surface_count: int = lift.function_surface_count

info: disrobe.HermesInfo = disrobe.hermes_info(bundle)
version: int | None = info.version
header_size: int | None = info.header_size

Hermes report classes

Mach-O and Swift

from __future__ import annotations

from pathlib import Path

import disrobe

data: bytes = Path("universal.dylib").read_bytes()

macho: disrobe.MachoReport = disrobe.macho_dump(data)
kind: str | None = macho.kind
fat_entry_count: int = macho.fat_entry_count
slice_count: int = macho.slice_count

swift: disrobe.SwiftReport = disrobe.swift_analyze(data)
container: str | None = swift.container
swift_fat_entry_count: int = swift.fat_entry_count
swift_slice_count: int = swift.slice_count

Mach-O report classes

JVM and Android

131 of 131 JVM methods recompile error-free under javac (CI floor 131 of 131, JDK 25). 100% of verifier-presented committed DEX classes pass -Xverify:all, with 37 of 155 classes link-skipped and never reaching the verifier.

from __future__ import annotations

from pathlib import Path

import disrobe

cls: disrobe.JvmClass = disrobe.jvm_parse_class(Path("Hello.class").read_bytes())
major_version: int | None = cls.major_version
minor_version: int | None = cls.minor_version
method_count: int = cls.method_count
field_count: int = cls.field_count
constant_pool_count: int = cls.constant_pool_count

dex: disrobe.DexFileReport = disrobe.jvm_parse_dex(Path("classes.dex").read_bytes())
class_count: int = dex.class_count
dex_method_count: int = dex.method_count

decompiled: disrobe.JvmDecompiledClass = disrobe.jvm_decompile_class(
    Path("Hello.class").read_bytes()
)
source: str | None = decompiled.source
fully_lifted_methods: int = decompiled.fully_lifted_methods
fallback_methods: int = decompiled.fallback_methods

decompiled_dex: disrobe.JvmDecompiledDex = disrobe.jvm_decompile_dex(
    Path("classes.dex").read_bytes()
)
dex_source: str | None = decompiled_dex.source
source_count: int = decompiled_dex.source_count
dex_fully_lifted_methods: int = decompiled_dex.fully_lifted_methods
dex_fallback_methods: int = decompiled_dex.fallback_methods

detections: disrobe.DetectionList = disrobe.jvm_detect(Path("obf.class").read_bytes())
detection_count: int = detections.count

backends: disrobe.JvmBackends = disrobe.jvm_backends()
jvm_count: int = backends.jvm_count
android_count: int = backends.android_count

apk: disrobe.ApkResources = disrobe.apk_resources(Path("app.apk").read_bytes())
package: str | None = apk.package
manifest_xml: str | None = apk.manifest_xml
resource_entry_count: int = apk.resource_entry_count
certificate_count: int = apk.certificate_count
dex_count: int = apk.dex_count

jvm_backends and dotnet_backends probe the host for installed external tools but never shell out to them. Counts are informational only.

JVM/Android report classes

.NET

from __future__ import annotations

from pathlib import Path

import disrobe

pe_bytes: bytes = Path("Sample.dll").read_bytes()

pe: disrobe.DotnetPe = disrobe.dotnet_parse_pe(pe_bytes)
bitness: str | None = pe.bitness
machine: int | None = pe.machine
section_count: int = pe.section_count
entry_point_rva: int | None = pe.entry_point_rva

metadata: disrobe.DotnetMetadata = disrobe.dotnet_parse_metadata(pe_bytes)
version: str | None = metadata.version
major_runtime_version: int | None = metadata.major_runtime_version
stream_count: int = metadata.stream_count

detection: disrobe.DotnetDetection = disrobe.dotnet_detect(pe_bytes)
primary: str | None = detection.primary
match_count: int = detection.match_count

analysis: disrobe.DotnetAnalysis = disrobe.dotnet_analyze(pe_bytes)
pe_bitness: str | None = analysis.pe_bitness
is_native_aot: bool = analysis.native_aot
primary_protector: str | None = analysis.primary_protector
opcode_spec_coverage_pct: int | None = analysis.opcode_spec_coverage_pct

decompilation: disrobe.DotnetDecompilation = disrobe.dotnet_decompile(pe_bytes)
module_name: str | None = decompilation.module_name
methods_decompiled: int | None = decompilation.methods_decompiled
methods_bodyless: int | None = decompilation.methods_bodyless
methods_failed: int | None = decompilation.methods_failed

decoders: disrobe.DotnetDecoders = disrobe.dotnet_recover_decoders(pe_bytes)
pure_decoders_found: int | None = decoders.pure_decoders_found
constants_recovered: int = decoders.constants_recovered

image_bytes: bytes = Path("HelloAppAot.exe").read_bytes()

native_aot: disrobe.DotnetNativeAot = disrobe.dotnet_native_aot(image_bytes)
runtime_label: str | None = native_aot.runtime_label
method_count: int = native_aot.method_count
methods_with_code_range: int = native_aot.methods_with_code_range
managed_signature_count: int = native_aot.managed_signature_count
register_signature_count: int = native_aot.register_signature_count

backend_list: disrobe.BackendList = disrobe.dotnet_backends()
available_count: int = backend_list.available_count

dotnet_native_aot reads an ahead-of-time compiled .NET image rather than a managed assembly, so it accepts PE, ELF and Mach-O input. It never raises on a file that is not a NativeAOT image: is_native_aot is then false and every count is zero.

managed_signature_count and register_signature_count partition the method bodies disrobe recovered. A body counts as managed when its prototype was reattached from the image's own managed signature. It counts as registers when reattachment abstained and the body kept the types the machine-code lifter inferred from register use, which happens for generics, varargs, a hidden struct return, and the other cases the pass declines rather than guesses. The two counts separate a prototype disrobe sourced from metadata from one it could only infer, so read them as a pair.

.NET report classes

WebAssembly

1034 of 1034 opcodes lowered across the 38 parseable corpus modules (133 of 133 functions), against an instruction inventory wasm-tools produced rather than disrobe. 57 of 57 execution-eligible functions are execution-equivalent under wasmtime.

from __future__ import annotations

from pathlib import Path

import disrobe

wasm_bytes: bytes = Path("module.wasm").read_bytes()

analysis: disrobe.WasmAnalysis = disrobe.wasm_analyze(wasm_bytes)
import_count: int = analysis.import_count
export_count: int = analysis.export_count
func_count: int | None = analysis.func_count
code_size_bytes: int | None = analysis.code_size_bytes
has_dwarf: bool = analysis.has_dwarf

detection: disrobe.WasmDetection = disrobe.wasm_detect(wasm_bytes)
obfuscator: str | None = detection.obfuscator
confidence: float | None = detection.confidence
has_name_section: bool = detection.has_name_section
function_count: int | None = detection.function_count

WebAssembly report classes

JavaScript

Detects 11 bundlers. The explicit target hint accepts auto, webpack4, webpack5/webpack, vite, rollup, esbuild, turbopack, and bun. An unrecognized hint string raises DisrobeError.

from __future__ import annotations

from pathlib import Path

import disrobe

source: str = Path("main.js").read_text(encoding="utf-8")

detection: disrobe.JsDetection = disrobe.js_detect(source)
family: str | None = detection.family
confidence: float | None = detection.confidence
marker_count: int = detection.marker_count

unminified: disrobe.JsUnminify = disrobe.js_unminify(source)
recovered_source: str | None = unminified.source

bundle_source: str = Path("bundle.js").read_text(encoding="utf-8")
unbundled: disrobe.JsUnbundle = disrobe.js_unbundle(bundle_source)
module_count: int = unbundled.module_count
bundler: str | None = unbundled.bundler

unbundled_hinted: disrobe.JsUnbundle = disrobe.js_unbundle(
    bundle_source, bundler="webpack5"
)

JavaScript report classes

Lua

Detects, decompiles, and deobfuscates 14 Lua obfuscator families, with 16 catalog entries once Luau and GLua dialect detectors are included. IronBrew2 2.7.0 is reversed against real committed output with a Lua execution differential.

from __future__ import annotations

from pathlib import Path

import disrobe

bytecode: bytes = Path("chunk.luac").read_bytes()

det: disrobe.LuaDetection = disrobe.lua_detect(bytecode)
lua_format: str | None = det.format

decompiled: disrobe.LuaDecompilation = disrobe.lua_decompile(bytecode)
decompiled_source: str | None = decompiled.source
fidelity: str | None = decompiled.fidelity
warning_count: int = decompiled.warning_count

deob: disrobe.LuaDeobfuscation = disrobe.lua_deobfuscate(
    Path("obf.lua").read_text(encoding="utf-8"), authorize=True
)
obfuscator: str | None = deob.obfuscator
deobfuscated: str | None = deob.deobfuscated
fully_recovered: bool = deob.fully_recovered
passes_run_count: int = deob.passes_run_count
recovered_string_count: int = deob.recovered_string_count

Lua report classes

Go

from __future__ import annotations

from pathlib import Path

import disrobe

go_bytes: bytes = Path("binary").read_bytes()

analysis: disrobe.GoAnalysis = disrobe.go_analyze(go_bytes)
image_kind: str | None = analysis.image_kind
pclntab_version: str | None = analysis.pclntab_version
buildversion: str | None = analysis.buildversion
ptr_size: int | None = analysis.ptr_size

symbols: disrobe.GoSymbols = disrobe.go_symbols(go_bytes)
version_label: str | None = symbols.version_label
function_count: int = symbols.function_count
source_file_count: int = symbols.source_file_count
package_count: int = symbols.package_count

pclntab: disrobe.GoPclntab = disrobe.go_pclntab(go_bytes)
version: str | None = pclntab.version
func_count: int | None = pclntab.func_count

garble: disrobe.GarbleReport = disrobe.go_garble(go_bytes)
quality: str | None = garble.quality
detection_score: int | None = garble.detection_score
recovered_string_count: int = garble.recovered_string_count

Go report classes

Ruby

from __future__ import annotations

from pathlib import Path

import disrobe

ruby_bytes: bytes = Path("hello.rb.enc").read_bytes()

det: disrobe.RubyDetection = disrobe.ruby_detect(ruby_bytes, source_path="hello.rb.enc")
flavor: str | None = det.flavor

analysis: disrobe.RubyAnalysis = disrobe.ruby_decompile(
    ruby_bytes, source_path="hello.rb.enc"
)
ruby_flavor: str | None = analysis.flavor
source_path: str | None = analysis.source_path
input_len: int | None = analysis.input_len

Ruby report classes

PHP

from __future__ import annotations

from pathlib import Path

import disrobe

php_bytes: bytes = Path("obfuscated.php").read_bytes()

det: disrobe.PhpDetection = disrobe.php_detect(php_bytes)
kind: str | None = det.kind
confidence: str | None = det.confidence
open_tag_offset: int | None = det.open_tag_offset
has_halt_compiler: bool = det.has_halt_compiler

scan: disrobe.PhpScan = disrobe.php_scan(php_bytes)
hit_count: int = scan.hit_count
family_count: int = scan.family_count

decoded: disrobe.PhpDecode = disrobe.php_decode(php_bytes, max_depth=10)
php_source: str | None = decoded.source
layer_count: int = decoded.layer_count
residual_eval: bool = decoded.residual_eval

PHP report classes

Shell

from __future__ import annotations

from pathlib import Path

import disrobe

batch_script: str = Path("dropper.bat").read_text(encoding="utf-8")
batch_result: disrobe.BatchDeobReport = disrobe.batch_deobfuscate(
    batch_script, args=["/run"]
)
output: str | None = batch_result.output
embedded_payload_count: int = batch_result.embedded_payload_count
decrypted_stage_count: int = batch_result.decrypted_stage_count
commands_emulated: int | None = batch_result.commands_emulated

ps_script: str = Path("obf.ps1").read_text(encoding="utf-8")
ps_det: disrobe.PowershellDetection = disrobe.powershell_detect(ps_script)
obfuscator: str | None = ps_det.obfuscator
ps_confidence: float | None = ps_det.confidence
marker_count: int = ps_det.marker_count

ps_deob: disrobe.PowershellDeobfuscation = disrobe.powershell_deobfuscate(ps_script)
ps_output: str | None = ps_deob.output
level: str | None = ps_deob.level
transformation_count: int = ps_deob.transformation_count

Shell report classes

Containers

from a committed input that match an independent extractor. See container docs for the full family list.

from __future__ import annotations

from pathlib import Path

import disrobe

container_bytes: bytes = Path("archive.zip").read_bytes()

det: disrobe.ContainerDetection = disrobe.container_detect(container_bytes)
detected: bool = det.detected
kind: str | None = det.kind
is_zip_family: bool = det.is_zip_family

members: disrobe.ContainerMembers = disrobe.container_members(container_bytes)
fmt: str | None = members.format
size: int | None = members.size
listing: disrobe.ContainerListing | None = members.listing
entry_count: int = members.entry_count

Container report classes

Pickle

Nothing is ever unpickled; the VM is symbolic.

from __future__ import annotations

from pathlib import Path

import disrobe

pkl: bytes = Path("model.pkl").read_bytes()

listing: str = disrobe.pickle_disasm(pkl)

decompilation: disrobe.PickleDecompilation = disrobe.pickle_decompile(pkl)
pkl_source: str | None = decompilation.source

safety: disrobe.PickleSafety = disrobe.pickle_safety(pkl)
severity: str | None = safety.severity
finding_count: int = safety.finding_count
import_count: int = safety.import_count
reduce_count: int | None = safety.reduce_count

trace: disrobe.PickleTrace = disrobe.pickle_trace(pkl)
protocol: int | None = trace.protocol
memo_count: int | None = trace.memo_count
max_stack_depth: int | None = trace.max_stack_depth
global_ref_count: int = trace.global_ref_count
trace_reduce_count: int | None = trace.reduce_count

polyglot: disrobe.PicklePolyglot = disrobe.pickle_polyglot(pkl)
is_pickle: bool = polyglot.is_pickle
is_polyglot: bool = polyglot.is_polyglot
kind_count: int = polyglot.kind_count

ml_report: disrobe.PickleMlReport = disrobe.pickle_ml_detect(
    Path("model.pt").read_bytes()
)
fmt: str | None = ml_report.format
framing: str | None = ml_report.framing
embedded_count: int = ml_report.embedded_count

Pickle report classes

Editable IR objects

CodeObject, Instruction, and Symbol let you load a Disasm- or Raw-rung .dr envelope, modify it in Python, and write a fresh integrity-hashed .dr.

Instruction

from __future__ import annotations

import disrobe

instr: disrobe.Instruction = disrobe.Instruction(
    offset=0,
    mnemonic="mov",
    operands=["rax", "rbx"],
    bytes=b"\x48\x89\xd8",
)
instr.branch_target = None
flow: disrobe.InstructionFlow = instr.flow
text: str = instr.text()

Symbol

from __future__ import annotations

import disrobe

sym: disrobe.Symbol = disrobe.Symbol(address=0x1000, name="entry", kind="function")
sym.name = "main"
sym.kind = "export"

CodeObject

from __future__ import annotations

from pathlib import Path

import disrobe

co: disrobe.CodeObject = disrobe.CodeObject.from_dr(Path("module.dr").read_bytes())

instruction_count: int = co.instruction_count
symbol_count: int = co.symbol_count
source_hash: str = co.source_hash
produced_by: str = co.produced_by

instrs: list[disrobe.Instruction] = co.instructions
syms: list[disrobe.Symbol] = co.symbols
metadata: dict[str, str] = co.metadata
capabilities: list[str] = co.capabilities

new_sym: disrobe.Symbol = disrobe.Symbol(
    address=0x2000, name="renamed_fn", kind="function"
)
co.add_symbol(new_sym)
co.set_metadata("analysis", "patched")
co.add_capability("NETWORK_CONNECT", 1)

fresh_dr: bytes = co.to_dr()
Path("module_patched.dr").write_bytes(fresh_dr)

CodeObject.from_dr parses a Disasm- or Raw-rung .dr envelope. to_dr produces a fresh envelope with a recomputed integrity hash. The set_instructions and set_symbols methods replace the full list; add_instruction / add_symbol append. set_metadata(key, value) sets a single string key; clear_metadata resets all. set_llm(sidecar) attaches or removes the metadata sidecar dict.

Scope

• auto returns the plan document without writing stage trees. extract(data, out_dir) writes container members, and flutter_engine_symbols can use an explicit cache directory.
• External backend tools (jvm_backends, dotnet_backends, native_probe_backends) are probed for availability but never executed.
• AS3, BEAM (beyond disasm/parse), and the freezer family beyond PyInstaller/Nuitka have no dedicated bindings in this release.
• No SARIF/NDJSON emitters and no serve daemon; drive the CLI or daemon directly.