regipy

⚠️ Breaking Changes in v6.0.0

Version 6.0.0 includes significant modernization changes:

Python 3.9+ required - Dropped support for Python 3.6, 3.7, and 3.8

attrs library removed - Data classes now use Python's built-in dataclasses module

If your code imports internal classes (Cell, VKRecord, Value, Subkey) and uses attrs functions like attr.asdict(), switch to dataclasses.asdict()

See the CHANGELOG for full details.

Regipy is a python library for parsing offline registry hives (Hive files with REGF header). regipy has a lot of capabilities:

Use as a library:
- Recurse over the registry hive, from root or a given path and get all subkeys and values
- Read specific subkeys and values
- Apply transaction logs on a registry hive
Command Line Tools
- Dump an entire registry hive to json
- Apply transaction logs on a registry hive
- Compare registry hives
- Execute plugins from a robust plugin system (i.e: amcache, shimcache, extract computer name...)

Requires Python 3.9 or higher.

Installation

Regipy latest version can be installed from pypi:

pip install regipy[full]

NOTE: regipy[full] installs dependencies that require compilation tools and might take some time. It is possible to install a version with relaxed dependencies, by omitting the [full].

Also, it is possible to install from source by cloning the repository and executing:

pip install --editable .[full]

CLI

Parse the header:

regipy-parse-header ~/Documents/TestEvidence/Registry/SYSTEM

Example output:

╒════════════════════════╤══════════╕
│ signature              │ b'regf'  │
├────────────────────────┼──────────┤
│ primary_sequence_num   │ 11639    │
├────────────────────────┼──────────┤
│ secondary_sequence_num │ 11638    │
├────────────────────────┼──────────┤
│ last_modification_time │ 0        │
├────────────────────────┼──────────┤
│ major_version          │ 1        │
├────────────────────────┼──────────┤
│ minor_version          │ 5        │
├────────────────────────┼──────────┤
│ file_type              │ 0        │
├────────────────────────┼──────────┤
│ file_format            │ 1        │
├────────────────────────┼──────────┤
│ root_key_offset        │ 32       │
├────────────────────────┼──────────┤
│ hive_bins_data_size    │ 10534912 │
├────────────────────────┼──────────┤
│ clustering_factor      │ 1        │
├────────────────────────┼──────────┤
│ file_name              │ SYSTEM   │
├────────────────────────┼──────────┤
│ checksum               │ 0        │
╘════════════════════════╧══════════╛
[2019-02-09 13:46:12.111654] WARNING: regipy.cli: Hive is not clean! You should apply transaction logs

When parsing the header of a hive, also checksum validation and transaction validations are done

Dump entire hive to disk (this might take some time)

regipy-dump ~/Documents/TestEvidence/Registry/NTUSER-CCLEANER.DAT -o /tmp/output.json

regipy-dump util can also output a timeline instead of a JSON, by adding the -t flag

Run relevant plugins on Hive

regipy-plugins-run ~/Documents/TestEvidence/Registry/SYSTEM -o /tmp/plugins_output.json

The hive type will be detected automatically and the relevant plugins will be executed. See the plugins section for more information

Compare registry hives

Compare registry hives of the same type and output to CSV (if -o is not specified output will be printed to screen)

regipy-diff NTUSER.dat NTUSER_modified.dat -o /tmp/diff.csv

Example output:

[2019-02-11 19:49:18.824245] INFO: regipy.cli: Comparing NTUSER.DAT vs NTUSER_modified.DAT
╒══════════════╤══════════════╤════════════════════════════════════════════════════════════════════════════════╤════════════════════════════════════════════════╕
│ difference   │ first_hive   │ second_hive                                                                    │ description                                    │
╞══════════════╪══════════════╪════════════════════════════════════════════════════════════════════════════════╪════════════════════════════════════════════════╡
│ new_subkey   │              │ 2019-02-11T19:46:31.832134+00:00                                               │ \Software\Microsoft\legitimate_subkey          │
├──────────────┼──────────────┼────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┤
│ new_value    │              │ not_a_malware: c:\temp\legitimate_binary.exe @ 2019-02-11 19:45:25.516346+00:00 │ \Software\Microsoft\Windows\CurrentVersion\Run │
╘══════════════╧══════════════╧════════════════════════════════════════════════════════════════════════════════╧════════════════════════════════════════════════╛
[2019-02-11 19:49:18.825328] INFO: regipy.cli: Detected 2 differences

