MaldocTrace

MaldocTrace ist ein defensiver Analyzer für bösartige Office-Dokumente, geschrieben in Go. Er extrahiert VBA- und Excel 4.0 (XLM)-Makros, rekonstruiert obfuskierte Zeichenketten und emuliert die Makros in einer vollständig simulierten Umgebung. Die Ausgabe berichtet, was das Dokument tun würde: die Befehle, die es ausführen würde, die Payloads, die es dekodieren würde, und die Dateien, die es ablegen würde. All dies wird durch Belege gestützt, die auf das Modul, die Prozedur und die Zeile (oder das Arbeitsblatt und die Zelle) verweisen, die es erzeugt haben.

Dokumente ganz ohne Makros werden ebenfalls abgedeckt. Remote-Template-Injection, DDE-Felder, verknüpfte und eingebettete OLE-Objekte (einschließlich Equation-Editor-Exploits in RTF), mit Hyperlinks versehene Köderbilder und VBA-Stomping werden als statische Befunde gemeldet.

---

Funktionen

• Container-Extraktion: OLE/CFB (.doc, .xls, .ppt), OOXML (.docx, .docm, .xlsx, .xlsm, .pptm), RTF und roher VBA-Text. Enthält MS-OVBA-Dekompression, UserForm-Steuerelementeigenschaften und Ressourcenlimits gegen Zip-Bomben und fehlerhafte Container.
• Excel 4.0 (XLM)-Makros:
  • Makroblätter aus .xls (BIFF8-Formeln dekompiliert aus geparsten Tokens unter Verwendung der MS-XLS-Funktionstabellen) und .xlsm, einschließlich ausgeblendeter und sehr ausgeblendeter Blätter;
  • ein XLM-Interpreter, der bei Auto_Open beginnt (jeder Name, den Excel ausführen würde). Er folgt GOTO, RUN, IF, WHILE/FOR/NEXT, ON.TIME und RETURN und wendet FORMULA/FORMULA.FILL/SET.VALUE/SET.NAME an, sodass selbstdekodierende Makros ihren echten Code rekonstruieren;
  • simuliertes EXEC, CALL, REGISTER und Aliase (URLDownloadToFileA, ShellExecuteA, WinExec, CreateProcessA) sowie FOPEN/FWRITE. Anti-Sandbox-Probes (GET.WORKSPACE, GET.WINDOW, GET.CELL) erhalten plausible Antworten, die als simuliert gekennzeichnet werden;
  • die zur Laufzeit geschriebenen Formeln werden als deobfuskiertes Makro aufgeführt.
• Statische Befunde (keine Emulation erforderlich):
  • Remote-Template-Injection (attachedTemplate, RTF \*\template);
  • externe OLE-Objekte, einschließlich MHTML (CVE-2021-40444) und ms-msdt (Follina)-Moniker;
  • DDE/DDEAUTO-Felder (einschließlich QUOTE-kodierter) sowie Excel-DDE-Formeln und -Verknüpfungen;
  • in RTF eingebettete Objekte, dekodiert so, wie Word sie liest (obfuskiertes \objdata, beschädigte OLE1-Header), mit Erkennung von Equation-Editor-Exploits: der MTEF-FONT-Überlauf (CVE-2017-11882 / CVE-2018-0802) und der MATRIX-Überlauf (CVE-2018-0798), plus Extraktion der nachfolgenden Bytes;
  • Hyperlinks auf Bildern und Zellen sowie QR-Code-Köder;
  • VBA-Stomping: String-Literale, die in den p-Code kompiliert, aber im Quelltext fehlen, bedeuten, dass der angezeigte Quelltext nicht der Code ist, den Office ausführt. Diese Literale werden gemeldet und auf Indikatoren geprüft.
• Verstecke für Payloads: Zellwerte (Sheets("x").Range("A1"), Cells(r, c)), Dokumenteigenschaften (BuiltInDocumentProperties("Comments"), benutzerdefinierte Eigenschaften), Dokumentvariablen (ActiveDocument.Variables) und UserForm-Steuerelemente (TextBox.Text, Label.Caption) stehen alle dem emulierten Makro zur Verfügung.
• Dokumenttextkörper: extrahiert aus Word 97-2003 (Piece Table) und .docx. Dropper verstecken ihre Payload oft im Dokumenttextkörper und lesen sie über ActiveDocument.Paragraphs(n).Range.Text zurück.
• VBA-Interpreter: ein Lexer, Parser und begrenzter Interpreter, der die Teilmenge von VBA abdeckt, auf die sich Malware stützt: Prozeduren, ByRef-Parameter, benannte Argumente, bedingte Kompilierung, Schleifen, Arrays und die String-Built-ins.
• Statische Deobfuskierung: Konstantenfaltung von Chr/StrReverse/Replace/Verkettung. Jeder Wert zeichnet auf, wie er rekonstruiert wurde (concatenation+Chr, StrReverse, ...).
• Simulierte Umgebung:
  • Prozesse: WScript.Shell, Shell, WMI Win32_Process.Create (sowohl GetObject als auch CreateObject("winmgmts:..."))
  • Dateien und Netzwerk: FileSystemObject, ADODB.Stream, XMLHTTP/WinHttp
  • Skript-Engines: MSScriptControl.ScriptControl
  • Words Dokumentmodell: Paragraphs, Range, Delete, SaveAs2
  • Excels Objektmodell (Sheets, Worksheets, Range, Cells, Offset), gemeinsam mit der XLM-Engine genutzt, sowie ExecuteExcel4Macro/Application.Run in Makroblätter
  • deklarierte Windows-APIs mit simulierten VarPtr-Zeigern
