mkorman90/regipyRegipy è una libreria Python indipendente dal sistema operativo per l'analisi di hive del registro offline.
# regipy
[](https://securityscorecards.dev/viewer/?uri=github.com/mkorman90/regipy)
> **⚠️ Modifiche incompatibili nella v6.0.0**
>
> La versione 6.0.0 include significative modifiche di modernizzazione:
>
> - **Richiesto Python 3.9+** - Rimosso il supporto per Python 3.6, 3.7 e 3.8
> - **Libreria `attrs` rimossa** - Le data class ora utilizzano il modulo integrato `dataclasses` di Python
> - Se il tuo codice importa classi interne (`Cell`, `VKRecord`, `Value`, `Subkey`) e utilizza funzioni di `attrs` come `attr.asdict()`, passa a `dataclasses.asdict()`
>
> Consulta il [CHANGELOG](https://github.com/mkorman90/regipy/blob/master/CHANGELOG.md) per tutti i dettagli.
Regipy è una libreria Python per l'analisi di hive del registro offline (file Hive con header REGF). regipy ha molte funzionalità:
- Utilizzo come libreria:
- Ricorsione sull'hive del registro, dalla radice o da un percorso specificato, per ottenere tutte le sottochiavi e i valori
- Lettura di sottochiavi e valori specifici
- Applicazione dei log di transazione su un hive del registro
- Strumenti da riga di comando
- Esportazione di un intero hive del registro in json
- Applicazione dei log di transazione su un hive del registro
- Confronto di hive del registro
- Esecuzione di plugin da un robusto sistema di plugin (es: amcache, shimcache, estrazione del nome del computer...)
**Richiede Python 3.9 o superiore.**
## Installazione
L'ultima versione di Regipy può essere installata da pypi:
```bash
pip install regipy[full]
```
NOTA: ``regipy[full]`` installa dipendenze che richiedono strumenti di compilazione e potrebbe richiedere del tempo.
È possibile installare una versione con dipendenze ridotte, omettendo ``[full]``.
Inoltre, è possibile installare dal sorgente clonando il repository ed eseguendo:
```bash
pip install --editable .[full]
```
### Backend accelerato in Rust (alpha)
Un'implementazione opzionale in Rust del parser REGF principale è disponibile come
backend opt-in, pubblicato separatamente su PyPI come
[`regipy-rs`](https://pypi.org/project/regipy-rs/):
```bash
pip install regipy[rust]
```
```python
from regipy.registry_rs import RegistryHive # invece di regipy.registry
reg = RegistryHive("/tmp/NTUSER.dat")
# Stessa API: get_key, iter_values, recurse_subkeys, plugins — tutto
# funziona invariato, inclusi tutti i plugin di regipy.
```
È un sostituto drop-in validato 1:1 rispetto al parser in puro Python su
l'intero corpus di hive di test — ogni percorso di chiave, timestamp, valore e output
dei plugin, notarizzato tramite digest di attraversamento SHA-256 corrispondenti (vedi
`regipy_tests/comparison_test.py` e la sezione *Forensic parity evidence*
di [regipy-rs/BENCHMARKS.md](https://github.com/mkorman90/regipy/blob/master/regipy-rs/BENCHMARKS.md)).
Attraversamento completo con valori (`recurse_subkeys`), migliore di 3 esecuzioni:
| Hive | Chiavi | Python | Rust | Velocità |
| ------ | -----: | -------: | -----: | --------: |
| 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` mostra il perché: nel backend Python, il tempo di attraversamento è dominato dal
parsing della struct `construct` per record e dalla decodifica dei valori; con il backend
Rust, il parser scompare completamente dal profilo e l'unico
costo Python rimanente è la costruzione delle dataclass `Subkey` restituite.
I profili completi, i digest per hive e un disclaimer che documenta le poche
divergenze intenzionali (tipi di eccezione su hive corrotti, comportamento di
protezione dai cicli) sono in [regipy-rs/BENCHMARKS.md](https://github.com/mkorman90/regipy/blob/master/regipy-rs/BENCHMARKS.md);
`python regipy-rs/benchmark.py` rigenera l'intero report.
Il parser in puro Python rimane quello predefinito e non è influenzato quando il backend
Rust non è installato.
## CLI
#### Analizzare l'header
```bash
regipy-parse-header ~/Documents/TestEvidence/Registry/SYSTEM
```
Output di esempio:
```
╒════════════════════════╤══════════╕
│ 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
```
- Durante l'analisi dell'header di un hive, vengono eseguite anche la validazione del checksum e le validazioni delle transazioni
#### Esportare l'intero hive su disco (potrebbe richiedere del tempo)
```bash
regipy-dump ~/Documents/TestEvidence/Registry/NTUSER-CCLEANER.DAT -o /tmp/output.json
```
L'utility regipy-dump può anche produrre una timeline invece di un JSON, aggiungendo il flag `-t`
#### Eseguire i plugin rilevanti sull'Hive
```bash
regipy-plugins-run ~/Documents/TestEvidence/Registry/SYSTEM -o /tmp/plugins_output.json
```
Il tipo di hive verrà rilevato automaticamente e i plugin rilevanti verranno eseguiti.
[**Consulta la sezione dei plugin per maggiori informazioni**](https://github.com/mkorman90/regipy/blob/master/docs/PLUGINS.md)
#### Confrontare hive del registro
Confronta hive del registro dello stesso tipo e produce un CSV (se `-o` non è specificato, l'output verrà stampato a schermo)
```bash
regipy-diff NTUSER.dat NTUSER_modified.dat -o /tmp/diff.csv
```
Output di esempio:
```
[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
```
## Recuperare un hive del registro, utilizzando i log di transazione
```bash
regipy-process-transaction-logs NTUSER.DAT -p ntuser.dat.log1 -s ntuser.dat.log2 -o recovered_NTUSER.dat
```
Dopo il recupero, confronta gli hive con registry-diff per vedere cosa è cambiato
## Utilizzo come libreria
#### Inizializzare l'oggetto hive del registro
```python
from regipy.registry import RegistryHive
reg = RegistryHive("/Users/martinkorman/Documents/TestEvidence/Registry/Vibranium-NTUSER.DAT")
```
#### Iterare ricorsivamente sull'intero hive, dalla chiave radice
```python
for entry in reg.recurse_subkeys(as_json=True):
print(entry)
```
#### Iterare su una chiave e ottenere tutte le sottochiavi e il loro tempo di modifica
```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
```
#### Ottenere i valori di una chiave
```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},
]
```
#### Utilizzo come plugin
```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,
}
],
}
}
```
#### Eseguire tutti i plugin rilevanti per uno specifico hive
```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",
}
],
}
```
## Casi di validazione
[Report dei casi di validazione](https://github.com/mkorman90/regipy/blob/master/regipy_tests/validation/plugin_validation.md)
Tutti i nuovi plugin dovrebbero avere uno o più casi di validazione di base (che potranno essere ampliati in futuro), ad esempio:
```python
from regipy.plugins.system.bam import BAMPlugin
from regipy_tests.validation.validation import ValidationCase
class NTUserUserAssistValidationCase(ValidationCase):
# definisci la tua classe plugin
plugin = BAMPlugin
# definisci il nome del file di test, che deve essere presente in `regipy_tests/data`
test_hive_file_name = "SYSTEM_WIN_10_1709.xz"
# Usa `expected_entries` per verificare la presenza di alcuni campioni dai risultati del plugin
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",
}
]
# OPPURE usa `exact_expected_result` per verificare un risultato esatto:
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
```
## Sviluppo
### Configurazione per lo sviluppo
```bash
# Clona il repository
git clone https://github.com/mkorman90/regipy.git
cd regipy
# Installa in modalità sviluppo con tutte le dipendenze
pip install -e ".[full,dev]"
# Installa gli hook pre-commit
pre-commit install
```
### Esecuzione dei test
```bash
# Esegui tutti i test
pytest
# Esegui file di test specifici
pytest regipy_tests/tests.py
pytest regipy_tests/cli_tests.py
# Esegui la validazione dei plugin
PYTHONPATH=. python regipy_tests/validation/plugin_validation.py
```
### Qualità del codice
```bash
# Esegui il linter
ruff check .
# Esegui il formatter
ruff format .
# Esegui il type checker
mypy regipy/
```
### Testare GitHub Actions in locale
Per testare le modifiche ai workflow CI in locale prima del push, usa [act](https://github.com/nektos/act):
```bash
# Installa act (Fedora)
sudo dnf install act-cli
# Installa act (macOS)
brew install act
# Installa act (altro)
# Vedi https://nektosact.com/installation/index.html
```
Assicurati che Docker sia in esecuzione, poi:
```bash
# Elenca i job disponibili
act -l
# Esegui il job lint
act -j lint
# Esegui tutti i job per un evento push
act push
# Esegui il job test con una versione specifica di Python
act -j test
# Testa il job build dal workflow publish (simula una release)
act release -j build --eventpath /dev/stdin <<< '{"action": "published"}'
```
Nota: alcuni job potrebbero richiedere dei secret. Puoi fornirli con:
```bash
act -j publish --secret PYPI_API_TOKEN=your_token
```
## Licenza
MIT