Macro emulation
Attackers hide the links, commands and file names of a macro behind many small steps. The macro builds them while it runs, so they stay hidden in the text of the macro.
livewells follows the macro code step by step, in a disposable container. It reads the code as data and works out what the macro builds. It reports the links, commands and file names that it finds.
Send a file with macros
Send a Word, Excel or PowerPoint file on the Upload a file tab, or through the API. livewells follows the macros of every Office file it reads. See Word, Excel, PowerPoint and RTF files.
What livewells follows
| Code | Where it comes from |
|---|---|
| VBA macros | Word, Excel and PowerPoint files, in the Open XML format (.docx, .xlsx, .pptx) and in the older binary format |
| Excel 4.0 macros (macro sheets) | Excel files, including hidden and very hidden sheets |
| Compiled macro code | Files where the compiled code is different from the visible macro text |
livewells follows the code of one document at a time. An Office file inside another Office file is a document of its own, up to three levels deep.
How livewells follows the code
- livewells starts at the places that start by themselves: names such as
AutoOpenandDocument_Open, the names that start a macro sheet, and the click and event handlers that the file lists. A macro with no start has every procedure that needs no input followed. - livewells works out the built-in functions the way Office does, and reads the values that the file keeps for the macro: document variables, properties, form and control values, cell values and document text.
- livewells follows loops, branches, calls between modules and strings that the macro builds in many functions. When the macro writes more macro code, livewells follows that code too.
- When the macro builds a command line, livewells decodes the line. This covers PowerShell encoded commands, base64 and compressed text, joined and reversed text, character codes and the escape marks of the command prompt.
Calls that reach outside the file
Many macros start a program, connect to an address or write a file. livewells records each of these calls as a call that the macro would make. It shows the call with its decoded arguments. The arguments are the links, commands and paths that you look for. The calls stay in the report.
| Group | Examples |
|---|---|
| Start a program | Shell, WScript.Shell run and exec, ShellExecute, WMI process create, Excel 4.0 EXEC |
| Connect to an address | XMLHTTP and WinHttp requests, downloads through URLDownloadToFile, HYPERLINK |
| Write or change files | Open for output, FileSystemObject, ADODB.Stream save, Kill, FileCopy, MkDir |
| Change the registry | RegWrite, RegDelete, SaveSetting |
| Start a script host | Script control AddCode, Eval and ExecuteStatement |
| Call a system library | Every Declare line, and each call through it |
| Other | Timed macros (OnTime, OnKey), SendKeys, Run of a name that is not in the file |
When a macro creates an object that livewells cannot model, the call returns an empty value and the report lists the object under Unknown functions and differences.
What the report shows
- Decoded strings. The text that the macro built, with the steps that made it. Each string shows where in the macro it was made.
- Indicators. Links, host names, addresses, mail addresses, file names, commands, registry keys, paths and the SHA-256 of decoded payloads and written files. Each indicator names the decoded string that holds it.
- Calls the macro would make. The table in the section above, with the decoded arguments.
- Second stages. Command lines and scripts that the macro built, with the layers that livewells removed. Programs and shell code that the macro builds are shown by their size and SHA-256.
- Written files. Each file that the macro would write, with its size, its SHA-256 and the start of its text.
- Code that the macro writes. Macro code, scripts and Excel 4.0 formulas that the macro writes and then runs.
- Obfuscation methods. The tricks that livewells met. The table below lists them.
- Where. Each finding shows its place: a module and line, a compiled code position, or an Excel 4.0 sheet and cell. A finding from compiled code is labelled as such.
- Compiled and visible code. When the two differ, livewells follows both. The report lists what only one of them does.
Each web address that the macro builds is an item that you can send to the browser with one click. livewells opens it in a disposable browser. Every address, host name and mail address in the report is defanged. For example, an address appears as hxxps[://]login[.]example[.]com/verify. No address in a report is a link that you can click.
Obfuscation methods
| Method | What it means |
|---|---|
| Joined text | The macro joins many small pieces of text. |
| Character codes | The macro builds text from Chr or ChrW codes. |
| Computed character codes | The macro does a sum, a product or a remainder to get each code. |
| Reversed text | The macro reverses the text. |
| Replaced text | The macro removes or swaps marker text. |
| Xor | The macro decodes with the Xor operator. |
| Base64 | The macro decodes base64. |
| Hex text | The macro decodes hexadecimal text. |
| Picked characters | The macro picks single characters from other text. |
| Joined lists | The macro joins the items of a list. |
| Text conversion | The macro changes the case or the code page of text. |
| Format strings | A command line builds text with a format string. |
| Compressed text | The macro unpacks compressed data. |
| Environment text | The macro takes characters from environment values. |
| Excel 4.0 characters | An Excel 4.0 macro builds text with CHAR. |
| Excel 4.0 joins | An Excel 4.0 macro joins cells. |
| Decode loops | The macro decodes text in a loop. |
| Dynamic calls | The macro picks the name of a call at run time. |
| Document data | The macro reads its text from the document. |
| Self-writing code | The macro writes code and runs it. |
| Many functions | The macro builds one string in three or more functions. |
| Junk code | Much of the code never runs. |
| Dead branches | A branch can never run, and it holds code. |
| Compiled code differs | The compiled code and the visible text are not the same. |
| Encoded PowerShell | A command line holds an encoded PowerShell command. |
| Escape marks | A command line hides its words with ^ or backtick marks. |
Status of each document
Each module and each Excel 4.0 sheet has a status.
| Status | What it means |
|---|---|
| Decoded | livewells followed all the code that can run. |
| Partly decoded | livewells stopped early, met code that is unknown to it, or could not read a statement. The report gives the reason. |
| Not decoded | livewells could not read the code. |
| Not checked | livewells did not follow the code. The reason is that the file is locked, or that the compiled code could not be read. |
| Not supported | The macro data has a version that this checker cannot read. |
When a document is partly decoded, treat the file as hostile and read the indicators that livewells found. The report gives the reason: a step, time, memory, string, array, compression or output limit, a function that is unknown to livewells, or a statement that livewells could not read.
Limits
| Limit | Value |
|---|---|
| Steps | 5,000,000 |
| Memory | 384 MiB |
| One string | 1 MiB |
| One array | 1,000,000 items |
| Unpacked data | 1 MiB, and at most 100 times the packed size |
| Calls inside calls | 200 |
| Decoded strings kept | 500, each up to 2,048 characters |
| Indicators | 500 |
| Calls the macro would make | 500 |
| Second stages | 50 |
| Written files | 24 |
| Unknown items for one module | 100 |
| Report size for this part | 1 MiB |
A macro that goes over a limit gets the status Partly decoded. livewells keeps the findings that it made before the limit and lists the limit in the report.
Flags
| Level | What livewells tells you |
|---|---|
| High | The macro would start a program. |
| High | The macro would connect to another computer. |
| High | The macro would start a script host. |
| High | The macro builds a second program or script. |
| High | The stored code and the visible code differ. |
| High | The macro writes new macro code and runs it. |
| High | The macro builds a link that is not visible in the file. |
| Medium | The macro would write a file to disk. |
| Medium | The macro would change or read the Windows registry. |
| Medium | The macro hides its text with encoding tricks. |
| Medium | Part of the macro code was not emulated. |
| Medium | The macro data could not be read. |
| Medium | The macro data was too large to read. |
| Medium | The file is locked. The macro code was not read. |
| Medium | The macro emulator stopped on this file. |
| Low | The macro calls functions that are outside the livewells model. |
| Info | The macro has no automatic start. All procedures were emulated. |
| Info | The Excel 4.0 macro starts when the workbook opens. |