reg2es

A command-line tool and Python library for extracting forensic artifacts from Windows NT Registry (REGF) hives and importing them into Elasticsearch.

Includes Registry artifact plugins based on regrippy and inspired by RegRipper.

Usage

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

reg2es SYSTEM SOFTWARE SAM
reg2json NTUSER.DAT -o artifacts.json

from reg2es import reg2es

reg2es(["SYSTEM", "SOFTWARE", "SAM"])

Arguments

Multiple inputs passed in one invocation form one registry dataset. This lets plugins such as localgroups enrich SAM results using SOFTWARE data, regardless of the order of input paths.

reg2es SAM SOFTWARE

reg2es can recursively process all registry files under a specified directory:

tree .
regfiles/
  ├── NTUSER.DAT
  ├── NTUSER.MAN
  ├── SAM
  └── subdirectory/
    ├── SOFTWARE
    └── subsubdirectory/
      ├── SYSTEM
      └── UsrClass.dat

reg2es /regfiles/ # Recursively collects hives as one dataset.

Directory scans process REGF hive files only. Registry transaction logs and unrelated files are not treated as standalone hives.

Common options

• --plugin NAME: run one plugin; repeat to select several. By default, compatible, default-enabled plugins run. The exhaustive regtime plugin is opt-in.
• --list-plugins: print the 41 bundled plugins and exit.
• --size N: set the generation and indexing chunk size (default: 500).
• --tags tag1,tag2: add custom tags to every document.
• --quiet: suppress progress output.

reg2es also accepts Elasticsearch connection options including --host, --port, --index, --scheme, --pipeline, --login, --pwd, --ca-certs, and --no-verify-certs. TLS verification is enabled by default; use --ca-certs /path/to/ca.pem for a private CA bundle. Run reg2es --help or reg2json --help for all options.

Examples

When using from the command line:

reg2es SYSTEM --plugin services --host localhost --index registry-artifacts

When using from a Python script:

reg2es(
    ["SYSTEM", "SOFTWARE"],
    host="localhost",
    index="registry-artifacts",
    plugin_names=["services", "systeminfo"],
    additional_tags=["host-01", "case-42"],
)

With Elasticsearch authentication:

reg2es SYSTEM --login elastic --pwd '******'

Appendix

reg2json

reg2es also includes reg2json, a command-line tool for converting Windows NT Registry into JSON files. 🍣 🍣 🍣

reg2json NTUSER.DAT --plugin userassist -o artifacts.json

Use --format jsonl (or ndjson) to write one record per line. The default output extension is .jsonl:

reg2json NTUSER.DAT --plugin userassist --format jsonl -o artifacts.jsonl

Use --split to write one file per plugin. With --split, -o names the output directory:

reg2json collected-hives/ --split -o artifacts/

The exhaustive regtime timeline is excluded from the default plugin set because it emits one record for every registry key. Run it explicitly when needed:

reg2json collected-hives/ --plugin regtime -o regtime.json

You can also convert registry files directly into a Python list[dict]:

from reg2es import reg2json

result: list[dict] = reg2json(
    ["SOFTWARE", "SAM"],
    plugin_names=["localgroups"],
    additional_tags=["host-01"],
)

Output Format Example

{
  "@timestamp": "2015-10-30T07:24:57.814133Z",
  "event": {
    "provider": "registry",
    "module": "windows",
    "dataset": "windows.registry",
    "kind": "event",
    "category": ["registry"],
    "type": ["info"],
    "action": "compname"
  },
  "registry": {
    "hive": "HKLM",
    "key": "SYSTEM\\ControlSet001\\Control\\ComputerName\\ComputerName",
    "path": "HKLM\\SYSTEM\\ControlSet001\\Control\\ComputerName\\ComputerName\\ComputerName",
    "value": "ComputerName",
    "data": {
      "type": "REG_SZ",
      "strings": ["DESKTOP-EXAMPLE"]
    }
  },
  "log": {
    "file": {"path": "/evidence/SYSTEM"}
  },
  "tags": ["registry", "host-01"],
  "reg2es": {
    "plugin": {"name": "compname"},
    "source": {
      "hive": "SYSTEM",
      "key_path": "ROOT\\ControlSet001\\Control\\ComputerName\\ComputerName"
    },
    "value_data": "DESKTOP-EXAMPLE",
    "value_type": "RegSZ"
  }
}

Installation

From PyPI

$ pip install reg2es

With uv

$ uv add reg2es

From GitHub Releases

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

$ chmod +x ./reg2es
$ ./reg2es {{options...}}

> reg2es.exe {{options...}}

Contributing

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

License

Standalone release ZIPs include LICENSES.txt with the project, bundled plugin, runtime dependency and build Python license notices. Keep it with the executables when redistributing them.

reg2es is released under the MIT License.

Third-Party Notices

This product includes code derived from regrippy v2.0.3 by Airbus CERT, licensed under Apache License 2.0. The included ShimCache parser carries the original copyright notice of Andrew Davis, Mandiant (2012). See the Apache 2.0 license text and the source-file notices.