This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or (at

your option) any later version.

This program is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

VOLATILITY PLUGINS

Honeynet Plugins

The code for the following plugins were originally written for Challenge 3 of the Honeynet Forensic Challenge 2010 (Banking Troubles - see https://github.com/carlpulley/volatility/tree/v1.3 and http://honeynet.org/challenges/2010_3_banking_troubles for more information).

exportfile.py [DEPRECIATED: replaced by dumpfiles in Volatility 2.3] - this plugin implements the exporting and saving of _FILE_OBJECT's. In addition, file reconstruction functionality is offered by the plugin. exportstack.py - this plugin displays information regarding an _EPROCESS'es thread data structures.

To install these plugins simply include them (e.g. with the --plugins command line option), when running Volatility.

For documentation on using these plugins, please use the Volatility --help option to the plugin command.

CURRENT LIMITATIONS: exportfile.py should work with Volatility 2.0 whilst exportstack.py should work with Volatility 2.3.

Other Plugins

symbols.py - this plugin is designed to resolve: * Windows addresses to the nearest function/method name within a symbol table * symbol names to addresses. Including this plugin will ensure that _EPROCESS object classes are injected with a symbol_table and lookup method.

When symbols_table is called with build_symbols True, SQLite DB symbol 
tables are built (these include Microsoft's debugging symbol information). 
The symbol PDB files are downloaded and, after processing, their contents 
are inserted into the underlying SQLite DB (which is located within 
Volatility's caching directories). Brendan Dolan-Gavitt's pdbparse is used 
here.

When lookup is called with use_symbols True, then Microsoft's debugging 
symbol information is used during resolution. Otherwise, module exports 
information is used for resolution.

Example usage (from a volshell command prompt):

  # Case 1: SQLite Symbols DB not built:
  volshell> self.proc.symbol_table(build_symbols=True)

  # Case 2: SQLite Symbols DB already built:
  volshell> self.proc.symbol_table()

Example queries:

  # lookup nearest symbol to an address
  volshell> self.proc.lookup(0xb25fc838)
  [ 'sysaudio.sys/PAGE!CClockInstance::ClockGetCorrelatedPhysicalTime' ]

  # lookup nearest module export symbol to an address
  volshell> self.proc.lookup(0x71ab3076, use_symbols=False)
  [ 'ws2_32.dll/????!WSALookupServiceNextW+0x1dd' ]

  # get stack cookie address for ntoskrnl.exe
  volshell> self.proc.lookup("ntoskrnl.exe/.data!___security_cookie")
  [ 2153029696L ]

  # "all" (known) stack cookie addresses within self.proc's address space
  volshell> self.proc.lookup(".data!___security_cookie")
  [ 2153029696L, 2154673632L, 4166547756L, ... ]

  # wininet.dll stack cookie and cookie complement addresses ('%' matches 
  # anything)
  volshell> self.proc.lookup("wininet%/.data!%security_cookie%")
  [ 1998821912, 1998822580 ]

  # view all wshtcpip.dll global variables
  volshell> [ self.proc.lookup(a) for a in self.proc.lookup("wshtcpip.dll/.data!%") ]
  [ 'wshtcpip.dll/.data!__security_cookie',
    'wshtcpip.dll/.data!__security_cookie_complement',
    'wshtcpip.dll/.data!TcpMappingTriples',
    'wshtcpip.dll/.data!UdpMappingTriples',
    'wshtcpip.dll/.data!RawMappingTriples',
    'wshtcpip.dll/.data!Winsock2Protocols',
    'wshtcpip.dll/.data!TcpipProviderGuid',
    'wshtcpip.dll/.data!_NLG_Destination'
  ]

NOTE: due to a bug in pdbparse's src/undname.c code, it is currently 
  necessary to hand patch this file prior building pdbparse. For more 
  details, see:
      https://code.google.com/p/pdbparse/issues/detail?id=13

volshell.py - this plugin is a reworking of the existing Volatility volshell plugin. Major changes are as follows: + hh has been deleted. All help information is now available as Python documentation strings. For example, help(self) and dir(self) give general command help, whilst help() provides help on a specific command. TODO: when using the IPython command line prompt, builtin.help currently overwrites the defined help alias (to self.help), so it is necessary to manually correct this by entering 'help = self.help' after the IPython shell starts. Failing to do this means that individual plugin help will be limited. + the type of volshell instance launched (i.e. WinVolshell, LinuxVolshell, MacVolshell, etc.) is chosen using the profile metadata (specifically the os attribute). When the OS is unknown, a base Volshell is launched - so just load the image and go! + all Volatility plugins are potentially available as commands. These are filtered using the image's profile. Any plugin without a render_text is additionally filtered out. Plugin commands can produce three types of output: * with render=True, the plugin prints to stdout * with render=False and table_data=True, the plugin hooks the table_header and table_row methods and returns a list of hashes representing the displayed tabular data * with render=False and table_data=False, the plugin returns the plugin's calculate result. Plugin arguments are scraped by hooking the singleton class conf. ConfObject and grabbing command line options. These are used (after filtering out generic options from commands.Command) to generate valid keyword arguments with defaults (if specified). Plugin commands are dynamically added to the Volshell class and are accessed via self.. For convenience, aliases are generated using ' = self.'. + it is now possible to override exiting commands in BaseVolshell (e.g. see ps in WinVolshell, LinuxVolshell and MacVolshell) and to add in commands that are OS specific (e.g. see WinVolshell for list_entry). + a source command has been added to ease loading Volshell scripts into the current session. Any function in the loaded file matching the pattern:

      def func(self, ..):
        ..

    is blindly bound to the current Volshell instance and made available 
    as self.func(..) or func(self, ..). If this code was located in 
    /path/to/func.py then it can be sourced using the Volshell command (
    for convenience, sys.path is also searched):

      source("/path/to/func.py")

    TODO: implement code to assign 'func = self.func' in the Volshell 
      session.
  + [EXPERIMENTAL] it is possible to use the Volshell plugin in a 
    Volatility as a library like manner [1]. The following simple code 
    demonstrates the idea by printing out a (sorted) process tree:

      from volatility.plugins.volshell import Volshell
      from itertools import groupby

      def analyse(mem_image):
        shell = Volshell(filename=mem_image)
        data = groupby(sorted(shell.pslist(), key=lambda x: x['PPID']), lambda x: x['PPID'])
        for ppid, pids in data:
          print "PPID: {0}".format(ppid)
          for pid in pids:
            print "  PID: {0}".format(pid['PID'])

    In library mode, the Volshell plugin related methods (i.e. the help, 
    calculate and render_* methods) are disabled.
    TODO: generate examples demonstrating the potential uses for Volshell 
      script and library code.
  + [EXPERIMENTAL] based on [2] and [3], there appears to be a longer term 
    preference for IPython being the default command line experience (+1 
    from myself!). So, when we failover to a basic Python Volshell, an 
    IPython "nag" banner is displayed on startup.

INSTALLATION: run the following commands to install (WARNING: the existing 
  Volshell code is deleted):

    rm $VOLATILITY_SRC/volatility/plugins/linux/linux_volshell.py
    rm $VOLATILITY_SRC/volatility/plugins/mac/mac_volshell.py
    cp -f volshell/volshell.py $VOLATILITY_SRC/volatility/plugins/
    cp -fr volshell/linux $VOLATILITY_SRC/volatility/plugins/
    cp -fr volshell/mac $VOLATILITY_SRC/volatility/plugins/
    cp -fr volshell/windows $VOLATILITY_SRC/volatility/plugins/

REFERENCES:

[1] Using Volatility as a Library (accessed 24/Mar/2013): https://code.google.com/p/volatility/wiki/VolatilityUsage23#Using_Volatility_as_a_Library [2] Volatility Roadmap: Volatility 3.0 (Official Tech Preview Merge) (accessed 24/Mar/2013): https://code.google.com/p/volatility/wiki/VolatilityRoadmap#Volatility_3.0_(Official_Tech_Preview_Merge) [3] Volatility Technology Preview Documentation: Tutorial (accessed 24/Mar/2013): https://volatility.googlecode.com/svn/branches/scudette/docs/tutorial.html