As a co-author and instructor for Guidance Software’s EnScript Programming course, I spend a lot of time teaching investigators in person around the globe. Investigators are faced with a dizzying variety of challenges. We work together in class, coming up with solutions that send EnCase off to do our bidding. EnCase and EnScript allow us to “bottle” the result of our efforts to share with other investigators (e.g. categorizing internet history, detecting files hidden by rootkits).
Python is used similarly. The interweb hosts great tools written in Python to accomplish all measures of tasks facing DFIR examiners. The community benefits from the hours of work that go into each and every .py that gets baked. It seemed to me that there should be a way for EnCase and Python to work together, so I put together a brief tutorial.
I’m writing this post primarily as a tutorial for EnScripters, but I thought I would drop in a little something for the EnCase Examiners that are reading through this, as well. To do this, I’m going to use a favorite Python script called pdf-parser.py written by Didier Stevens throughout this tutorial. You can download pdf-parser.py directly from Didier Stevens’ blog. I’m making an assumption that you have Python already, and it is located at c:\Python27\Python.exe. And to make things simpler, let’s place the pdf-parser.py file in the same folder. If your paths are different, just make note for the rest of the tutorial.
This tutorial is broken out into several sections that range from easy to expert. First will be a method of using a Python module that anyone can put together in EnCase. Then I work through EnScript methods that most of you with a little programming experience can follow. The final section covers an EnScript that takes input from the examiner through the use of a GUI and passes those options on through to Python for execution.
Examiner Method: External File Viewers
Open your File Viewers window (right click ‘open with’) and create a new view with these settings:
- Name: PDF-Parser (Python)
- Application Path: c:\windows\system32\cmd.exe
- Command Line: /k c:\Python27\Python.exe "c:\Python27\pdf-parser.py" [file]
We’re not going directly to the Python executable because it’s designed to run its tasks and quit. This will result in the command shell showing and disappearing very quickly. Instead, we use cmd.exe with the /k parameter to get the window open, execute the task, and stay open for us to review the output.
Click OK twice, and you will find the data from pdf-parser in a window. You’ll likely have to adjust your screen buffers in order to get the complete data, especially for the larger PDF files.
You can now run this on any PDF file in EnCase with a right click. To keep them around you’ll have to copy/paste the results into a text file or bookmark.
EnScript Method: Easy Mode
Sample code is available for download here.
EnCase provides functionality in EnScript to run external tools utilizing ExecuteClass. This is essentially the same as running a tool at the command shell. The nice thing here is that we can capture the output from these tools, and bring it back into EnCase. Here’s what the help page shows:
And here’s a very simple example Python script to show the interaction. It outputs “hello world” to the command shell, and then loops through the arguments provided and writes them to the command shell, as well.
Here are the basics of getting an EnScript to run a Python script and collect the output. For simplicity, I’ve hard coded several values. The location of these two scripts doesn’t matter much, but they do need to be located next to each other in the same folder.
ExecuteClass uses a ConnectionClass as a tunnel to send and receive program data through. This allows us to execute on a remote machine, but here we use LocalMachine on line 18 to designate the examiner’s computer.
- Backslashes in EnScript code need to be escaped “\\”
- The uppercase L and M characters of LocalMachine
- SetApplication() needs to be given a full and valid path to an executable
- SetFolder() only sets the working directory and is not required
- SetCommandLine() takes all parameters going to the set application
- Make sure to quote any paths that might contain spaces
EnScript Method: Intermediate Mode
The example above provides input to the Python script and collects the output, but it has no file data to act upon. Here I’ll demonstrate how to send the currently highlighted entry in EnCase out to where Python can work with it, but the code will remain as simple as possible to show just what is needed to apply this to other Python scripts.
I’ve switched over to using the pdf-parser since the previous Python script doesn’t have any code for working with files. Take a look:
Line 6 does the work of telling us which file the examiner has highlighted. The GetCurrentItem function returns an ItemClass object that can be a file from any of these views: Evidence (EntryClass), Records (RecordClass), Results (ResultClass), or Bookmarks (BookmarkClass).
Because the pdf-parser doesn’t understand e01 evidence files, the PDF files have to be taken out and placed on the file system where they can be accessed individually. Lines 9 and 10 open the file internally and an empty one externally, while line 11 fills the external with the contents of the internal.
Once Python has finished its work, we create a bookmark folder (Line 24) and a note (line 25) inside that holds the output (line 26) of the pdf-parser.
The results in the bookmarks tab display the results:
Make it Work for You
The EnScript just above has been made simple enough that this can be modified easily to use any other Python module that targets individual files of any type. Line 13 is what needs to be changed.
Now you can take advantage of the great work from our community and apply the Python tools to files inside your EnCase evidence files. I did a search and found a few Python based projects to consider:
- analyzeMFT - http://www.integriography.com
- $USNJRNL•$J Parser - http://code.google.com/p/parser-usnjrnl
- libpff - https://code.google.com/p/libpff
- peepdf - https://code.google.com/p/peepdf
- registrydecoder - https://code.google.com/p/registrydecoder
- ntdsxtract - https://code.google.com/p/ntdsxtract
Tell me your favorite Python based file parser in the comments below or on Twitter with hashtag #en2py. In the next post, I’ll be showing you an EnScript that is more advanced and utilizes a GUI to accept input from the examiner when running the pdf-parser Python script.