regipy

⚠️ Bahnbrechende Änderungen in v6.0.0

Version 6.0.0 enthält bedeutende Modernisierungen:

Python 3.9+ erforderlich – Unterstützung für Python 3.6, 3.7 und 3.8 wurde eingestellt

attrs-Bibliothek entfernt – Datenklassen verwenden jetzt das integrierte dataclasses-Modul von Python

Wenn Ihr Code interne Klassen (Cell, VKRecord, Value, Subkey) importiert und attrs-Funktionen wie attr.asdict() verwendet, wechseln Sie zu dataclasses.asdict()

Vollständige Details finden Sie im CHANGELOG.

Regipy ist eine Python-Bibliothek zum Parsen von Offline-Registry-Hives (Hive-Dateien mit REGF-Header). Regipy bietet viele Möglichkeiten:

Verwendung als Bibliothek:
- Rekursion über die Registry-Hive, vom Root oder einem bestimmten Pfad aus, und alle Unterschlüssel und Werte abrufen
- Bestimmte Unterschlüssel und Werte lesen
- Transaktionsprotokolle auf eine Registry-Hive anwenden
Kommandozeilenwerkzeuge
- Eine gesamte Registry-Hive als JSON ausgeben
- Transaktionsprotokolle auf eine Registry-Hive anwenden
- Registry-Hives vergleichen
- Plugins aus einem robusten Plugin-System ausführen (z. B. amcache, shimcache, Rechnernamen extrahieren ...)

Erfordert Python 3.9 oder höher.

Installation

Die neueste Version von Regipy kann von PyPI installiert werden:

pip install regipy[full]

HINWEIS: regipy[full] installiert Abhängigkeiten, die Compiler-Werkzeuge erfordern und etwas Zeit in Anspruch nehmen können. Es ist möglich, eine Version mit reduzierten Abhängigkeiten zu installieren, indem man [full] weglässt.

Außerdem kann man aus dem Quellcode installieren, indem man das Repository klont und folgendes ausführt:

pip install --editable .[full]

Rust-beschleunigtes Backend (Alpha)

Eine optionale Rust-Implementierung des Kern-REGF-Parsers ist als optionales Backend verfügbar, das separat auf PyPI als regipy-rs veröffentlicht wird:

pip install regipy[rust]

from regipy.registry_rs import RegistryHive  # statt regipy.registry

reg = RegistryHive('/tmp/NTUSER.dat')
# Gleiche API: get_key, iter_values, recurse_subkeys, plugins – alles
# funktioniert unverändert, einschließlich aller regipy-Plugins.

Es handelt sich um einen Drop-in-Ersatz, der 1:1 gegen den reinen Python-Parser über den gesamten Test-Hive-Korpus validiert wurde – jeder Schlüsselpfad, Zeitstempel, Wert und jede Plugin-Ausgabe, notariell beglaubigt durch übereinstimmende SHA-256-Traversal-Digests (siehe regipy_tests/comparison_test.py und den Abschnitt Forensic parity evidence von regipy-rs/BENCHMARKS.md).

Vollständiges Traversal mit Werten (recurse_subkeys), Beste von 3 Läufen:

cProfile zeigt, warum: Im Python-Backend wird die Traversalzeit von der construct-Strukturanalyse pro Datensatz und der Wertedekodierung dominiert; mit dem Rust-Backend verschwindet der Parser vollständig aus dem Profil und die einzige verbleibende Python-Kosten ist das Erstellen der zurückgegebenen Subkey-Datenklassen. Die vollständigen Profile, Hive-Digests und ein Haftungsausschluss, der die wenigen beabsichtigten Abweichungen dokumentiert (Ausnahmetypen bei beschädigten Hives, Zyklenschutzverhalten) finden Sie in regipy-rs/BENCHMARKS.md; python regipy-rs/benchmark.py generiert den gesamten Bericht neu.

Der reine Python-Parser bleibt der Standard und ist nicht betroffen, wenn das Rust-Backend nicht installiert ist.

CLI

Header parsen:

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

Beispielausgabe:

╒════════════════════════╤══════════╕
│ 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

Beim Parsen des Headers einer Hive wird auch die Prüfsummenvalidierung und die Transaktionsvalidierung durchgeführt

Gesamte Hive auf die Festplatte ausgeben (dies kann einige Zeit in Anspruch nehmen)

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

Das regipy-dump-Dienstprogramm kann auch anstelle von JSON eine Timeline ausgeben, indem das -t-Flag hinzugefügt wird

Relevante Plugins auf der Hive ausführen

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

Der Hive-Typ wird automatisch erkannt und die relevanten Plugins werden ausgeführt. Weitere Informationen finden Sie im Abschnitt Plugins

Registry-Hives vergleichen

