Added evtx section

docs/index.rst

@@ -15,6 +15,7 @@ A guide for developing Python scripts in DFIR
 
    section1
    section2
+   section3
 
 Handbook Sections
 ==============================

docs/section3.rst

@@ -0,0 +1,10 @@
+Section 3 - Windows Event Log Parsing
+=====================================
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Section 3.1 - Opening an Event Log
+----------------------------------
+.. automodule:: sections.section_03.open_evtx
+   :members:

requirements.txt

@@ -1 +1,2 @@
 -e git+https://github.com/msuhanov/yarp@1.0.28#egg=yarp
+python-evtx==0.6.1

sections/__init__.py

@@ -8,6 +8,9 @@ This handbook is not intended to be read in order - if anything
 this outline is the main launching point to find the correct page
 containing the code block you wish to reference.
 
+Please feel free to contribute your own sections with the snippets that have
+worked well for you, even if a similar section already exists.
+
 Section 1 - Essential Script Elements
 -------------------------------------
 
@@ -50,17 +53,22 @@ Section 3 - Event Logs
 
 * Using python-evtx
     - Opening evtx files
-* Counts/Metadata about EVTX container
 * Parsing Logins (with types, levels, privs)
+    - Parse out the commonly investigated 4624/4672 events
 * Parsing Logouts (durations)
+    - Parse 4624/4634 events to get information on user sessions
 * Parsing Powershell decoding
+    - Reassemble PowerShell strings in events and decode commands
 
 Section 4 - Text logs
 ---------------------
 
 * Handling IIS Logs
+    - Parse common fields in IIS logs into a report
 * Handling Syslog
+    - Parse common syslog formats into a report
 * Adding in GeoIP
+    - Function to add GeoIP recognition
 
 Section 5 - API calls & JSON data
 ---------------------------------

sections/section_03/__init__.py

@@ -0,0 +1,7 @@
+"""Windows Event Log Snippets
+
+Parsing event logs is a common task for Windows host analysis.
+The ``python-evtx`` library is a robust library for parsing event logs
+and this section will show examples of how to leverage this library to
+answer common questions in the event log.
+"""

sections/section_03/open_evtx.py

@@ -0,0 +1,100 @@
+"""Example for opening EVTX files.
+
+Demonstrates how to open an EVTX file and get basic details about the event log.
+This section makes use of python-evtx, a python library for reading event log
+files. To install, run ``pip install python-evtx``.
+
+Other libraries for parsing these event logs exist and we welcome others to
+add snippets that showcase how to make use of them in reading EVTX files.
+
+Example Usage:
+
+    ``$ python open_evtx.py System.evtx``
+
+References:
+
+* https://github.com/williballenthin/python-evtx
+
+
+Open Windows Event Logs (EVTX)
+==============================
+
+This function shows an example of opening an EVTX file and parsing out several
+common parameters about the file.
+
+.. literalinclude:: ../sections/section_03/open_evtx.py
+    :pyobject: open_evtx
+
+Docstring References
+====================
+"""
+
+from collections import OrderedDict
+import os
+import Evtx.Evtx as evtx
+
+
+"""
+Copyright 2019 Chapin Bryce
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+__author__ = 'Chapin Bryce'
+__date__ = 20191103
+__license__ = 'MIT Copyright 2019 Chapin Bryce'
+__desc__ = '''Sample script to read EVTX files.'''
+__docs__ = [
+    'https://github.com/williballenthin/python-evtx'
+]
+
+
+def open_evtx(input_file):
+    """Opens a Windows Event Log and displays common log parameters.
+
+    Arguments:
+        input_file (str): Path to evtx file to open
+    """
+
+    with evtx.Evtx(input_file) as open_log:
+        header = open_log.get_file_header()
+        properties = OrderedDict([
+            ('major_version', 'File version (major)'),
+            ('minor_version', 'File version (minor)'),
+            ('is_dirty', 'File is ditry'),
+            ('is_full', 'File is full'),
+            ('next_record_number', 'Next record number')
+        ])
+
+        for key, value in properties.items():
+            print(f"{value}: {getattr(header, key)()}")
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(
+        description=__desc__,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        epilog=f"Built by {__author__}, v.{__date__}"
+    )
+    parser.add_argument('EVTX_FILE', help="EVTX file to read")
+    args = parser.parse_args()
+
+    open_evtx(args.EVTX_FILE)