regipy

⚠️ v6.0.0 における互換性のない変更

バージョン6.0.0では、以下の重要な近代化変更が含まれています：

Python 3.9以上が必要 - Python 3.6、3.7、3.8のサポートを廃止

attrsライブラリを削除 - データクラスはPython標準のdataclassesモジュールを使用するようになりました

コードが内部クラス（Cell、VKRecord、Value、Subkey）をインポートし、attr.asdict()などのattrs関数を使用している場合は、dataclasses.asdict()に切り替えてください

詳細はCHANGELOGを参照してください。

Regipyは、オフレジストリハイブ（REGFヘッダを持つハイブファイル）を解析するためのPythonライブラリです。regipyには多くの機能があります：

ライブラリとして使用：
- レジストリハイブをルートまたは指定されたパスから再帰的に探索し、すべてのサブキーと値を取得
- 特定のサブキーと値を読み取り
- トランザクションログをレジストリハイブに適用
コマンドラインツール
- レジストリハイブ全体をJSONにダンプ
- トランザクションログをレジストリハイブに適用
- レジストリハイブの比較
- 堅牢なプラグインシステムを使用したプラグインの実行（例：amcache、shimcache、コンピュータ名の抽出など）

Python 3.9以上が必要です。

インストール

regipyの最新バージョンはpypiからインストールできます：

pip install regipy[full]

注：regipy[full]はコンパイルツールを必要とする依存関係をインストールするため、時間がかかる場合があります。 [full]を省略することで、依存関係を緩和したバージョンをインストールすることも可能です。

また、リポジトリをクローンしてソースからインストールすることもできます：

pip install --editable .[full]

Rust加速バックエンド（アルファ版）

コアREGFパーサーのオプションのRust実装が、オプトインバックエンドとして利用可能で、PyPIにregipy-rsとして公開されています：

pip install regipy[rust]

from regipy.registry_rs import RegistryHive  # 代わりに regipy.registry を使用

reg = RegistryHive('/tmp/NTUSER.dat')
# 同じAPI: get_key、iter_values、recurse_subkeys、プラグイン — すべて
# regipyプラグインも含めて変更なしで動作します。

これは純粋Pythonパーサーに対して1:1で検証されたドロップイン置き換えであり、テストハイブコーパス全体で検証されています — すべてのキーパス、タイムスタンプ、値、プラグイン出力がSHA-256トラバーサルダイジェストによって認証されています（regipy_tests/comparison_test.pyおよびregipy-rs/BENCHMARKS.mdの「Forensic parity evidence」セクションを参照）。

値を使用した完全トラバーサル（recurse_subkeys）、3回実行の最良値：

cProfileがその理由を示しています：Pythonバックエンドでは、トラバーサル時間はレコードごとのconstruct構造体解析と値デコードによって占められています。Rustバックエンドでは、パーサーはプロファイルから完全に消え、唯一残るPythonのコストは返されたSubkeyデータクラスの構築だけです。完全なプロファイル、ハイブごとのダイジェスト、および意図的な相違点（破損したハイブでの例外タイプ、サイクルガードの動作）を文書化した免責事項は、regipy-rs/BENCHMARKS.mdにあります。python regipy-rs/benchmark.pyでレポート全体を再生成できます。

純粋Pythonパーサーはデフォルトのままであり、Rustバックエンドがインストールされていない場合は影響を受けません。

CLI

ヘッダーの解析：

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

出力例：

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

ハイブのヘッダーを解析するとき、チェックサムの検証とトランザクションの検証も行われます。

ハイブ全体をディスクにダンプ（時間がかかる場合があります）

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

regipy-dumpユーティリティは、-tフラグを追加することで、JSONの代わりにタイムラインを出力することもできます。

ハイブに関連するプラグインを実行

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

ハイブの種類は自動的に検出され、関連するプラグインが実行されます。 プラグインセクションの詳細についてはこちら

レジストリハイブの比較

同じ種類のレジストリハイブを比較し、CSVに出力します（-oが指定されない場合は画面に出力されます）。

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

出力例：

[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

トランザクションログを使用したレジストリハイブの復元：

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

復元後、registry-diffでハイブを比較して変更点を確認します。

ライブラリとしての使用

レジストリハイブオブジェクトの初期化

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

ハイブ全体をルートキーから再帰的に反復処理

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

キーを反復処理し、すべてのサブキーとその変更時間を取得：

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

キーの値を取得：

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

プラグインとして使用：

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

特定のハイブに関連するすべてのプラグインを実行

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

検証ケース

検証ケースレポート

すべての新しいプラグインは、1つ以上の基本的な検証ケース（将来拡張可能）を持つ必要があります。例：

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


class NTUserUserAssistValidationCase(ValidationCase):
    # プラグインクラスを定義
    plugin = BAMPlugin
    # テスト用のファイル名を定義。`regipy_tests/data`に存在する必要があります
    test_hive_file_name = "SYSTEM_WIN_10_1709.xz"

    # `expected_entries`を使用して、プラグイン結果からいくつかのサンプルの存在をテスト
    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",
        }
    ]

    # または`exact_expected_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

開発

開発環境のセットアップ

# リポジトリをクローン
git clone https://github.com/mkorman90/regipy.git
cd regipy

# 全ての依存関係を含む開発モードでインストール
pip install -e ".[full,dev]"

# プリコミットフックをインストール
pre-commit install

テストの実行

# 全てのテストを実行
pytest

# 特定のテストファイルを実行
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py

# プラグイン検証を実行
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py

コード品質

# リンターを実行
ruff check .

# フォーマッターを実行
ruff format .

# 型チェッカーを実行
mypy regipy/

ローカルでのGitHub Actionsのテスト

プッシュ前にCIワークフローの変更をローカルでテストするには、actを使用します：

# actのインストール (Fedora)
sudo dnf install act-cli

# actのインストール (macOS)
brew install act

# actのインストール (その他)
# https://nektosact.com/installation/index.html を参照

Dockerが実行されていることを確認し、以下のコマンドを実行します：

# 利用可能なジョブを一覧表示
act -l

# lintジョブを実行
act -j lint

# pushイベントの全てのジョブを実行
act push

# 特定のPythonバージョンでテストジョブを実行
act -j test

# publishワークフローからビルドジョブをテスト（リリースをシミュレート）
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'

注意：一部のジョブはシークレットを必要とする場合があります。以下のように指定できます：

act -j publish --secret PYPI_API_TOKEN=your_token

ライセンス

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

人気

regipy

インストール

Rust加速バックエンド（アルファ版）

CLI

ヘッダーの解析：

ハイブ全体をディスクにダンプ（時間がかかる場合があります）

ハイブに関連するプラグインを実行

レジストリハイブの比較

トランザクションログを使用したレジストリハイブの復元：

ライブラリとしての使用

レジストリハイブオブジェクトの初期化

ハイブ全体をルートキーから再帰的に反復処理

キーを反復処理し、すべてのサブキーとその変更時間を取得：

キーの値を取得：

プラグインとして使用：

特定のハイブに関連するすべてのプラグインを実行

検証ケース

開発

開発環境のセットアップ

テストの実行

コード品質

ローカルでのGitHub Actionsのテスト

ライセンス