updated doc and setup.py for v0.50

decalage2
1 parent d02c8456
Showing 17 changed files with 342 additions and 85 deletions
oletools/README.html
oletools/README.rst
oletools/doc/Contribute.html
oletools/doc/Contribute.md
oletools/doc/Home.html
oletools/doc/Home.md
oletools/doc/Install.html
oletools/doc/Install.md
oletools/doc/mraptor.html
oletools/doc/mraptor.md
oletools/doc/olebrowse.html
oletools/doc/olebrowse.md
oletools/doc/olevba.html
oletools/doc/olevba.md
oletools/doc/rtfobj.html
oletools/doc/rtfobj.md
setup.py
@@ -9,12 +9,19 @@
 </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</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><a href="http://www.decalage.info/python/oletools">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://github.com/decalage2/oletools/wiki/Install">Download/Install</a> - <a href="https://github.com/decalage2/oletools/wiki">Documentation</a> - <a href="https://github.com/decalage2/oletools/issues">Report Issues/Suggestions/Questions</a> - <a href="http://decalage.info/contact">Contact the Author</a> - <a href="https://github.com/decalage2/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>2016-06-10 v0.47</strong>: <a href="https://github.com/decalage2/oletools/wiki/olevba">olevba</a> added PPT97 macros support, improved handling of malformed/incomplete documents, improved error handling and JSON output, now returns an exit code based on analysis results, new --relaxed option. <a href="https://github.com/decalage2/oletools/wiki/rtfobj">rtfobj</a>: improved parsing to handle obfuscated RTF documents, added -d option to set output dir. Moved repository and documentation to GitHub.</li>
+<li><strong>2016-10-?? v0.50 (development version)</strong>: most tools now support python 2 and 3.
+<ul>
+<li>olevba: Several bugfixes and improvements.</li>
+<li>mraptor: improved detection, added mraptor_milter for Sendmail/Postfix integration.</li>
+<li>rtfobj: brand new RTF parser, obfuscation-aware, improved display, detect executable files in OLE Package objects.</li>
+<li>setup: now creates handy command-line scripts to run oletools from anywhere.</li>
+</ul></li>
+<li>2016-06-10 v0.47: <a href="https://github.com/decalage2/oletools/wiki/olevba">olevba</a> added PPT97 macros support, improved handling of malformed/incomplete documents, improved error handling and JSON output, now returns an exit code based on analysis results, new --relaxed option. <a href="https://github.com/decalage2/oletools/wiki/rtfobj">rtfobj</a>: improved parsing to handle obfuscated RTF documents, added -d option to set output dir. Moved repository and documentation to GitHub.</li>
 <li>2016-04-19 v0.46: <a href="https://github.com/decalage2/oletools/wiki/olevba">olevba</a> does not deobfuscate VBA expressions by default (much faster), new option --deobf to enable it. Fixed color display bug on Windows for several tools.</li>
 <li>2016-04-12 v0.45: improved <a href="https://github.com/decalage2/oletools/wiki/rtfobj">rtfobj</a> to handle several <a href="http://www.decalage.info/rtf_tricks">anti-analysis tricks</a>, improved <a href="https://github.com/decalage2/oletools/wiki/olevba">olevba</a> to export results in JSON format.</li>
 <li>2016-03-11 v0.44: improved <a href="https://github.com/decalage2/oletools/wiki/olevba">olevba</a> to extract and analyse strings from VBA Forms.</li>
@@ -51,6 +58,8 @@
 <li><a href="https://github.com/decalage2/oletools/wiki/rtfobj">rtfobj</a>: to extract embedded objects from RTF files.</li>
 <li>and a few others (coming soon)</li>
 </ul>
