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 — это библиотека Python для разбора офлайн-кустов реестра (файлов кустов с заголовком REGF). 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, plugins — всё
# работает без изменений, включая все плагины regipy.

Это замена «drop-in», проверенная 1:1 против чисто-Python парсера на всём корпусе тестовых кустов — каждый путь ключа, временная метка, значение и вывод плагина, заверенные совпадающими SHA-256 дайджестами обхода (см. regipy_tests/comparison_test.py и раздел Forensic parity evidence в regipy-rs/BENCHMARKS.md).

Полный обход со значениями (recurse_subkeys), лучший из 3 запусков:

Куст	Ключей	Python	Rust	Ускорение
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

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 также может выводить временную шкалу вместо JSON, добавив флаг -t

Запуск соответствующих плагинов на кусте

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

regipy v6.3.0