Peter M. Groen / oletools

<p>olevba</p>
<p>======</p>
<p>olevba is a script to parse OLE and OpenXML files such as MS Office documents</p>
<p>(e.g. Word, Excel), to <strong>detect VBA Macros</strong>, extract their <strong>source code</strong> in clear text,</p>
<p>and detect security-related patterns such as <strong>auto-executable macros</strong>, **suspicious</p>
<p>VBA keywords** used by malware, anti-sandboxing and anti-virtualization techniques,</p>
<p>and potential <strong>IOCs</strong> (IP addresses, URLs, executable filenames, etc).</p>
<p>It also detects and decodes several common **obfuscation methods including Hex encoding,</p>
<p>StrReverse, Base64, Dridex, VBA expressions**, and extracts IOCs from decoded strings.</p>
<p>It can be used either as a command-line tool, or as a python module from your own applications.</p>
<p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
<p>olevba is based on source code from <a href="https://github.com/unixfreak0037/officeparser">officeparser</a></p>
<p>by John William Davison, with significant modifications.</p>
<h2 id="supported-formats">Supported formats</h2>
<ul>
<li><p>Word 97-2003 (.doc, .dot)</p></li>
<li><p>Word 2007+ (.docm, .dotm)</p></li>
<li><p>Word 2003 XML (.xml)</p></li>
<li><p>Word/Excel MHTML, aka Single File Web Page (.mht)</p></li>
<li><p>Excel 97-2003 (.xls)</p></li>
<li><p>Excel 2007+ (.xlsm, .xlsb)</p></li>
<li><p>PowerPoint 2007+ (.pptm, .ppsm)</p></li>
</ul>
<h2 id="main-features">Main Features</h2>
<ul>
<li><p>Detect VBA macros in MS Office 97-2003 and 2007+ files, XML, MHT</p></li>
<li><p>Extract VBA macro source code</p></li>
<li><p>Detect auto-executable macros</p></li>
<li><p>Detect suspicious VBA keywords often used by malware</p></li>
<li><p>Detect anti-sandboxing and anti-virtualization techniques</p></li>
<li><p>Detect and decodes strings obfuscated with Hex/Base64/StrReverse/Dridex</p></li>
<li><p>Deobfuscates VBA expressions with any combination of Chr, Asc, Val, StrReverse, Environ, +, &amp;, using a VBA parser built with</p></li>
</ul>
<p><a href="http://pyparsing.wikispaces.com">pyparsing</a></p>
<ul>
<li><p>Extract IOCs/patterns of interest such as IP addresses, URLs, e-mail addresses and executable file names</p></li>
<li><p>Scan multiple files and sample collections (wildcards, recursive)</p></li>
<li><p>Triage mode for a summary view of multiple files</p></li>
<li><p>Scan malware samples in password-protected Zip archives</p></li>
<li><p>Python API to use olevba from your applications</p></li>
</ul>
<p>MS Office files encrypted with a password are also supported, because VBA macro code is never</p>
<p>encrypted, only the content of the document.</p>
<h2 id="about-vba-macros">About VBA Macros</h2>
<p>See <a href="http://www.decalage.info/en/vba_tools">this article</a> for more information and technical details about VBA Macros</p>
<p>and how they are stored in MS Office documents.</p>
<h2 id="how-it-works">How it works</h2>
<ol style="list-style-type: decimal">
<li><p>olevba checks the file type: If it is an OLE file (i.e MS Office 97-2003), it is parsed right away.</p></li>
<li><p>If it is a zip file (i.e. MS Office 2007+), XML or MHTML, olevba looks for all OLE files stored in it (e.g. vbaProject.bin, editdata.mso), and opens them.</p></li>
<li><p>olevba identifies all the VBA projects stored in the OLE structure.</p></li>
<li><p>Each VBA project is parsed to find the corresponding OLE streams containing macro code.</p></li>
<li><p>In each of these OLE streams, the VBA macro source code is extracted and decompressed (RLE compression).</p></li>
<li><p>olevba looks for specific strings obfuscated with various algorithms (Hex, Base64, StrReverse, Dridex, VBA expressions).</p></li>
<li><p>olevba scans the macro source code and the deobfuscated strings to find suspicious keywords, auto-executable macros</p></li>
</ol>
<p>and potential IOCs (URLs, IP addresses, e-mail addresses, executable filenames, etc).</p>
<h2 id="usage">Usage</h2>
<pre><code>Usage: olevba.py [options] &lt;filename&gt; [filename2 ...]