+<h2 id="projects-using-oletools">Projects using oletools:</h2>
+<p>oletools are used by a number of projects and online malware analysis services, including <a href="http://viper.li/">Viper</a>, <a href="https://remnux.org/">REMnux</a>, <a href="https://www.hybrid-analysis.com/">Hybrid-analysis.com</a>, <a href="https://www.document-analyzer.net/">Joe Sandbox</a>, <a href="https://sandbox.deepviz.com/">Deepviz</a>, <a href="https://github.com/lmco/laikaboss">Laika BOSS</a>, <a href="https://github.com/cuckoosandbox/cuckoo">Cuckoo Sandbox</a>, <a href="https://sandbox.anlyz.io/">Anlyz.io</a>, <a href="https://github.com/bontchev/pcodedmp">pcodedmp</a> and probably <a href="https://www.virustotal.com">VirusTotal</a>. (Please <a href="(http://decalage.info/contact)">contact me</a> if you have or know a project using oletools)</p>
 <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://github.com/decalage2/oletools/releases">download the latest release archive</a> and extract the files into the directory of your choice.</p>
 <p>You may also download the <a href="https://github.com/decalage2/oletools/archive/master.zip">latest development version</a> with the most recent features.</p>
 python-oletools
 ===============
  
-`python-oletools <http://www.decalage.info/python/oletools>`__ is a
-package of python tools to analyze `Microsoft OLE2
+`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
@@ -26,7 +26,18 @@ Software.
 News
 ----
  
--  **2016-06-10 v0.47**:
+-  **2016-10-?? v0.50 (development version)**: most tools now support
+   python 2 and 3.
+
+   -  olevba: Several bugfixes and improvements.
+   -  mraptor: improved detection, added mraptor\_milter for
+      Sendmail/Postfix integration.
+   -  rtfobj: brand new RTF parser, obfuscation-aware, improved display,
+      detect executable files in OLE Package objects.
+   -  setup: now creates handy command-line scripts to run oletools from
+      anywhere.
+
+-  2016-06-10 v0.47:
    `olevba <https://github.com/decalage2/oletools/wiki/olevba>`__ added
    PPT97 macros support, improved handling of malformed/incomplete
    documents, improved error handling and JSON output, now returns an
@@ -152,6 +163,23 @@ Tools in python-oletools:
    extract embedded objects from RTF files.
 -  and a few others (coming soon)
  
+Projects using oletools:
+------------------------
+
+oletools are used by a number of projects and online malware analysis
+services, including `Viper <http://viper.li/>`__,
+`REMnux <https://remnux.org/>`__,
+`Hybrid-analysis.com <https://www.hybrid-analysis.com/>`__, `Joe
+Sandbox <https://www.document-analyzer.net/>`__,
+`Deepviz <https://sandbox.deepviz.com/>`__, `Laika
+BOSS <https://github.com/lmco/laikaboss>`__, `Cuckoo
+Sandbox <https://github.com/cuckoosandbox/cuckoo>`__,
+`Anlyz.io <https://sandbox.anlyz.io/>`__,
+`pcodedmp <https://github.com/bontchev/pcodedmp>`__ and probably
+`VirusTotal <https://www.virustotal.com>`__. (Please `contact
+me <(http://decalage.info/contact)>`__ if you have or know a project
+using oletools)
+
 Download and Install:
 ---------------------
  
@@ -10,8 +10,8 @@
 <body>
 <h1 id="how-to-suggest-improvements-report-issues-or-contribute">How to Suggest Improvements, Report Issues or Contribute</h1>
 <p>This is a personal open-source project, developed on my spare time. Any contribution, suggestion, feedback or bug report is welcome.</p>
-<p>To <strong>suggest improvements, report a bug or any issue</strong>, please use the <a href="https://github.com/decalage2/oletools/issues">issue reporting page</a>, providing all the information and files to reproduce the problem.</p>
-<p>You may also <a href="http://decalage.info/contact">contact the author</a> directly to <strong>provide feedback</strong>.</p>
+<p>To <strong>suggest improvements, report a bug or any issue</strong>, please use the <a href="https://github.com/decalage2/oletools/issues">issue reporting page</a>, and provide all the information and files to reproduce the problem.</p>
+<p>You may also <a href="http://decalage.info/contact">contact the author</a> directly to <strong>send feedback</strong>.</p>
 <p>The code is available in <a href="https://github.com/decalage2/oletools">a repository on GitHub</a>. You may use it to <strong>submit enhancements</strong> using forks and pull requests.</p>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 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.
+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://github.com/decalage2/oletools/issues),
-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://github.com/decalage2/oletools/issues),
+and provide all the information and files to reproduce the problem.
  