Vergleichen Sie Registry-Hives des gleichen Typs und geben Sie das Ergebnis als CSV aus (wenn -o nicht angegeben ist, wird die Ausgabe auf dem Bildschirm angezeigt)

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

Beispielausgabe:

[2019-02-11 19:49:18.824245] INFO: regipy.cli: Vergleiche 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: 2 Unterschiede erkannt

Wiederherstellen einer Registry-Hive mithilfe von Transaktionsprotokollen:

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

Vergleichen Sie nach der Wiederherstellung die Hives mit registry-diff, um zu sehen, was sich geändert hat

Verwendung als Bibliothek

Registry-Hive-Objekt initialisieren

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

Rekursiv über die gesamte Hive iterieren, beginnend vom Root-Schlüssel

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

Über einen Schlüssel iterieren und alle Unterschlüssel sowie deren Änderungszeit erhalten:

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

Werte eines Schlüssels abrufen:

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}]

Als Plugin verwenden:

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
		}]
	}
}

Alle relevanten Plugins für eine bestimmte Hive ausführen

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'
	}]
}

Validierungsfälle

Bericht zu Validierungsfällen

Alle neuen Plugins sollten einen oder mehrere grundlegende Validierungsfälle haben (die in Zukunft erweitert werden können), zum Beispiel:

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


class NTUserUserAssistValidationCase(ValidationCase):
    # Definieren Sie Ihre Plugin-Klasse
    plugin = BAMPlugin
    # Definieren Sie den Namen der Testdatei, die in `regipy_tests/data` vorhanden sein sollte
    test_hive_file_name = "SYSTEM_WIN_10_1709.xz"

    # Verwenden Sie `expected_entries`, um das Vorhandensein einiger Beispiele aus den Plugin-Ergebnissen zu testen
    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",
        }
    ]

    # ODER verwenden Sie `exact_expected_result`, um auf ein exaktes Ergebnis zu testen:
    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

Entwicklung

Einrichtung für die Entwicklung

# Repository klonen
git clone https://github.com/mkorman90/regipy.git
cd regipy

# Im Entwicklungsmodus mit allen Abhängigkeiten installieren
pip install -e ".[full,dev]"

# Pre-Commit-Hooks installieren
pre-commit install

Tests ausführen

# Alle Tests ausführen
pytest

# Bestimmte Testdateien ausführen
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py

# Plugin-Validierung durchführen
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py

Codequalität

# Linter ausführen
ruff check .

# Formatierer ausführen
ruff format .

# Typprüfer ausführen
mypy regipy/

GitHub Actions lokal testen

Um CI-Workflow-Änderungen vor dem Pushen lokal zu testen, verwenden Sie act:

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

# act installieren (macOS)
brew install act

# act installieren (andere)
# Siehe https://nektosact.com/installation/index.html

Stellen Sie sicher, dass Docker läuft, dann:

# Verfügbare Jobs auflisten
act -l

# Den Lint-Job ausführen
act -j lint

# Alle Jobs für ein Push-Ereignis ausführen
act push

# Den Test-Job mit einer bestimmten Python-Version ausführen
act -j test

# Den Build-Job aus dem Publish-Workflow testen (simuliert ein Release)
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'

Hinweis: Einige Jobs erfordern möglicherweise Secrets. Sie können diese wie folgt bereitstellen:

act -j publish --secret PYPI_API_TOKEN=your_token

Lizenz

MIT

NTUSER.DAT	1.812	173 ms	5 ms	38x
UsrClass.dat	6.205	948 ms	17 ms	55x
amcache.hve	2.105	837 ms	12 ms	67x
SYSTEM	30.756	23,1 s	91 ms	253x
SYSTEM (Win10 1709)	43.211	118,7 s	111 ms	1.068x
SOFTWARE	117.488	745,6 s	292 ms	2.550x

regipy

Beliebteste

regipy

Installation

Rust-beschleunigtes Backend (Alpha)

CLI

Header parsen:

Gesamte Hive auf die Festplatte ausgeben (dies kann einige Zeit in Anspruch nehmen)

Relevante Plugins auf der Hive ausführen

Registry-Hives vergleichen

Wiederherstellen einer Registry-Hive mithilfe von Transaktionsprotokollen:

Verwendung als Bibliothek

Registry-Hive-Objekt initialisieren

Rekursiv über die gesamte Hive iterieren, beginnend vom Root-Schlüssel

Über einen Schlüssel iterieren und alle Unterschlüssel sowie deren Änderungszeit erhalten:

Werte eines Schlüssels abrufen:

Als Plugin verwenden:

Alle relevanten Plugins für eine bestimmte Hive ausführen

Validierungsfälle

Entwicklung

Einrichtung für die Entwicklung

Tests ausführen

Codequalität

GitHub Actions lokal testen

Lizenz