added better comments, more testing, and reformatted output

Author: ajread4

README.md

@@ -29,7 +29,7 @@ python-evtx operates on event log files from Windows operating systems newer tha
 
 Examples
 --------
-Provided with the parsing module `Evtx` are three scripts that mimic the tools distributed with Parse-Evtx.  `evtx_info.py` prints metadata about the event log and verifies the checksums of each chunk.  `evtx_templates.py` builds and prints the templates used throughout the event log.  Finally, `evtx_dump.py` parses the event log and transforms the binary XML into a human readable ASCII XML format.
+Provided with the parsing module `Evtx` are four scripts that mimic the tools distributed with Parse-Evtx.  `evtx_info.py` prints metadata about the event log and verifies the checksums of each chunk.  `evtx_templates.py` builds and prints the templates used throughout the event log. `evtx_dump.py` parses the event log and transforms the binary XML into a human readable ASCII XML format. Finally, `evtx_dump_json.py` parses event logs, similar to `evtx_dump.py` and transforms the binary XML into JSON with the added capability to output new line delimited JSON to a file. 
 
 Note the length of the `evtx_dump.py` script: its only 20 lines.  Now, review the contents and notice the complete implementation of the logic:
 

scripts/evtx_dump.py

@@ -19,10 +19,6 @@
 #   Version v0.1.1
 import Evtx.Evtx as evtx
 import Evtx.Views as e_views
-import os
-import xmltodict
-import json
-
 
 def main():
     import argparse
@@ -31,43 +27,14 @@ def main():
         description="Dump a binary EVTX file into XML.")
     parser.add_argument("evtx", type=str,
                         help="Path to the Windows EVTX event log file")
-    parser.add_argument("-o","--output",type=str,help="Path to output JSON file")
     args = parser.parse_args()
 
     with evtx.Evtx(args.evtx) as log:
-
-        if (args.output):
-            final_json=[]
-            for record in log.records():
-                data_dict=xmltodict.parse(record.xml()) #convert the xml to a dictionary
-                for event_system_key, event_system_value in data_dict['Event']['System'].items():  # loop through each key and value pair
-                    if (event_system_key=="EventRecordID"):
-                        json_subline={}
-                        firstline={event_system_key:event_system_value}
-                        json_subline.update(firstline) #add the event ID to JSON subline
-                for event_data_key, event_data_value in data_dict['Event']['EventData'].items():  # loop through each key and value pair
-                    for values in event_data_value:
-                        for event_data_subkey,event_data_subvalue in values.items(): #loop through each
-                            if event_data_subkey=="@Name": #extract the name from the value
-                                data_name=event_data_subvalue
-                            else:
-                                data_value=event_data_subvalue #extract the true value
-                        json_subline.update({data_name:data_value}) #update the JSON sub line
-                final_json.append(json_subline) #update the final
-
-            # Output the JSON data
-            if (os.path.splitext(args.output)[1] == ".json"): #if the file extension is correct
-                json_file=args.output
-            else: # if the file extension is incorrect
-                json_file=args.output +".json"
-            with open(json_file,"w") as outfile: #write to an output file
-                json.dump(final_json,outfile)
-        else:
-            print(e_views.XML_HEADER)
-            print("<Events>")
-            for record in log.records():
-                print(record.xml())
-            print("</Events>")
+        print(e_views.XML_HEADER)
+        print("<Events>")
+        for record in log.records():
+            print(record.xml())
+        print("</Events>")
 
 
 if __name__ == "__main__":

scripts/evtx_dump_json.py

@@ -1,52 +1,84 @@
-# Written by AJ Read with help from evtx_dump.py file
-# Adds functionality to evtx_dump so that the user can dump evtx data formatted in JSON to the command line or a file.
-# The JSON data uses only the "EventRecordID" from the "System" XML structure while using all the fields in the "EventData" xml structure.
+#!/usr/bin/env python3
+#   This file is part of python-evtx.
+#   Written by AJ Read with help from evtx_dump.py file written by Willi Ballenthin.
+#
+#   Purpose: User can dump evtx data into JSON format to either the command line or a JSON file in new line delimited format.
 
 import Evtx.Evtx as evtx
 import Evtx.Views as e_views
