updated doc and readme

Philippe Lagadec
1 parent cdbcd101
Showing 13 changed files with 452 additions and 115 deletions
README.md
oletools/README.html
oletools/README.rst
oletools/doc/Home.html
oletools/doc/Home.md
oletools/doc/Install.html
oletools/doc/Install.md
oletools/doc/oleid.html
oletools/doc/oleid.md
oletools/doc/oletimes.html
oletools/doc/oletimes.md
oletools/doc/olevba.html
oletools/doc/olevba.md
@@ -22,7 +22,7 @@ Note: python-oletools is not related to OLETools published by BeCubed Software.
 News
 ----
  
-- **2015-02-05 v0.08**: [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba) can now decode strings 
+- **2015-02-08 v0.08**: [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba) 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.
 - 2015-01-05 v0.07: improved [olevba](https://bitbucket.org/decalage/oletools/wiki/olevba) to detect suspicious 
@@ -13,7 +13,7 @@
 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
 <h2 id="news">News</h2>
 <ul>
-<li><strong>2015-02-05 v0.08</strong>: <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>
+<li><strong>2015-02-08 v0.08</strong>: <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>
 <li>2015-01-05 v0.07: improved <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> to detect suspicious keywords and IOCs in VBA macros, can now scan several files and open password-protected zip archives, added a Python API, upgraded OleFileIO_PL to olefile v0.41</li>
 <li>2014-08-28 v0.06: added <a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a>, a new tool to extract VBA Macro source code from MS Office documents (97-2003 and 2007+). Improved <a href="https://bitbucket.org/decalage/oletools/wiki">documentation</a></li>
 <li>2013-07-24 v0.05: added new tools <a href="https://bitbucket.org/decalage/oletools/wiki/olemeta">olemeta</a> and <a href="https://bitbucket.org/decalage/oletools/wiki/oletimes">oletimes</a></li>
@@ -27,7 +27,7 @@ Software.
 News
 ----
  
--  **2015-02-05 v0.08**:
+-  **2015-02-08 v0.08**:
    `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`_ can
    now decode strings obfuscated with Hex/StrReverse/Base64/Dridex and
    extract IOCs. Added new triage mode, support for non-western
@@ -7,7 +7,7 @@
   <title></title>
 </head>
 <body>
-<h1 id="python-oletools-v0.07-documentation">python-oletools v0.07 documentation</h1>
+<h1 id="python-oletools-v0.08-documentation">python-oletools v0.08 documentation</h1>
 <p>This is the home page of the documentation for python-oletools. The latest version can be found <a href="https://bitbucket.org/decalage/oletools/wiki">online</a>, otherwise a copy is provided in the doc subfolder of the package.</p>
 <p><a href="http://www.decalage.info/python/oletools">python-oletools</a> is a package of python tools to analyze <a href="http://en.wikipedia.org/wiki/Compound_File_Binary_Format">Microsoft OLE2 files</a> (also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft Office documents or Outlook messages, mainly for malware analysis, forensics and debugging. It is based on the <a href="http://www.decalage.info/olefile">olefile</a> parser. See <a href="http://www.decalage.info/python/oletools">http://www.decalage.info/python/oletools</a> for more info.</p>
 <p><strong>Quick links:</strong> <a href="http://www.decalage.info/python/oletools">Home page</a> - <a href="https://bitbucket.org/decalage/oletools/wiki/Install">Download/Install</a> - <a href="https://bitbucket.org/decalage/oletools/wiki">Documentation</a> - <a href="https://bitbucket.org/decalage/oletools/issues?status=new&amp;status=open">Report Issues/Suggestions/Questions</a> - <a href="http://decalage.info/contact">Contact the author</a> - <a href="https://bitbucket.org/decalage/oletools">Repository</a> - <a href="https://twitter.com/decalage2">Updates on Twitter</a></p>
@@ -18,7 +18,7 @@
 <li><strong><a href="oleid.html">oleid</a></strong>: a tool to analyze OLE files to detect specific characteristics usually found in malicious files.</li>
 <li><strong><a href="olemeta.html">olemeta</a></strong>: a tool to extract all standard properties (metadata) from OLE files.</li>
 <li><strong><a href="oletimes.html">oletimes</a></strong>: a tool to extract creation and modification timestamps of all streams and storages.</li>
-<li><strong><a href="olevba.html">olevba</a></strong>: a tool to extract VBA Macro source code from MS Office documents (OLE and OpenXML).</li>
+<li><strong><a href="olevba.html">olevba</a></strong>: a tool to extract and analyze VBA Macro source code from MS Office documents (OLE and OpenXML).</li>
 <li><strong><a href="pyxswf.html">pyxswf</a></strong>: a tool to detect, extract and analyze Flash objects (SWF) that may be embedded in files such as MS Office documents (e.g. Word, Excel) and RTF, which is especially useful for malware analysis.</li>
 <li><strong><a href="rtfobj.html">rtfobj</a></strong>: a tool and python module to extract embedded objects from RTF files.</li>
 <li>and a few others (coming soon)</li>
-python-oletools v0.07 documentation
+python-oletools v0.08 documentation
 ===================================
  
 This is the home page of the documentation for python-oletools. The latest version can be found 
@@ -29,7 +29,7 @@ Tools in python-oletools:
 - **[[oleid]]**: a tool to analyze OLE files to detect specific characteristics usually found in malicious files.
 - **[[olemeta]]**: a tool to extract all standard properties (metadata) from OLE files.
 - **[[oletimes]]**: a tool to extract creation and modification timestamps of all streams and storages.
-- **[[olevba]]**: a tool to extract VBA Macro source code from MS Office documents (OLE and OpenXML).
+- **[[olevba]]**: a tool to extract and analyze VBA Macro source code from MS Office documents (OLE and OpenXML).
 - **[[pyxswf]]**: a tool to detect, extract and analyze Flash objects (SWF) that may
   be embedded in files such as MS Office documents (e.g. Word, Excel) and RTF,
   which is especially useful for malware analysis.
@@ -9,14 +9,15 @@
 <body>
 <h1 id="how-to-download-and-install-python-oletools">How to Download and Install python-oletools</h1>
 <h2 id="pre-requisites">Pre-requisites</h2>
-<p>For now, python-oletools require Python 2.x. They are not compatible with Python 3.x yet.</p>
-<h2 id="for-command-line-tools">For command-line tools</h2>
-<p>To use python-oletools from the command line as analysis tools, you may simply <a href="https://bitbucket.org/decalage/oletools/downloads">download the zip archive</a> and extract the files in the directory of your choice.</p>
-<p>You may then add the directory to your PATH environment variable to access the tools from anywhere.</p>
-<p>To get the latest development version, click on &quot;Download repository&quot; on the <a href="https://bitbucket.org/decalage/oletools/downloads">downloads page</a>, or use mercurial to clone the repository.</p>
+<p>For now, python-oletools require Python 2.x, if possible 2.6 or 2.7. They are not compatible with Python 3.x yet.</p>
+<h2 id="to-use-oletools-as-command-line-tools">To use oletools as command-line tools</h2>
+<p>To use python-oletools from the command line as analysis tools, you may simply <a href="https://bitbucket.org/decalage/oletools/downloads">download the zip archive</a> and extract the files in the directory of your choice. Pick the latest release version, or click on &quot;Download Repository&quot; to get the latest development version with the most recent features.</p>
+<p>Another possibility is to use a Mercurial client (hg) to clone the repository in a folder. You can then update it easily in the future.</p>
+<p>You may add the oletools directory to your PATH environment variable to access the tools from anywhere.</p>
 <h2 id="for-python-applications">For python applications</h2>
-<p>If you plan to use python-oletools with other Python applications or your own scripts, the simplest solution is to use &quot;<strong>pip install oletools</strong>&quot; or &quot;<strong>easy_install oletools</strong>&quot; to download and install the package in one go.</p>
-<p>Otherwise you may download/extract the <a href="https://bitbucket.org/decalage/oletools/downloads">zip archive</a> in a temporary directory and run &quot;<strong>python setup.py install</strong>&quot;.</p>
+<p>If you plan to use python-oletools with other Python applications or your own scripts, the simplest solution is to use <strong>&quot;pip install oletools&quot;</strong> or <strong>&quot;easy_install oletools&quot;</strong> to download and install the package in one go. Pip is included with Python since version 2.7.9.</p>
+<p><strong>Important: to update oletools</strong> if it is already installed, you must run <strong>&quot;pip install -U oletools&quot;</strong>, otherwise pip will not update it.</p>
+<p>Alternatively, you may download/extract the <a href="https://bitbucket.org/decalage/oletools/downloads">zip archive</a> in a temporary directory and run <strong>&quot;python setup.py install&quot;</strong>.</p>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 <ul>
@@ -4,30 +4,35 @@ How to Download and Install python-oletools
 Pre-requisites
 --------------
  
-For now, python-oletools require Python 2.x. They are not compatible with Python 3.x yet.
+For now, python-oletools require Python 2.x, if possible 2.6 or 2.7. They are not compatible with Python 3.x yet.
  
  
-For command-line tools
-----------------------
+To use oletools as command-line tools
+-------------------------------------
  
 To use python-oletools from the command line as analysis tools, you may simply 
 [download the zip archive](https://bitbucket.org/decalage/oletools/downloads) 
-and extract the files in the directory of your choice.
+and extract the files in the directory of your choice. Pick the latest release version, or click on "Download Repository"
+to get the latest development version with the most recent features.
  
-You may then add the directory to your PATH environment variable to access the tools from anywhere.
+Another possibility is to use a Mercurial client (hg) to clone the repository in a folder. You can then update it easily
+in the future.
  
-To get the latest development version, click on "Download repository" on the 
-[downloads page](https://bitbucket.org/decalage/oletools/downloads), or use mercurial to clone the repository.
+You may add the oletools directory to your PATH environment variable to access the tools from anywhere.
  
  
 For python applications
-----------------------
+-----------------------
  
 If you plan to use python-oletools with other Python applications or your own scripts, the simplest solution is to use 
-"**pip install oletools**" or "**easy_install oletools**" to download and install the package in one go. 
+**"pip install oletools"** or **"easy_install oletools"** to download and install the package in one go. Pip is included
+with Python since version 2.7.9.
  
-Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary 
-directory and run "**python setup.py install**".
+**Important: to update oletools** if it is already installed, you must run **"pip install -U oletools"**, otherwise pip
+will not update it.
+
+Alternatively, you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary 
+directory and run **"python setup.py install"**.
  
 --------------------------------------------------------------------------
  
@@ -39,19 +39,43 @@
 <pre><code>C:\oletools&gt;oleid.py word_flash_vba.doc
  
 Filename: word_flash_vba.doc
-OLE format: True
-Has SummaryInformation stream: True
-Application name: Microsoft Office Word
-Encrypted: False
-Word Document: True
-VBA Macros: True
-Excel Workbook: False
-PowerPoint Presentation: False
-Visio Drawing: False
-ObjectPool: True
-Flash objects: 1</code></pre>
-<h2 id="how-to-use-oleid-in-python-applications">How to use oleid in Python applications</h2>
-<p>TODO</p>
++-------------------------------+-----------------------+
+| Indicator                     | Value                 |
++-------------------------------+-----------------------+
+| OLE format                    | True                  |
+| Has SummaryInformation stream | True                  |
+| Application name              | Microsoft Office Word |
+| Encrypted                     | False                 |
+| Word Document                 | True                  |
+| VBA Macros                    | True                  |
+| Excel Workbook                | False                 |
+| PowerPoint Presentation       | False                 |
+| Visio Drawing                 | False                 |
+| ObjectPool                    | True                  |
+| Flash objects                 | 1                     |
++-------------------------------+-----------------------+</code></pre>
+<h2 id="how-to-use-oleid-in-your-python-applications">How to use oleid in your Python applications</h2>
+<p>First, import oletools.oleid, and create an <strong>OleID</strong> object to scan a file:</p>
+<pre><code>import oletools.oleid
+
+oid = oletools.oleid.OleID(filename)</code></pre>
+<p>Note: filename can be a filename, a file-like object, or a bytes string containing the file to be analyzed.</p>
+<p>Second, call the <strong>check()</strong> method. It returns a list of <strong>Indicator</strong> objects.</p>
+<p>Each Indicator object has the following attributes:</p>
+<ul>
+<li><strong>id</strong>: str, identifier for the indicator</li>
+<li><strong>name</strong>: str, name to display the indicator</li>
+<li><strong>description</strong>: str, long description of the indicator</li>
+<li><strong>type</strong>: class of the indicator (e.g. bool, str, int)</li>
+<li><strong>value</strong>: value of the indicator</li>
+</ul>
+<p>For example, the following code displays all the indicators:</p>
+<pre><code>indicators = oid.check()
+for i in indicators:
+    print &#39;Indicator id=%s name=&quot;%s&quot; type=%s value=%s&#39; % (i.id, i.name, i.type, repr(i.value))
+    print &#39;description:&#39;, i.description
+    print &#39;&#39;</code></pre>
+<p>See the source code of oleid.py for more details.</p>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 <ul>
@@ -42,21 +42,53 @@ Analyzing a Word document containing a Flash object and VBA macros:
 	C:\oletools>oleid.py word_flash_vba.doc
  
 	Filename: word_flash_vba.doc
-	OLE format: True
-	Has SummaryInformation stream: True
-	Application name: Microsoft Office Word
-	Encrypted: False
-	Word Document: True
-	VBA Macros: True
-	Excel Workbook: False
-	PowerPoint Presentation: False
-	Visio Drawing: False
-	ObjectPool: True
-	Flash objects: 1
-
-## How to use oleid in Python applications	
-
-TODO
+	+-------------------------------+-----------------------+
+	| Indicator                     | Value                 |
+	+-------------------------------+-----------------------+
+	| OLE format                    | True                  |
+	| Has SummaryInformation stream | True                  |
+	| Application name              | Microsoft Office Word |
+	| Encrypted                     | False                 |
+	| Word Document                 | True                  |
+	| VBA Macros                    | True                  |
+	| Excel Workbook                | False                 |
+	| PowerPoint Presentation       | False                 |
+	| Visio Drawing                 | False                 |
+	| ObjectPool                    | True                  |
+	| Flash objects                 | 1                     |
+	+-------------------------------+-----------------------+
+
+## How to use oleid in your Python applications	
+
+First, import oletools.oleid, and create an **OleID** object to scan a file:
+
+	:::python
+	import oletools.oleid
+	
+	oid = oletools.oleid.OleID(filename)
+
+Note: filename can be a filename, a file-like object, or a bytes string containing the file to be analyzed.
+
+Second, call the **check()** method. It returns a list of **Indicator** objects.
+
+Each Indicator object has the following attributes:
+
+- **id**: str, identifier for the indicator
+- **name**: str, name to display the indicator
+- **description**: str, long description of the indicator
+- **type**: class of the indicator (e.g. bool, str, int)
+- **value**: value of the indicator
+
+For example, the following code displays all the indicators:
+
+	:::python
+	indicators = oid.check()
+	for i in indicators:
+		print 'Indicator id=%s name="%s" type=%s value=%s' % (i.id, i.name, i.type, repr(i.value))
+		print 'description:', i.description
+		print ''
+
+See the source code of oleid.py for more details.
  
 --------------------------------------------------------------------------
  
@@ -16,24 +16,29 @@
 <p>Checking the malware sample <a href="https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/">DIAN_caso-5415.doc</a>:</p>
 <pre><code>&gt;oletimes.py DIAN_caso-5415.doc
  
-- Root mtime=2014-05-14 12:45:24.752000 ctime=None
-- &#39;\x01CompObj&#39;: mtime=None ctime=None
-- &#39;\x05DocumentSummaryInformation&#39;: mtime=None ctime=None
-- &#39;\x05SummaryInformation&#39;: mtime=None ctime=None
-- &#39;1Table&#39;: mtime=None ctime=None
-- &#39;Data&#39;: mtime=None ctime=None
-- &#39;Macros&#39;: mtime=2014-05-14 12:45:24.708000 ctime=2014-05-14 12:45:24.355000
-- &#39;Macros/PROJECT&#39;: mtime=None ctime=None
-- &#39;Macros/PROJECTwm&#39;: mtime=None ctime=None
-- &#39;Macros/VBA&#39;: mtime=2014-05-14 12:45:24.684000 ctime=2014-05-14 12:45:24.355000
-- &#39;Macros/VBA/ThisDocument&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/_VBA_PROJECT&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/__SRP_0&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/__SRP_1&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/__SRP_2&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/__SRP_3&#39;: mtime=None ctime=None
-- &#39;Macros/VBA/dir&#39;: mtime=None ctime=None
-- &#39;WordDocument&#39;: mtime=None ctime=None</code></pre>
++----------------------------+---------------------+---------------------+
+| Stream/Storage name        | Modification Time   | Creation Time       |
++----------------------------+---------------------+---------------------+
+| Root                       | 2014-05-14 12:45:24 | None                |
+| &#39;\x01CompObj&#39;              | None                | None                |
+| &#39;\x05DocumentSummaryInform | None                | None                |
+| ation&#39;                     |                     |                     |
+| &#39;\x05SummaryInformation&#39;   | None                | None                |
+| &#39;1Table&#39;                   | None                | None                |
+| &#39;Data&#39;                     | None                | None                |
+| &#39;Macros&#39;                   | 2014-05-14 12:45:24 | 2014-05-14 12:45:24 |
+| &#39;Macros/PROJECT&#39;           | None                | None                |
+| &#39;Macros/PROJECTwm&#39;         | None                | None                |
+| &#39;Macros/VBA&#39;               | 2014-05-14 12:45:24 | 2014-05-14 12:45:24 |
+| &#39;Macros/VBA/ThisDocument&#39;  | None                | None                |
+| &#39;Macros/VBA/_VBA_PROJECT&#39;  | None                | None                |
+| &#39;Macros/VBA/__SRP_0&#39;       | None                | None                |
+| &#39;Macros/VBA/__SRP_1&#39;       | None                | None                |
+| &#39;Macros/VBA/__SRP_2&#39;       | None                | None                |
+| &#39;Macros/VBA/__SRP_3&#39;       | None                | None                |
+| &#39;Macros/VBA/dir&#39;           | None                | None                |
+| &#39;WordDocument&#39;             | None                | None                |
++----------------------------+---------------------+---------------------+</code></pre>
 <h2 id="how-to-use-oletimes-in-python-applications">How to use oletimes in Python applications</h2>
 <p>TODO</p>
 <hr />
@@ -19,24 +19,29 @@ Checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4
 	:::text
 	>oletimes.py DIAN_caso-5415.doc
  
-	- Root mtime=2014-05-14 12:45:24.752000 ctime=None
-	- '\x01CompObj': mtime=None ctime=None
-	- '\x05DocumentSummaryInformation': mtime=None ctime=None
-	- '\x05SummaryInformation': mtime=None ctime=None
-	- '1Table': mtime=None ctime=None
-	- 'Data': mtime=None ctime=None
-	- 'Macros': mtime=2014-05-14 12:45:24.708000 ctime=2014-05-14 12:45:24.355000
-	- 'Macros/PROJECT': mtime=None ctime=None
-	- 'Macros/PROJECTwm': mtime=None ctime=None
-	- 'Macros/VBA': mtime=2014-05-14 12:45:24.684000 ctime=2014-05-14 12:45:24.355000
-	- 'Macros/VBA/ThisDocument': mtime=None ctime=None
-	- 'Macros/VBA/_VBA_PROJECT': mtime=None ctime=None
-	- 'Macros/VBA/__SRP_0': mtime=None ctime=None
-	- 'Macros/VBA/__SRP_1': mtime=None ctime=None
-	- 'Macros/VBA/__SRP_2': mtime=None ctime=None
-	- 'Macros/VBA/__SRP_3': mtime=None ctime=None
-	- 'Macros/VBA/dir': mtime=None ctime=None
-	- 'WordDocument': mtime=None ctime=None
+	+----------------------------+---------------------+---------------------+
+	| Stream/Storage name        | Modification Time   | Creation Time       |
+	+----------------------------+---------------------+---------------------+
+	| Root                       | 2014-05-14 12:45:24 | None                |
+	| '\x01CompObj'              | None                | None                |
+	| '\x05DocumentSummaryInform | None                | None                |
+	| ation'                     |                     |                     |
+	| '\x05SummaryInformation'   | None                | None                |
+	| '1Table'                   | None                | None                |
+	| 'Data'                     | None                | None                |
+	| 'Macros'                   | 2014-05-14 12:45:24 | 2014-05-14 12:45:24 |
+	| 'Macros/PROJECT'           | None                | None                |
+	| 'Macros/PROJECTwm'         | None                | None                |
+	| 'Macros/VBA'               | 2014-05-14 12:45:24 | 2014-05-14 12:45:24 |
+	| 'Macros/VBA/ThisDocument'  | None                | None                |
+	| 'Macros/VBA/_VBA_PROJECT'  | None                | None                |
+	| 'Macros/VBA/__SRP_0'       | None                | None                |
+	| 'Macros/VBA/__SRP_1'       | None                | None                |
+	| 'Macros/VBA/__SRP_2'       | None                | None                |
+	| 'Macros/VBA/__SRP_3'       | None                | None                |
+	| 'Macros/VBA/dir'           | None                | None                |
+	| 'WordDocument'             | None                | None                |
+	+----------------------------+---------------------+---------------------+
  
 ## How to use oletimes in Python applications	
  
@@ -8,7 +8,7 @@
 </head>
 <body>
 <h1 id="olevba">olevba</h1>
-<p>olevba is a script to parse OLE and OpenXML files such as MS Office documents (e.g. Word, Excel), to <strong>detect VBA Macros</strong>, extract their <strong>source code</strong> in clear text, and detect security-related patterns such as <strong>auto-executable macros</strong>, <strong>suspicious VBA keywords</strong> used by malware, and potential <strong>IOCs</strong> (IP addresses, URLs, executable filenames, etc).</p>
+<p>olevba is a script to parse OLE and OpenXML files such as MS Office documents (e.g. Word, Excel), to <strong>detect VBA Macros</strong>, extract their <strong>source code</strong> in clear text, and detect security-related patterns such as <strong>auto-executable macros</strong>, <strong>suspicious VBA keywords</strong> used by malware, and potential <strong>IOCs</strong> (IP addresses, URLs, executable filenames, etc). It also detects and decodes several common <strong>obfuscation methods including Hex encoding, StrReverse, Base64, Dridex</strong>, 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> by John William Davison, with significant modifications.</p>
@@ -24,14 +24,26 @@
 <li>Extract VBA macro source code</li>
 <li>Detect auto-executable macros</li>
 <li>Detect suspicious VBA keywords often used by malware</li>
+<li>Detect and decodes strings obfuscated with Hex/Base64/StrReverse/Dridex</li>
 <li>Extract IOCs/patterns of interest such as IP addresses, URLs, e-mail addresses and executable file names</li>
 <li>Scan multiple files and sample collections (wildcards, recursive)</li>
+<li>Triage mode for a summary view of multiple files</li>
 <li>Scan malware samples in password-protected Zip archives</li>
 <li>Python API to use olevba from your applications</li>
 </ul>
 <p>MS Office files encrypted with a password are also supported, because VBA macro code is never 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 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>olevba checks the file type: If it is an OLE file (i.e MS Office 97-2003), it is parsed right away.</li>
+<li>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.</li>
+<li>olevba identifies all the VBA projects stored in the OLE structure.</li>
+<li>Each VBA project is parsed to find the corresponding OLE streams containing macro code.</li>
+<li>In each of these OLE streams, the VBA macro source code is extracted and decompressed (RLE compression).</li>
+<li>olevba looks for specific strings obfuscated with various algorithms (Hex, Base64, StrReverse, Dridex).</li>
+<li>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).</li>
+</ol>
 <h2 id="usage">Usage</h2>
 <pre><code>Usage: olevba.py [options] &lt;filename&gt; [filename2 ...]
  
@@ -44,9 +56,34 @@ Options:
   -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:*)</code></pre>
-<h3 id="example">Example</h3>
-<p>Checking the malware sample <a href="https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/">DIAN_caso-5415.doc</a>:</p>
+                        (default:*)
+  -t                    triage mode, display results as a summary table
+                        (default for multiple files)
+  -d                    detailed mode, display full results (default for
+                        single file)
+  -i INPUT, --input=INPUT
+                        input file containing VBA source code to be analyzed
+                        (no parsing)
+  --hex                 display all the hex-encoded strings with their decoded
+                        content.</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 --hex</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
@@ -108,22 +145,63 @@ ANALYSIS:
 | 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. 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><strong>OLE</strong>: the file type is OLE, for example MS Office 97-2003</li>
+<li><strong>OpX</strong>: the file type is OpenXML, for example MS Office 2007+</li>
+<li><strong>?</strong>: the file type is not supported</li>
+<li><strong>M</strong>: contains VBA Macros</li>
+<li><strong>A</strong>: auto-executable macros</li>
+<li><strong>S</strong>: suspicious VBA keywords</li>
+<li><strong>I</strong>: potential IOCs</li>
+<li><strong>H</strong>: hex-encoded strings (potential obfuscation)</li>
+<li><strong>B</strong>: Base64-encoded strings (potential obfuscation)</li>
+<li><strong>D</strong>: Dridex-encoded strings (potential obfuscation)</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 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 class:</p>
-<pre><code>from oletools.olevba import VBA_Parser</code></pre>
+<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>Create an instance of the <strong>VBA_Parser</strong> class, providing the name of the file to open as parameter. The file may also be provided as a bytes string containing its data, or a file-like object. In that case, the actual filename may be provided as a second parameter, if available.</p>
+<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. 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 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 (MS Office 2007+).</p>
 <h3 id="detect-vba-macros">Detect VBA macros</h3>
-<p>The method <strong>detect_vba_macros</strong> returns True if VBA macros have been found in the file, False otherwise.</p>
+<p>The method <strong>detect_vba_macros</strong> of a VBA_Parser object returns True if VBA macros have been found in the file, 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 for all the supported formats listed above. However, for some formats such as PowerPoint 97-2003, this method will always return False because VBA Macros are stored in a different way.</p>
+<p>Note: The detection algorithm looks for streams and storage with specific names in the OLE structure, which works fine for all the supported formats listed above. However, for some formats such as PowerPoint 97-2003, this method will 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 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 including embedded files). It is a generator yielding a tuple (filename, stream_path, vba_filename, vba_code) for each VBA macro found.</p>
@@ -141,7 +219,29 @@ else:
     print &#39;VBA filename:&#39;, vba_filename
     print &#39;- &#39;*39
     print vba_code</code></pre>
-<h3 id="detect-auto-executable-macros">Detect auto-executable macros</h3>
+<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, 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 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 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>type may be either 'AutoExec', 'Suspicious', 'IOC', 'Hex String', 'Base64 String' or 'Dridex String'.</li>
+<li>keyword is the string found for auto-executable macros, suspicious keywords or IOCs. For obfuscated strings, it is the decoded value of the string.</li>
+<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: (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 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 description of the trigger. (See the malware example above)</p>
 <p>Sample usage:</p>
@@ -153,7 +253,8 @@ if 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">Detect suspicious VBA keywords</h3>
+<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 keywords often used by malware to act on the system (create files, run commands or applications, write to the registry, etc).</p>
 <p>It returns a list of tuples containing two strings, the detected keyword, and the description of the corresponding malicious behaviour. (See the malware example above)</p>
 <p>Sample usage:</p>
@@ -165,7 +266,8 @@ if 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">Extract potential IOCs</h3>
+<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 patterns of interest, that may be useful for malware analysis and detection (potential Indicators of Compromise): IP addresses, e-mail addresses, URLs, executable file names.</p>
 <p>It returns a list of tuples containing two strings, the pattern type, and the extracted value. (See the malware example above)</p>
 <p>Sample usage:</p>
@@ -5,7 +5,8 @@ olevba is a script to parse OLE and OpenXML files such as MS Office documents
 (e.g. Word, Excel), to **detect VBA Macros**, extract their **source code** in clear text, 
 and detect security-related patterns such as **auto-executable macros**, **suspicious
 VBA keywords** used by malware, and potential **IOCs** (IP addresses, URLs, executable
-filenames, etc).
+filenames, etc). It also detects and decodes several common **obfuscation methods including Hex encoding,
+StrReverse, Base64, Dridex**, 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.
  
@@ -26,8 +27,10 @@ by John William Davison, with significant modifications.
 - Extract VBA macro source code
 - Detect auto-executable macros
 - Detect suspicious VBA keywords often used by malware
+- Detect and decodes strings obfuscated with Hex/Base64/StrReverse/Dridex
 - 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
 - Scan malware samples in password-protected Zip archives
 - Python API to use olevba from your applications
  
@@ -39,6 +42,18 @@ encrypted, only the content of the document.
 See [this article](http://www.decalage.info/en/vba_tools) for more information and technical details about VBA Macros
 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. 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 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).
+
+
 ## Usage
  
 	:::text
@@ -54,10 +69,59 @@ and how they are stored in MS Office documents.
                             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
+                            (default for multiple files)
+      -d                    detailed mode, display full results (default for
+                            single file)
+      -i INPUT, --input=INPUT
+                            input file containing VBA source code to be analyzed
+                            (no parsing)
+      --hex                 display all the hex-encoded strings with their decoded
+                            content.
  
-### Example
+### Examples
+
+Scan a single file:
+
+    :::text
+    olevba.py file.doc
+    
+Scan a single file, stored in a Zip archive with password "infected":
+
+    :::text
+    olevba.py malicious_file.xls.zip -z infected
+    
+Scan a single file, showing all obfuscated strings decoded:
+
+    :::text
+    olevba.py file.doc --hex
+    
+Scan VBA source code extracted into a text file:
+
+    :::text
+    olevba.py -i source_code.vba
+
+Scan a collection of files stored in a folder:
  
-Checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/):
+    :::text
+    olevba.py MalwareZoo/VBA/*
+    
+Scan all .doc and .xls files, recursively in all subfolders:
+
+    :::text
+    olevba.py MalwareZoo/VBA/*.doc MalwareZoo/VBA/*.xls -r
+    
+Scan all .doc files within all .zip files with password, recursively:
+
+    :::text
+    olevba.py MalwareZoo/VBA/*.zip -r -z infected -f *.doc
+
+
+### Detailed analysis mode (default for single file)
+
+When a single file is scanned, or when using the option -d, all details of the analysis are displayed. 
+
+For example, checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/):
  
 	:::text
     >olevba.py c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
@@ -122,33 +186,87 @@ Checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4
     | IOC        | sfjozjero.exe        | Executable file name                    |
     +------------+----------------------+-----------------------------------------+
  
+### Triage mode (default for multiple files)
+
+When several files are scanned, or when using the option -t, a summary of the analysis for each file is displayed.
+This is more convenient for quick triage of a collection of suspicious files.
+
+The following flags show the results of the analysis:
+
+- **OLE**: the file type is OLE, for example MS Office 97-2003
+- **OpX**: the file type is OpenXML, for example MS Office 2007+
+- **?**: the file type is not supported
+- **M**: contains VBA Macros
+- **A**: auto-executable macros
+- **S**: suspicious VBA keywords
+- **I**: potential IOCs
+- **H**: hex-encoded strings (potential obfuscation)
+- **B**: Base64-encoded strings (potential obfuscation)
+- **D**: Dridex-encoded strings (potential obfuscation)
+
+Here is an example:
+
+    :::text
+    c:\>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
+  
+  
+--------------------------------------------------------------------------
+    
 ## How to use olevba in Python applications	
  
 olevba may be used to open a MS Office file, detect if it contains VBA macros, extract and analyze the VBA source code 
 from your own python applications.
  
+IMPORTANT: olevba is currently under active development, therefore this API is likely to change.
+
 ### Import olevba
  
-First, import the **oletools.olevba** package, using at least the VBA_Parser class:
+First, import the **oletools.olevba** package, using at least the VBA_Parser and VBA_Scanner classes:
  
     :::python
-    from oletools.olevba import VBA_Parser
+    from oletools.olevba import VBA_Parser, VBA_Scanner
  
 ### Parse a MS Office file 
  
-Create an instance of the **VBA_Parser** class, providing the name of the file to open as parameter.
-The file may also be provided as a bytes string containing its data, or a file-like object. In that case, the actual 
-filename may be provided as a second parameter, if available.
+To parse a file on disk, create an instance of the **VBA_Parser** class, providing the name of the file to open as parameter.
+For example:
  
     :::python
     vba = VBA_Parser('my_file_with_macros.doc')
+
+The file may also be provided as a bytes string containing its data. In that case, the actual 
+filename must be provided for reference, and the file content with the data parameter. For example:
+
+    :::python
+    myfile = 'my_file_with_macros.doc'
+    filedata = open(myfile, 'rb').read()
+    vba = VBA_Parser(myfile, data=filedata)
  
 VBA_Parser will raise an exception if the file is not a supported format, either OLE (MS Office 97-2003) or OpenXML 
 (MS Office 2007+). 
  
 ### Detect VBA macros
  
-The method **detect_vba_macros** returns True if VBA macros have been found in the file, False otherwise.
+The method **detect_vba_macros** of a VBA_Parser object returns True if VBA macros have been found in the file, 
+False otherwise.
  
     :::python
     if vba.detect_vba_macros():
@@ -158,7 +276,7 @@ The method **detect_vba_macros** returns True if VBA macros have been found in t
  
 Note: The detection algorithm looks for streams and storage with specific names in the OLE structure, which works fine
 for all the supported formats listed above. However, for some formats such as PowerPoint 97-2003, this method will 
-always return False because VBA Macros are stored in a different way.
+always return False because VBA Macros are stored in a different way which is not yet supported by olevba.
  
 Moreover, if the file contains an embedded document (e.g. an Excel workbook inserted into a Word document), this method
 may return True if the embedded document contains VBA Macros, even if the main document does not.
@@ -186,8 +304,49 @@ Example:
         print 'VBA filename:', vba_filename
         print '- '*39
         print vba_code
-    
-### Detect auto-executable macros
+
+### Analyze VBA Source Code
+
+Note: this API is under active development and may change in the future.
+
+The class **VBA_Scanner** can be used to scan the source code of a VBA module to find obfuscated strings,
+suspicious keywords, IOCs, auto-executable macros, etc.
+
+First, create a VBA_Scanner object with a string containing the VBA source code (for example returned by the 
+extract_macros method). Then call the methods **scan** or **scan_summary** to get the results of the analysis.
+
+scan() takes an optional argument include_decoded_strings: if set to True, the results will contain all the encoded
+strings found in the code (Hex, Base64, Dridex) with their decoded value.
+
+**scan** returns a list of tuples (type, keyword, description), one for each item in the results. 
+
+- type may be either 'AutoExec', 'Suspicious', 'IOC', 'Hex String', 'Base64 String' or 'Dridex String'.
+- keyword is the string found for auto-executable macros, suspicious keywords or IOCs. For obfuscated strings, it is
+  the decoded value of the string.
+- description provides a description of the keyword. For obfuscated strings, it is the encoded value of the string.
+
+Example:
+
+    :::python
+    vba_scanner = VBA_Scanner(vba_code)
+    results = vba_scanner.scan(include_decoded_strings=True)
+    for kw_type, keyword, description in results:
+        print 'type=%s - keyword=%s - description=%s' % (kw_type, keyword, description)
+
+The function **scan_vba** is a shortcut for VBA_Scanner(vba_code).scan():
+
+    :::python
+    results = scan_vba(vba_code, include_decoded_strings=True)
+    for kw_type, keyword, description in results:
+        print 'type=%s - keyword=%s - description=%s' % (kw_type, keyword, description)
+        
+**scan_summary** returns a tuple with the number of items found for each category: 
+(autoexec, suspicious, IOCs, hex, base64, dridex).
+
+
+### Detect auto-executable macros (deprecated)
+
+**Deprecated**: It is preferable to use either scan_vba or VBA_Scanner to get all results at once. 
  
 The function **detect_autoexec** checks if VBA macro code contains specific macro names
 that will be triggered when the document/workbook is opened, closed, changed, etc.
@@ -208,7 +367,9 @@ Sample usage:
         print 'Auto-executable macro keywords: None found'
  
  
-### Detect suspicious VBA keywords
+### Detect suspicious VBA keywords (deprecated)
+
+**Deprecated**: It is preferable to use either scan_vba or VBA_Scanner to get all results at once. 
  
 The function **detect_suspicious** checks if VBA macro code contains specific
 keywords often used by malware to act on the system (create files, run
@@ -230,7 +391,9 @@ Sample usage:
         print 'Suspicious VBA keywords: None found'
  
  
-### Extract potential IOCs
+### Extract potential IOCs (deprecated)
+
+**Deprecated**: It is preferable to use either scan_vba or VBA_Scanner to get all results at once. 
  
 The function **detect_patterns** checks if VBA macro code contains specific
 patterns of interest, that may be useful for malware analysis and detection