How to Suggest Improvements, Report Issues or Contribute
This is a personal open-source project, developed on my spare time. Any contribution, suggestion, feedback or bug report is welcome.
-To suggest improvements, report a bug or any issue, please use the issue reporting page, providing all the information and files to reproduce the problem.
-You may also contact the author directly to provide feedback.
+To suggest improvements, report a bug or any issue, please use the issue reporting page, and provide all the information and files to reproduce the problem.
+You may also contact the author directly to send feedback.
The code is available in a repository on GitHub. You may use it to submit enhancements using forks and pull requests.
python-oletools documentation
diff --git a/oletools/doc/Contribute.md b/oletools/doc/Contribute.md index 504894e..f27a22d 100644 --- a/oletools/doc/Contribute.md +++ b/oletools/doc/Contribute.md @@ -1,12 +1,15 @@ 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. diff --git a/oletools/doc/Home.html b/oletools/doc/Home.html index dd9ef47..2283a25 100644 --- a/oletools/doc/Home.html +++ b/oletools/doc/Home.html @@ -8,7 +8,7 @@ -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 online, otherwise a copy is provided in the doc subfolder of the package.
python-oletools is a package of python tools to analyze Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft Office documents or Outlook messages, mainly for malware analysis, forensics and debugging. It is based on the olefile parser. See http://www.decalage.info/python/oletools for more info.
Quick links: Home page - Download/Install - Documentation - Report Issues/Suggestions/Questions - Contact the Author - Repository - Updates on Twitter
diff --git a/oletools/doc/Home.md b/oletools/doc/Home.md index 10da17f..700ee88 100644 --- a/oletools/doc/Home.md +++ b/oletools/doc/Home.md @@ -1,4 +1,4 @@ -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 diff --git a/oletools/doc/Install.html b/oletools/doc/Install.html index 00c1180..b8e42fc 100644 --- a/oletools/doc/Install.html +++ b/oletools/doc/Install.html @@ -10,24 +10,39 @@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.
-They are not compatible with Python 3.x yet. (Please contact me if that is a strong requirement)
-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 and extract the files into the directory of your choice.
-You may also download the latest development version with the most recent features.
-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.
-Windows
-You may add the oletools directory to your PATH environment variable to access the tools from anywhere.
+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.
+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 you may encounter.
+Recommended way to Download+Install/Update oletools: pip
+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/
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:
chmod +x /opt/oletools/oletools/olevba.py
-ln -s /opt/oletools/oletools/olevba.py /usr/local/bin/olevbaThen the olevba command can be used from any directory:
-user@remnux:~/MalwareZoo/VBA$ olevba dridex427.xls |lessFor 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.
-Important: to update oletools if it is already installed, you must run "pip install -U oletools", otherwise pip will not update it.
-Alternatively if you prefer the old school way, you may download the latest archive, extract it into a temporary directory and run "python setup.py install".
+To download and install/update the latest release version of oletools, run the following command in a shell:
+sudo -H pip install -U oletoolsImportant: 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
+To download and install/update the latest release version of oletools, run the following command in a cmd window:
+pip install -U oletoolsImportant: 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
+sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zipWindows
+pip install -U https://github.com/decalage2/oletools/archive/master.zipHow 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:
+sudo -H pip install -U oletools.zipOn Windows:
+pip install -U oletools.zipOld 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
+Then extract the archive, open a shell and go to the oletools directory.
+Linux, Mac OSX, Unix
+sudo -H python setup.py installWindows:
+python setup.py installpython-oletools documentation
-
diff --git a/oletools/doc/Install.md b/oletools/doc/Install.md
index 197a1a3..5db9c10 100644
--- a/oletools/doc/Install.md
+++ b/oletools/doc/Install.md
@@ -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"**.
--------------------------------------------------------------------------
diff --git a/oletools/doc/mraptor.html b/oletools/doc/mraptor.html
index 9f5b4e0..1c5e479 100644
--- a/oletools/doc/mraptor.html
+++ b/oletools/doc/mraptor.html
@@ -9,8 +9,11 @@
mraptor (MacroRaptor)
-mraptor is a script to detect malicious VBA Macros.
-It can be used either as a command-line tool, or as a python module from your own applications.
+mraptor is a tool designed to detect most malicious VBA Macros using generic heuristics. Unlike antivirus engines, it does not rely on signatures.
+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.
+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 package.
Usage
Usage: mraptor.py [options] <filename> [filename2 ...]
@@ -47,6 +50,8 @@ An exit code is returned based on the analysis result:
+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
diff --git a/oletools/doc/mraptor.md b/oletools/doc/mraptor.md
index e41533b..c5b7f46 100644
--- a/oletools/doc/mraptor.md
+++ b/oletools/doc/mraptor.md
@@ -1,9 +1,23 @@
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.
+## 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
diff --git a/oletools/doc/olebrowse.html b/oletools/doc/olebrowse.html
index 00d7b7d..6a369ca 100644
--- a/oletools/doc/olebrowse.html
+++ b/oletools/doc/olebrowse.html
@@ -11,6 +11,12 @@
olebrowse
olebrowse is a simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint documents), to view and extract individual data streams.
It is part of the python-oletools package.
+Dependencies
+olebrowse requires 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.
diff --git a/oletools/doc/olebrowse.md b/oletools/doc/olebrowse.md
index 1cce285..57f727b 100644
--- a/oletools/doc/olebrowse.md
+++ b/oletools/doc/olebrowse.md
@@ -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
-----------
diff --git a/oletools/doc/olevba.html b/oletools/doc/olevba.html
index d04aa53..5ed2781 100644
--- a/oletools/doc/olevba.html
+++ b/oletools/doc/olevba.html
@@ -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.docPython 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
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.
diff --git a/oletools/doc/olevba.md b/oletools/doc/olevba.md index 07a58ed..5b1e130 100644 --- a/oletools/doc/olevba.md +++ b/oletools/doc/olevba.md @@ -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 diff --git a/oletools/doc/rtfobj.html b/oletools/doc/rtfobj.html index db0e441..15d9b3d 100644 --- a/oletools/doc/rtfobj.html +++ b/oletools/doc/rtfobj.html @@ -28,18 +28,48 @@ code > span.er { color: #ff0000; font-weight: bold; }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" for some concrete examples.
+rtfobj can be used as a Python library or a command-line tool.
It is part of the python-oletools package.
Usage
-rtfobj.py <file.rtf>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.
+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:
+
+To extract an object or file, use the option -s followed by the object number as shown in the table.
+Example:
+rtfobj -s 0It 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
-Usage as a python module:
-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.
+As of v0.50, the API has changed significantly and it is not final yet. For now, see the class RtfObjectParser in the code.
+Deprecated API (still functional):
+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:
-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))python-oletools documentation
-
diff --git a/oletools/doc/rtfobj.md b/oletools/doc/rtfobj.md
index 9166db3..79f7deb 100644
--- a/oletools/doc/rtfobj.md
+++ b/oletools/doc/rtfobj.md
@@ -1,35 +1,82 @@
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