MaldocTrace

MaldocTrace é um analisador defensivo para documentos Office maliciosos, escrito em Go. Ele extrai macros VBA e Excel 4.0 (XLM), reconstrói strings ofuscadas e emula as macros em um ambiente totalmente simulado. A saída relata o que o documento faria: os comandos que executaria, os payloads que decodificaria e os arquivos que deixaria cair. Tudo isso é respaldado por evidências que apontam para o módulo, procedimento e linha (ou planilha e célula) que o produziu.

Documentos sem macros também são cobertos. Injeção de template remoto, campos DDE, objetos OLE vinculados e incorporados (incluindo exploits do Equation Editor em RTF), imagens de isca com hiperlink e VBA stomping são relatados como achados estáticos.

---

Recursos

• Extração de contêineres: OLE/CFB (.doc, .xls, .ppt), OOXML (.docx, .docm, .xlsx, .xlsm, .pptm), RTF e texto VBA bruto. Inclui descompressão MS-OVBA, propriedades de controle UserForm e limites de recursos contra zip bombs e contêineres malformados.
• Macros do Excel 4.0 (XLM):
  • planilhas de macro de .xls (fórmulas BIFF8 descompiladas a partir de tokens analisados, usando as tabelas de funções MS-XLS) e .xlsm, incluindo planilhas ocultas e muito ocultas;
  • um interpretador XLM que começa em Auto_Open (qualquer nome que o Excel executaria). Ele segue GOTO, RUN, IF, WHILE/FOR/NEXT, ON.TIME e RETURN, e aplica FORMULA/FORMULA.FILL/SET.VALUE/SET.NAME, de modo que macros auto-decodificadoras reconstroem seu código real;
  • EXEC, CALL, REGISTER e aliases simulados (URLDownloadToFileA, ShellExecuteA, WinExec, CreateProcessA) e FOPEN/FWRITE. Sondagens anti-sandbox (GET.WORKSPACE, GET.WINDOW, GET.CELL) recebem respostas plausíveis, sinalizadas como simuladas;
  • as fórmulas escritas em tempo de execução são listadas como a macro desofuscada.
• Achados estáticos (sem necessidade de emulação):
  • injeção de template remoto (attachedTemplate, RTF \*\template);
  • objetos OLE externos, incluindo monikers MHTML (CVE-2021-40444) e ms-msdt (Follina);
  • campos DDE/DDEAUTO (incluindo os codificados com QUOTE) e fórmulas e links DDE do Excel;
  • objetos incorporados em RTF decodificados da forma como o Word os lê (\objdata ofuscado, cabeçalhos OLE1 corrompidos), com detecção de exploits do Equation Editor: o overflow de FONT do MTEF (CVE-2017-11882 / CVE-2018-0802) e o overflow de MATRIX (CVE-2018-0798), além da extração dos bytes que os seguem;
  • hiperlinks em imagens e células, e iscas de QR-code;
  • VBA stomping: literais de string compilados no p-code mas ausentes do código-fonte significam que o código-fonte exibido não é o código que o Office executa. Esses literais são reportados e verificados em busca de indicadores.
• Esconderijos de payload: valores de células (Sheets("x").Range("A1"), Cells(r, c)), propriedades do documento (BuiltInDocumentProperties("Comments"), propriedades personalizadas), variáveis do documento (ActiveDocument.Variables) e controles UserForm (TextBox.Text, Label.Caption) estão todos disponíveis para a macro emulada.
• Texto do corpo do documento: extraído do Word 97-2003 (piece table) e de .docx. Droppers frequentemente escondem seu payload no corpo do documento e o leem de volta através de ActiveDocument.Paragraphs(n).Range.Text.
• Interpretador VBA: um lexer, parser e interpretador limitado que cobre o subconjunto de VBA do qual o malware depende: procedimentos, parâmetros ByRef, argumentos nomeados, compilação condicional, laços, arrays e as funções de string embutidas.
• Desofuscação estática: dobramento de constantes de Chr/StrReverse/Replace/concatenação. Cada valor registra como foi reconstruído (concatenation+Chr, StrReverse, ...).
• Ambiente simulado:
  • processos: WScript.Shell, Shell, WMI Win32_Process.Create (tanto GetObject quanto CreateObject("winmgmts:..."))
  • arquivos e rede: FileSystemObject, ADODB.Stream, XMLHTTP/WinHttp
  • motores de script: MSScriptControl.ScriptControl
  • modelo de documento do Word: Paragraphs, Range, Delete, SaveAs2
  • modelo de objetos do Excel (Sheets, Worksheets, Range, Cells, Offset), compartilhado com o motor XLM, e ExecuteExcel4Macro/Application.Run em planilhas de macro
  • APIs do Windows declaradas, com ponteiros VarPtr simulados
• Recuperação de payload:
  • decodificação de -EncodedCommand do PowerShell, com dobramento estático de concatenações 'ht'+'tp' antes da extração de URLs
  • buffers de shellcode UTF-7 passados para MultiByteToWideChar(CP_UTF7)
  • certutil -decode, reproduzido sobre um sistema de arquivos virtual construído a partir do que a macro escreveu
  • scripts passados para ScriptControl.AddCode, reportados como payloads de script em vez de linhas de comando
  • identificação de PE/ZIP/OLE/PDF a partir de cabeçalhos de arquivo
• Proveniência em toda parte: comandos, payloads e indicadores carregam IDs de evidência (event-3, command-1, payload-1) e localizações de origem. Visões secundárias referem-se a um item pelo seu ID em vez de repetir grandes blobs.
• Robusto contra entradas hostis: cada estágio do pipeline se recupera de panics e registra a falha como um diagnóstico. Portanto, uma amostra ruim nunca encerra uma execução em lote. O pipeline VBA e os parsers de contêiner são submetidos a fuzzing.

Download

Binários pré-compilados para Windows, Linux e macOS (x64 e ARM64) estão na página de Releases, juntamente com checksums SHA-256. As notas de cada versão vêm do CHANGELOG.md.

Build

Requer Go 1.23+.

go build -o maldocTrace ./cmd/maldoctrace

No Windows:

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

Uso

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

Opção	Descrição
--format text	Relatório legível por humanos (padrão).
--format json	Relatório JSON completo e versionado (esquema 1.3.0). Sempre inclui indicadores, diagnósticos, strings decodificadas e conteúdo completo do payload.
--format jsonl	Um relatório JSON por linha, para análise em lote com --recursive.
--show-strings	Apenas no formato texto. Lista as strings reconstruídas, deduplicadas, com cada ocorrência de módulo/procedimento/linha e o método de reconstrução.
--dump-payloads DIR	Grava os payloads decodificados e os arquivos liberados pela macro em DIR/<input-sha256>/, com um manifest.json. Os arquivos recebem extensões neutras (.bin, .txt), de modo que nada possa ser executado com um duplo clique. Arquivos existentes nunca são sobrescritos.
--input-format vba	Analisa um arquivo VBA em texto simples.
--timeout, --max-steps	Orçamento de tempo por arquivo e orçamento de passos do interpretador.

Códigos de saída: 0 sucesso (mesmo quando a amostra é maliciosa), 1 erro de análise ou interno, 2 erro de uso.

---

Exemplos

Os quatro relatórios abaixo vêm de documentos maliciosos reais e mostram os principais caminhos de recuperação. Blobs longos são encurtados com …. Os valores completos estão na saída JSON.

1. Carregador de shellcode UTF-7 (MultiByteToWideChar → EnumUILanguages)