Recover a registry hive, using transaction logs:

regipy-process-transaction-logs NTUSER.DAT -p ntuser.dat.log1 -s ntuser.dat.log2 -o recovered_NTUSER.dat

After recovering, compare the hives with registry-diff to see what changed

Using as a library

Initiate the registry hive object

from regipy.registry import RegistryHive
reg = RegistryHive('/Users/martinkorman/Documents/TestEvidence/Registry/Vibranium-NTUSER.DAT')

Iterate recursively over the entire hive, from root key

for entry in reg.recurse_subkeys(as_json=True):
    print(entry)

Iterate over a key and get all subkeys and their modification time:

for sk in reg.get_key('Software').iter_subkeys():
    print(sk.name, convert_wintime(sk.header.last_modified).isoformat())

Adobe 2019-02-03T22:05:32.525965
AppDataLow 2019-02-03T22:05:32.526047
McAfee 2019-02-03T22:05:32.526140
Microsoft 2019-02-03T22:05:32.526282
Netscape 2019-02-03T22:05:32.526352
ODBC 2019-02-03T22:05:32.526521
Policies 2019-02-03T22:05:32.526592

Get the values of a key:

reg.get_key('Software\Microsoft\Internet Explorer\BrowserEmulation').get_values(as_json=True)
[{'name': 'CVListTTL',
  'value': 0,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'UnattendLoaded',
  'value': 0,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'TLDUpdates',
  'value': 0,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'CVListXMLVersionLow',
  'value': 2097211,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'CVListXMLVersionHigh',
  'value': None,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'CVListLastUpdateTime',
  'value': None,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'IECompatVersionHigh',
  'value': None,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'IECompatVersionLow',
  'value': 2097211,
  'value_type': 'REG_DWORD',
  'is_corrupted': False},
 {'name': 'StaleCompatCache',
  'value': 0,
  'value_type': 'REG_DWORD',
  'is_corrupted': False}]

Use as a plugin:

from regipy.plugins.ntuser.ntuser_persistence import NTUserPersistencePlugin
NTUserPersistencePlugin(reg, as_json=True).run()

{
	'Software\\Microsoft\\Windows\\CurrentVersion\\Run': {
		'timestamp': '2019-02-03T22:10:52.655462',
		'values': [{
			'name': 'Sidebar',
			'value': '%ProgramFiles%\\Windows Sidebar\\Sidebar.exe /autoRun',
			'value_type': 'REG_EXPAND_SZ',
			'is_corrupted': False
		}]
	}
}

Run all relevant plugins for a specific hive

from regipy.plugins.utils import run_relevant_plugins
reg = RegistryHive('/Users/martinkorman/Documents/TestEvidence/Registry/SYSTEM')
run_relevant_plugins(reg, as_json=True)

{
	'routes': {},
	'computer_name': [{
		'control_set': 'ControlSet001\\Control\\ComputerName\\ComputerName',
		'computer_name': 'DESKTOP-5EG84UG',
		'timestamp': '2019-02-03T22:19:28.853219'
	}]
}

Validation cases

Validation cases report

All new plugins should have one or more basic validation cases (which can be expanded in the future), for example:

from regipy.plugins.system.bam import BAMPlugin
from regipy_tests.validation.validation import ValidationCase


