malware-deobfuscator (mwdeo)

Defensive multi-stage analyser for obfuscated scripts (PowerShell, JavaScript, VBScript, Python, Bash). Layers static deobfuscation, IoC extraction, capability classification, and (optional) LLM analyst on top of a synthetic sandbox-trace comparator.

• Detector — language fingerprinting + 13 obfuscation kinds (base64_blob, char_code_array, string_concat_spam, eval_wrapper, powershell_frombase64, powershell_invoke_expression, powershell_gzip, xor_loop, unicode_escape, hex_escape, packed_array, heavy_entropy_blob, hex_blob).
• Static deobfuscator — multi-pass layer peeler: [Convert]::FromBase64String('…') (with optional gzip / zlib), String.fromCharCode([…]), 'a'+'b'+'c'+…, \xNN, \uNNNN. Bounded by max_layers (default 8). Never executes the sample.
• LLM deobfuscator (optional) — defensive fallback when static passes don't fully decode. The model is asked to produce a plain-English summary plus a fenced deob reconstruction; output is sanitised — reconstructions that still contain a base64 blob or a FromBase64String(…) call are discarded.
• IoC extractor — URLs, IPv4 addresses, domains, emails, file paths, registry keys, CLSIDs, mutex/named-object strings, MD5/SHA-256 hashes. Whitelists Microsoft schema URLs and example.* domains; emits a defang() helper for safe rendering.
• Intent classifier — heuristic capability bag (18 capabilities: network_c2, downloader, persistence ×3, credential_dumping, keylog, lateral ×2, AMSI bypass, AV disable, discovery ×2, exfil_http, inject_process, shellcode_loader, ransomware_indicator, cryptominer) → primary intent (one of downloader_dropper, credential_stealer, ransomware, remote_access_trojan, cryptominer, wiper, keylogger, scareware, lateral_mover, persistence_loader, reconnaissance, benign, unknown). Optional LLM analyst overrides only when its intent is in the valid enum and not a benign-to-malicious escalation without heuristic support.
• Sandbox-trace comparator — checks whether dynamic events (Cuckoo, CAPE, ProcMon, normalised to TraceEvent) confirm or contradict the static capabilities. Flags downloader_dropper intents with no network activity, ransomware intents with no file writes, and zero-coverage analyses.

Install

pip install -r requirements.txt

Quickstart

from mwdeo import Analyzer, SandboxTrace, TraceEvent
from mwdeo.sandbox import EventKind

result = Analyzer().analyze(
    open("sample.ps1").read(),
    trace=SandboxTrace(sample_sha256="...", events=[
        TraceEvent(EventKind.NET_HTTP, "GET http://x/p"),
        TraceEvent(EventKind.FILE_WRITE, "C:\\dropper.exe"),
    ]),
)

from mwdeo.report import Report
print(Report(result).to_markdown())

LLM analyst:

from mwdeo.llm_client import LLMClient
analyzer = Analyzer(llm=LLMClient())

CLI

python -m mwdeo.cli analyze sample.js
python -m mwdeo.cli analyze sample.ps1 --llm --format json
python -m mwdeo.cli analyze - < sample.vbs --no-defang

Tests

pytest tests/                                        # 83 mocked tests
LLM_LIVE=1 pytest tests/test_llm_live.py             # 5 live tests

Caveats

• We do not execute the sample. Submit a sandbox trace for dynamic confirmation.
• The static deobfuscator handles common patterns; novel custom encodings will need either an LLM analyst or a hand-written pass.
• IoCExtractor filters loopback IPs by default; pass IoCExtractor(include_loopback_ips=True) if you need them.

License

MIT