Metadata-Version: 2.5
Name: evtx2es
Version: 1.11.1
Summary: A fast library for parsing and importing Windows Event Logs into Elasticsearch.
Author-email: sumeshi <sum3sh1@protonmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: elasticsearch==9.4.1
Requires-Dist: evtx==0.11.1
Requires-Dist: orjson==3.11.9
Requires-Dist: tqdm>=4.67.3
Requires-Dist: urllib3>=2.6.3
Description-Content-Type: text/markdown

# evtx2es

[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
[![PyPI Version](https://img.shields.io/pypi/v/evtx2es)](https://pypi.org/project/evtx2es/)

![evtx2es logo](https://gist.githubusercontent.com/sumeshi/c2f430d352ae763273faadf9616a29e5/raw/1bf24feb55571bf7f0c7d8d4cb04bd0a511120f2/evtx2es.svg)

A command-line tool and Python library for parsing Windows Event Logs and importing the results into Elasticsearch.

Life is too short to process **huge Windows Event Logs** using **pure Python**.  
**evtx2es** leverages the Rust-based parser [pyevtx-rs](https://github.com/omerbenamram/pyevtx-rs), making it significantly faster than traditional tools.
It can also recover as many records as possible from corrupted, partially overwritten, or carved `.evtx` files.


## Usage

**evtx2es** can be used as a standalone command-line tool or integrated directly into your Python scripts.

```bash
$ evtx2es /path/to/your/file.evtx
```

```python
from evtx2es import evtx2es

evtx2es('/path/to/your/file.evtx')
```


### Arguments

**evtx2es** can process multiple files at once:

```bash
$ evtx2es file1.evtx file2.evtx file3.evtx
```

evtx2es can recursively process all `.evtx` files under a specified directory:

```bash
$ tree .
evtxfiles/
  ├── file1.evtx
  ├── file2.evtx
  ├── file3.evtx
  └── subdirectory/
    ├── file4.evtx
    └── subsubdirectory/
      ├── file5.evtx
      └── file6.evtx

$ evtx2es /evtxfiles/ # This recursively processes file1 through file6.
```


### Options

```
--version, -v

--help, -h

--quiet, -q
  Suppress standard output
  (default: False)

--multiprocess, -m:
  Enable multiprocessing for faster processing.
  (default: False)

--size:
  Number of records to process per chunk (default: 500)

--host:
  Elasticsearch host address (default: localhost)

--port:
  Elasticsearch port number (default: 9200)

--index:
  Destination index name (default: evtx2es)

--scheme:
  Protocol scheme to use (http or https) (default: http)

--pipeline:
  Elasticsearch ingest pipeline to use (default: )

--datasetdate:
  Shift timestamps based on the latest record's `TimeCreated` value
  (MM/DD/YYYY.HH:MM:SS). If omitted, timestamps are not shifted.

--login:
  Username for Elasticsearch authentication

--pwd:
  Password for Elasticsearch authentication

--no-verify-certs:
  Disable TLS certificate verification (default: False)

--ca-certs:
  Path to a CA certificate bundle for TLS verification (default: None)
```


### Examples

When using from the command line:

```bash
$ evtx2es /path/to/your/file.evtx --host=localhost --port=9200 --index=foobar --size=500
```

When using from a Python script:

```py
evtx2es("/path/to/your/file.evtx", host="localhost", port=9200, index="foobar", chunk_size=500)
```

With Elasticsearch authentication:

```bash
$ evtx2es /path/to/your/file.evtx --host=localhost --port=9200 --index=foobar --login=elastic --pwd=******
```

> [!WARNING]
> TLS certificate verification is enabled by default. Use `--no-verify-certs` only
> when connecting to a trusted cluster with a self-signed or otherwise
> unverifiable certificate. Use `--ca-certs /path/to/ca.pem` to provide a
> private CA bundle while keeping verification enabled.


## Appendix

### evtx2json

**evtx2es** also includes `evtx2json`, a command-line tool for converting Windows Event Logs into JSON files. :sushi: :sushi: :sushi:

```bash
$ evtx2json /path/to/your/file.evtx /path/to/output/target.json
```

`evtx2json` also supports line-delimited output. `--format jsonl` (or `ndjson`)
writes one record per line without holding the entire dataset in memory. When
no output path is specified, the default extension is `.jsonl`:

```bash
$ evtx2json /path/to/your/file.evtx --format jsonl
```

You can also convert `.evtx` files directly into a Python `list[dict]`:

```python
from evtx2es import evtx2json

result: list[dict] = evtx2json('/path/to/your/file.evtx')
```


## Output Format Example

The following example uses a sample `.evtx` file from [JPCERT/CC:LogonTracer](https://github.com/JPCERTCC/LogonTracer).

```json
[
  {
    "@timestamp": "2016-10-06T01:47:07.509504Z",
    "event": {
      "action": "eventlog-security-1102",
      "category": [
        "host"
      ],
      "type": [
        "info"
      ],
      "kind": "event",
      "provider": "microsoft-windows-eventlog",
      "module": "windows",
      "dataset": "windows.eventlog",
      "code": 1102,
      "created": "2016-10-06T01:47:07.509504Z"
    },
    "winlog": {
      "channel": "Security",
      "computer_name": "WIN-WFBHIBE5GXZ.example.co.jp",
      "event_id": 1102,
      "opcode": 0,
      "record_id": 227126,
      "task": 104,
      "version": 0,
      "provider": {
        "name": "Microsoft-Windows-Eventlog",
        "guid": "{fc65ddd8-d6ef-4962-83d5-6e5cfe9ce148}"
      }
    },
    "userdata": {
      "LogFileCleared": {
        "#attributes": {
          "xmlns:auto-ns3": "http://schemas.microsoft.com/win/2004/08/events",
          "xmlns": "http://manifests.microsoft.com/win/2004/08/windows/eventlog"
        },
        "SubjectUserSid": "S-1-5-21-1524084746-3249201829-3114449661-500",
        "SubjectUserName": "Administrator",
        "SubjectDomainName": "EXAMPLE",
        "SubjectLogonId": "0x32cfb"
      }
    },
    "process": {
      "pid": 960,
      "thread": {
        "id": 3020
      }
    },
    "log": {
      "file": {
        "path": "/path/to/your/Security.evtx"
      }
    },
    "tags": [
      "eventlog"
    ]
  },
  ...
]
```


## Performance Evaluation (v1.8.0)

Performance was evaluated using a sample `.evtx` file from [JPCERT/CC:LogonTracer](https://github.com/JPCERTCC/LogonTracer) (approx. 30MB of binary data).

```bash
$ time uv run evtx2es Security.evtx
Importing Security.evtx...
1it [00:08,  8.09s/it]
Bulk import completed: 1 batches processed
Successfully indexed: 62031 documents
Import completed successfully.

________________________________________________________
Executed in    8.60 secs    fish           external
   usr time    4.85 secs  481.00 micros    4.85 secs
   sys time    0.40 secs    0.00 micros    0.40 secs
```


### Running Environment

```
OS: Ubuntu 20.04 (Dev Container on WSL2)
CPU: Intel Core i5-12400F
RAM: DDR4 32GB
```

The tests were conducted within the provided development container, pushing data into a local [Elasticsearch 9.0.2 Docker container](https://hub.docker.com/_/elasticsearch).


## Installation

### From PyPI

```bash
$ pip install evtx2es
```

### With uv

```bash
$ uv add evtx2es
```

### From GitHub Releases

Standalone binaries built with Nuitka are available from GitHub Releases for systems without a Python environment.

```bash
$ chmod +x ./evtx2es
$ ./evtx2es {{options...}}
```

```powershell
> evtx2es.exe {{options...}}
```

## Contributing

The source code for **evtx2es** is hosted on GitHub: https://github.com/sumeshi/evtx2es.
Please report issues and feature requests. :sushi: :sushi: :sushi:


## Included in

- [Tsurugi Linux [Lab]](https://tsurugi-linux.org/) — included in releases from 2022 to 2026
- [Drift Linux Fast/Fast XS](https://www.driftlinux.org/) — included in 2026 releases

Thank you for your interest in evtx2es!


## License

Released under the [MIT](LICENSE) License.


## Third-party licenses

Standalone releases are ZIP archives containing both commands and `LICENSES.txt`
with project, runtime dependency and Python license notices. Keep the notices
with the executables when redistributing them.

For the parser binding, which declares MIT but supplies no license file, the
archive includes the standard MIT text and upstream attribution. See
[.github/LICENSE-NOTES.md](.github/LICENSE-NOTES.md) for provenance.

The standalone binaries distributed via GitHub Releases may bundle the following third-party libraries.
These libraries remain under their original licenses.

### Apache-2.0

- [elasticsearch-py / elasticsearch](https://github.com/elastic/elasticsearch-py) — licensed under the Apache License 2.0.
  - Bundled version: `elasticsearch==9.4.1`
  - License text: https://github.com/elastic/elasticsearch-py/blob/main/LICENSE

### MIT

- [evtx / pyevtx-rs](https://github.com/omerbenamram/pyevtx-rs) — licensed under the MIT License.
  - Bundled version: `evtx==0.11.1`
  - License text: https://github.com/omerbenamram/pyevtx-rs/blob/master/pyproject.toml

- [urllib3](https://github.com/urllib3/urllib3) — licensed under the MIT License.
  - Bundled version: `urllib3==2.6.3`
  - License text: https://github.com/urllib3/urllib3/blob/main/LICENSE.txt

### Apache-2.0 OR MIT, with MPL-2.0 components

- [orjson](https://github.com/ijl/orjson) — licensed under Apache-2.0 OR MIT, and contains source code licensed under MPL-2.0.
  - Bundled version: `orjson==3.11.9`
  - License text:
    - https://github.com/ijl/orjson/blob/master/LICENSE-APACHE
    - https://github.com/ijl/orjson/blob/master/LICENSE-MIT
    - https://github.com/ijl/orjson/blob/master/LICENSE-MPL-2.0

### MIT and MPL-2.0

- [tqdm](https://github.com/tqdm/tqdm) — licensed under MIT, with MPL-2.0-covered files/components.
  - Bundled version: `tqdm==4.67.3`
  - License text: https://github.com/tqdm/tqdm/blob/master/LICENCE
