regipy

⚠️ v6.0.0 版本的破坏性变更

版本 6.0.0 包含了重要的现代化更改：

需要 Python 3.9+ - 放弃了对 Python 3.6、3.7 和 3.8 的支持

移除了 attrs 库 - 数据类现在使用 Python 内置的 dataclasses 模块

如果你的代码导入了内部类（Cell, VKRecord, Value, Subkey）并使用了 attrs 的函数如 attr.asdict()，请切换到 dataclasses.asdict()

详见 CHANGELOG。

Regipy 是一个用于解析离线注册表配置单元（具有 REGF 头的配置单元文件）的 Python 库。regipy 具有许多功能：

作为库使用：
- 从根目录或指定路径递归遍历注册表配置单元，获取所有子键和值
- 读取特定的子键和值
- 在注册表配置单元上应用事务日志
命令行工具
- 将整个注册表配置单元转储为 JSON
- 在注册表配置单元上应用事务日志
- 比较注册表配置单元
- 从强大的插件系统执行插件（例如：amcache、shimcache、提取计算机名...）

需要 Python 3.9 或更高版本。

安装

可以从 pypi 安装最新版本的 regipy：

pip install regipy[full]

注意：regipy[full] 安装的依赖需要编译工具，可能需要一些时间。也可以通过省略 [full] 来安装依赖较宽松的版本。

另外，可以通过克隆仓库并从源码安装：

pip install --editable .[full]

Rust 加速后端（alpha）

一个可选的 Rust 实现的核心 REGF 解析器可以作为 opt-in 后端使用，并作为单独的包发布到 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, plugins — 一切
# 正常工作，包括所有 regipy 插件。

这是一个即插即用的替代品，已在整个测试配置单元集合上以 1:1 的比例与纯 Python 解析器进行了验证 — 每个键路径、时间戳、值和插件输出，都通过匹配的 SHA-256 遍历摘要进行了公证（参见 regipy_tests/comparison_test.py 和 regipy-rs/BENCHMARKS.md 中的 Forensic parity evidence 部分）。

完整遍历（包括值，recurse_subkeys），取三次运行的最佳结果：

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: 配置单元不干净！你应该应用事务日志

解析配置单元头部时，还会进行校验和验证和事务验证

将整个配置单元转储到磁盘（可能需要一些时间）

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: 正在比较 NTUSER.DAT 与 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 处差异

使用事务日志恢复注册表配置单元：

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

验证用例

验证用例报告

所有新插件应具有一个或多个基本验证用例（将来可以扩展），例如：

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 钩子
pre-commit install

运行测试

# 运行所有测试
pytest

# 运行特定测试文件
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py

# 运行插件验证
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py

代码质量

# 运行 linter
ruff check .

# 运行格式化工具
ruff format .

# 运行类型检查器
mypy regipy/

本地测试 GitHub Actions

在推送前，使用 act 本地测试 CI 工作流更改：

# 安装 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

# 测试发布工作流中的 build 作业（模拟发布版本）
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'

注意：某些作业可能需要 secrets。可以通过以下方式提供：

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 加速后端（alpha）

CLI

解析头部：

将整个配置单元转储到磁盘（可能需要一些时间）

在配置单元上运行相关插件

比较注册表配置单元

使用事务日志恢复注册表配置单元：

作为库使用

初始化注册表配置单元对象

递归遍历整个配置单元，从根键开始

遍历一个键并获取所有子键及其修改时间：

获取一个键的值：

作为插件使用：

为特定配置单元运行所有相关插件

验证用例

开发

设置开发环境

运行测试

代码质量

本地测试 GitHub Actions

许可证