updated readme and doc for oletools 0.12

Philippe Lagadec
1 parent bd53eff6
Showing 8 changed files with 57 additions and 19 deletions
README.md
oletools/README.html
oletools/README.rst
oletools/doc/Home.html
oletools/doc/Home.md
oletools/doc/olevba.html
oletools/doc/olevba.md
oletools/olevba.py
@@ -22,7 +22,11 @@ Note: python-oletools is not related to OLETools published by BeCubed Software.
 News
 ----
-- **2015-05-29 v0.11**: Improved parsing of MHTML and ActiveMime/MSO files in 
+- **2015-06-19 v0.12**: [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba) can now deobfuscate VBA 
+expressions with any combination of Chr, Asc, Val, StrReverse, Environ, +, \&, using a VBA parser built with
+[pyparsing](http://pyparsing.wikispaces.com). New options to display only the analysis results or only the macros source code. 
+The analysis is now done on all the VBA modules at once.
+- 2015-05-29 v0.11: Improved parsing of MHTML and ActiveMime/MSO files in 
 [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba), added several suspicious keywords to VBA scanner
 (thanks to @ozhermit and Davy Douhine for the suggestions) 
 - 2015-05-06 v0.10: [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba) now supports Word MHTML files
@@ -4,7 +4,8 @@
 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
 <h2 id="news">News</h2>
 <ul>
-<li><strong>2015-05-29 v0.11</strong>: Improved parsing of MHTML and ActiveMime/MSO files in <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a>, added several suspicious keywords to VBA scanner (thanks to <span class="citation">@ozhermit</span> and Davy Douhine for the suggestions)</li>
+<li><strong>2015-06-19 v0.12</strong>: <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> can now deobfuscate VBA expressions with any combination of Chr, Asc, Val, StrReverse, Environ, +, &amp;, using a VBA parser built with <a href="http://pyparsing.wikispaces.com">pyparsing</a>. New options to display only the analysis results or only the macros source code. The analysis is now done on all the VBA modules at once.</li>
+<li>2015-05-29 v0.11: Improved parsing of MHTML and ActiveMime/MSO files in <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a>, added several suspicious keywords to VBA scanner (thanks to <span class="citation">@ozhermit</span> and Davy Douhine for the suggestions)</li>
 <li>2015-05-06 v0.10: <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> now supports Word MHTML files with macros, aka &quot;Single File Web Page&quot; (.mht) - see <a href="https://bitbucket.org/decalage/oletools/issue/10">issue #10</a> for more info</li>
 <li>2015-03-23 v0.09: <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> now supports Word 2003 XML files, added anti-sandboxing/VM detection</li>
 <li>2015-02-08 v0.08: <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> can now decode strings obfuscated with Hex/StrReverse/Base64/Dridex and extract IOCs. Added new triage mode, support for non-western codepages with olefile 0.42, improved API and display, several bugfixes.</li>
@@ -26,9 +26,15 @@ Software.
 News
 ----
--  **2015-05-29 v0.11**: Improved parsing of MHTML and ActiveMime/MSO
-   files in
-   `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`__,
+-  **2015-06-19 v0.12**:
+   `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`__ can
+   now deobfuscate VBA expressions with any combination of Chr, Asc,
+   Val, StrReverse, Environ, +, &, using a VBA parser built with
+   `pyparsing <http://pyparsing.wikispaces.com>`__. New options to
+   display only the analysis results or only the macros source code. The
+   analysis is now done on all the VBA modules at once.
+-  2015-05-29 v0.11: Improved parsing of MHTML and ActiveMime/MSO files
+   in `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`__,
    added several suspicious keywords to VBA scanner (thanks to @ozhermit
    and Davy Douhine for the suggestions)
 -  2015-05-06 v0.10:
-<p>python-oletools v0.11 documentation</p>
+<p>python-oletools v0.12 documentation</p>
 <p>===================================</p>
 <p>This is the home page of the documentation for python-oletools. The latest version can be found</p>
 <p><a href="https://bitbucket.org/decalage/oletools/wiki">online</a>, otherwise a copy is provided in the doc subfolder of the package.</p>
-python-oletools v0.11 documentation
+python-oletools v0.12 documentation
 ===================================
 This is the home page of the documentation for python-oletools. The latest version can be found 
@@ -6,7 +6,7 @@
 <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**, and extracts IOCs from decoded strings.</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>
@@ -29,6 +29,10 @@
 <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>
@@ -43,11 +47,11 @@
 <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+), olevba looks for all OLE files stored in it (e.g. vbaProject.bin), and opens them.</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).</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>