-You may also [contact the author](http://decalage.info/contact) directly to **provide feedback**.
+You may also [contact the author](http://decalage.info/contact) directly
+to **send feedback**.
  
 The code is available in [a repository on GitHub](https://github.com/decalage2/oletools).
 You may use it to **submit enhancements** using forks and pull requests.
@@ -8,7 +8,7 @@
   <style type="text/css">code{white-space: pre;}</style>
 </head>
 <body>
-<h1 id="python-oletools-v0.47-documentation">python-oletools v0.47 documentation</h1>
+<h1 id="python-oletools-v0.50-documentation">python-oletools v0.50 documentation</h1>
 <p>This is the home page of the documentation for python-oletools. The latest version can be found <a href="https://github.com/decalage2/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://github.com/decalage2/oletools/wiki/Install">Download/Install</a> - <a href="https://github.com/decalage2/oletools/wiki">Documentation</a> - <a href="https://github.com/decalage2/oletools/issues">Report Issues/Suggestions/Questions</a> - <a href="http://decalage.info/contact">Contact the Author</a> - <a href="https://github.com/decalage2/oletools">Repository</a> - <a href="https://twitter.com/decalage2">Updates on Twitter</a></p>
-python-oletools v0.47 documentation
+python-oletools v0.50 documentation
 ===================================
  
 This is the home page of the documentation for python-oletools. The latest version can be found 
@@ -10,24 +10,39 @@
 <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 <strong>Python 2.x</strong>, if possible 2.7 or 2.6 to enable all features.</p>
-<p>They are not compatible with Python 3.x yet. (Please contact me if that is a strong requirement)</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://github.com/decalage2/oletools/releases">download the latest release archive</a> and extract the files into the directory of your choice.</p>
-<p>You may also download the <a href="https://github.com/decalage2/oletools/archive/master.zip">latest development version</a> with the most recent features.</p>
-<p>Another possibility is to use a git client to clone the repository (https://github.com/decalage2/oletools.git) into a folder. You can then update it easily in the future.</p>
-<h3 id="windows">Windows</h3>
-<p>You may add the oletools directory to your PATH environment variable to access the tools from anywhere.</p>
+<p>The recommended Python version to run oletools is <strong>Python 2.7</strong>. Python 2.6 is also supported, but as it is not tested as often as 2.7, some features might not work as expected.</p>
+<p>Since oletools v0.50, thanks to contributions by <span class="citation">[@Sebdraven]</span>(https://twitter.com/Sebdraven), most tools can also run with <strong>Python 3.x</strong>. As this is quite new, please <a href="(https://github.com/decalage2/oletools/issues)">report any issue</a> you may encounter.</p>
+<h2 id="recommended-way-to-downloadinstallupdate-oletools-pip">Recommended way to Download+Install/Update oletools: pip</h2>
+<p>Pip is included with Python since version 2.7.9 and 3.4. If it is not installed on your system, either upgrade Python or see https://pip.pypa.io/en/stable/installing/</p>
 <h3 id="linux-mac-osx-unix">Linux, Mac OSX, Unix</h3>
-<p>It is very convenient to create symbolic links to each tool in one of the bin directories in order to run them as shell commands from anywhere. For example, here is how to create an executable link &quot;olevba&quot; in <code>/usr/local/bin</code> pointing to olevba.py, assuming oletools was unzipped into /opt/oletools:</p>
-<pre class="text"><code>chmod +x /opt/oletools/oletools/olevba.py
-ln -s /opt/oletools/oletools/olevba.py /usr/local/bin/olevba</code></pre>
-<p>Then the olevba command can be used from any directory:</p>
-<pre class="text"><code>user@remnux:~/MalwareZoo/VBA$ olevba dridex427.xls |less</code></pre>
-<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 <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 if you prefer the old school way, you may download the <a href="https://github.com/decalage2/oletools/releases">latest archive</a>, extract it into a temporary directory and run <strong>&quot;python setup.py install&quot;</strong>.</p>
+<p>To download and install/update the latest release version of oletools, run the following command in a shell:</p>
+<pre class="text"><code>sudo -H pip install -U oletools</code></pre>
+<p><strong>Important</strong>: Since version 0.50, pip will automatically create convenient command-line scripts in /usr/local/bin to run all the oletools from any directory.</p>
+<h3 id="windows">Windows</h3>
+<p>To download and install/update the latest release version of oletools, run the following command in a cmd window:</p>
+<pre class="text"><code>pip install -U oletools</code></pre>
+<p><strong>Important</strong>: Since version 0.50, pip will automatically create convenient command-line scripts to run all the oletools from any directory: olevba, mraptor, oleid, rtfobj, etc.</p>
+<h2 id="how-to-install-the-latest-development-version">How to install the latest development version</h2>
+<p>If you want to benefit from the latest improvements in the development version, you may also use pip:</p>
+<h3 id="linux-mac-osx-unix-1">Linux, Mac OSX, Unix</h3>
+<pre class="text"><code>sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></pre>
+<h3 id="windows-1">Windows</h3>
+<pre class="text"><code>pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></pre>
+<h2 id="how-to-install-offline---computer-without-internet-access">How to install offline - Computer without Internet access</h2>
+<p>First, download the oletools archive on a computer with Internet access: * Latest stable version: from https://github.com/decalage2/oletools/releases * Development version: https://github.com/decalage2/oletools/archive/master.zip</p>
+<p>Copy the archive file to the target computer.</p>
+<p>On Linux, Mac OSX, Unix, run the following command using the filename of the archive that you downloaded:</p>
+<pre class="text"><code>sudo -H pip install -U oletools.zip</code></pre>
+<p>On Windows:</p>
+<pre class="text"><code>pip install -U oletools.zip</code></pre>
+<h2 id="old-school-install-using-setup.py">Old school install using setup.py</h2>
+<p>If you cannot use pip, it is still possible to run the setup.py script directly. However, this method will not create the command-line scripts automatically.</p>
+<p>First, download the oletools archive: * Latest stable version: from https://github.com/decalage2/oletools/releases * Development version: https://github.com/decalage2/oletools/archive/master.zip</p>
+<p>Then extract the archive, open a shell and go to the oletools directory.</p>
+<h3 id="linux-mac-osx-unix-2">Linux, Mac OSX, Unix</h3>
+<pre class="text"><code>sudo -H python setup.py install</code></pre>
+<h3 id="windows-2">Windows:</h3>
+<pre class="text"><code>python setup.py install</code></pre>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 <ul>
@@ -4,56 +4,113 @@ How to Download and Install python-oletools
 Pre-requisites
 --------------
  
-For now, python-oletools require **Python 2.x**, if possible 2.7 or 2.6 to enable all features. 
+The recommended Python version to run oletools is **Python 2.7**.
+Python 2.6 is also supported, but as it is not tested as often as 2.7, some features
+might not work as expected.
  
-They are not compatible with Python 3.x yet. (Please contact me if that is a strong requirement)
+Since oletools v0.50, thanks to contributions by [@Sebdraven](https://twitter.com/Sebdraven),
+most tools can also run with **Python 3.x**. As this is quite new, please
+[report any issue]((https://github.com/decalage2/oletools/issues)) you may encounter.
  
  
-To use oletools as command-line tools
--------------------------------------
  
-To use python-oletools from the command line as analysis tools, you may simply 
-[download the latest release archive](https://github.com/decalage2/oletools/releases)
-and extract the files into the directory of your choice.
+Recommended way to Download+Install/Update oletools: pip
+--------------------------------------------------------
  
-You may also download the [latest development version](https://github.com/decalage2/oletools/archive/master.zip) with the most recent features.
+Pip is included with Python since version 2.7.9 and 3.4. If it is not installed on your
+system, either upgrade Python or see https://pip.pypa.io/en/stable/installing/
  
-Another possibility is to use a git client to clone the repository (https://github.com/decalage2/oletools.git) into a folder.
-You can then update it easily in the future.
+### Linux, Mac OSX, Unix
+
+To download and install/update the latest release version of oletools,
+run the following command in a shell:
+
+```text
+sudo -H pip install -U oletools
+```
+
+**Important**: Since version 0.50, pip will automatically create convenient command-line scripts
+in /usr/local/bin to run all the oletools from any directory.
  
 ### Windows
  
-You may add the oletools directory to your PATH environment variable to access the tools from anywhere.
+To download and install/update the latest release version of oletools,
+run the following command in a cmd window:
+
+```text
+pip install -U oletools
+```
+
+**Important**: Since version 0.50, pip will automatically create convenient command-line scripts
+to run all the oletools from any directory: olevba, mraptor, oleid, rtfobj, etc.
+
+
+How to install the latest development version
+---------------------------------------------
+
+If you want to benefit from the latest improvements in the development version,
+you may also use pip:
  
 ### Linux, Mac OSX, Unix
  
-It is very convenient to create symbolic links to each tool in one of the bin directories in order to run them as shell 
-commands from anywhere. For example, here is how to create an executable link "olevba" in `/usr/local/bin` pointing to
-olevba.py, assuming oletools was unzipped into /opt/oletools:
+```text
+sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip
+```
+
+### Windows
+
+```text
+pip install -U https://github.com/decalage2/oletools/archive/master.zip
+```
+
+How to install offline - Computer without Internet access
+---------------------------------------------------------
+
+First, download the oletools archive on a computer with Internet access:
+* Latest stable version: from https://github.com/decalage2/oletools/releases
+* Development version: https://github.com/decalage2/oletools/archive/master.zip
+
+Copy the archive file to the target computer.
+
+On Linux, Mac OSX, Unix, run the following command using the filename of the
+archive that you downloaded:
  
 ```text
-chmod +x /opt/oletools/oletools/olevba.py
-ln -s /opt/oletools/oletools/olevba.py /usr/local/bin/olevba
+sudo -H pip install -U oletools.zip
 ```
-Then the olevba command can be used from any directory:
+
+On Windows:
  
 ```text
-user@remnux:~/MalwareZoo/VBA$ olevba dridex427.xls |less
+pip install -U oletools.zip
 ```
  
-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 is included
-with Python since version 2.7.9.
+Old school install using setup.py
+---------------------------------
+
+If you cannot use pip, it is still possible to run the setup.py script
+directly. However, this method will not create the command-line scripts
+automatically.
+
+First, download the oletools archive:
+* Latest stable version: from https://github.com/decalage2/oletools/releases
+* Development version: https://github.com/decalage2/oletools/archive/master.zip
  
-**Important: to update oletools** if it is already installed, you must run **"pip install -U oletools"**, otherwise pip
-will not update it.
+Then extract the archive, open a shell and go to the oletools directory.
+
+### Linux, Mac OSX, Unix
+
+```text
+sudo -H python setup.py install
+```
+
+### Windows:
+
+```text
+python setup.py install
+```
  
-Alternatively if you prefer the old school way, you may download the 
-[latest archive](https://github.com/decalage2/oletools/releases), extract it into
-a temporary directory and run **"python setup.py install"**.
  
 --------------------------------------------------------------------------
  
@@ -9,8 +9,11 @@
 </head>
 <body>
 <h1 id="mraptor-macroraptor">mraptor (MacroRaptor)</h1>
-<p>mraptor is a script to detect malicious VBA Macros.</p>
-<p>It can be used either as a command-line tool, or as a python module from your own applications.</p>
+<p>mraptor is a tool designed to detect most malicious VBA Macros using generic heuristics. Unlike antivirus engines, it does not rely on signatures.</p>
+<p>In a nutshell, mraptor detects keywords corresponding to the three following types of behaviour that are present in clear text in almost any macro malware: - A: Auto-execution trigger - W: Write to the file system or memory - X: Execute a file or any payload outside the VBA context</p>
+<p>mraptor considers that a macro is suspicious when A and (W or X) is true.</p>
+<p>For more information about mraptor's detection algorithm, see the article <a href="http://www.decalage.info/mraptor">How to detect most malicious macros without an antivirus</a>.</p>
+<p>mraptor 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>
 <h2 id="usage">Usage</h2>
 <pre class="text"><code>Usage: mraptor.py [options] &lt;filename&gt; [filename2 ...]
@@ -47,6 +50,8 @@ An exit code is returned based on the analysis result:
 <div class="figure">
 <img src="mraptor1.png" />
 </div>
+<h2 id="python-3-support---mraptor3">Python 3 support - mraptor3</h2>
+<p>As of v0.50, mraptor has been ported to Python 3 thanks to <span class="citation">@sebdraven</span>. However, the differences between Python 2 and 3 are significant and for now there is a separate version of mraptor named mraptor3 to be used with Python 3.</p>
 <hr />
 <h2 id="how-to-use-mraptor-in-python-applications">How to use mraptor in Python applications</h2>
 <p>TODO</p>
 mraptor (MacroRaptor)
 =====================
  
-mraptor is a script to detect malicious VBA Macros.
+mraptor is a tool designed to detect most malicious VBA Macros using
+generic heuristics. Unlike antivirus engines, it does not rely on signatures.
  
-It can be used either as a command-line tool, or as a python module from your own applications.
+In a nutshell, mraptor detects keywords corresponding to the three
+following types of behaviour that are present in clear text in almost
+any macro malware:
+- A: Auto-execution trigger
+- W: Write to the file system or memory
+- X: Execute a file or any payload outside the VBA context
+
+mraptor considers that a macro is suspicious when A and (W or X) is true.
+
+For more information about mraptor's detection algorithm, see the article
+[How to detect most malicious macros without an antivirus](http://www.decalage.info/mraptor).
+
+mraptor 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.
  
@@ -61,12 +75,21 @@ list of files matching the wildcards before starting the script.
  
 ![](mraptor1.png)
  
+## Python 3 support - mraptor3
+
+As of v0.50, mraptor has been ported to Python 3 thanks to @sebdraven.
+However, the differences between Python 2 and 3 are significant and for now
+there is a separate version of mraptor named mraptor3 to be used with
+Python 3.
+
+
 --------------------------------------------------------------------------
  
 ## How to use mraptor in Python applications
  
 TODO
  
+
 --------------------------------------------------------------------------
  
 python-oletools documentation
@@ -11,6 +11,12 @@
 <h1 id="olebrowse">olebrowse</h1>
 <p>olebrowse is a simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint documents), to view and extract individual data streams.</p>
 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
+<h2 id="dependencies">Dependencies</h2>
+<p>olebrowse requires <a href="https://en.wikipedia.org/wiki/Tkinter">Tkinter</a>. On Windows and MacOSX, it should be installed with Python, and olebrowse should work out of the box.</p>
+<p>However, on Linux it might be necessary to install the tkinter package for Python separately. For example, on Ubuntu this is done with the following command:</p>
+<pre><code>sudo apt-get install python-tk</code></pre>
+<p>And for Python 3:</p>
+<pre><code>sudo apt-get install python3-tk</code></pre>
 <h2 id="usage">Usage</h2>
 <pre><code>olebrowse.py [file]</code></pre>
 <p>If you provide a file it will be opened, else a dialog will allow you to browse folders to open a file. Then if it is a valid OLE file, the list of data streams will be displayed. You can select a stream, and then either view its content in a builtin hexadecimal viewer, or save it to a file for further analysis.</p>
@@ -6,12 +6,37 @@ view and extract individual data streams.
  
 It is part of the [python-oletools](http://www.decalage.info/python/oletools) package.
  
+Dependencies
+------------
+
+olebrowse requires [Tkinter](https://en.wikipedia.org/wiki/Tkinter).
+On Windows and MacOSX, it should be installed with Python, and
+olebrowse should work out of the box.
+
+However, on Linux it might be necessary to install the tkinter
+package for Python separately. For example, on Ubuntu this is done with the
+following command:
+
+```
+sudo apt-get install python-tk
+```
+
+And for Python 3:
+
+```
+sudo apt-get install python3-tk
+```
+
+
 Usage
 -----
  
 	olebrowse.py [file]
  
-If you provide a file it will be opened, else a dialog will allow you to browse folders to open a file. Then if it is a valid OLE file, the list of data streams will be displayed. You can select a stream, and then either view its content in a builtin hexadecimal viewer, or save it to a file for further analysis.
+If you provide a file it will be opened, else a dialog will allow you to browse
+folders to open a file. Then if it is a valid OLE file, the list of data streams
+will be displayed. You can select a stream, and then either view its content
+in a builtin hexadecimal viewer, or save it to a file for further analysis.
  
 Screenshots
 -----------
@@ -211,6 +211,8 @@ 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>
+<h2 id="python-3-support---olevba3">Python 3 support - olevba3</h2>
+<p>As of v0.50, olevba has been ported to Python 3 thanks to <span class="citation">@sebdraven</span>. However, the differences between Python 2 and 3 are significant and for now there is a separate version of olevba named olevba3 to be used with Python 3.</p>
 <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>
@@ -253,7 +253,14 @@ 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
 ```
-  
+
+## Python 3 support - olevba3
+
+As of v0.50, olevba has been ported to Python 3 thanks to @sebdraven.
+However, the differences between Python 2 and 3 are significant and for now
+there is a separate version of olevba named olevba3 to be used with
+Python 3.
+
 --------------------------------------------------------------------------
  
 ## How to use olevba in Python applications	
@@ -28,18 +28,48 @@ code &gt; span.er { color: #ff0000; font-weight: bold; }
 </head>
 <body>
 <h1 id="rtfobj">rtfobj</h1>
-<p>rtfobj is a Python module to extract embedded objects from RTF files, such as OLE ojects. It can be used as a Python library or a command-line tool.</p>
+<p>rtfobj is a Python module to detect and extract embedded objects stored in RTF files, such as OLE objects. It can also detect OLE Package objects, and extract the embedded files.</p>
+<p>Since v0.50, rtfobj contains a custom RTF parser that has been designed to match MS Word's behaviour, in order to handle obfuscated RTF files. See my article <a href="http://decalage.info/rtf_tricks">&quot;Anti-Analysis Tricks in Weaponized RTF&quot;</a> for some concrete examples.</p>
+<p>rtfobj can be used as a Python library or a command-line tool.</p>
 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
 <h2 id="usage">Usage</h2>
-<pre class="text"><code>rtfobj.py &lt;file.rtf&gt;</code></pre>
-<p>It extracts and decodes all the data blocks encoded as hexadecimal in the RTF document, and saves them as files named &quot;object_xxxx.bin&quot;, xxxx being the location of the object in the RTF file.</p>
+<pre class="text"><code>rtfobj [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:*)
+  -l LOGLEVEL, --loglevel=LOGLEVEL
+                        logging level debug/info/warning/error/critical
+                        (default=warning)
+  -s SAVE_OBJECT, --save=SAVE_OBJECT
+                        Save the object corresponding to the provided number
+                        to a file, for example &quot;-s 2&quot;. Use &quot;-s all&quot; to save
+                        all objects at once.
+  -d OUTPUT_DIR         use specified directory to save output files.</code></pre>
+<p>rtfobj displays a list of the OLE and Package objects that have been detected, with their attributes such as class and filename.</p>
+<p>When an OLE Package object contains an executable file or script, it is highlighted as such. For example:</p>
+<div class="figure">
+<img src="rtfobj1.png" />
+</div>
+<p>To extract an object or file, use the option -s followed by the object number as shown in the table.</p>
+<p>Example:</p>
+<pre class="text"><code>rtfobj -s 0</code></pre>
+<p>It extracts and decodes the corresponding object, and saves it as a file named &quot;object_xxxx.bin&quot;, xxxx being the location of the object in the RTF file.</p>
 <h2 id="how-to-use-rtfobj-in-python-applications">How to use rtfobj in Python applications</h2>
-<p>Usage as a python module:</p>
-<p>rtf_iter_objects(filename) is an iterator which yields a tuple (index, object) providing the index of each hexadecimal stream in the RTF file, and the corresponding decoded object.</p>
+<p>As of v0.50, the API has changed significantly and it is not final yet. For now, see the class RtfObjectParser in the code.</p>
+<h3 id="deprecated-api-still-functional">Deprecated API (still functional):</h3>
+<p>rtf_iter_objects(filename) is an iterator which yields a tuple (index, orig_len, object) providing the index of each hexadecimal stream in the RTF file, and the corresponding decoded object.</p>
 <p>Example:</p>
-<pre class="sourceCode python"><code class="sourceCode python"><span class="ch">import</span> rtfobj
-<span class="kw">for</span> index, data in rtfobj.rtf_iter_objects(<span class="st">&quot;myfile.rtf&quot;</span>):
-    <span class="dt">print</span> <span class="st">&#39;found object size </span><span class="ot">%d</span><span class="st"> at index </span><span class="ot">%08X</span><span class="st">&#39;</span> % (<span class="dt">len</span>(data), index)</code></pre>
+<pre class="sourceCode python"><code class="sourceCode python"><span class="ch">from</span> oletools <span class="ch">import</span> rtfobj
+<span class="kw">for</span> index, orig_len, data in rtfobj.rtf_iter_objects(<span class="st">&quot;myfile.rtf&quot;</span>):
+    <span class="dt">print</span>(<span class="st">&#39;found object size </span><span class="ot">%d</span><span class="st"> at index </span><span class="ot">%08X</span><span class="st">&#39;</span> % (<span class="dt">len</span>(data), index))</code></pre>
 <hr />
 <h2 id="python-oletools-documentation">python-oletools documentation</h2>
 <ul>
 rtfobj
 ======
  
-rtfobj is a Python module to extract embedded objects from RTF files, such as
-OLE ojects. It can be used as a Python library or a command-line tool.
+rtfobj is a Python module to detect and extract embedded objects stored
+in RTF files, such as OLE objects. It can also detect OLE Package objects,
+and extract the embedded files.
+
+Since v0.50, rtfobj contains a custom RTF parser that has been designed to
+match MS Word's behaviour, in order to handle obfuscated RTF files. See my
+article ["Anti-Analysis Tricks in Weaponized RTF"](http://decalage.info/rtf_tricks)
+for some concrete examples.
+
+rtfobj can be used as a Python library or a command-line tool.
  
 It is part of the [python-oletools](http://www.decalage.info/python/oletools) package.
  
 ## Usage
  
 ```text
-rtfobj.py <file.rtf>
+rtfobj [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:*)
+  -l LOGLEVEL, --loglevel=LOGLEVEL
+                        logging level debug/info/warning/error/critical
+                        (default=warning)
+  -s SAVE_OBJECT, --save=SAVE_OBJECT
+                        Save the object corresponding to the provided number
+                        to a file, for example "-s 2". Use "-s all" to save
+                        all objects at once.
+  -d OUTPUT_DIR         use specified directory to save output files.
+```
+
+rtfobj displays a list of the OLE and Package objects that have been detected,
+with their attributes such as class and filename.
+
+When an OLE Package object contains an executable file or script, it is
+highlighted as such. For example:
+
+![](rtfobj1.png)
+
+To extract an object or file, use the option -s followed by the object number
+as shown in the table.
+
+Example:
+
+```text
+rtfobj -s 0
 ```
  
-It extracts and decodes all the data blocks encoded as hexadecimal in the RTF document,
-and saves them as files named "object_xxxx.bin", xxxx being the location of the object
-in the RTF file.
+It extracts and decodes the corresponding object, and saves it as a file
+named "object_xxxx.bin", xxxx being the location of the object in the RTF file.
  
  
+## How to use rtfobj in Python applications
  
-## How to use rtfobj in Python applications	
+As of v0.50, the API has changed significantly and it is not final yet.
+For now, see the class RtfObjectParser in the code.
  
-Usage as a python module: 
+### Deprecated API (still functional):
  
-rtf_iter_objects(filename) is an iterator which yields a tuple (index, object) providing the index of each hexadecimal stream in the RTF file, and the corresponding decoded object. 
+rtf_iter_objects(filename) is an iterator which yields a tuple
+(index, orig_len, object) providing the index of each hexadecimal stream
+in the RTF file, and the corresponding decoded object.
  
 Example:
  
 ```python
-import rtfobj
-for index, data in rtfobj.rtf_iter_objects("myfile.rtf"):
-    print 'found object size %d at index %08X' % (len(data), index)
+from oletools import rtfobj
+for index, orig_len, data in rtfobj.rtf_iter_objects("myfile.rtf"):
+    print('found object size %d at index %08X' % (len(data), index))
 ```
  
 --------------------------------------------------------------------------
@@ -40,7 +40,7 @@ import sys, os, fnmatch
 #--- METADATA -----------------------------------------------------------------
  
 name         = "oletools"
-version      = '0.50a'
+version      = '0.50'
 desc         = "Python tools to analyze security characteristics of MS Office and OLE files (also called Structured Storage, Compound File Binary Format or Compound Document File Format), for Malware Analysis and Incident Response #DFIR"
 long_desc    = open('oletools/README.rst').read()
 author       = "Philippe Lagadec"