doc update for 0.60.1

oletools/README.html

@@ -23,6 +23,51 @@ <h1 id="python-oletools">python-oletools</h1>
 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
 <h2 id="news">News</h2>
 <ul>
+<li><strong>2022-05-09 v0.60.1</strong>:
+<ul>
+<li>olevba:
+<ul>
+<li>fixed a bug when calling XLMMacroDeobfuscator (PR #737)</li>
+<li>removed keyword &quot;sample&quot; causing false positives</li>
+</ul></li>
+<li>oleid: fixed OleID init issue (issue #695, PR #696)</li>
+<li>oleobj:
+<ul>
+<li>added simple detection of CVE-2021-40444 initial stage</li>
+<li>added detection for customUI onLoad</li>
+<li>improved handling of incorrect filenames in OLE package (PR #451)</li>
+</ul></li>
+<li>rtfobj: fixed code to find URLs in OLE2Link objects for Py3 (issue #692)</li>
+<li>ftguess:
+<ul>
+<li>added PowerPoint and XPS formats (PR #716)</li>
+<li>fixed issue with XPS and malformed documents (issue #711)</li>
+<li>added XLSB format (issue #758)</li>
+</ul></li>
+<li>improved logging with common module log_helper (PR #449)</li>
+</ul></li>
+<li><strong>2021-06-02 v0.60</strong>:
+<ul>
+<li>ftguess: new tool to identify file formats and containers (issue #680)</li>
+<li>oleid: (issue #679)
+<ul>
+<li>each indicator now has a risk level</li>
+<li>calls ftguess to identify file formats<br />
+</li>
+<li>calls olevba+mraptor to detect and analyse VBA+XLM macros</li>
+</ul></li>
+<li>olevba:
+<ul>
+<li>when XLMMacroDeobfuscator is available, use it to extract and deobfuscate XLM macros</li>
+</ul></li>
+<li>rtfobj:
+<ul>
+<li>use ftguess to identify file type of OLE Package (issue #682)</li>
+<li>fixed bug in re_executable_extensions</li>
+</ul></li>
+<li>crypto: added PowerPoint transparent password '/01Hannes Ruescher/01' (issue #627)</li>
+<li>setup: XLMMacroDeobfuscator, xlrd2 and pyxlsb2 added as optional dependencies</li>
+</ul></li>
 <li><strong>2021-05-07 v0.56.2</strong>:
 <ul>
 <li>olevba:
@@ -130,14 +175,15 @@ <h3 id="tools-to-analyze-the-structure-of-ole-files">Tools to analyze the struct
 <li><a href="https://github.com/decalage2/oletools/wiki/olemap">olemap</a>: to display a map of all the sectors in an OLE file.</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="https://github.com/IntegralDefense/ACE">ACE</a>, <a href="https://sandbox.anlyz.io/">Anlyz.io</a>, <a href="https://www.cse-cst.gc.ca/en/assemblyline">AssemblyLine</a>, <a href="https://github.com/ctxis/CAPE">CAPE</a>, <a href="https://cincan.io">CinCan</a>, <a href="https://github.com/cuckoosandbox/cuckoo">Cuckoo Sandbox</a>, <a href="https://github.com/cryps1s/DARKSURGEON">DARKSURGEON</a>, <a href="https://sandbox.deepviz.com/">Deepviz</a>, <a href="https://diario.elevenpaths.com/">DIARIO</a>, <a href="https://dridex.malwareconfig.com">dridex.malwareconfig.com</a>, <a href="https://github.com/ninoseki/eml_analyzer">EML Analyzer</a>, <a href="https://certsocietegenerale.github.io/fame/">FAME</a>, <a href="https://github.com/fireeye/flare-vm">FLARE-VM</a>, <a href="https://www.hybrid-analysis.com/">Hybrid-analysis.com</a>, <a href="https://github.com/certego/IntelOwl">IntelOwl</a>, <a href="https://www.document-analyzer.net/">Joe Sandbox</a>, <a href="https://github.com/lmco/laikaboss">Laika BOSS</a>, <a href="https://github.com/sbidy/MacroMilter">MacroMilter</a>, <a href="https://mailcow.email/">mailcow</a>, <a href="https://malshare.io">malshare.io</a>, <a href="https://github.com/Tigzy/malware-repo">malware-repo</a>, <a href="https://www.adlice.com/download/mrf/">Malware Repository Framework (MRF)</a>, <a href="https://bazaar.abuse.ch/">MalwareBazaar</a>, <a href="https://github.com/HeinleinSupport/olefy">olefy</a>, <a href="https://github.com/scVENUS/PeekabooAV">PeekabooAV</a>, <a href="https://github.com/bontchev/pcodedmp">pcodedmp</a>, <a href="https://github.com/CIRCL/PyCIRCLean">PyCIRCLean</a>, <a href="https://remnux.org/">REMnux</a>, <a href="https://github.com/countercept/snake">Snake</a>, <a href="https://app.sndbox.com">SNDBOX</a>, <a href="https://splunkbase.splunk.com/app/5365/">Splunk add-on for MS O365 Email</a>, <a href="https://github.com/ldbo/SpuriousEmu">SpuriousEmu</a>, <a href="https://github.com/target/strelka">Strelka</a>, <a href="https://stoq.punchcyber.com/">stoQ</a>, <a href="https://github.com/TheHive-Project/Cortex-Analyzers">TheHive/Cortex</a>, <a href="https://tsurugi-linux.org/">TSUGURI Linux</a>, <a href="https://github.com/MalwareCantFly/Vba2Graph">Vba2Graph</a>, <a href="http://viper.li/">Viper</a>, <a href="https://github.com/decalage2/ViperMonkey">ViperMonkey</a>, <a href="https://yomi.yoroi.company">YOMI</a>, and probably <a href="https://www.virustotal.com">VirusTotal</a>. And quite a few <a href="https://github.com/search?q=oletools&amp;type=Repositories">other projects on GitHub</a>. (Please <a href="(http://decalage.info/contact)">contact me</a> if you have or know a project using oletools)</p>
+<p>oletools are used by a number of projects and online malware analysis services, including <a href="https://github.com/IntegralDefense/ACE">ACE</a>, <a href="https://sandbox.anlyz.io/">Anlyz.io</a>, <a href="https://www.cse-cst.gc.ca/en/assemblyline">AssemblyLine</a>, <a href="https://github.com/ctxis/CAPE">CAPE</a>, <a href="https://cincan.io">CinCan</a>, <a href="https://github.com/cuckoosandbox/cuckoo">Cuckoo Sandbox</a>, <a href="https://github.com/cryps1s/DARKSURGEON">DARKSURGEON</a>, <a href="https://sandbox.deepviz.com/">Deepviz</a>, <a href="https://diario.elevenpaths.com/">DIARIO</a>, <a href="https://dridex.malwareconfig.com">dridex.malwareconfig.com</a>, <a href="https://github.com/ninoseki/eml_analyzer">EML Analyzer</a>, <a href="https://certsocietegenerale.github.io/fame/">FAME</a>, <a href="https://github.com/fireeye/flare-vm">FLARE-VM</a>, <a href="https://www.hybrid-analysis.com/">Hybrid-analysis.com</a>, <a href="https://github.com/certego/IntelOwl">IntelOwl</a>, <a href="https://www.document-analyzer.net/">Joe Sandbox</a>, <a href="https://github.com/lmco/laikaboss">Laika BOSS</a>, <a href="https://github.com/sbidy/MacroMilter">MacroMilter</a>, <a href="https://mailcow.email/">mailcow</a>, <a href="https://malshare.io">malshare.io</a>, <a href="https://github.com/Tigzy/malware-repo">malware-repo</a>, <a href="https://www.adlice.com/download/mrf/">Malware Repository Framework (MRF)</a>, <a href="https://bazaar.abuse.ch/">MalwareBazaar</a>, <a href="https://github.com/HeinleinSupport/olefy">olefy</a>, <a href="https://github.com/pandora-analysis/pandora">Pandora</a>, <a href="https://github.com/scVENUS/PeekabooAV">PeekabooAV</a>, <a href="https://github.com/bontchev/pcodedmp">pcodedmp</a>, <a href="https://github.com/CIRCL/PyCIRCLean">PyCIRCLean</a>, <a href="https://remnux.org/">REMnux</a>, <a href="https://github.com/countercept/snake">Snake</a>, <a href="https://app.sndbox.com">SNDBOX</a>, <a href="https://splunkbase.splunk.com/app/5365/">Splunk add-on for MS O365 Email</a>, <a href="https://github.com/ldbo/SpuriousEmu">SpuriousEmu</a>, <a href="https://github.com/target/strelka">Strelka</a>, <a href="https://stoq.punchcyber.com/">stoQ</a>, <a href="https://docs.sublimesecurity.com/docs/enrichment-functions">Sublime Platform/MQL</a>, <a href="https://github.com/TheHive-Project/Cortex-Analyzers">TheHive/Cortex</a>, <a href="https://tsurugi-linux.org/">TSUGURI Linux</a>, <a href="https://github.com/MalwareCantFly/Vba2Graph">Vba2Graph</a>, <a href="http://viper.li/">Viper</a>, <a href="https://github.com/decalage2/ViperMonkey">ViperMonkey</a>, <a href="https://yomi.yoroi.company">YOMI</a>, and probably <a href="https://www.virustotal.com">VirusTotal</a>, <a href="https://www.filescan.io">FileScan.IO</a>. And quite a few <a href="https://github.com/search?q=oletools&amp;type=Repositories">other projects on GitHub</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>The recommended way to download and install/update the <strong>latest stable release</strong> of oletools is to use <a href="https://pip.pypa.io/en/stable/installing/">pip</a>:</p>
 <ul>
-<li>On Linux/Mac: <code>sudo -H pip install -U oletools</code></li>
-<li>On Windows: <code>pip install -U oletools</code></li>
+<li>On Linux/Mac: <code>sudo -H pip install -U oletools[full]</code></li>
+<li>On Windows: <code>pip install -U oletools[full]</code></li>
 </ul>
 <p>This should automatically create command-line scripts to run each tool from any directory: <code>olevba</code>, <code>mraptor</code>, <code>rtfobj</code>, etc.</p>
+<p>The keyword <code>[full]</code> means that all optional dependencies will be installed, such as XLMMacroDeobfuscator. If you prefer a lighter version without optional dependencies, just remove <code>[full]</code> from the command line.</p>
 <p>To get the <strong>latest development version</strong> instead:</p>
 <ul>
 <li>On Linux/Mac: <code>sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></li>
@@ -153,7 +199,7 @@ <h2 id="how-to-suggest-improvements-report-issues-or-contribute">How to Suggest
 <p>The code is available in <a href="https://github.com/decalage2/oletools">a GitHub repository</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-2021 Philippe Lagadec (http://www.decalage.info)</p>
+<p>The python-oletools package is copyright (c) 2012-2022 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>

oletools/README.rst

@@ -29,6 +29,56 @@ Software.
 News
 ----
 
+-  **2022-05-09 v0.60.1**:
+
+   -  olevba:
+
+      -  fixed a bug when calling XLMMacroDeobfuscator (PR #737)
+      -  removed keyword "sample" causing false positives
+
+   -  oleid: fixed OleID init issue (issue #695, PR #696)
+   -  oleobj:
+
+      -  added simple detection of CVE-2021-40444 initial stage
+      -  added detection for customUI onLoad
+      -  improved handling of incorrect filenames in OLE package (PR
+         #451)
+
+   -  rtfobj: fixed code to find URLs in OLE2Link objects for Py3 (issue
+      #692)
+   -  ftguess:
+
+      -  added PowerPoint and XPS formats (PR #716)
+      -  fixed issue with XPS and malformed documents (issue #711)
+      -  added XLSB format (issue #758)
+
+   -  improved logging with common module log_helper (PR #449)
+
+-  **2021-06-02 v0.60**:
+
+   -  ftguess: new tool to identify file formats and containers (issue
+      #680)
+   -  oleid: (issue #679)
+
+      -  each indicator now has a risk level
+      -  calls ftguess to identify file formats
+      -  calls olevba+mraptor to detect and analyse VBA+XLM macros
+
+   -  olevba:
+
+      -  when XLMMacroDeobfuscator is available, use it to extract and
+         deobfuscate XLM macros
+
+   -  rtfobj:
+
+      -  use ftguess to identify file type of OLE Package (issue #682)
+      -  fixed bug in re_executable_extensions
+
+   -  crypto: added PowerPoint transparent password '/01Hannes
+      Ruescher/01' (issue #627)
+   -  setup: XLMMacroDeobfuscator, xlrd2 and pyxlsb2 added as optional
+      dependencies
+
 -  **2021-05-07 v0.56.2**:
 
    -  olevba:
@@ -202,6 +252,7 @@ BOSS <https://github.com/lmco/laikaboss>`__,
 Repository Framework (MRF) <https://www.adlice.com/download/mrf/>`__,
 `MalwareBazaar <https://bazaar.abuse.ch/>`__,
 `olefy <https://github.com/HeinleinSupport/olefy>`__,
+`Pandora <https://github.com/pandora-analysis/pandora>`__,
 `PeekabooAV <https://github.com/scVENUS/PeekabooAV>`__,
 `pcodedmp <https://github.com/bontchev/pcodedmp>`__,
 `PyCIRCLean <https://github.com/CIRCL/PyCIRCLean>`__,
@@ -211,14 +262,16 @@ Repository Framework (MRF) <https://www.adlice.com/download/mrf/>`__,
 Email <https://splunkbase.splunk.com/app/5365/>`__,
 `SpuriousEmu <https://github.com/ldbo/SpuriousEmu>`__,
 `Strelka <https://github.com/target/strelka>`__,
-`stoQ <https://stoq.punchcyber.com/>`__,
+`stoQ <https://stoq.punchcyber.com/>`__, `Sublime
+Platform/MQL <https://docs.sublimesecurity.com/docs/enrichment-functions>`__,
 `TheHive/Cortex <https://github.com/TheHive-Project/Cortex-Analyzers>`__,
 `TSUGURI Linux <https://tsurugi-linux.org/>`__,
 `Vba2Graph <https://github.com/MalwareCantFly/Vba2Graph>`__,
 `Viper <http://viper.li/>`__,
 `ViperMonkey <https://github.com/decalage2/ViperMonkey>`__,
 `YOMI <https://yomi.yoroi.company>`__, and probably
-`VirusTotal <https://www.virustotal.com>`__. And quite a few `other
+`VirusTotal <https://www.virustotal.com>`__,
+`FileScan.IO <https://www.filescan.io>`__. And quite a few `other
 projects on
 GitHub <https://github.com/search?q=oletools&type=Repositories>`__.
 (Please `contact me <(http://decalage.info/contact)>`__ if you have or
@@ -231,12 +284,17 @@ The recommended way to download and install/update the **latest stable
 release** of oletools is to use
 `pip <https://pip.pypa.io/en/stable/installing/>`__:
 
--  On Linux/Mac: ``sudo -H pip install -U oletools``
--  On Windows: ``pip install -U oletools``
+-  On Linux/Mac: ``sudo -H pip install -U oletools[full]``
+-  On Windows: ``pip install -U oletools[full]``
 
 This should automatically create command-line scripts to run each tool
 from any directory: ``olevba``, ``mraptor``, ``rtfobj``, etc.
 
+The keyword ``[full]`` means that all optional dependencies will be
+installed, such as XLMMacroDeobfuscator. If you prefer a lighter version
+without optional dependencies, just remove ``[full]`` from the command
+line.
+
 To get the **latest development version** instead:
 
 -  On Linux/Mac:
@@ -279,7 +337,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-2021 Philippe Lagadec
+The python-oletools package is copyright (c) 2012-2022 Philippe Lagadec
 (http://www.decalage.info)
 
 All rights reserved.

oletools/doc/Install.html

@@ -18,16 +18,20 @@
 <body>
 <h1 id="how-to-download-and-install-oletools">How to Download and Install oletools</h1>
 <h2 id="pre-requisites">Pre-requisites</h2>
-<p>The recommended Python version to run oletools is the latest <strong>Python 3.x</strong> (3.7 for now). Python 2.7 is still supported, but as it will become end of life in 2020 (see https://pythonclock.org/), it is highly recommended to switch to Python 3 now.</p>
+<p>The recommended Python version to run oletools is the latest <strong>Python 3.x</strong> (3.9 for now). Python 2.7 is still supported for the moment, even if it reached end of life in 2020 (for projects still using Python 2/PyPy 2 such as ViperMonkey). It is highly recommended to switch to Python 3 if possible.</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>To download and install/update the latest release version of oletools, run the following command in a shell:</p>
+<p>To download and install/update the latest release version of oletools with all its dependencies, run the following command in a shell:</p>
+<pre class="text"><code>sudo -H pip install -U oletools[full]</code></pre>
+<p>The keyword <code>[full]</code> means that all optional dependencies will be installed, such as XLMMacroDeobfuscator. If you prefer a lighter version without optional dependencies, use the following command instead:</p>
 <pre class="text"><code>sudo -H pip install -U oletools</code></pre>
 <p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
 <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>
+<p>To download and install/update the latest release version of oletools with all its dependencies, run the following command in a cmd window:</p>
+<pre class="text"><code>pip install -U oletools[full]</code></pre>
+<p>The keyword <code>[full]</code> means that all optional dependencies will be installed, such as XLMMacroDeobfuscator. If you prefer a lighter version without optional dependencies, use the following command instead:</p>
 <pre class="text"><code>pip install -U oletools</code></pre>
 <p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
 <p><strong>Note</strong>: with Python 3, you may need to open a cmd window with Administrator privileges in order to run pip and install for all users. If that is not possible, you may also install only for the current user by adding the <code>--user</code> option:</p>
@@ -37,9 +41,11 @@ <h2 id="how-to-install-the-latest-development-version">How to install the latest
 <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>
+<p>Note that it will install oletools without optional dependencies such as XLMMacroDeobfuscator, so you may need to install them separately.</p>
 <p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
 <h3 id="windows-1">Windows</h3>
 <pre class="text"><code>pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></pre>
+<p>Note that it will install oletools without optional dependencies such as XLMMacroDeobfuscator, so you may need to install them separately.</p>
 <p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
 <p><strong>Note</strong>: with Python 3, you may need to open a cmd window with Administrator privileges in order to run pip and install for all users. If that is not possible, you may also install only for the current user by adding the <code>--user</code> option:</p>
 <pre class="text"><code>pip3 install -U --user https://github.com/decalage2/oletools/archive/master.zip</code></pre>