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 가속 백엔드(알파)

선택적인 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 플러그인을 그대로 사용할 수 있습니다.

이는 순수 Python 파서와 전체 테스트 하이브 코퍼스에 대해 1:1로 검증된 드롭인(drop-in) 대체품입니다. 모든 키 경로, 타임스탬프, 값 및 플러그인 출력이 일치하며, 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'
	}]
}

검증 사례

검증 사례 보고서

모든 새 플러그인에는 하나 이상의 기본 검증 사례(향후 확장 가능)가 있어야 합니다. 예를 들어:

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

개발

개발 환경 설정

# 저장소 클론
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

코드 품질

# 린터 실행
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 버전으로 test 작업 실행
act -j test

# publish 워크플로에서 build 작업 테스트 (릴리스 시뮬레이션)
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 로컬 테스트

라이선스