Options:

  -h, --help            show this help message and exit

  -r                    find files recursively in subdirectories.

  -z ZIP_PASSWORD, --zip=ZIP_PASSWORD

                        if the file is a zip archive, open first file from it,

                        using the provided password (requires Python 2.6+)

  -f ZIP_FNAME, --zipfname=ZIP_FNAME

                        if the file is a zip archive, file(s) to be opened

                        within the zip. Wildcards * and ? are supported.

                        (default:*)

  -t, --triage          triage mode, display results as a summary table

                        (default for multiple files)

  -d, --detailed        detailed mode, display full results (default for

                        single file)

  -a, --analysis        display only analysis results, not the macro source

                        code

  -c, --code            display only VBA source code, do not analyze it

  -i INPUT, --input=INPUT

                        input file containing VBA source code to be analyzed

                        (no parsing)

  --decode              display all the obfuscated strings with their decoded

                        content (Hex, Base64, StrReverse, Dridex, VBA).

  --attr                display the attribute lines at the beginning of VBA

                        source code

  --each                analyze each VBA module separately</code></pre>
<h3 id="examples">Examples</h3>
<p>Scan a single file:</p>
<pre><code>olevba.py file.doc</code></pre>
<p>Scan a single file, stored in a Zip archive with password &quot;infected&quot;:</p>
<pre><code>olevba.py malicious_file.xls.zip -z infected</code></pre>
<p>Scan a single file, showing all obfuscated strings decoded:</p>
<pre><code>olevba.py file.doc --decode</code></pre>
<p>Scan VBA source code extracted into a text file:</p>
<pre><code>olevba.py -i source_code.vba</code></pre>
<p>Scan a collection of files stored in a folder:</p>
<pre><code>olevba.py MalwareZoo/VBA/*</code></pre>
<p>Scan all .doc and .xls files, recursively in all subfolders:</p>
<pre><code>olevba.py MalwareZoo/VBA/*.doc MalwareZoo/VBA/*.xls -r</code></pre>
<p>Scan all .doc files within all .zip files with password, recursively:</p>
<pre><code>olevba.py MalwareZoo/VBA/*.zip -r -z infected -f *.doc</code></pre>
<h3 id="detailed-analysis-mode-default-for-single-file">Detailed analysis mode (default for single file)</h3>
<p>When a single file is scanned, or when using the option -d, all details of the analysis are displayed.</p>
<p>For example, checking the malware sample <a href="https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/">DIAN_caso-5415.doc</a>:</p>
<pre><code>&gt;olevba.py c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected

===============================================================================

FILE: DIAN_caso-5415.doc.malware in c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip

Type: OLE

-------------------------------------------------------------------------------

VBA MACRO ThisDocument.cls

in file: DIAN_caso-5415.doc.malware - OLE stream: Macros/VBA/ThisDocument

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Option Explicit

Private Declare Function URLDownloadToFileA Lib &quot;urlmon&quot; (ByVal FVQGKS As Long,_

ByVal WSGSGY As String, ByVal IFRRFV As String, ByVal NCVOLV As Long, _

ByVal HQTLDG As Long) As Long

Sub AutoOpen()

    Auto_Open

End Sub

Sub Auto_Open()

SNVJYQ

End Sub

Public Sub SNVJYQ()

    [Malicious Code...]

End Sub

Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean

    [Malicious Code...]

    Application.DisplayAlerts = False

    Application.Quit

End Function

Sub Workbook_Open()

    Auto_Open

End Sub



- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ANALYSIS:

+------------+----------------------+-----------------------------------------+

| Type       | Keyword              | Description                             |

+------------+----------------------+-----------------------------------------+

| AutoExec   | AutoOpen             | Runs when the Word document is opened   |

| AutoExec   | Auto_Open            | Runs when the Excel Workbook is opened  |

| AutoExec   | Workbook_Open        | Runs when the Excel Workbook is opened  |

| Suspicious | Lib                  | May run code from a DLL                 |

| Suspicious | Shell                | May run an executable file or a system  |

|            |                      | command                                 |

| Suspicious | Environ              | May read system environment variables   |

| Suspicious | URLDownloadToFileA   | May download files from the Internet    |

| IOC        | http://germanya.com. | URL                                     |

|            | ec/logs/test.exe&quot;    |                                         |

| IOC        | http://germanya.com. | URL                                     |

|            | ec/logs/counter.php&quot; |                                         |

| IOC        | germanya.com         | Executable file name                    |

| IOC        | test.exe             | Executable file name                    |

| IOC        | sfjozjero.exe        | Executable file name                    |

+------------+----------------------+-----------------------------------------+</code></pre>
<h3 id="triage-mode-default-for-multiple-files">Triage mode (default for multiple files)</h3>
<p>When several files are scanned, or when using the option -t, a summary of the analysis for each file is displayed.</p>
<p>This is more convenient for quick triage of a collection of suspicious files.</p>
<p>The following flags show the results of the analysis:</p>
<ul>
<li><p><strong>OLE</strong>: the file type is OLE, for example MS Office 97-2003</p></li>
<li><p><strong>OpX</strong>: the file type is OpenXML, for example MS Office 2007+</p></li>
<li><p><strong>XML</strong>: the file type is Word 2003 XML</p></li>
<li><p><strong>MHT</strong>: the file type is Word MHTML, aka Single File Web Page (.mht)</p></li>
<li><p><strong>?</strong>: the file type is not supported</p></li>
<li><p><strong>M</strong>: contains VBA Macros</p></li>
<li><p><strong>A</strong>: auto-executable macros</p></li>
<li><p><strong>S</strong>: suspicious VBA keywords</p></li>
<li><p><strong>I</strong>: potential IOCs</p></li>
<li><p><strong>H</strong>: hex-encoded strings (potential obfuscation)</p></li>
<li><p><strong>B</strong>: Base64-encoded strings (potential obfuscation)</p></li>
<li><p><strong>D</strong>: Dridex-encoded strings (potential obfuscation)</p></li>
<li><p><strong>V</strong>: VBA string expressions (potential obfuscation)</p></li>
</ul>
<p>Here is an example:</p>
<pre><code>c:\&gt;olevba.py \MalwareZoo\VBA\samples\*

Flags       Filename

----------- -----------------------------------------------------------------

OLE:MASI--- \MalwareZoo\VBA\samples\DIAN_caso-5415.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_1.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_2.doc.malware

OLE:MASI--- \MalwareZoo\VBA\samples\DRIDEX_3.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_4.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_5.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_6.doc.malware

OLE:MAS---- \MalwareZoo\VBA\samples\DRIDEX_7.doc.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_8.doc.malware

OLE:MASIHBD \MalwareZoo\VBA\samples\DRIDEX_9.xls.malware

OLE:MASIH-- \MalwareZoo\VBA\samples\DRIDEX_A.doc.malware

OLE:------- \MalwareZoo\VBA\samples\Normal_Document.doc

OLE:M------ \MalwareZoo\VBA\samples\Normal_Document_Macro.doc

OpX:MASI--- \MalwareZoo\VBA\samples\RottenKitten.xlsb.malware

OLE:MASI-B- \MalwareZoo\VBA\samples\ROVNIX.doc.malware

OLE:MA----- \MalwareZoo\VBA\samples\Word within Word macro auto.doc</code></pre>
<hr />
<h2 id="how-to-use-olevba-in-python-applications">How to use olevba in Python applications</h2>
<p>olevba may be used to open a MS Office file, detect if it contains VBA macros, extract and analyze the VBA source code</p>
<p>from your own python applications.</p>
<p>IMPORTANT: olevba is currently under active development, therefore this API is likely to change.</p>
<h3 id="import-olevba">Import olevba</h3>
<p>First, import the <strong>oletools.olevba</strong> package, using at least the VBA_Parser and VBA_Scanner classes:</p>
<pre><code>from oletools.olevba import VBA_Parser, VBA_Scanner</code></pre>
<h3 id="parse-a-ms-office-file">Parse a MS Office file</h3>
<p>To parse a file on disk, create an instance of the <strong>VBA_Parser</strong> class, providing the name of the file to open as parameter.</p>
<p>For example:</p>
<pre><code>vba = VBA_Parser(&#39;my_file_with_macros.doc&#39;)</code></pre>
<p>The file may also be provided as a bytes string containing its data. In that case, the actual</p>
<p>filename must be provided for reference, and the file content with the data parameter. For example:</p>
<pre><code>myfile = &#39;my_file_with_macros.doc&#39;

filedata = open(myfile, &#39;rb&#39;).read()

vba = VBA_Parser(myfile, data=filedata)</code></pre>
<p>VBA_Parser will raise an exception if the file is not a supported format, either OLE (MS Office 97-2003) or OpenXML</p>
<p>(MS Office 2007+).</p>
<h3 id="detect-vba-macros">Detect VBA macros</h3>
<p>The method <strong>detect_vba_macros</strong> of a VBA_Parser object returns True if VBA macros have been found in the file,</p>
<p>False otherwise.</p>
<pre><code>if vba.detect_vba_macros():

    print &#39;VBA Macros found&#39;

else:

    print &#39;No VBA Macros found&#39;</code></pre>
<p>Note: The detection algorithm looks for streams and storage with specific names in the OLE structure, which works fine</p>
<p>for all the supported formats listed above. However, for some formats such as PowerPoint 97-2003, this method will</p>
<p>always return False because VBA Macros are stored in a different way which is not yet supported by olevba.</p>
<p>Moreover, if the file contains an embedded document (e.g. an Excel workbook inserted into a Word document), this method</p>
<p>may return True if the embedded document contains VBA Macros, even if the main document does not.</p>
<h3 id="extract-vba-macro-source-code">Extract VBA Macro Source Code</h3>
<p>The method <strong>extract_macros</strong> extracts and decompresses source code for each VBA macro found in the file (possibly</p>
<p>including embedded files). It is a generator yielding a tuple (filename, stream_path, vba_filename, vba_code)</p>
<p>for each VBA macro found.</p>
<ul>
<li><p>filename: If the file is OLE (MS Office 97-2003), filename is the path of the file.</p>
<p>If the file is OpenXML (MS Office 2007+), filename is the path of the OLE subfile containing VBA macros within the zip archive,</p>
<p>e.g. word/vbaProject.bin.</p></li>
<li><p>stream_path: path of the OLE stream containing the VBA macro source code</p></li>
<li><p>vba_filename: corresponding VBA filename</p></li>
<li><p>vba_code: string containing the VBA source code in clear text</p></li>
</ul>
<p>Example:</p>
<pre><code>for (filename, stream_path, vba_filename, vba_code) in vba.extract_macros():

    print &#39;-&#39;*79

    print &#39;Filename    :&#39;, filename

    print &#39;OLE stream  :&#39;, stream_path

    print &#39;VBA filename:&#39;, vba_filename

    print &#39;- &#39;*39

    print vba_code</code></pre>
<h3 id="analyze-vba-source-code">Analyze VBA Source Code</h3>
<p>Note: this API is under active development and may change in the future.</p>
<p>The class <strong>VBA_Scanner</strong> can be used to scan the source code of a VBA module to find obfuscated strings,</p>
<p>suspicious keywords, IOCs, auto-executable macros, etc.</p>
<p>First, create a VBA_Scanner object with a string containing the VBA source code (for example returned by the</p>
<p>extract_macros method). Then call the methods <strong>scan</strong> or <strong>scan_summary</strong> to get the results of the analysis.</p>
<p>scan() takes an optional argument include_decoded_strings: if set to True, the results will contain all the encoded</p>
<p>strings found in the code (Hex, Base64, Dridex) with their decoded value.</p>
<p><strong>scan</strong> returns a list of tuples (type, keyword, description), one for each item in the results.</p>
<ul>
<li><p>type may be either 'AutoExec', 'Suspicious', 'IOC', 'Hex String', 'Base64 String' or 'Dridex String'.</p></li>
<li><p>keyword is the string found for auto-executable macros, suspicious keywords or IOCs. For obfuscated strings, it is</p></li>
</ul>
<p>the decoded value of the string.</p>
<ul>
<li>description provides a description of the keyword. For obfuscated strings, it is the encoded value of the string.</li>
</ul>
<p>Example:</p>
<pre><code>vba_scanner = VBA_Scanner(vba_code)

results = vba_scanner.scan(include_decoded_strings=True)

for kw_type, keyword, description in results:

    print &#39;type=%s - keyword=%s - description=%s&#39; % (kw_type, keyword, description)</code></pre>
<p>The function <strong>scan_vba</strong> is a shortcut for VBA_Scanner(vba_code).scan():</p>
<pre><code>results = scan_vba(vba_code, include_decoded_strings=True)

for kw_type, keyword, description in results:

    print &#39;type=%s - keyword=%s - description=%s&#39; % (kw_type, keyword, description)</code></pre>
<p><strong>scan_summary</strong> returns a tuple with the number of items found for each category:</p>
<p>(autoexec, suspicious, IOCs, hex, base64, dridex).</p>
<h3 id="detect-auto-executable-macros-deprecated">Detect auto-executable macros (deprecated)</h3>
<p><strong>Deprecated</strong>: It is preferable to use either scan_vba or VBA_Scanner to get all results at once.</p>
<p>The function <strong>detect_autoexec</strong> checks if VBA macro code contains specific macro names</p>
<p>that will be triggered when the document/workbook is opened, closed, changed, etc.</p>
<p>It returns a list of tuples containing two strings, the detected keyword, and the</p>
<p>description of the trigger. (See the malware example above)</p>
<p>Sample usage:</p>
<pre><code>from oletools.olevba import detect_autoexec

autoexec_keywords = detect_autoexec(vba_code)

if autoexec_keywords:

    print &#39;Auto-executable macro keywords found:&#39;

    for keyword, description in autoexec_keywords:

        print &#39;%s: %s&#39; % (keyword, description)

else:

    print &#39;Auto-executable macro keywords: None found&#39;</code></pre>
<h3 id="detect-suspicious-vba-keywords-deprecated">Detect suspicious VBA keywords (deprecated)</h3>
<p><strong>Deprecated</strong>: It is preferable to use either scan_vba or VBA_Scanner to get all results at once.</p>
<p>The function <strong>detect_suspicious</strong> checks if VBA macro code contains specific</p>
<p>keywords often used by malware to act on the system (create files, run</p>
<p>commands or applications, write to the registry, etc).</p>
<p>It returns a list of tuples containing two strings, the detected keyword, and the</p>
<p>description of the corresponding malicious behaviour. (See the malware example above)</p>
<p>Sample usage:</p>
<pre><code>from oletools.olevba import detect_suspicious

suspicious_keywords = detect_suspicious(vba_code)

if suspicious_keywords:

    print &#39;Suspicious VBA keywords found:&#39;

    for keyword, description in suspicious_keywords:

        print &#39;%s: %s&#39; % (keyword, description)

else:

    print &#39;Suspicious VBA keywords: None found&#39;</code></pre>
<h3 id="extract-potential-iocs-deprecated">Extract potential IOCs (deprecated)</h3>
<p><strong>Deprecated</strong>: It is preferable to use either scan_vba or VBA_Scanner to get all results at once.</p>
<p>The function <strong>detect_patterns</strong> checks if VBA macro code contains specific</p>
<p>patterns of interest, that may be useful for malware analysis and detection</p>
<p>(potential Indicators of Compromise): IP addresses, e-mail addresses,</p>
<p>URLs, executable file names.</p>
<p>It returns a list of tuples containing two strings, the pattern type, and the</p>
<p>extracted value. (See the malware example above)</p>
<p>Sample usage:</p>
<pre><code>from oletools.olevba import detect_patterns

patterns = detect_patterns(vba_code)

if patterns:

    print &#39;Patterns found:&#39;

    for pattern_type, value in patterns:

        print &#39;%s: %s&#39; % (pattern_type, value)

else:

    print &#39;Patterns: None found&#39;</code></pre>
<h3 id="close-the-vba_parser">Close the VBA_Parser</h3>
<p>After usage, it is better to call the <strong>close</strong> method of the VBA_Parser object, to make sure the file is closed,</p>
<p>especially if your application is parsing many files.</p>
<pre><code>vba.close()</code></pre>
<hr />
<p>python-oletools documentation</p>
<hr />
<ul>
<li><p><a href="Home.html">Home</a></p></li>
<li><p><a href="License.html">License</a></p></li>
<li><p><a href="Install.html">Install</a></p></li>
<li><p><a href="Contribute.html">Contribute</a>, Suggest Improvements or Report Issues</p></li>
<li><p>Tools:</p>
<ul>
<li><p><a href="olebrowse.html">olebrowse</a></p></li>
<li><p><a href="oleid.html">oleid</a></p></li>
<li><p><a href="olemeta.html">olemeta</a></p></li>
<li><p><a href="oletimes.html">oletimes</a></p></li>
<li><p><a href="olevba.html">olevba</a></p></li>
<li><p><a href="pyxswf.html">pyxswf</a></p></li>
<li><p><a href="rtfobj.html">rtfobj</a></p></li>
</ul></li>
</ul>