• Payload-Wiederherstellung:
  • PowerShell--EncodedCommand-Dekodierung mit statischer Faltung von 'ht'+'tp'-Verkettungen, bevor URLs extrahiert werden
  • UTF-7-Shellcode-Puffer, die an MultiByteToWideChar(CP_UTF7) übergeben werden
  • certutil -decode, reproduziert über ein virtuelles Dateisystem, das aus dem aufgebaut wird, was das Makro geschrieben hat
  • Skripte, die an ScriptControl.AddCode übergeben werden, gemeldet als Skript-Payloads statt als Befehlszeilen
  • PE/ZIP/OLE/PDF-Identifikation anhand von Dateiheadern
• Provenienz überall: Befehle, Payloads und Indikatoren tragen Evidenz-IDs (event-3, command-1, payload-1) und Quellorte. Sekundäre Ansichten verweisen auf ein Element über seine ID, statt große Blobs zu wiederholen.
• Robust gegenüber feindlichen Eingaben: Jede Pipeline-Stufe erholt sich von Panics und zeichnet den Fehler als Diagnose auf. Eine fehlerhafte Probe bringt daher niemals einen Batch-Lauf zum Absturz. Die VBA-Pipeline und die Container-Parser werden gefuzzt.

Download

Vorkompilierte Binärdateien für Windows, Linux und macOS (x64 und ARM64) finden Sie auf der Releases-Seite, zusammen mit SHA-256-Prüfsummen. Die Versionshinweise zu jedem Release stammen aus CHANGELOG.md.

Build

Erfordert Go 1.23+.

go build -o maldocTrace ./cmd/maldoctrace

Unter Windows:

go build -o maldocTrace.exe ./cmd/maldoctrace

Verwendung

maldocTrace inspect <file>
maldocTrace extract <file> --out <dir> [--force]
maldocTrace analyze <file> [--format json|text|jsonl] [--timeout 30s] [--max-steps N]
                           [--input-format vba] [--show-strings] [--dump-payloads DIR]
maldocTrace analyze <dir> --recursive [--format jsonl] [--workers N]
maldocTrace version

Option	Beschreibung
--format text	Menschenlesbarer Bericht (Standard).
--format json	Vollständiger, versionierter JSON-Bericht (Schema 1.3.0). Er enthält immer Indikatoren, Diagnosen, dekodierte Strings und den vollständigen Payload-Inhalt.
--format jsonl	Ein JSON-Bericht pro Zeile, für die Batch-Analyse mit --recursive.
--show-strings	Nur Textformat. Listet die rekonstruierten Strings dedupliziert auf, mit jedem Vorkommen in Modul/Prozedur/Zeile und der Rekonstruktionsmethode.
--dump-payloads DIR	Schreibt dekodierte Payloads und vom Makro abgelegte Dateien nach DIR/<input-sha256>/, mit einer manifest.json. Dateien erhalten neutrale Erweiterungen (.bin, .txt), sodass nichts per Doppelklick ausgeführt werden kann. Vorhandene Dateien werden niemals überschrieben.
--input-format vba	Analysiert eine VBA-Datei im Klartextformat.
--timeout, --max-steps	Zeitbudget pro Datei und Schrittbudget des Interpreters.

Exit-Codes: 0 Erfolg (auch wenn die Probe bösartig ist), 1 Analyse- oder interner Fehler, 2 Nutzungsfehler.

---

Beispiele

Die vier folgenden Berichte stammen aus echten bösartigen Dokumenten und zeigen die wichtigsten Wiederherstellungswege. Lange Blobs werden mit … gekürzt. Die vollständigen Werte stehen in der JSON-Ausgabe.

1. UTF-7-Shellcode-Loader (MultiByteToWideChar → EnumUILanguages)