Peter M. Groen / oletools

Commit 66347e8e0062405e6300c627c8310499b13b3375

Authored by decalage2
1 parent d03c8683

updated readme and doc for v0.54

Inline Side-by-side
Showing 26 changed files with 258 additions and 120 deletions
oletools/README.html
  View file @66347e8
... ... @@ -17,13 +17,27 @@
17 17 </head>
18 18 <body>
19 19 <h1 id="python-oletools">python-oletools</h1>
20   -<p><a href="https://pypi.org/project/oletools/"><img src="https://img.shields.io/pypi/v/oletools.svg" alt="PyPI" /></a> <a href="https://travis-ci.org/decalage2/oletools"><img src="https://travis-ci.org/decalage2/oletools.svg?branch=master" alt="Build Status" /></a></p>
  20 +<p><a href="https://pypi.org/project/oletools/"><img src="https://img.shields.io/pypi/v/oletools.svg" alt="PyPI" /></a> <a href="https://travis-ci.org/decalage2/oletools"><img src="https://travis-ci.org/decalage2/oletools.svg?branch=master" alt="Build Status" /></a> <a href="https://saythanks.io/to/decalage2"><img src="https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg" alt="Say Thanks!" /></a></p>
21 21 <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" class="uri">http://www.decalage.info/python/oletools</a> for more info.</p>
22 22 <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> <a href="https://github.com/decalage2/oletools/blob/master/cheatsheet/oletools_cheatsheet.pdf">Cheatsheet</a></p>
23 23 <p>Note: python-oletools is not related to OLETools published by BeCubed Software.</p>
24 24 <h2 id="news">News</h2>
25 25 <ul>
26   -<li><strong>2018-05-30 v0.53</strong>:
  26 +<li><strong>2019-04-04 v0.54</strong>:
  27 +<ul>
  28 +<li>olevba, msodde: added support for encrypted MS Office files</li>
  29 +<li>olevba: added detection and extraction of XLM/XLF Excel 4 macros (thanks to plugin_biff from Didier Stevens' oledump)</li>
  30 +<li>olevba, mraptor: added detection of VBA running Excel 4 macros</li>
  31 +<li>olevba: detect and display special characters such as backspace</li>
  32 +<li>olevba: colorized output showing suspicious keywords in the VBA code</li>
  33 +<li>olevba, mraptor: full Python 3 compatibility, no separate olevba3/mraptor3 anymore</li>
  34 +<li>olevba: improved handling of code pages and unicode</li>
  35 +<li>olevba: fixed a false-positive in VBA macro detection</li>
  36 +<li>rtfobj: improved OLE Package handling, improved Equation object detection</li>
  37 +<li>oleobj: added detection of external links to objects in OpenXML</li>
  38 +<li>replaced third party packages by PyPI dependencies</li>
  39 +</ul></li>
  40 +<li>2018-05-30 v0.53:
27 41 <ul>
28 42 <li>olevba and mraptor can now parse Word/PowerPoint 2007+ pure XML files (aka Flat OPC format)</li>
29 43 <li>improved support for VBA forms in olevba (oleform)</li>
... ... @@ -66,7 +80,7 @@
66 80 <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>
67 81 </ul>
68 82 <h2 id="projects-using-oletools">Projects using oletools:</h2>
69   -<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://certsocietegenerale.github.io/fame/">FAME</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/decalage2/ViperMonkey">ViperMonkey</a>, <a href="https://github.com/bontchev/pcodedmp">pcodedmp</a>, <a href="https://dridex.malwareconfig.com">dridex.malwareconfig.com</a>, <a href="https://github.com/countercept/snake">Snake</a>, <a href="https://github.com/cryps1s/DARKSURGEON">DARKSURGEON</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>
  83 +<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://github.com/fireeye/flare-vm">FLARE-VM</a>, <a href="https://certsocietegenerale.github.io/fame/">FAME</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/decalage2/ViperMonkey">ViperMonkey</a>, <a href="https://github.com/bontchev/pcodedmp">pcodedmp</a>, <a href="https://dridex.malwareconfig.com">dridex.malwareconfig.com</a>, <a href="https://github.com/countercept/snake">Snake</a>, <a href="https://github.com/cryps1s/DARKSURGEON">DARKSURGEON</a>, <a href="https://github.com/ctxis/CAPE">CAPE</a>, <a href="https://www.cse-cst.gc.ca/en/assemblyline">AssemblyLine</a>, <a href="https://malshare.io">malshare.io</a>, <a href="https://www.adlice.com/download/mrf/">Malware Repository Framework (MRF)</a>, <a href="https://github.com/Tigzy/malware-repo">malware-repo</a>, <a href="https://github.com/MalwareCantFly/Vba2Graph">Vba2Graph</a>, <a href="https://github.com/target/strelka">Strelka</a>, <a href="https://stoq.punchcyber.com/">stoQ</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>
70 84 <h2 id="download-and-install">Download and Install:</h2>
71 85 <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>
72 86 <ul>
... ... @@ -89,7 +103,7 @@
89 103 <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>
90 104 <h2 id="license">License</h2>
91 105 <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>
92   -<p>The python-oletools package is copyright (c) 2012-2018 Philippe Lagadec (http://www.decalage.info)</p>
  106 +<p>The python-oletools package is copyright (c) 2012-2019 Philippe Lagadec (http://www.decalage.info)</p>
93 107 <p>All rights reserved.</p>
94 108 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
95 109 <ul>
... ...
oletools/README.rst
  View file @66347e8
1 1 python-oletools
2 2 ===============
3 3  
4   -|PyPI| |Build Status|
  4 +|PyPI| |Build Status| |Say Thanks!|
5 5  
6 6 `oletools <http://www.decalage.info/python/oletools>`__ is a package of
7 7 python tools to analyze `Microsoft OLE2
... ... @@ -29,7 +29,25 @@ Software.
29 29 News
30 30 ----
31 31  
32   -- **2018-05-30 v0.53**:
  32 +- **2019-04-04 v0.54**:
  33 +
  34 + - olevba, msodde: added support for encrypted MS Office files
  35 + - olevba: added detection and extraction of XLM/XLF Excel 4 macros
  36 + (thanks to plugin_biff from Didier Stevens' oledump)
  37 + - olevba, mraptor: added detection of VBA running Excel 4 macros
  38 + - olevba: detect and display special characters such as backspace
  39 + - olevba: colorized output showing suspicious keywords in the VBA
  40 + code
  41 + - olevba, mraptor: full Python 3 compatibility, no separate
  42 + olevba3/mraptor3 anymore
  43 + - olevba: improved handling of code pages and unicode
  44 + - olevba: fixed a false-positive in VBA macro detection
  45 + - rtfobj: improved OLE Package handling, improved Equation object
  46 + detection
  47 + - oleobj: added detection of external links to objects in OpenXML
  48 + - replaced third party packages by PyPI dependencies
  49 +
  50 +- 2018-05-30 v0.53:
33 51  
34 52 - olevba and mraptor can now parse Word/PowerPoint 2007+ pure XML
35 53 files (aka Flat OPC format)
... ... @@ -115,6 +133,7 @@ Projects using oletools:
115 133 oletools are used by a number of projects and online malware analysis
116 134 services, including `Viper <http://viper.li/>`__,
117 135 `REMnux <https://remnux.org/>`__,
  136 +`FLARE-VM <https://github.com/fireeye/flare-vm>`__,
118 137 `FAME <https://certsocietegenerale.github.io/fame/>`__,
119 138 `Hybrid-analysis.com <https://www.hybrid-analysis.com/>`__, `Joe
120 139 Sandbox <https://www.document-analyzer.net/>`__,
... ... @@ -126,10 +145,20 @@ Sandbox &lt;https://github.com/cuckoosandbox/cuckoo&gt;`__,
126 145 `pcodedmp <https://github.com/bontchev/pcodedmp>`__,
127 146 `dridex.malwareconfig.com <https://dridex.malwareconfig.com>`__,
128 147 `Snake <https://github.com/countercept/snake>`__,
129   -`DARKSURGEON <https://github.com/cryps1s/DARKSURGEON>`__, and probably
130   -`VirusTotal <https://www.virustotal.com>`__. (Please `contact
131   -me <(http://decalage.info/contact)>`__ if you have or know a project
132   -using oletools)
  148 +`DARKSURGEON <https://github.com/cryps1s/DARKSURGEON>`__,
  149 +`CAPE <https://github.com/ctxis/CAPE>`__,
  150 +`AssemblyLine <https://www.cse-cst.gc.ca/en/assemblyline>`__,
  151 +`malshare.io <https://malshare.io>`__, `Malware Repository Framework
  152 +(MRF) <https://www.adlice.com/download/mrf/>`__,
  153 +`malware-repo <https://github.com/Tigzy/malware-repo>`__,
  154 +`Vba2Graph <https://github.com/MalwareCantFly/Vba2Graph>`__,
  155 +`Strelka <https://github.com/target/strelka>`__,
  156 +`stoQ <https://stoq.punchcyber.com/>`__, and probably
  157 +`VirusTotal <https://www.virustotal.com>`__. And quite a few `other
  158 +projects on
  159 +GitHub <https://github.com/search?q=oletools&type=Repositories>`__.
  160 +(Please `contact me <(http://decalage.info/contact)>`__ if you have or
  161 +know a project using oletools)
133 162  
134 163 Download and Install:
135 164 ---------------------
... ... @@ -186,7 +215,7 @@ This license applies to the python-oletools package, apart from the
186 215 thirdparty folder which contains third-party files published with their
187 216 own license.
188 217  
189   -The python-oletools package is copyright (c) 2012-2018 Philippe Lagadec
  218 +The python-oletools package is copyright (c) 2012-2019 Philippe Lagadec
190 219 (http://www.decalage.info)
191 220  
192 221 All rights reserved.
... ... @@ -243,3 +272,5 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
243 272 :target: https://pypi.org/project/oletools/
244 273 .. |Build Status| image:: https://travis-ci.org/decalage2/oletools.svg?branch=master
245 274 :target: https://travis-ci.org/decalage2/oletools
  275 +.. |Say Thanks!| image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg
  276 + :target: https://saythanks.io/to/decalage2
... ...
oletools/doc/Home.html
  View file @66347e8
... ... @@ -16,7 +16,7 @@
16 16 <![endif]-->
17 17 </head>
18 18 <body>
19   -<h1 id="python-oletools-v0.53-documentation">python-oletools v0.53 documentation</h1>
  19 +<h1 id="python-oletools-v0.54-documentation">python-oletools v0.54 documentation</h1>
20 20 <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>
21 21 <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" class="uri">http://www.decalage.info/python/oletools</a> for more info.</p>
22 22 <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>
... ...
oletools/doc/Home.md
  View file @66347e8
1   -python-oletools v0.53 documentation
  1 +python-oletools v0.54 documentation
2 2 ===================================
3 3  
4 4 This is the home page of the documentation for python-oletools. The latest version can be found
... ...
oletools/doc/Install.html
  View file @66347e8
... ... @@ -16,28 +16,43 @@
16 16 <![endif]-->
17 17 </head>
18 18 <body>
19   -<h1 id="how-to-download-and-install-python-oletools">How to Download and Install python-oletools</h1>
  19 +<h1 id="how-to-download-and-install-oletools">How to Download and Install oletools</h1>
20 20 <h2 id="pre-requisites">Pre-requisites</h2>
21   -<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>
22   -<p>Since oletools v0.50, thanks to contributions by <span class="citation" data-cites="Sebdraven">[@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>
  21 +<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>
23 22 <h2 id="recommended-way-to-downloadinstallupdate-oletools-pip">Recommended way to Download+Install/Update oletools: pip</h2>
24 23 <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>
25 24 <h3 id="linux-mac-osx-unix">Linux, Mac OSX, Unix</h3>
26 25 <p>To download and install/update the latest release version of oletools, run the following command in a shell:</p>
27 26 <pre class="text"><code>sudo -H pip install -U oletools</code></pre>
  27 +<p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
  28 +<p><strong>New in v0.54:</strong> To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:</p>
  29 +<pre class="text"><code>sudo -H pip install -U msoffcrypto-tool</code></pre>
28 30 <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>
29 31 <h3 id="windows">Windows</h3>
30 32 <p>To download and install/update the latest release version of oletools, run the following command in a cmd window:</p>
31 33 <pre class="text"><code>pip install -U oletools</code></pre>
  34 +<p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
  35 +<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>
  36 +<pre class="text"><code>pip3 install -U --user oletools</code></pre>
  37 +<p><strong>New in v0.54:</strong> To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:</p>
  38 +<pre class="text"><code>pip install -U msoffcrypto-tool</code></pre>
32 39 <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>
33 40 <h2 id="how-to-install-the-latest-development-version">How to install the latest development version</h2>
34 41 <p>If you want to benefit from the latest improvements in the development version, you may also use pip:</p>
35 42 <h3 id="linux-mac-osx-unix-1">Linux, Mac OSX, Unix</h3>
36 43 <pre class="text"><code>sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></pre>
  44 +<p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
  45 +<p><strong>New in v0.54:</strong> To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:</p>
  46 +<pre class="text"><code>sudo -H pip install -U msoffcrypto-tool</code></pre>
37 47 <h3 id="windows-1">Windows</h3>
38 48 <pre class="text"><code>pip install -U https://github.com/decalage2/oletools/archive/master.zip</code></pre>
  49 +<p>Replace <code>pip</code> by <code>pip3</code> or <code>pip2</code> to install on a specific Python version.</p>
  50 +<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>
  51 +<pre class="text"><code>pip3 install -U --user https://github.com/decalage2/oletools/archive/master.zip</code></pre>
  52 +<p><strong>New in v0.54:</strong> To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:</p>
  53 +<pre class="text"><code>pip install -U msoffcrypto-tool</code></pre>
39 54 <h2 id="how-to-install-offline---computer-without-internet-access">How to install offline - Computer without Internet access</h2>
40   -<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>
  55 +<p>First, download the oletools archive on a computer with Internet access: * Latest stable version: from https://pypi.org/project/oletools/ or https://github.com/decalage2/oletools/releases * Development version: https://github.com/decalage2/oletools/archive/master.zip</p>
41 56 <p>Copy the archive file to the target computer.</p>
42 57 <p>On Linux, Mac OSX, Unix, run the following command using the filename of the archive that you downloaded:</p>
43 58 <pre class="text"><code>sudo -H pip install -U oletools.zip</code></pre>
... ...
oletools/doc/Install.md
  View file @66347e8
1   -How to Download and Install python-oletools
2   -===========================================
  1 +How to Download and Install oletools
  2 +====================================
3 3  
4 4 Pre-requisites
5 5 --------------
6 6  
7   -The recommended Python version to run oletools is **Python 2.7**.
8   -Python 2.6 is also supported, but as it is not tested as often as 2.7, some features
9   -might not work as expected.
10   -
11   -Since oletools v0.50, thanks to contributions by [@Sebdraven](https://twitter.com/Sebdraven),
12   -most tools can also run with **Python 3.x**. As this is quite new, please
13   -[report any issue]((https://github.com/decalage2/oletools/issues)) you may encounter.
14   -
15   -
  7 +The recommended Python version to run oletools is the latest **Python 3.x** (3.7 for now).
  8 +Python 2.7 is still supported, but as it will become end of life in 2020 (see https://pythonclock.org/), it is highly
  9 +recommended to switch to Python 3 now.
16 10  
17 11 Recommended way to Download+Install/Update oletools: pip
18 12 --------------------------------------------------------
... ... @@ -29,6 +23,14 @@ run the following command in a shell:
29 23 sudo -H pip install -U oletools
30 24 ```
31 25  
  26 +Replace `pip` by `pip3` or `pip2` to install on a specific Python version.
  27 +
  28 +**New in v0.54:** To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:
  29 +```text
  30 +sudo -H pip install -U msoffcrypto-tool
  31 +```
  32 +
  33 +
32 34 **Important**: Since version 0.50, pip will automatically create convenient command-line scripts
33 35 in /usr/local/bin to run all the oletools from any directory.
34 36  
... ... @@ -41,6 +43,21 @@ run the following command in a cmd window:
41 43 pip install -U oletools
42 44 ```
43 45  
  46 +Replace `pip` by `pip3` or `pip2` to install on a specific Python version.
  47 +
  48 +**Note**: with Python 3, you may need to open a cmd window with Administrator privileges in order to run pip
  49 +and install for all users. If that is not possible, you may also install only for the current user
  50 +by adding the `--user` option:
  51 +
  52 +```text
  53 +pip3 install -U --user oletools
  54 +```
  55 +
  56 +**New in v0.54:** To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:
  57 +```text
  58 +pip install -U msoffcrypto-tool
  59 +```
  60 +
44 61 **Important**: Since version 0.50, pip will automatically create convenient command-line scripts
45 62 to run all the oletools from any directory: olevba, mraptor, oleid, rtfobj, etc.
46 63  
... ... @@ -57,17 +74,40 @@ you may also use pip:
57 74 sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip
58 75 ```
59 76  
  77 +Replace `pip` by `pip3` or `pip2` to install on a specific Python version.
  78 +
  79 +**New in v0.54:** To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:
  80 +```text
  81 +sudo -H pip install -U msoffcrypto-tool
  82 +```
  83 +
60 84 ### Windows
61 85  
62 86 ```text
63 87 pip install -U https://github.com/decalage2/oletools/archive/master.zip
64 88 ```
65 89  
  90 +Replace `pip` by `pip3` or `pip2` to install on a specific Python version.
  91 +
  92 +**Note**: with Python 3, you may need to open a cmd window with Administrator privileges in order to run pip
  93 +and install for all users. If that is not possible, you may also install only for the current user
  94 +by adding the `--user` option:
  95 +
  96 +```text
  97 +pip3 install -U --user https://github.com/decalage2/oletools/archive/master.zip
  98 +```
  99 +
  100 +**New in v0.54:** To enable the decryption of encrypted documents, you also need to install the msoffcrypto-tool package:
  101 +```text
  102 +pip install -U msoffcrypto-tool
  103 +```
  104 +
  105 +
66 106 How to install offline - Computer without Internet access
67 107 ---------------------------------------------------------
68 108  
69 109 First, download the oletools archive on a computer with Internet access:
70   -* Latest stable version: from https://github.com/decalage2/oletools/releases
  110 +* Latest stable version: from https://pypi.org/project/oletools/ or https://github.com/decalage2/oletools/releases
71 111 * Development version: https://github.com/decalage2/oletools/archive/master.zip
72 112  
73 113 Copy the archive file to the target computer.
... ...
oletools/doc/License.html
  View file @66347e8
... ... @@ -18,7 +18,7 @@
18 18 <body>
19 19 <h1 id="license-for-python-oletools">License for python-oletools</h1>
20 20 <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>
21   -<p>The python-oletools package is copyright (c) 2012-2018 Philippe Lagadec (<a href="http://www.decalage.info" class="uri">http://www.decalage.info</a>)</p>
  21 +<p>The python-oletools package is copyright (c) 2012-2019 Philippe Lagadec (<a href="http://www.decalage.info" class="uri">http://www.decalage.info</a>)</p>
22 22 <p>All rights reserved.</p>
23 23 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
24 24 <ul>
... ...
oletools/doc/License.md
  View file @66347e8
... ... @@ -4,7 +4,7 @@ License for python-oletools
4 4 This license applies to the [python-oletools](http://www.decalage.info/python/oletools) package, apart from the
5 5 thirdparty folder which contains third-party files published with their own license.
6 6  
7   -The python-oletools package is copyright (c) 2012-2018 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
  7 +The python-oletools package is copyright (c) 2012-2019 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
8 8  
9 9 All rights reserved.
10 10  
... ...
oletools/doc/mraptor.html
  View file @66347e8
... ... @@ -24,7 +24,7 @@
24 24 <p>mraptor can be used either as a command-line tool, or as a python module from your own applications.</p>
25 25 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
26 26 <h2 id="usage">Usage</h2>
27   -<pre class="text"><code>Usage: mraptor.py [options] &lt;filename&gt; [filename2 ...]
  27 +<pre class="text"><code>Usage: mraptor [options] &lt;filename&gt; [filename2 ...]
28 28  
29 29 Options:
30 30 -h, --help show this help message and exit
... ... @@ -49,15 +49,15 @@ An exit code is returned based on the analysis result:
49 49 - 20: SUSPICIOUS</code></pre>
50 50 <h3 id="examples">Examples</h3>
51 51 <p>Scan a single file:</p>
52   -<pre class="text"><code>mraptor.py file.doc</code></pre>
  52 +<pre class="text"><code>mraptor file.doc</code></pre>
53 53 <p>Scan a single file, stored in a Zip archive with password “infected”:</p>
54   -<pre class="text"><code>mraptor.py malicious_file.xls.zip -z infected</code></pre>
  54 +<pre class="text"><code>mraptor malicious_file.xls.zip -z infected</code></pre>
55 55 <p>Scan a collection of files stored in a folder:</p>
56   -<pre class="text"><code>mraptor.py &quot;MalwareZoo/VBA/*&quot;</code></pre>
  56 +<pre class="text"><code>mraptor &quot;MalwareZoo/VBA/*&quot;</code></pre>
57 57 <p><strong>Important</strong>: on Linux/MacOSX, always add double quotes around a file name when you use wildcards such as <code>*</code> and <code>?</code>. Otherwise, the shell may replace the argument with the actual list of files matching the wildcards before starting the script.</p>
58 58 <p><img src="mraptor1.png" /></p>
59 59 <h2 id="python-3-support---mraptor3">Python 3 support - mraptor3</h2>
60   -<p>As of v0.50, mraptor has been ported to Python 3 thanks to <span class="citation" data-cites="sebdraven">@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>
  60 +<p>Since v0.54, mraptor is fully compatible with both Python 2 and 3. There is no need to use mraptor3 anymore, however it is still present for backward compatibility.</p>
61 61 <hr />
62 62 <h2 id="how-to-use-mraptor-in-python-applications">How to use mraptor in Python applications</h2>
63 63 <p>TODO</p>
... ...
oletools/doc/mraptor.md
  View file @66347e8
... ... @@ -24,7 +24,7 @@ It is part of the [python-oletools](http://www.decalage.info/python/oletools) pa
24 24 ## Usage
25 25  
26 26 ```text
27   -Usage: mraptor.py [options] <filename> [filename2 ...]
  27 +Usage: mraptor [options] <filename> [filename2 ...]
28 28  
29 29 Options:
30 30 -h, --help show this help message and exit
... ... @@ -54,19 +54,19 @@ An exit code is returned based on the analysis result:
54 54 Scan a single file:
55 55  
56 56 ```text
57   -mraptor.py file.doc
  57 +mraptor file.doc
58 58 ```
59 59  
60 60 Scan a single file, stored in a Zip archive with password "infected":
61 61  
62 62 ```text
63   -mraptor.py malicious_file.xls.zip -z infected
  63 +mraptor malicious_file.xls.zip -z infected
64 64 ```
65 65  
66 66 Scan a collection of files stored in a folder:
67 67  
68 68 ```text
69   -mraptor.py "MalwareZoo/VBA/*"
  69 +mraptor "MalwareZoo/VBA/*"
70 70 ```
71 71  
72 72 **Important**: on Linux/MacOSX, always add double quotes around a file name when you use
... ... @@ -77,10 +77,8 @@ list of files matching the wildcards before starting the script.
77 77  
78 78 ## Python 3 support - mraptor3
79 79  
80   -As of v0.50, mraptor has been ported to Python 3 thanks to @sebdraven.
81   -However, the differences between Python 2 and 3 are significant and for now
82   -there is a separate version of mraptor named mraptor3 to be used with
83   -Python 3.
  80 +Since v0.54, mraptor is fully compatible with both Python 2 and 3.
  81 +There is no need to use mraptor3 anymore, however it is still present for backward compatibility.
84 82  
85 83  
86 84 --------------------------------------------------------------------------
... ...
oletools/doc/olebrowse.html
  View file @66347e8
... ... @@ -26,7 +26,7 @@
26 26 <p>And for Python 3:</p>
27 27 <pre><code>sudo apt-get install python3-tk</code></pre>
28 28 <h2 id="usage">Usage</h2>
29   -<pre><code>olebrowse.py [file]</code></pre>
  29 +<pre><code>olebrowse [file]</code></pre>
30 30 <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>
31 31 <h2 id="screenshots">Screenshots</h2>
32 32 <p>Main menu, showing all streams in the OLE file:</p>
... ...
oletools/doc/olebrowse.md
  View file @66347e8
... ... @@ -30,9 +30,9 @@ sudo apt-get install python3-tk
30 30  
31 31 Usage
32 32 -----
33   -
34   - olebrowse.py [file]
35   -
  33 +```
  34 +olebrowse [file]
  35 +```
36 36 If you provide a file it will be opened, else a dialog will allow you to browse
37 37 folders to open a file. Then if it is a valid OLE file, the list of data streams
38 38 will be displayed. You can select a stream, and then either view its content
... ...
oletools/doc/oledir.html
  View file @66347e8
... ... @@ -21,10 +21,21 @@
21 21 <p>It can be used either as a command-line tool, or as a python module from your own applications.</p>
22 22 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
23 23 <h2 id="usage">Usage</h2>
24   -<pre class="text"><code>Usage: oledir.py &lt;filename&gt;</code></pre>
  24 +<pre class="text"><code>Usage: oledir [options] &lt;filename&gt; [filename2 ...]
  25 +
  26 +Options:
  27 + -h, --help show this help message and exit
  28 + -r find files recursively in subdirectories.
  29 + -z ZIP_PASSWORD, --zip=ZIP_PASSWORD
  30 + if the file is a zip archive, open all files from it,
  31 + using the provided password (requires Python 2.6+)
  32 + -f ZIP_FNAME, --zipfname=ZIP_FNAME
  33 + if the file is a zip archive, file(s) to be opened
  34 + within the zip. Wildcards * and ? are supported.
  35 + (default:*)</code></pre>
25 36 <h3 id="examples">Examples</h3>
26 37 <p>Scan a single file:</p>
27   -<pre class="text"><code>oledir.py file.doc</code></pre>
  38 +<pre class="text"><code>oledir file.doc</code></pre>
28 39 <p><img src="oledir.png" /></p>
29 40 <hr />
30 41 <h2 id="how-to-use-oledir-in-python-applications">How to use oledir in Python applications</h2>
... ...
oletools/doc/oledir.md
  View file @66347e8
... ... @@ -11,7 +11,18 @@ It is part of the [python-oletools](http://www.decalage.info/python/oletools) pa
11 11 ## Usage
12 12  
13 13 ```text
14   -Usage: oledir.py <filename>
  14 +Usage: oledir [options] <filename> [filename2 ...]
  15 +
  16 +Options:
  17 + -h, --help show this help message and exit
  18 + -r find files recursively in subdirectories.
  19 + -z ZIP_PASSWORD, --zip=ZIP_PASSWORD
  20 + if the file is a zip archive, open all files from it,
  21 + using the provided password (requires Python 2.6+)
  22 + -f ZIP_FNAME, --zipfname=ZIP_FNAME
  23 + if the file is a zip archive, file(s) to be opened
  24 + within the zip. Wildcards * and ? are supported.
  25 + (default:*)
15 26 ```
16 27  
17 28 ### Examples
... ... @@ -19,7 +30,7 @@ Usage: oledir.py &lt;filename&gt;
19 30 Scan a single file:
20 31  
21 32 ```text
22   -oledir.py file.doc
  33 +oledir file.doc
23 34 ```
24 35  
25 36 ![](oledir.png)
... ...
oletools/doc/oleid.html
  View file @66347e8
... ... @@ -107,10 +107,10 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
107 107 <li>CSV output</li>
108 108 </ul>
109 109 <h2 id="usage">Usage</h2>
110   -<pre class="text"><code>oleid.py &lt;file&gt;</code></pre>
  110 +<pre class="text"><code>oleid &lt;file&gt;</code></pre>
111 111 <h3 id="example">Example</h3>
112 112 <p>Analyzing a Word document containing a Flash object and VBA macros:</p>
113   -<pre class="text"><code>C:\oletools&gt;oleid.py word_flash_vba.doc
  113 +<pre class="text"><code>C:\oletools&gt;oleid word_flash_vba.doc
114 114  
115 115 Filename: word_flash_vba.doc
116 116 +-------------------------------+-----------------------+
... ...
oletools/doc/oleid.md
  View file @66347e8
... ... @@ -32,7 +32,7 @@ Planned improvements:
32 32 ## Usage
33 33  
34 34 ```text
35   -oleid.py <file>
  35 +oleid <file>
36 36 ```
37 37  
38 38 ### Example
... ... @@ -40,7 +40,7 @@ oleid.py &lt;file&gt;
40 40 Analyzing a Word document containing a Flash object and VBA macros:
41 41  
42 42 ```text
43   -C:\oletools>oleid.py word_flash_vba.doc
  43 +C:\oletools>oleid word_flash_vba.doc
44 44  
45 45 Filename: word_flash_vba.doc
46 46 +-------------------------------+-----------------------+
... ...
oletools/doc/olemap.html
  View file @66347e8
... ... @@ -21,10 +21,10 @@
21 21 <p>It can be used either as a command-line tool, or as a python module from your own applications.</p>
22 22 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
23 23 <h2 id="usage">Usage</h2>
24   -<pre class="text"><code>Usage: olemap.py &lt;filename&gt;</code></pre>
  24 +<pre class="text"><code>Usage: olemap &lt;filename&gt;</code></pre>
25 25 <h3 id="examples">Examples</h3>
26 26 <p>Scan a single file:</p>
27   -<pre class="text"><code>olemap.py file.doc</code></pre>
  27 +<pre class="text"><code>olemap file.doc</code></pre>
28 28 <p><img src="olemap1.png" /></p>
29 29 <p><img src="olemap2.png" /></p>
30 30 <hr />
... ...
oletools/doc/olemap.md
  View file @66347e8
... ... @@ -10,7 +10,7 @@ It is part of the [python-oletools](http://www.decalage.info/python/oletools) pa
10 10 ## Usage
11 11  
12 12 ```text
13   -Usage: olemap.py <filename>
  13 +Usage: olemap <filename>
14 14 ```
15 15  
16 16 ### Examples
... ... @@ -18,7 +18,7 @@ Usage: olemap.py &lt;filename&gt;
18 18 Scan a single file:
19 19  
20 20 ```text
21   -olemap.py file.doc
  21 +olemap file.doc
22 22 ```
23 23  
24 24 ![](olemap1.png)
... ...
oletools/doc/olemeta.html
  View file @66347e8
... ... @@ -20,7 +20,7 @@
20 20 <p>olemeta is a script to parse OLE files such as MS Office documents (e.g. Word, Excel), to extract all standard properties present in the OLE file.</p>
21 21 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
22 22 <h2 id="usage">Usage</h2>
23   -<pre class="text"><code>olemeta.py &lt;file&gt;</code></pre>
  23 +<pre class="text"><code>olemeta &lt;file&gt;</code></pre>
24 24 <h3 id="example">Example</h3>
25 25 <p><img src="olemeta1.png" /></p>
26 26 <h2 id="how-to-use-olemeta-in-python-applications">How to use olemeta in Python applications</h2>
... ...
oletools/doc/olemeta.md
  View file @66347e8
... ... @@ -9,7 +9,7 @@ It is part of the [python-oletools](http://www.decalage.info/python/oletools) pa
9 9 ## Usage
10 10  
11 11 ```text
12   -olemeta.py <file>
  12 +olemeta <file>
13 13 ```
14 14  
15 15 ### Example
... ...
oletools/doc/oletimes.html
  View file @66347e8
... ... @@ -20,10 +20,10 @@
20 20 <p>oletimes is a script to parse OLE files such as MS Office documents (e.g. Word, Excel), to extract creation and modification times of all streams and storages in the OLE file.</p>
21 21 <p>It is part of the <a href="http://www.decalage.info/python/oletools">python-oletools</a> package.</p>
22 22 <h2 id="usage">Usage</h2>
23   -<pre class="text"><code>oletimes.py &lt;file&gt;</code></pre>
  23 +<pre class="text"><code>oletimes &lt;file&gt;</code></pre>
24 24 <h3 id="example">Example</h3>
25 25 <p>Checking the malware sample <a href="https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/">DIAN_caso-5415.doc</a>:</p>
26   -<pre class="text"><code>&gt;oletimes.py DIAN_caso-5415.doc
  26 +<pre class="text"><code>&gt;oletimes DIAN_caso-5415.doc
27 27  
28 28 +----------------------------+---------------------+---------------------+
29 29 | Stream/Storage name | Modification Time | Creation Time |
... ...
oletools/doc/oletimes.md
  View file @66347e8
... ... @@ -10,7 +10,7 @@ It is part of the [python-oletools](http://www.decalage.info/python/oletools) pa
10 10 ## Usage
11 11  
12 12 ```text
13   -oletimes.py <file>
  13 +oletimes <file>
14 14 ```
15 15  
16 16 ### Example
... ... @@ -18,7 +18,7 @@ oletimes.py &lt;file&gt;
18 18 Checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/):
19 19  
20 20 ```text
21   ->oletimes.py DIAN_caso-5415.doc
  21 +>oletimes DIAN_caso-5415.doc
22 22  
23 23 +----------------------------+---------------------+---------------------+
24 24 | Stream/Storage name | Modification Time | Creation Time |
... ...
oletools/doc/olevba.html
  View file @66347e8
... ... @@ -127,56 +127,65 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
127 127 <li>olevba scans the macro source code and the deobfuscated strings to find suspicious keywords, auto-executable macros and potential IOCs (URLs, IP addresses, e-mail addresses, executable filenames, etc).</li>
128 128 </ol>
129 129 <h2 id="usage">Usage</h2>
130   -<pre class="text"><code>Usage: olevba.py [options] &lt;filename&gt; [filename2 ...]
131   -
  130 +<pre class="text"><code>Usage: olevba [options] &lt;filename&gt; [filename2 ...]
  131 +
132 132 Options:
133 133 -h, --help show this help message and exit
134 134 -r find files recursively in subdirectories.
135 135 -z ZIP_PASSWORD, --zip=ZIP_PASSWORD
136 136 if the file is a zip archive, open all files from it,
137   - using the provided password (requires Python 2.6+)
  137 + using the provided password.
  138 + -p PASSWORD, --password=PASSWORD
  139 + if encrypted office files are encountered, try
  140 + decryption with this password. May be repeated.
138 141 -f ZIP_FNAME, --zipfname=ZIP_FNAME
139 142 if the file is a zip archive, file(s) to be opened
140 143 within the zip. Wildcards * and ? are supported.
141 144 (default:*)
142   - -t, --triage triage mode, display results as a summary table
143   - (default for multiple files)
144   - -d, --detailed detailed mode, display full results (default for
145   - single file)
146 145 -a, --analysis display only analysis results, not the macro source
147 146 code
148 147 -c, --code display only VBA source code, do not analyze it
149   - -i INPUT, --input=INPUT
150   - input file containing VBA source code to be analyzed
151   - (no parsing)
152 148 --decode display all the obfuscated strings with their decoded
153 149 content (Hex, Base64, StrReverse, Dridex, VBA).
154 150 --attr display the attribute lines at the beginning of VBA
155 151 source code
156 152 --reveal display the macro source code after replacing all the
157   - obfuscated strings by their decoded content.</code></pre>
  153 + obfuscated strings by their decoded content.
  154 + -l LOGLEVEL, --loglevel=LOGLEVEL
  155 + logging level debug/info/warning/error/critical
  156 + (default=warning)
  157 + --deobf Attempt to deobfuscate VBA expressions (slow)
  158 + --relaxed Do not raise errors if opening of substream fails
  159 +
  160 + Output mode (mutually exclusive):
  161 + -t, --triage triage mode, display results as a summary table
  162 + (default for multiple files)
  163 + -d, --detailed detailed mode, display full results (default for
  164 + single file)
  165 + -j, --json json mode, detailed in json format (never default)</code></pre>
  166 +<p><strong>New in v0.54:</strong> the -p option can now be used to decrypt encrypted documents using the provided password(s).</p>
158 167 <h3 id="examples">Examples</h3>
159 168 <p>Scan a single file:</p>
160   -<pre class="text"><code>olevba.py file.doc</code></pre>
  169 +<pre class="text"><code>olevba file.doc</code></pre>
161 170 <p>Scan a single file, stored in a Zip archive with password “infected”:</p>
162   -<pre class="text"><code>olevba.py malicious_file.xls.zip -z infected</code></pre>
  171 +<pre class="text"><code>olevba malicious_file.xls.zip -z infected</code></pre>
163 172 <p>Scan a single file, showing all obfuscated strings decoded:</p>
164   -<pre class="text"><code>olevba.py file.doc --decode</code></pre>
  173 +<pre class="text"><code>olevba file.doc --decode</code></pre>
165 174 <p>Scan a single file, showing the macro source code with VBA strings deobfuscated:</p>
166   -<pre class="text"><code>olevba.py file.doc --reveal</code></pre>
  175 +<pre class="text"><code>olevba file.doc --reveal</code></pre>
167 176 <p>Scan VBA source code extracted into a text file:</p>
168   -<pre class="text"><code>olevba.py source_code.vba</code></pre>
  177 +<pre class="text"><code>olevba source_code.vba</code></pre>
169 178 <p>Scan a collection of files stored in a folder:</p>
170   -<pre class="text"><code>olevba.py &quot;MalwareZoo/VBA/*&quot;</code></pre>
  179 +<pre class="text"><code>olevba &quot;MalwareZoo/VBA/*&quot;</code></pre>
171 180 <p>NOTE: On Linux, MacOSX and other Unix variants, it is required to add double quotes around wildcards. Otherwise, they will be expanded by the shell instead of olevba.</p>
172 181 <p>Scan all .doc and .xls files, recursively in all subfolders:</p>
173   -<pre class="text"><code>olevba.py &quot;MalwareZoo/VBA/*.doc&quot; &quot;MalwareZoo/VBA/*.xls&quot; -r</code></pre>
  182 +<pre class="text"><code>olevba &quot;MalwareZoo/VBA/*.doc&quot; &quot;MalwareZoo/VBA/*.xls&quot; -r</code></pre>
174 183 <p>Scan all .doc files within all .zip files with password, recursively:</p>
175   -<pre class="text"><code>olevba.py &quot;MalwareZoo/VBA/*.zip&quot; -r -z infected -f &quot;*.doc&quot;</code></pre>
  184 +<pre class="text"><code>olevba &quot;MalwareZoo/VBA/*.zip&quot; -r -z infected -f &quot;*.doc&quot;</code></pre>
176 185 <h3 id="detailed-analysis-mode-default-for-single-file">Detailed analysis mode (default for single file)</h3>
177 186 <p>When a single file is scanned, or when using the option -d, all details of the analysis are displayed.</p>
178 187 <p>For example, checking the malware sample <a href="https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/">DIAN_caso-5415.doc</a>:</p>
179   -<pre class="text"><code>&gt;olevba.py c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
  188 +<pre class="text"><code>&gt;olevba c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
180 189 ===============================================================================
181 190 FILE: DIAN_caso-5415.doc.malware in c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip
182 191 Type: OLE
... ... @@ -246,7 +255,7 @@ ANALYSIS:
246 255 <li><strong>V</strong>: VBA string expressions (potential obfuscation)</li>
247 256 </ul>
248 257 <p>Here is an example:</p>
249   -<pre class="text"><code>c:\&gt;olevba.py \MalwareZoo\VBA\samples\*
  258 +<pre class="text"><code>c:\&gt;olevba \MalwareZoo\VBA\samples\*
250 259 Flags Filename
251 260 ----------- -----------------------------------------------------------------
252 261 OLE:MASI--- \MalwareZoo\VBA\samples\DIAN_caso-5415.doc.malware
... ... @@ -266,7 +275,7 @@ OpX:MASI--- \MalwareZoo\VBA\samples\RottenKitten.xlsb.malware
266 275 OLE:MASI-B- \MalwareZoo\VBA\samples\ROVNIX.doc.malware
267 276 OLE:MA----- \MalwareZoo\VBA\samples\Word within Word macro auto.doc</code></pre>
268 277 <h2 id="python-3-support---olevba3">Python 3 support - olevba3</h2>
269   -<p>As of v0.50, olevba has been ported to Python 3 thanks to <span class="citation" data-cites="sebdraven">@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>
  278 +<p>Since v0.54, olevba is fully compatible with both Python 2 and 3. There is no need to use olevba3 anymore, however it is still present for backward compatibility.</p>
270 279 <hr />
271 280 <h2 id="how-to-use-olevba-in-python-applications">How to use olevba in Python applications</h2>
272 281 <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>
... ...
oletools/doc/olevba.md
  View file @66347e8
... ... @@ -67,85 +67,95 @@ and potential IOCs (URLs, IP addresses, e-mail addresses, executable filenames,
67 67 ## Usage
68 68  
69 69 ```text
70   -Usage: olevba.py [options] <filename> [filename2 ...]
71   -
  70 +Usage: olevba [options] <filename> [filename2 ...]
  71 +
72 72 Options:
73 73 -h, --help show this help message and exit
74 74 -r find files recursively in subdirectories.
75 75 -z ZIP_PASSWORD, --zip=ZIP_PASSWORD
76 76 if the file is a zip archive, open all files from it,
77   - using the provided password (requires Python 2.6+)
  77 + using the provided password.
  78 + -p PASSWORD, --password=PASSWORD
  79 + if encrypted office files are encountered, try
  80 + decryption with this password. May be repeated.
78 81 -f ZIP_FNAME, --zipfname=ZIP_FNAME
79 82 if the file is a zip archive, file(s) to be opened
80 83 within the zip. Wildcards * and ? are supported.
81 84 (default:*)
82   - -t, --triage triage mode, display results as a summary table
83   - (default for multiple files)
84   - -d, --detailed detailed mode, display full results (default for
85   - single file)
86 85 -a, --analysis display only analysis results, not the macro source
87 86 code
88 87 -c, --code display only VBA source code, do not analyze it
89   - -i INPUT, --input=INPUT
90   - input file containing VBA source code to be analyzed
91   - (no parsing)
92 88 --decode display all the obfuscated strings with their decoded
93 89 content (Hex, Base64, StrReverse, Dridex, VBA).
94 90 --attr display the attribute lines at the beginning of VBA
95 91 source code
96 92 --reveal display the macro source code after replacing all the
97 93 obfuscated strings by their decoded content.
  94 + -l LOGLEVEL, --loglevel=LOGLEVEL
  95 + logging level debug/info/warning/error/critical
  96 + (default=warning)
  97 + --deobf Attempt to deobfuscate VBA expressions (slow)
  98 + --relaxed Do not raise errors if opening of substream fails
  99 +
  100 + Output mode (mutually exclusive):
  101 + -t, --triage triage mode, display results as a summary table
  102 + (default for multiple files)
  103 + -d, --detailed detailed mode, display full results (default for
  104 + single file)
  105 + -j, --json json mode, detailed in json format (never default)
98 106 ```
99 107  
  108 +**New in v0.54:** the -p option can now be used to decrypt encrypted documents using the provided password(s).
  109 +
100 110 ### Examples
101 111  
102 112 Scan a single file:
103 113  
104 114 ```text
105   -olevba.py file.doc
  115 +olevba file.doc
106 116 ```
107 117  
108 118 Scan a single file, stored in a Zip archive with password "infected":
109 119  
110 120 ```text
111   -olevba.py malicious_file.xls.zip -z infected
  121 +olevba malicious_file.xls.zip -z infected
112 122 ```
113 123  
114 124 Scan a single file, showing all obfuscated strings decoded:
115 125  
116 126 ```text
117   -olevba.py file.doc --decode
  127 +olevba file.doc --decode
118 128 ```
119 129  
120 130 Scan a single file, showing the macro source code with VBA strings deobfuscated:
121 131  
122 132 ```text
123   -olevba.py file.doc --reveal
  133 +olevba file.doc --reveal
124 134 ```
125 135  
126 136 Scan VBA source code extracted into a text file:
127 137  
128 138 ```text
129   -olevba.py source_code.vba
  139 +olevba source_code.vba
130 140 ```
131 141  
132 142 Scan a collection of files stored in a folder:
133 143  
134 144 ```text
135   -olevba.py "MalwareZoo/VBA/*"
  145 +olevba "MalwareZoo/VBA/*"
136 146 ```
137 147 NOTE: On Linux, MacOSX and other Unix variants, it is required to add double quotes around wildcards. Otherwise, they will be expanded by the shell instead of olevba.
138 148  
139 149 Scan all .doc and .xls files, recursively in all subfolders:
140 150  
141 151 ```text
142   -olevba.py "MalwareZoo/VBA/*.doc" "MalwareZoo/VBA/*.xls" -r
  152 +olevba "MalwareZoo/VBA/*.doc" "MalwareZoo/VBA/*.xls" -r
143 153 ```
144 154  
145 155 Scan all .doc files within all .zip files with password, recursively:
146 156  
147 157 ```text
148   -olevba.py "MalwareZoo/VBA/*.zip" -r -z infected -f "*.doc"
  158 +olevba "MalwareZoo/VBA/*.zip" -r -z infected -f "*.doc"
149 159 ```
150 160  
151 161  
... ... @@ -156,7 +166,7 @@ When a single file is scanned, or when using the option -d, all details of the a
156 166 For example, checking the malware sample [DIAN_caso-5415.doc](https://malwr.com/analysis/M2I4YWRhM2IwY2QwNDljN2E3ZWFjYTg3ODk4NmZhYmE/):
157 167  
158 168 ```text
159   ->olevba.py c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
  169 +>olevba c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
160 170 ===============================================================================
161 171 FILE: DIAN_caso-5415.doc.malware in c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip
162 172 Type: OLE
... ... @@ -233,7 +243,7 @@ The following flags show the results of the analysis:
233 243 Here is an example:
234 244  
235 245 ```text
236   -c:\>olevba.py \MalwareZoo\VBA\samples\*
  246 +c:\>olevba \MalwareZoo\VBA\samples\*
237 247 Flags Filename
238 248 ----------- -----------------------------------------------------------------
239 249 OLE:MASI--- \MalwareZoo\VBA\samples\DIAN_caso-5415.doc.malware
... ... @@ -256,10 +266,9 @@ OLE:MA----- \MalwareZoo\VBA\samples\Word within Word macro auto.doc
256 266  
257 267 ## Python 3 support - olevba3
258 268  
259   -As of v0.50, olevba has been ported to Python 3 thanks to @sebdraven.
260   -However, the differences between Python 2 and 3 are significant and for now
261   -there is a separate version of olevba named olevba3 to be used with
262   -Python 3.
  269 +Since v0.54, olevba is fully compatible with both Python 2 and 3.
  270 +There is no need to use olevba3 anymore, however it is still present for backward compatibility.
  271 +
263 272  
264 273 --------------------------------------------------------------------------
265 274  
... ...
oletools/doc/pyxswf.html
  View file @66347e8
... ... @@ -24,7 +24,7 @@
24 24 <p>It can also extract Flash objects from RTF documents, by parsing embedded objects encoded in hexadecimal format (-f option).</p>
25 25 <p>For this, simply add the -o option to work on OLE streams rather than raw files, or the -f option to work on RTF files.</p>
26 26 <h2 id="usage">Usage</h2>
27   -<pre class="text"><code>Usage: pyxswf.py [options] &lt;file.bad&gt;
  27 +<pre class="text"><code>Usage: pyxswf [options] &lt;file.bad&gt;
28 28  
29 29 Options:
30 30 -o, --ole Parse an OLE file (e.g. Word, Excel) to look for SWF
... ... @@ -46,18 +46,18 @@ Options:
46 46 contain SWFs. Must provide path in quotes
47 47 -c, --compress Compresses the SWF using Zlib</code></pre>
48 48 <h3 id="example-1---detecting-and-extracting-a-swf-file-from-a-word-document-on-windows">Example 1 - detecting and extracting a SWF file from a Word document on Windows:</h3>
49   -<pre class="text"><code>C:\oletools&gt;pyxswf.py -o word_flash.doc
  49 +<pre class="text"><code>C:\oletools&gt;pyxswf -o word_flash.doc
50 50 OLE stream: &#39;Contents&#39;
51 51 [SUMMARY] 1 SWF(s) in MD5:993664cc86f60d52d671b6610813cfd1:Contents
52 52 [ADDR] SWF 1 at 0x8 - FWS Header
53 53  
54   -C:\oletools&gt;pyxswf.py -xo word_flash.doc
  54 +C:\oletools&gt;pyxswf -xo word_flash.doc
55 55 OLE stream: &#39;Contents&#39;
56 56 [SUMMARY] 1 SWF(s) in MD5:993664cc86f60d52d671b6610813cfd1:Contents
57 57 [ADDR] SWF 1 at 0x8 - FWS Header
58 58 [FILE] Carved SWF MD5: 2498e9c0701dc0e461ab4358f9102bc5.swf</code></pre>
59 59 <h3 id="example-2---detecting-and-extracting-a-swf-file-from-a-rtf-document-on-windows">Example 2 - detecting and extracting a SWF file from a RTF document on Windows:</h3>
60   -<pre class="text"><code>C:\oletools&gt;pyxswf.py -xf &quot;rtf_flash.rtf&quot;
  60 +<pre class="text"><code>C:\oletools&gt;pyxswf -xf &quot;rtf_flash.rtf&quot;
61 61 RTF embedded object size 1498557 at index 000036DD
62 62 [SUMMARY] 1 SWF(s) in MD5:46a110548007e04f4043785ac4184558:RTF_embedded_object_0
63 63 00036DD
... ...
oletools/doc/pyxswf.md
  View file @66347e8
... ... @@ -21,7 +21,7 @@ For this, simply add the -o option to work on OLE streams rather than raw files,
21 21 ## Usage
22 22  
23 23 ```text
24   -Usage: pyxswf.py [options] <file.bad>
  24 +Usage: pyxswf [options] <file.bad>
25 25  
26 26 Options:
27 27 -o, --ole Parse an OLE file (e.g. Word, Excel) to look for SWF
... ... @@ -47,12 +47,12 @@ Options:
47 47 ### Example 1 - detecting and extracting a SWF file from a Word document on Windows:
48 48  
49 49 ```text
50   -C:\oletools>pyxswf.py -o word_flash.doc
  50 +C:\oletools>pyxswf -o word_flash.doc
51 51 OLE stream: 'Contents'
52 52 [SUMMARY] 1 SWF(s) in MD5:993664cc86f60d52d671b6610813cfd1:Contents
53 53 [ADDR] SWF 1 at 0x8 - FWS Header
54 54  
55   -C:\oletools>pyxswf.py -xo word_flash.doc
  55 +C:\oletools>pyxswf -xo word_flash.doc
56 56 OLE stream: 'Contents'
57 57 [SUMMARY] 1 SWF(s) in MD5:993664cc86f60d52d671b6610813cfd1:Contents
58 58 [ADDR] SWF 1 at 0x8 - FWS Header
... ... @@ -62,7 +62,7 @@ OLE stream: &#39;Contents&#39;
62 62 ### Example 2 - detecting and extracting a SWF file from a RTF document on Windows:
63 63  
64 64 ```text
65   -C:\oletools>pyxswf.py -xf "rtf_flash.rtf"
  65 +C:\oletools>pyxswf -xf "rtf_flash.rtf"
66 66 RTF embedded object size 1498557 at index 000036DD
67 67 [SUMMARY] 1 SWF(s) in MD5:46a110548007e04f4043785ac4184558:RTF_embedded_object_0
68 68 00036DD
... ...