mkorman90/regipyRegipy는 오프라인 레지스트리 하이브를 파싱하기 위한 OS 독립적인 파이썬 라이브러리입니다.
# regipy
[](https://securityscorecards.dev/viewer/?uri=github.com/mkorman90/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](https://github.com/mkorman90/regipy/blob/master/CHANGELOG.md)를 참조하세요.
Regipy는 오프라인 레지스트리 하이브(REGF 헤더가 있는 Hive 파일)를 파싱하기 위한 Python 라이브러리입니다. regipy는 많은 기능을 제공합니다:
- 라이브러리로 사용:
- 루트 또는 지정된 경로에서 레지스트리 하이브를 재귀적으로 탐색하고 모든 하위 키와 값을 가져옵니다
- 특정 하위 키와 값을 읽습니다
- 레지스트리 하이브에 트랜잭션 로그를 적용합니다
- 명령줄 도구
- 전체 레지스트리 하이브를 json으로 덤프합니다
- 레지스트리 하이브에 트랜잭션 로그를 적용합니다
- 레지스트리 하이브를 비교합니다
- 강력한 플러그인 시스템에서 플러그인을 실행합니다 (예: amcache, shimcache, 컴퓨터 이름 추출...)
**Python 3.9 이상이 필요합니다.**
## 설치
Regipy 최신 버전은 pypi에서 설치할 수 있습니다:
```bash
pip install regipy[full]
```
참고: ``regipy[full]``은 컴파일 도구가 필요한 의존성을 설치하므로 시간이 다소 걸릴 수 있습니다.
``[full]``을 생략하여 완화된 의존성으로 버전을 설치할 수도 있습니다.
또한 저장소를 복제한 후 다음을 실행하여 소스에서 설치할 수도 있습니다:
```bash
pip install --editable .[full]
```
### Rust 가속 백엔드 (알파)
핵심 REGF 파서의 선택적 Rust 구현이 옵트인 백엔드로 제공되며,
PyPI에 [`regipy-rs`](https://pypi.org/project/regipy-rs/)로 별도 게시됩니다:
```bash
pip install regipy[rust]
```
```python
from regipy.registry_rs import RegistryHive # instead of regipy.registry
reg = RegistryHive("/tmp/NTUSER.dat")
# Same API: get_key, iter_values, recurse_subkeys, plugins — everything
# works unchanged, including all regipy plugins.
```
이것은 전체 테스트 하이브 코퍼스에 걸쳐 순수 Python 파서와 1:1로 검증된 드롭인 대체품입니다 — 모든 키 경로, 타임스탬프, 값 및 플러그인 출력이 일치하는 SHA-256 순회 다이제스트로 공증됩니다 (`regipy_tests/comparison_test.py` 및 [regipy-rs/BENCHMARKS.md](https://github.com/mkorman90/regipy/blob/master/regipy-rs/BENCHMARKS.md)의 *Forensic parity evidence* 섹션 참조).
값을 포함한 전체 순회(`recurse_subkeys`), 3회 실행 중 최고 기록:
| Hive | Keys | Python | Rust | Speedup |
| ------ | -----: | -------: | -----: | --------: |
| 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](https://github.com/mkorman90/regipy/blob/master/regipy-rs/BENCHMARKS.md)에 있습니다;
`python regipy-rs/benchmark.py`는 전체 보고서를 재생성합니다.
순수 Python 파서는 여전히 기본값이며 Rust 백엔드가 설치되지 않은 경우 영향을 받지 않습니다.
## CLI
#### 헤더 파싱
```bash
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
```
- 하이브의 헤더를 파싱할 때 체크섬 검증과 트랜잭션 검증도 수행됩니다
#### 전체 하이브를 디스크에 덤프 (시간이 다소 걸릴 수 있음)
```bash
regipy-dump ~/Documents/TestEvidence/Registry/NTUSER-CCLEANER.DAT -o /tmp/output.json
```
regipy-dump 유틸리티는 `-t` 플래그를 추가하여 JSON 대신 타임라인을 출력할 수도 있습니다
#### Hive에서 관련 플러그인 실행
```bash
regipy-plugins-run ~/Documents/TestEvidence/Registry/SYSTEM -o /tmp/plugins_output.json
```
하이브 유형이 자동으로 감지되고 관련 플러그인이 실행됩니다.
[**자세한 내용은 플러그인 섹션을 참조하세요**](https://github.com/mkorman90/regipy/blob/master/docs/PLUGINS.md)
#### 레지스트리 하이브 비교
동일한 유형의 레지스트리 하이브를 비교하고 CSV로 출력합니다 (`-o`가 지정되지 않은 경우 출력이 화면에 인쇄됩니다)
```bash
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
```
## 트랜잭션 로그를 사용하여 레지스트리 하이브 복구
```bash
regipy-process-transaction-logs NTUSER.DAT -p ntuser.dat.log1 -s ntuser.dat.log2 -o recovered_NTUSER.dat
```
복구 후 registry-diff로 하이브를 비교하여 변경된 내용을 확인하세요
## 라이브러리로 사용
#### 레지스트리 하이브 객체 초기화
```python
from regipy.registry import RegistryHive
reg = RegistryHive("/Users/martinkorman/Documents/TestEvidence/Registry/Vibranium-NTUSER.DAT")
```
#### 루트 키에서 전체 하이브를 재귀적으로 순회
```python
for entry in reg.recurse_subkeys(as_json=True):
print(entry)
```
#### 키를 순회하고 모든 하위 키와 수정 시간 가져오기
```python
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
```
#### 키의 값 가져오기
```python
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},
]
```
#### 플러그인으로 사용
```python
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,
}
],
}
}
```
#### 특정 하이브에 대한 모든 관련 플러그인 실행
```python
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",
}
],
}
```
## 검증 사례
[검증 사례 보고서](https://github.com/mkorman90/regipy/blob/master/regipy_tests/validation/plugin_validation.md)
모든 새 플러그인은 하나 이상의 기본 검증 사례를 가져야 합니다 (향후 확장 가능). 예를 들어:
```python
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
```
## 개발
### 개발 환경 설정
```bash
# Clone the repository
git clone https://github.com/mkorman90/regipy.git
cd regipy
# Install in development mode with all dependencies
pip install -e ".[full,dev]"
# Install pre-commit hooks
pre-commit install
```
### 테스트 실행
```bash
# Run all tests
pytest
# Run specific test files
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py
# Run plugin validation
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py
```
### 코드 품질
```bash
# Run linter
ruff check .
# Run formatter
ruff format .
# Run type checker
mypy regipy/
```
### GitHub Actions 로컬 테스트
푸시하기 전에 CI 워크플로 변경 사항을 로컬에서 테스트하려면 [act](https://github.com/nektos/act)를 사용하세요:
```bash
# Install act (Fedora)
sudo dnf install act-cli
# Install act (macOS)
brew install act
# Install act (other)
# See https://nektosact.com/installation/index.html
```
Docker가 실행 중인지 확인한 후:
```bash
# List available jobs
act -l
# Run the lint job
act -j lint
# Run all jobs for a push event
act push
# Run the test job with a specific Python version
act -j test
# Test the build job from publish workflow (simulates a release)
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'
```
참고: 일부 작업은 시크릿이 필요할 수 있습니다. 다음과 같이 제공할 수 있습니다:
```bash
act -j publish --secret PYPI_API_TOKEN=your_token
```
## 라이선스
MIT