Peter M. Groen / oletools

Commit 602504a04b2066702de0c181286d2e308fdd49ef

Authored by Philippe Lagadec
1 parent 86e21667

added readme

Inline Side-by-side
Showing 2 changed files with 242 additions and 0 deletions
README.md 0 → 100644
  View file @602504a
  1 +oletools
  2 +========
  3 +
  4 +[oletools](http://www.decalage.info/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)](http://en.wikipedia.org/wiki/Compound_File_Binary_Format), such as Microsoft Office documents or Outlook messages, mainly for malware analysis and debugging. It is based on the [OleFileIO_PL](http://www.decalage.info/python/olefileio) parser. See [http://www.decalage.info/python/oletools](http://www.decalage.info/python/oletools) for more info.
  5 +
  6 +
  7 +Tools in oletools:
  8 +-----------------------------------
  9 +
  10 +- **olebrowse**: A simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint documents), to
  11 +view and extract individual data streams.
  12 +- **xxxswf2**: a script to detect, extract and analyze Flash objects (SWF) that may
  13 +be embedded in files such as MS Office documents (e.g. Word, Excel),
  14 +which is especially useful for malware analysis.
  15 +
  16 +News
  17 +----
  18 +
  19 +- 2012-10-09: Initial version of olebrowse and xxxswf2
  20 +- see changelog in source code for more info.
  21 +
  22 +Download:
  23 +---------
  24 +
  25 +The archive is available on [the project page](https://bitbucket.org/decalage/oletools/downloads).
  26 +
  27 +
  28 +olebrowse:
  29 +----------
  30 +
  31 +A simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint documents), to
  32 +view and extract individual data streams.
  33 +
  34 + Usage: olebrowse.py [file]
  35 +
  36 +olebrowse project website: [http://www.decalage.info/python/olebrowse](http://www.decalage.info/python/olebrowse)
  37 +
  38 +xxxswf2:
  39 +--------
  40 +
  41 +xxxswf2 is a script to detect, extract and analyze Flash objects (SWF) that may
  42 +be embedded in files such as MS Office documents (e.g. Word, Excel),
  43 +which is especially useful for malware analysis.
  44 +xxxswf2 is an improved version of xxxswf.py published by Alexander Hanel on
  45 +[http://hooked-on-mnemonics.blogspot.nl/2011/12/xxxswfpy.html](http://hooked-on-mnemonics.blogspot.nl/2011/12/xxxswfpy.html)
  46 +Compared to xxxswf, it can extract streams from MS Office documents by parsing
  47 +their OLE structure properly, which is necessary when streams are fragmented.
  48 +Stream fragmentation is a known obfuscation technique, as explained on
  49 +[http://www.breakingpointsystems.com/resources/blog/evasion-with-ole2-fragmentation/](http://www.breakingpointsystems.com/resources/blog/evasion-with-ole2-fragmentation/)
  50 +
  51 + Usage: xxxswf2.py [options] <file.bad>
  52 +
  53 + Options:
  54 + -o, --ole Parse an OLE file (e.g. Word, Excel) to look for SWF
  55 + in each stream
  56 + -x, --extract Extracts the embedded SWF(s), names it MD5HASH.swf &
  57 + saves it in the working dir. No addition args needed
  58 + -h, --help show this help message and exit
  59 + -y, --yara Scans the SWF(s) with yara. If the SWF(s) is
  60 + compressed it will be deflated. No addition args
  61 + needed
  62 + -s, --md5scan Scans the SWF(s) for MD5 signatures. Please see func
  63 + checkMD5 to define hashes. No addition args needed
  64 + -H, --header Displays the SWFs file header. No addition args needed
  65 + -d, --decompress Deflates compressed SWFS(s)
  66 + -r PATH, --recdir=PATH
  67 + Will recursively scan a directory for files that
  68 + contain SWFs. Must provide path in quotes
  69 + -c, --compress Compresses the SWF using Zlib
  70 +
  71 +xxxswf2 project website: [http://www.decalage.info/python/xxxswf2](http://www.decalage.info/python/xxxswf2)
  72 +
  73 +
  74 +How to contribute:
  75 +------------------
  76 +
  77 +The code is available in [a Mercurial repository on bitbucket](https://bitbucket.org/decalage/oletools). You may use it to submit enhancements or to report any issue.
  78 +
  79 +If you would like to help us improve this module, or simply provide feedback, you may also send an e-mail to decalage(at)laposte.net.
  80 +
  81 +How to report bugs:
  82 +-------------------
  83 +
  84 +To report a bug or any issue, please use the [issue reporting page](https://bitbucket.org/decalage/olefileio_pl/issues?status=new&status=open), or send an e-mail with all the information and files to reproduce the problem.
  85 +
  86 +License
  87 +-------
  88 +
  89 +Copyright (c) 2012, Philippe Lagadec (http://www.decalage.info)
  90 +All rights reserved.
  91 +
  92 +Redistribution and use in source and binary forms, with or without modification,
  93 +are permitted provided that the following conditions are met:
  94 +
  95 + * Redistributions of source code must retain the above copyright notice, this
  96 + list of conditions and the following disclaimer.
  97 + * Redistributions in binary form must reproduce the above copyright notice,
  98 + this list of conditions and the following disclaimer in the documentation
  99 + and/or other materials provided with the distribution.
  100 +
  101 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  102 +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  103 +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  104 +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  105 +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  106 +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  107 +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  108 +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  109 +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  110 +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  111 +
oletools/README.txt 0 → 100644
  View file @602504a
  1 +oletools
  2 +========
  3 +
  4 +`oletools <http://www.decalage.info/python/oletools>`_ is a package of
  5 +python tools to analyze `Microsoft OLE2 files (also called Structured
  6 +Storage, Compound File Binary Format or Compound Document File
  7 +Format) <http://en.wikipedia.org/wiki/Compound_File_Binary_Format>`_,
  8 +such as Microsoft Office documents or Outlook messages, mainly for
  9 +malware analysis and debugging. It is based on the
  10 +`OleFileIO\_PL <http://www.decalage.info/python/olefileio>`_ parser. See
  11 +`http://www.decalage.info/python/oletools <http://www.decalage.info/python/oletools>`_
  12 +for more info.
  13 +
  14 +Tools in oletools:
  15 +------------------
  16 +
  17 +- **olebrowse**: A simple GUI to browse OLE files (e.g. MS Word, Excel,
  18 + Powerpoint documents), to view and extract individual data streams.
  19 +- **xxxswf2**: a script to detect, extract and analyze Flash objects
  20 + (SWF) that may be embedded in files such as MS Office documents (e.g.
  21 + Word, Excel), which is especially useful for malware analysis.
  22 +
  23 +News
  24 +----
  25 +
  26 +- 2012-10-09: Initial version of olebrowse and xxxswf2
  27 +- see changelog in source code for more info.
  28 +
  29 +Download:
  30 +---------
  31 +
  32 +The archive is available on `the project
  33 +page <https://bitbucket.org/decalage/oletools/downloads>`_.
  34 +
  35 +olebrowse:
  36 +----------
  37 +
  38 +A simple GUI to browse OLE files (e.g. MS Word, Excel, Powerpoint
  39 +documents), to view and extract individual data streams.
  40 +
  41 +::
  42 +
  43 + Usage: olebrowse.py [file]
  44 +
  45 +olebrowse project website:
  46 +`http://www.decalage.info/python/olebrowse <http://www.decalage.info/python/olebrowse>`_
  47 +
  48 +xxxswf2:
  49 +--------
  50 +
  51 +xxxswf2 is a script to detect, extract and analyze Flash objects (SWF)
  52 +that may be embedded in files such as MS Office documents (e.g. Word,
  53 +Excel), which is especially useful for malware analysis. xxxswf2 is an
  54 +improved version of xxxswf.py published by Alexander Hanel on
  55 +`http://hooked-on-mnemonics.blogspot.nl/2011/12/xxxswfpy.html <http://hooked-on-mnemonics.blogspot.nl/2011/12/xxxswfpy.html>`_
  56 +Compared to xxxswf, it can extract streams from MS Office documents by
  57 +parsing their OLE structure properly, which is necessary when streams
  58 +are fragmented. Stream fragmentation is a known obfuscation technique,
  59 +as explained on
  60 +`http://www.breakingpointsystems.com/resources/blog/evasion-with-ole2-fragmentation/ <http://www.breakingpointsystems.com/resources/blog/evasion-with-ole2-fragmentation/>`_
  61 +
  62 +::
  63 +
  64 + Usage: xxxswf2.py [options] <file.bad>
  65 +
  66 + Options:
  67 + -o, --ole Parse an OLE file (e.g. Word, Excel) to look for SWF
  68 + in each stream
  69 + -x, --extract Extracts the embedded SWF(s), names it MD5HASH.swf &
  70 + saves it in the working dir. No addition args needed
  71 + -h, --help show this help message and exit
  72 + -y, --yara Scans the SWF(s) with yara. If the SWF(s) is
  73 + compressed it will be deflated. No addition args
  74 + needed
  75 + -s, --md5scan Scans the SWF(s) for MD5 signatures. Please see func
  76 + checkMD5 to define hashes. No addition args needed
  77 + -H, --header Displays the SWFs file header. No addition args needed
  78 + -d, --decompress Deflates compressed SWFS(s)
  79 + -r PATH, --recdir=PATH
  80 + Will recursively scan a directory for files that
  81 + contain SWFs. Must provide path in quotes
  82 + -c, --compress Compresses the SWF using Zlib
  83 +
  84 +xxxswf2 project website:
  85 +`http://www.decalage.info/python/xxxswf2 <http://www.decalage.info/python/xxxswf2>`_
  86 +
  87 +How to contribute:
  88 +------------------
  89 +
  90 +The code is available in `a Mercurial repository on
  91 +bitbucket <https://bitbucket.org/decalage/oletools>`_. You may use it to
  92 +submit enhancements or to report any issue.
  93 +
  94 +If you would like to help us improve this module, or simply provide
  95 +feedback, you may also send an e-mail to decalage(at)laposte.net.
  96 +
  97 +How to report bugs:
  98 +-------------------
  99 +
  100 +To report a bug or any issue, please use the `issue reporting
  101 +page <https://bitbucket.org/decalage/olefileio_pl/issues?status=new&status=open>`_,
  102 +or send an e-mail with all the information and files to reproduce the
  103 +problem.
  104 +
  105 +License
  106 +-------
  107 +
  108 +Copyright (c) 2012, Philippe Lagadec (http://www.decalage.info) All
  109 +rights reserved.
  110 +
  111 +Redistribution and use in source and binary forms, with or without
  112 +modification, are permitted provided that the following conditions are
  113 +met:
  114 +
  115 +- Redistributions of source code must retain the above copyright
  116 + notice, this list of conditions and the following disclaimer.
  117 +- Redistributions in binary form must reproduce the above copyright
  118 + notice, this list of conditions and the following disclaimer in the
  119 + documentation and/or other materials provided with the distribution.
  120 +
  121 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  122 +IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  123 +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  124 +PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  125 +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  126 +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  127 +TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  128 +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  129 +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  130 +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  131 +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.