-import os #added dependency
-import xmltodict #added dependency
-import json #added dependency 
+
+# Added packages 
+import os
+import xmltodict
+import json
+
 
 def main():
     import argparse
-
     parser = argparse.ArgumentParser(
         description="Dump a binary EVTX file into XML.")
     parser.add_argument("evtx", type=str,
                         help="Path to the Windows EVTX event log file")
-    parser.add_argument("-o","--output",type=str,help="Path to output JSON file")
+    parser.add_argument("-o","--output",type=str,
+                        help="Path of output JSON file")
     args = parser.parse_args()
 
     with evtx.Evtx(args.evtx) as log:
+
+        # Instantiate the final json object
         final_json=[]
+
+        # Loop through each record in the evtx log
         for record in log.records():
-            data_dict=xmltodict.parse(record.xml()) #convert the xml to a dictionary
-            for event_system_key, event_system_value in data_dict['Event']['System'].items():  # loop through each key and value pair
+
+            # Convert the record to a dictionary for ease of parsing
+            data_dict=xmltodict.parse(record.xml())
+
+            # Loop through each key,value pair of the System section of the evtx logs and extract the EventRecordID
+            for event_system_key, event_system_value in data_dict['Event']['System'].items():
                 if (event_system_key=="EventRecordID"):
                     json_subline={}
                     firstline={event_system_key:event_system_value}
+
+                    # Add information to the JSON object for this specific log
                     json_subline.update(firstline) #add the event ID to JSON subline
-            for event_data_key, event_data_value in data_dict['Event']['EventData'].items():  # loop through each key and value pair
+
+            # Loop through each key, value pair of the EventData section of the evtx logs
+            for event_data_key, event_data_value in data_dict['Event']['EventData'].items():
                 for values in event_data_value:
-                    for event_data_subkey,event_data_subvalue in values.items(): #loop through each
-                        if event_data_subkey=="@Name": #extract the name from the value
+
+                    # Loop through each subvalue within the EvenData section to extract necessary information
+                    for event_data_subkey,event_data_subvalue in values.items():
+                        if event_data_subkey=="@Name":
                             data_name=event_data_subvalue
                         else:
-                            data_value=event_data_subvalue #extract the true value
-                    json_subline.update({data_name:data_value}) #update the JSON sub line
-            final_json.append(json_subline) #update the final
+                            data_value=event_data_subvalue
+
+                    # Add information to the JSON object for this specific log
+                    json_subline.update({data_name:data_value})
+
+            # Print the JSON object for the specific log if not requested to output to file
+            if not args.output:
+                print(json_subline)
+
+            # Add specific log JSON object to the final JSON object
+            if not final_json:
+                final_json=[json_subline]
+            else:
+                final_json.append(json_subline)
 
         # If output is desired
         if (args.output):
+
             # Output the JSON data
-            if (os.path.splitext(args.output)[1] == ".json"): #if the file extension is correct
+            if (os.path.splitext(args.output)[1] == ".json"):
                 json_file=args.output
-            else: # if the file extension is incorrect
+            else:
                 json_file=args.output +".json"
-            with open(json_file,"w") as outfile: #write to an output file
+
+            # Write to JSON file
+            with open(json_file,"w") as outfile:
                 json.dump(final_json,outfile)
-        else:
-            print(final_json)
+
 if __name__ == "__main__":
     main()

setup.py

@@ -40,6 +40,7 @@
             ]
         },
         scripts=['scripts/evtx_dump.py',
+                 'scripts/evtx_dump_json.py'
                  'scripts/evtx_dump_chunk_slack.py',
                  'scripts/evtx_eid_record_numbers.py',
                  'scripts/evtx_extract_record.py',