1python-oletools 2=============== 3 4|PyPI| |Build Status| |Say Thanks!| 5 6`oletools <http://www.decalage.info/python/oletools>`__ is a package of 7python tools to analyze `Microsoft OLE2 8files <http://en.wikipedia.org/wiki/Compound_File_Binary_Format>`__ 9(also called Structured Storage, Compound File Binary Format or Compound 10Document File Format), such as Microsoft Office documents or Outlook 11messages, mainly for malware analysis, forensics and debugging. It is 12based on the `olefile <http://www.decalage.info/olefile>`__ parser. See 13http://www.decalage.info/python/oletools for more info. 14 15**Quick links:** `Home 16page <http://www.decalage.info/python/oletools>`__ - 17`Download/Install <https://github.com/decalage2/oletools/wiki/Install>`__ 18- `Documentation <https://github.com/decalage2/oletools/wiki>`__ - 19`Report 20Issues/Suggestions/Questions <https://github.com/decalage2/oletools/issues>`__ 21- `Contact the Author <http://decalage.info/contact>`__ - 22`Repository <https://github.com/decalage2/oletools>`__ - `Updates on 23Twitter <https://twitter.com/decalage2>`__ 24`Cheatsheet <https://github.com/decalage2/oletools/blob/master/cheatsheet/oletools_cheatsheet.pdf>`__ 25 26Note: python-oletools is not related to OLETools published by BeCubed 27Software. 28 29News 30---- 31 32- **2019-05-22 v0.54.2**: 33 34 - bugfix release: fixed several issues related to encrypted 35 documents and XLM/XLF Excel 4 macros 36 - msoffcrypto-tool is now installed by default to handle encrypted 37 documents 38 - olevba and msodde now handle documents encrypted with common 39 passwords such as 123, 1234, 4321, 12345, 123456, VelvetSweatShop 40 automatically. 41 42- **2019-04-04 v0.54**: 43 44 - olevba, msodde: added support for encrypted MS Office files 45 - olevba: added detection and extraction of XLM/XLF Excel 4 macros 46 (thanks to plugin_biff from Didier Stevens' oledump) 47 - olevba, mraptor: added detection of VBA running Excel 4 macros 48 - olevba: detect and display special characters such as backspace 49 - olevba: colorized output showing suspicious keywords in the VBA 50 code 51 - olevba, mraptor: full Python 3 compatibility, no separate 52 olevba3/mraptor3 anymore 53 - olevba: improved handling of code pages and unicode 54 - olevba: fixed a false-positive in VBA macro detection 55 - rtfobj: improved OLE Package handling, improved Equation object 56 detection 57 - oleobj: added detection of external links to objects in OpenXML 58 - replaced third party packages by PyPI dependencies 59 60- 2018-05-30 v0.53: 61 62 - olevba and mraptor can now parse Word/PowerPoint 2007+ pure XML 63 files (aka Flat OPC format) 64 - improved support for VBA forms in olevba (oleform) 65 - rtfobj now displays the CLSID of OLE objects, which is the best 66 way to identify them. Known-bad CLSIDs such as MS Equation Editor 67 are highlighted in red. 68 - Updated rtfobj to handle obfuscated RTF samples. 69 - rtfobj now handles the "\'" obfuscation trick seen in recent 70 samples such as 71 https://twitter.com/buffaloverflow/status/989798880295444480, by 72 emulating the MS Word bug described in 73 https://securelist.com/disappearing-bytes/84017/ 74 - msodde: improved detection of DDE formulas in CSV files 75 - oledir now displays the tree of storage/streams, along with CLSIDs 76 and their meaning. 77 - common.clsid contains the list of known CLSIDs, and their links to 78 CVE vulnerabilities when relevant. 79 - oleid now detects encrypted OpenXML files 80 - fixed bugs in oleobj, rtfobj, oleid, olevba 81 82- 2018-02-18 v0.52: 83 84 - New tool 85 `msodde <https://github.com/decalage2/oletools/wiki/msodde>`__ to 86 detect and extract DDE links from MS Office files, RTF and CSV; 87 - Fixed bugs in olevba, rtfobj and olefile, to better handle 88 malformed/obfuscated files; 89 - Performance improvements in olevba and rtfobj; 90 - VBA form parsing in olevba; 91 - Office 2007+ support in oleobj. 92 93See the `full 94changelog <https://github.com/decalage2/oletools/wiki/Changelog>`__ for 95more information. 96 97Tools: 98------ 99 100Tools to analyze malicious documents 101~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 103- `oleid <https://github.com/decalage2/oletools/wiki/oleid>`__: to 104 analyze OLE files to detect specific characteristics usually found in 105 malicious files. 106- `olevba <https://github.com/decalage2/oletools/wiki/olevba>`__: to 107 extract and analyze VBA Macro source code from MS Office documents 108 (OLE and OpenXML). 109- `MacroRaptor <https://github.com/decalage2/oletools/wiki/mraptor>`__: 110 to detect malicious VBA Macros 111- `msodde <https://github.com/decalage2/oletools/wiki/msodde>`__: to 112 detect and extract DDE/DDEAUTO links from MS Office documents, RTF 113 and CSV 114- `pyxswf <https://github.com/decalage2/oletools/wiki/pyxswf>`__: to 115 detect, extract and analyze Flash objects (SWF) that may be embedded 116 in files such as MS Office documents (e.g. Word, Excel) and RTF, 117 which is especially useful for malware analysis. 118- `oleobj <https://github.com/decalage2/oletools/wiki/oleobj>`__: to 119 extract embedded objects from OLE files. 120- `rtfobj <https://github.com/decalage2/oletools/wiki/rtfobj>`__: to 121 extract embedded objects from RTF files. 122 123Tools to analyze the structure of OLE files 124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 125 126- `olebrowse <https://github.com/decalage2/oletools/wiki/olebrowse>`__: 127 A simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint 128 documents), to view and extract individual data streams. 129- `olemeta <https://github.com/decalage2/oletools/wiki/olemeta>`__: to 130 extract all standard properties (metadata) from OLE files. 131- `oletimes <https://github.com/decalage2/oletools/wiki/oletimes>`__: 132 to extract creation and modification timestamps of all streams and 133 storages. 134- `oledir <https://github.com/decalage2/oletools/wiki/oledir>`__: to 135 display all the directory entries of an OLE file, including free and 136 orphaned entries. 137- `olemap <https://github.com/decalage2/oletools/wiki/olemap>`__: to 138 display a map of all the sectors in an OLE file. 139 140Projects using oletools: 141------------------------ 142 143oletools are used by a number of projects and online malware analysis 144services, including `Viper <http://viper.li/>`__, 145`REMnux <https://remnux.org/>`__, 146`FLARE-VM <https://github.com/fireeye/flare-vm>`__, 147`FAME <https://certsocietegenerale.github.io/fame/>`__, 148`Hybrid-analysis.com <https://www.hybrid-analysis.com/>`__, `Joe 149Sandbox <https://www.document-analyzer.net/>`__, 150`Deepviz <https://sandbox.deepviz.com/>`__, `Laika 151BOSS <https://github.com/lmco/laikaboss>`__, `Cuckoo 152Sandbox <https://github.com/cuckoosandbox/cuckoo>`__, 153`Anlyz.io <https://sandbox.anlyz.io/>`__, 154`ViperMonkey <https://github.com/decalage2/ViperMonkey>`__, 155`pcodedmp <https://github.com/bontchev/pcodedmp>`__, 156`dridex.malwareconfig.com <https://dridex.malwareconfig.com>`__, 157`Snake <https://github.com/countercept/snake>`__, 158`DARKSURGEON <https://github.com/cryps1s/DARKSURGEON>`__, 159`CAPE <https://github.com/ctxis/CAPE>`__, 160`AssemblyLine <https://www.cse-cst.gc.ca/en/assemblyline>`__, 161`malshare.io <https://malshare.io>`__, `Malware Repository Framework 162(MRF) <https://www.adlice.com/download/mrf/>`__, 163`malware-repo <https://github.com/Tigzy/malware-repo>`__, 164`Vba2Graph <https://github.com/MalwareCantFly/Vba2Graph>`__, 165`Strelka <https://github.com/target/strelka>`__, 166`stoQ <https://stoq.punchcyber.com/>`__, 167`YOMI <https://yomi.yoroi.company>`__, and probably 168`VirusTotal <https://www.virustotal.com>`__. And quite a few `other 169projects on 170GitHub <https://github.com/search?q=oletools&type=Repositories>`__. 171(Please `contact me <(http://decalage.info/contact)>`__ if you have or 172know a project using oletools) 173 174Download and Install: 175--------------------- 176 177The recommended way to download and install/update the **latest stable 178release** of oletools is to use 179`pip <https://pip.pypa.io/en/stable/installing/>`__: 180 181- On Linux/Mac: ``sudo -H pip install -U oletools`` 182- On Windows: ``pip install -U oletools`` 183 184This should automatically create command-line scripts to run each tool 185from any directory: ``olevba``, ``mraptor``, ``rtfobj``, etc. 186 187To get the **latest development version** instead: 188 189- On Linux/Mac: 190 ``sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip`` 191- On Windows: 192 ``pip install -U https://github.com/decalage2/oletools/archive/master.zip`` 193 194See the 195`documentation <https://github.com/decalage2/oletools/wiki/Install>`__ 196for other installation options. 197 198Documentation: 199-------------- 200 201The latest version of the documentation can be found 202`online <https://github.com/decalage2/oletools/wiki>`__, otherwise a 203copy is provided in the doc subfolder of the package. 204 205How to Suggest Improvements, Report Issues or Contribute: 206--------------------------------------------------------- 207 208This is a personal open-source project, developed on my spare time. Any 209contribution, suggestion, feedback or bug report is welcome. 210 211To suggest improvements, report a bug or any issue, please use the 212`issue reporting page <https://github.com/decalage2/oletools/issues>`__, 213providing all the information and files to reproduce the problem. 214 215You may also `contact the author <http://decalage.info/contact>`__ 216directly to provide feedback. 217 218The code is available in `a GitHub 219repository <https://github.com/decalage2/oletools>`__. You may use it to 220submit enhancements using forks and pull requests. 221 222License 223------- 224 225This license applies to the python-oletools package, apart from the 226thirdparty folder which contains third-party files published with their 227own license. 228 229The python-oletools package is copyright (c) 2012-2019 Philippe Lagadec 230(http://www.decalage.info) 231 232All rights reserved. 233 234Redistribution and use in source and binary forms, with or without 235modification, are permitted provided that the following conditions are 236met: 237 238- Redistributions of source code must retain the above copyright 239 notice, this list of conditions and the following disclaimer. 240- Redistributions in binary form must reproduce the above copyright 241 notice, this list of conditions and the following disclaimer in the 242 documentation and/or other materials provided with the distribution. 243 244THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 245IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 246TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 247PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 248HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 249SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 250TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 251PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 252LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 253NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 254SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 255 256-------------- 257 258olevba contains modified source code from the officeparser project, 259published under the following MIT License (MIT): 260 261officeparser is copyright (c) 2014 John William Davison 262 263Permission is hereby granted, free of charge, to any person obtaining a 264copy of this software and associated documentation files (the 265"Software"), to deal in the Software without restriction, including 266without limitation the rights to use, copy, modify, merge, publish, 267distribute, sublicense, and/or sell copies of the Software, and to 268permit persons to whom the Software is furnished to do so, subject to 269the following conditions: 270 271The above copyright notice and this permission notice shall be included 272in all copies or substantial portions of the Software. 273 274THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 275OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 276MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 277IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 278CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 279TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 280SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 281 282.. |PyPI| image:: https://img.shields.io/pypi/v/oletools.svg 283 :target: https://pypi.org/project/oletools/ 284.. |Build Status| image:: https://travis-ci.org/decalage2/oletools.svg?branch=master 285 :target: https://travis-ci.org/decalage2/oletools 286.. |Say Thanks!| image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg 287 :target: https://saythanks.io/to/decalage2 288
