Skip to main content

Pure Python parser for Windows event log files (.evtx).

Project description

python-evtx

Introduction

python-evtx is a pure Python parser for recent Windows Event Log files (those with the file extension ".evtx"). The module provides programmatic access to the File and Chunk headers, record templates, and event entries. For example, you can use python-evtx to review the event logs of Windows 7 systems from a Mac or Linux workstation. The structure definitions and parsing strategies were heavily inspired by the work of Andreas Schuster and his Perl implementation "Parse-Evtx".

Background

With the release of Windows Vista, Microsoft introduced an updated event log file format. The format used in Windows XP was a circular buffer of record structures that each contained a list of strings. A viewer resolved templates hosted in system library files and inserted the strings into appropriate positions. The newer event log format is proprietary binary XML. Unpacking chunks from an event log file from Windows 7 results in a complete XML document with a variable schema. The changes helped Microsoft tune the file format to real-world uses of event logs, such as long running logs with hundreds of megabytes of data, and system independent template resolution.

Related Work

Andreas Schuster released the first public description of the .evtx file format in 2007. He is the author of the thorough document "Introducing the Microsoft Vista event log file format" that describes the motivation and details of the format. Mr. Schuster also maintains the Perl implementation of a parser called "Parse-Evtx". I referred to the source code of this library extensively during the development of python-evtx.

Joachim Metz also released a cross-platform, LGPL licensed C++ based parser in 2011. His document "Windows XML Event Log (EVTX): Analysis of EVTX" provides a detailed description of the structures and context of newer event log files.

Dependencies

python-evtx is a pure Python 3 module, so it works equally well across platforms like Windows, macOS, and Linux.

python-evtx operates on event log files from Windows operating systems newer than Windows Vista. These files typically have the file extension .evtx. Version 5.09 of the file utility identifies such a file as "MS Vista Windows Event Log". To manual confirm the file type, look for the ASCII string "ElfFile" in the first seven bytes:

willi/evtx  » xxd -l 32 Security.evtx 
0000000: 456c 6646 696c 6500 0000 0000 0000 0000  ElfFile.........
0000010: d300 0000 0000 0000 375e 0000 0000 0000  ........7^......

Examples

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 the JSON array 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:

print(e_views.XML_HEADER)
print('<Events>')
for record in log.records:
    print(record.xml())
print('</Events>')  

Working with python-evtx is really easy!

Installation

Updates to python-evtx are pushed to PyPi, so you can install the module using pip. For example:

pip install python-evtx

The source code for python-evtx is hosted at Github, and you may download, fork, and review it from this repository (http://www.github.com/williballenthin/python-evtx). Please report issues or feature requests through Github's bug tracker associated with the project.

Development

For formatting, use isort:

isort --length-sort --profile black --line-length=120 Evtx/ scripts/ tests/

and black:

black --line-length=120 Evtx/ scripts/ tests/

For linting, use ruff:

ruff check Evtx/ scripts/ tests/

Or use just to run the linters:

just lint

License

python-evtx is licensed under the Apache License, Version 2.0. This means it is freely available for use and modification in a personal and professional capacity.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_evtx-0.8.1.tar.gz (28.3 kB view details)

Uploaded Source

Built Distribution

python_evtx-0.8.1-py3-none-any.whl (26.7 kB view details)

Uploaded Python 3

File details

Details for the file python_evtx-0.8.1.tar.gz.

File metadata

  • Download URL: python_evtx-0.8.1.tar.gz
  • Upload date:
  • Size: 28.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for python_evtx-0.8.1.tar.gz
Algorithm Hash digest
SHA256 e96cea25536a3de5074af7f1bdbf011084d09c2e00664ab754d979820ed75fea
MD5 5d6895a38471bc18b8055b90376f6e7e
BLAKE2b-256 3444e28f31531834b1cd93d14472ec84136dad565e9db0f7abcbae96176c1e65

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_evtx-0.8.1.tar.gz:

Publisher: publish.yml on williballenthin/python-evtx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_evtx-0.8.1-py3-none-any.whl.

File metadata

  • Download URL: python_evtx-0.8.1-py3-none-any.whl
  • Upload date:
  • Size: 26.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for python_evtx-0.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 46336b854dbe0a1e75873ae30db5f583c9d2262ff1d21bdb6b1e624ecfa18ddb
MD5 e8697d1bb8c19831b960ed49867d0f68
BLAKE2b-256 3212f16a7a2f118a07649633b8f72803b932c8d9f0d24a2822cc08a1879ddf6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_evtx-0.8.1-py3-none-any.whl:

Publisher: publish.yml on williballenthin/python-evtx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page