regipy

# regipy

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/mkorman90/regipy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/mkorman90/regipy)

> **⚠️ تغييرات جذرية في الإصدار 6.0.0**
>
> يتضمن الإصدار 6.0.0 تغييرات تحديثية كبيرة:
>
> - **يتطلب Python 3.9+** - تم إسقاط دعم Python 3.6 و3.7 و3.8
> - **تمت إزالة مكتبة `attrs`** - تستخدم فئات البيانات الآن وحدة `dataclasses` المدمجة في Python
> - إذا كان الكود الخاص بك يستورد فئات داخلية (`Cell`، `VKRecord`، `Value`، `Subkey`) ويستخدم دوال `attrs` مثل `attr.asdict()`، فقم بالتبديل إلى `dataclasses.asdict()`
>
> راجع [CHANGELOG](https://github.com/mkorman90/regipy/blob/master/CHANGELOG.md) للحصول على التفاصيل الكاملة.

Regipy هي مكتبة Python لتحليل خلايا التسجيل (Registry Hives) غير المتصلة بالإنترنت (ملفات Hive التي تحتوي على ترويسة REGF). تمتلك regipy العديد من الإمكانيات:
- الاستخدام كمكتبة:
  - التنقل التكراري عبر خلية التسجيل، من الجذر أو من مسار معين والحصول على جميع المفاتيح الفرعية والقيم
  - قراءة مفاتيح فرعية وقيم محددة
  - تطبيق سجلات المعاملات (Transaction Logs) على خلية تسجيل
- أدوات سطر الأوامر
  - تفريغ خلية تسجيل كاملة إلى json
  - تطبيق سجلات المعاملات على خلية تسجيل
  - مقارنة خلايا التسجيل
  - تنفيذ الإضافات (Plugins) من نظام إضافات قوي (مثل: amcache، shimcache، استخراج اسم الكمبيوتر...)

**يتطلب Python 3.9 أو أعلى.**

## التثبيت

يمكن تثبيت أحدث إصدار من Regipy من pypi:

```bash
pip install regipy[full]
```

ملاحظة: يقوم ``regipy[full]`` بتثبيت التبعيات التي تتطلب أدوات الترجمة (Compilation Tools) وقد يستغرق بعض الوقت.
من الممكن تثبيت إصدار بتبعيات مخففة، عن طريق حذف ``[full]``.

أيضاً، من الممكن التثبيت من المصدر عن طريق استنساخ المستودع وتنفيذ:

```bash
pip install --editable .[full]
```

### الواجهة الخلفية المعجّلة بـ Rust (ألفا)

يتوفر تطبيق Rust اختياري لمحلل REGF الأساسي كواجهة خلفية اختيارية،
تُنشر بشكل منفصل على 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.
```

إنه بديل مباشر تم التحقق منه 1:1 مقابل المحلل المكتوب بلغة Python الخالصة عبر
مجموعة اختبارات الخلايا الكاملة — كل مسار مفتاح، وطابع زمني، وقيمة، ومخرجات
إضافة، موثّق بمطابقة ملخصات التنقل SHA-256 (راجع
`regipy_tests/comparison_test.py` وقسم *Forensic parity evidence*
في [regipy-rs/BENCHMARKS.md](https://github.com/mkorman90/regipy/blob/master/regipy-rs/BENCHMARKS.md)).

التنقل الكامل مع القيم (`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
```
- عند تحليل ترويسة خلية، يتم أيضاً إجراء التحقق من checksum والتحقق من المعاملات

#### تفريغ الخلية كاملة إلى القرص (قد يستغرق هذا بعض الوقت)

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

يمكن لأداة regipy-dump أيضاً إخراج خط زمني بدلاً من JSON، عن طريق إضافة العلامة `-t`

#### تشغيل الإضافات ذات الصلة على الخلية

```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