reg2es

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

The 38 bundled plugins are ported from airbus-cert/regrippy. reg2es runs standalone and does not require the regrippy package at runtime. Both reg2es and reg2json consume the same plugin runner and emit the same ECS-oriented documents.

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 files 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 38 bundled plugins and exit.
• --size N: set the generated/indexed chunk size (default: 500).
• --tags tag1,tag2: add tags to every document.
• --quiet: suppress progress output.

reg2es additionally accepts Elasticsearch connection options including --host, --port, --index, --scheme, --pipeline, --login, --pwd, and --no-verify-certs. Run reg2es --help or reg2json --help for the full current interface.

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 credentials for Elastic Security:

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

Appendix

reg2json

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

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

Use --split to write one JSON array per plugin that produced results. With this option, -o names an output directory (the current directory is used by default):

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

For example, the command above produces files such as artifacts/antivirus.json, artifacts/services.json, and artifacts/userassist.json. Plugins with no results do not produce an empty file.

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] object:

from reg2es import reg2json

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

Output Format Example

Each plugin result becomes one ECS-oriented document. Standard event, registry, log.file, tags, and @timestamp fields describe the artifact. Lossless plugin-specific data and the original offline-hive location are kept under reg2es.

Binary registry values report their size in registry.data.bytes; their raw hex is preserved once in reg2es.value_data. Parsed fields remain under reg2es.custom, and RecentDocs names are also exposed as ECS file.name.

{
  "@timestamp": "2015-10-30T07:24:57.814133+00:00",
  "event": {
    "kind": "event",
    "category": ["registry"],
    "type": ["info"],
    "action": "compname"
  },
  "registry": {
    "hive": "HKLM",
    "key": "SYSTEM\\ControlSet001\\Control\\ComputerName\\ComputerName",
    "path": "HKLM\\SYSTEM\\ControlSet001\\Control\\ComputerName\\ComputerName",
    "value": "ComputerName",
    "data": {
      "type": "RegSZ",
      "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"
  }
}

Installation

From PyPI

$ pip install reg2es

With uv

$ uv add reg2es

From GitHub Releases

Standalone binaries built with Nuitka 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. :sushi: :sushi: :sushi:

License

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.

• Repository: https://github.com/airbus-cert/regrippy
• Commit: 32e3ab3243415b7bf46f812d933f4d29862e3046
• Vendored components:
  • src/reg2es/plugins/base.py — BasePlugin, PluginResult, mactime
  • src/reg2es/plugins/*.py — 38 registry analysis plugins
  • src/reg2es/plugins/shimcache.py — Shim Cache plugin with its parser (original copyright: Andrew Davis, andrew.davis@mandiant.com, Mandiant 2012)
• Modifications: import paths changed from regrippy to reg2es.plugins and the formerly separate Shim Cache parser was integrated into its plugin. Unused upstream CLI display helpers were removed; artifact extraction logic remains unchanged.
• Full license text: LICENSES/Apache-2.0.txt

We gratefully thank the maintainers and contributors of regrippy, python-registry, and the other open-source projects that make reg2es possible.