Home

Awesome

<h1 align="center"><img style="padding:0;vertical-align:bottom;" height="32" width="32" src="/eventvwr.ico"/> EVTX</h1> <div align="center"> <p> <strong> A cross-platform parser for the Windows XML EventLog format </strong> </p> </div> <br /> <div align="center"> <!-- Crates version --> <a href="https://crates.io/crates/evtx"> <img src="https://img.shields.io/crates/v/evtx.svg?style=flat-square" alt="Crates.io version" /> </a> <!-- Downloads --> <a href="https://crates.io/crates/evtx"> <img src="https://img.shields.io/crates/d/evtx.svg?style=flat-square" alt="Download" /> </a> <!-- docs.rs docs --> <a href="https://docs.rs/evtx"> <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /> </a> <a href="https://github.com/rust-secure-code/safety-dance/"> <img src="https://img.shields.io/badge/unsafe-forbidden-success.svg" alt="safety-dance" /> </a> <a href="https://github.com/omerbenamram/evtx/actions/workflows/test.yml"> <img src="https://github.com/omerbenamram/evtx/actions/workflows/test.yml/badge.svg" alt="Build status" /> </a> </div> </br>

Features

Installation (associated binary utility):

evtx_dump (Binary utility):

The main binary utility provided with this crate is evtx_dump, and it provides a quick way to convert .evtx files to different output formats.

Some examples

evtx_dump can be combined with fd for convenient batch processing of files:

Note: by default, evtx_dump will try to utilize multithreading, this means that the records may be returned out of order.

To force single threaded usage (which will also ensure order), -t 1 can be passed.

Example usage (as library):

use evtx::EvtxParser;
use std::path::PathBuf;

// Change this to a path of your .evtx sample. 
let fp = PathBuf::from(format!("{}/samples/security.evtx", std::env::var("CARGO_MANIFEST_DIR").unwrap())); 

let mut parser = EvtxParser::from_path(fp).unwrap();
for record in parser.records() {
    match record {
        Ok(r) => println!("Record {}\n{}", r.event_record_id, r.data),
        Err(e) => eprintln!("{}", e),
    }
}

The parallel version is enabled when compiling with feature "multithreading" (enabled by default).

Performance benchmarking

When using multithreading - evtx is significantly faster than any other parser available. For single core performance, it is both the fastest and the only cross-platform parser than supports both xml and JSON outputs.

Performance was benched on my machine using hyperfine (statistical measurements tool).

I'm running tests on a 12-Core AMD Ryzen 3900X.

Tests are running under WSL2, on a linux filesystem (so there shouldn't be any overhead incurred from reading windows mounts).

Libraries benched:

evtx (1 thread)evtx (8 threads)evtx (24 threads)libevtx (C)velocidex/evtx (go)golang-evtx (uses multiprocessing)python-evtx (CPython 3.7.6)python-evtx (PyPy 7.3.0)
30MB evtx (XML)1.155 s ± 0.008 s277.4 ms ± 5.8 ms177.1 ms ± 4.5 ms4.509 s ± 0.100 sNo supportNo support4m11.046s (ran once)1m12.828s (ran once)
30MB evtx (JSON)1.631 s ± 0.006 s341.6 ms ± 7.3 ms207.2 ms ± 7.2 msNo support5.587 s ± 0.086 s2.216 s ± 0.027 sNo supportNo support

Note: numbers shown are real-time measurements (time it takes for invocation to complete). user-time measurements are higher when more using multithreading/multiprocessing, because of the synchronization overhead.

With 8 threads - evtx is more than 650x faster than python-evtx when dumping xml logs.

With maximum viable threads (number of logical cores) - evtx is about 8-10x faster golang-evtx. Both implementations utilize similar multithreading strategies.

Caveats

If the parser errors on any of these nodes, feel free to open an issue or drop me an email with a sample.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.