class NTUserUserAssistValidationCase(ValidationCase):
    # define your plugin class
    plugin = BAMPlugin
    # define the test file name, which should be present in `regipy_tests/data`
    test_hive_file_name = "SYSTEM_WIN_10_1709.xz"

    # Use `expected_entries` to test for presence of a few samples from the plugin results
    expected_entries = [
        {
            "sequence_number": 9,
            "version": 1,
            "sid": "S-1-5-90-0-1",
            "executable": "\\Device\\HarddiskVolume2\\Windows\\System32\\dwm.exe",
            "timestamp": "2020-04-19T09:09:35.731816+00:00",
            "key_path": "\\ControlSet001\\Services\\bam\\state\\UserSettings\\S-1-5-90-0-1",
        }
    ]

    # OR use `exact_expected_result` to test for an exact result:
    exact_expected_result = [
        {
            "sequence_number": 9,
            "version": 1,
            "sid": "S-1-5-90-0-1",
            "executable": "\\Device\\HarddiskVolume2\\Windows\\System32\\dwm.exe",
            "timestamp": "2020-04-19T09:09:35.731816+00:00",
            "key_path": "\\ControlSet001\\Services\\bam\\state\\UserSettings\\S-1-5-90-0-1",
        },
        {
            "sequence_number": 8,
            "version": 1,
            "sid": "S-1-5-90-0-1",
            "executable": "\\Device\\HarddiskVolume2\\Windows\\System32\\cmd.exe",
            "timestamp": "2020-04-19T09:09:34.544224+00:00",
            "key_path": "\\ControlSet001\\Services\\bam\\state\\UserSettings\\S-1-5-90-0-1",
        }
    ]

    expected_entries_count = 2

Development

Setting up for development

# Clone the repository
git clone https://github.com/mkorman90/regipy.git
cd regipy

# Install in development mode with all dependencies
pip install -e ".[full,dev]"

# Install pre-commit hooks
pre-commit install

Running tests

# Run all tests
pytest

# Run specific test files
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py

# Run plugin validation
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py

Code quality

# Run linter
ruff check .

# Run formatter
ruff format .

# Run type checker
mypy regipy/

Testing GitHub Actions Locally

To test CI workflow changes locally before pushing, use act:

# Install act (Fedora)
sudo dnf install act-cli

# Install act (macOS)
brew install act

# Install act (other)
# See https://nektosact.com/installation/index.html

Make sure Docker is running, then:

# List available jobs
act -l

# Run the lint job
act -j lint

# Run all jobs for a push event
act push

# Run the test job with a specific Python version
act -j test

# Test the build job from publish workflow (simulates a release)
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'

Note: Some jobs may require secrets. You can provide them with:

act -j publish --secret PYPI_API_TOKEN=your_token

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 658 Commits
.github		.github
docs		docs
regipy		regipy
regipy_tests		regipy_tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
renovate.json		renovate.json
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

regipy

Installation

CLI

Parse the header:

Dump entire hive to disk (this might take some time)

Run relevant plugins on Hive

Compare registry hives

Recover a registry hive, using transaction logs:

Using as a library

Initiate the registry hive object

Iterate recursively over the entire hive, from root key

Iterate over a key and get all subkeys and their modification time:

Get the values of a key:

Use as a plugin:

Run all relevant plugins for a specific hive

Validation cases

Development

Setting up for development

Running tests

Code quality

Testing GitHub Actions Locally

License

About

Uh oh!

Releases 60

Packages

Uh oh!

Contributors 26

Uh oh!

Languages

License

mkorman90/regipy

Folders and files

Latest commit

History

Repository files navigation

regipy

Installation

CLI

Parse the header:

Dump entire hive to disk (this might take some time)

Run relevant plugins on Hive

Compare registry hives

Recover a registry hive, using transaction logs:

Using as a library

Initiate the registry hive object

Iterate recursively over the entire hive, from root key

Iterate over a key and get all subkeys and their modification time:

Get the values of a key:

Use as a plugin:

Run all relevant plugins for a specific hive

Validation cases

Development

Setting up for development

Running tests

Code quality

Testing GitHub Actions Locally

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 60

Packages 0

Uh oh!

Contributors 26

Uh oh!

Languages

Packages