@@ -76,14 +80,20 @@ Options:
                         (default:*)
-  -t                    triage mode, display results as a summary table
+  -t, --triage          triage mode, display results as a summary table
                         (default for multiple files)
-  -d                    detailed mode, display full results (default for
+  -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
@@ -92,7 +102,13 @@ Options:
   --decode              display all the obfuscated strings with their decoded
-                        content (Hex, Base64, StrReverse, Dridex).          </code></pre>
+                        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>
@@ -249,6 +265,7 @@ ANALYSIS:
 <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\*
@@ -7,7 +7,7 @@ and detect security-related patterns such as **auto-executable macros**, **suspi
 VBA keywords** used by malware, anti-sandboxing and anti-virtualization techniques, 
 and potential **IOCs** (IP addresses, URLs, executable filenames, etc). 
 It also detects and decodes several common **obfuscation methods including Hex encoding,
-StrReverse, Base64, Dridex**, and extracts IOCs from decoded strings.
+StrReverse, Base64, Dridex, VBA expressions**, and extracts IOCs from decoded strings.
 It can be used either as a command-line tool, or as a python module from your own applications.
@@ -34,6 +34,8 @@ by John William Davison, with significant modifications.
 - Detect suspicious VBA keywords often used by malware
 - Detect anti-sandboxing and anti-virtualization techniques
 - Detect and decodes strings obfuscated with Hex/Base64/StrReverse/Dridex
+- Deobfuscates VBA expressions with any combination of Chr, Asc, Val, StrReverse, Environ, +, \&, using a VBA parser built with
+[pyparsing](http://pyparsing.wikispaces.com)
 - Extract IOCs/patterns of interest such as IP addresses, URLs, e-mail addresses and executable file names
 - Scan multiple files and sample collections (wildcards, recursive)
 - Triage mode for a summary view of multiple files
@@ -51,11 +53,11 @@ and how they are stored in MS Office documents.
 ## How it works
 1. olevba checks the file type: If it is an OLE file (i.e MS Office 97-2003), it is parsed right away.
-1. If it is a zip file (i.e. MS Office 2007+), olevba looks for all OLE files stored in it (e.g. vbaProject.bin), and opens them.
+1. 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.
 1. olevba identifies all the VBA projects stored in the OLE structure.
 1. Each VBA project is parsed to find the corresponding OLE streams containing macro code.
 1. In each of these OLE streams, the VBA macro source code is extracted and decompressed (RLE compression).
-1. olevba looks for specific strings obfuscated with various algorithms (Hex, Base64, StrReverse, Dridex).
+1. olevba looks for specific strings obfuscated with various algorithms (Hex, Base64, StrReverse, Dridex, VBA expressions).
 1. olevba scans the macro source code and the deobfuscated strings to find suspicious keywords, auto-executable macros
 and potential IOCs (URLs, IP addresses, e-mail addresses, executable filenames, etc).
@@ -75,15 +77,21 @@ and potential IOCs (URLs, IP addresses, e-mail addresses, executable filenames, 
                             if the file is a zip archive, file(s) to be opened
                             within the zip. Wildcards * and ? are supported.
                             (default:*)
-      -t                    triage mode, display results as a summary table
+      -t, --triage          triage mode, display results as a summary table
                             (default for multiple files)
-      -d                    detailed mode, display full results (default for
+      -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).          
+                            content (Hex, Base64, StrReverse, Dridex, VBA).
+      --attr                display the attribute lines at the beginning of VBA
+                            source code
+      --each                analyze each VBA module separately
 ### Examples
@@ -211,6 +219,7 @@ The following flags show the results of the analysis:
 - **H**: hex-encoded strings (potential obfuscation)
 - **B**: Base64-encoded strings (potential obfuscation)
 - **D**: Dridex-encoded strings (potential obfuscation)
+- **V**: VBA string expressions (potential obfuscation)
 Here is an example:
@@ -145,6 +145,7 @@ __version__ = &#39;0.31&#39;
 #------------------------------------------------------------------------------
 # TODO:
+# + option --fast to disable VBA expressions parsing
 # + do not use logging, but a provided logger (null logger by default)
 # + setup logging (common with other oletools)
 # + add xor bruteforcing like bbharvest