REPLAY["DIRTY-HIVE REPLAY<br/>transaction logs applied to a working copy"]
PARSERS["ARTIFACT PARSERS<br/>18 artifact types · live and offline"]

OUT["LIVING REPORT<br/>CSV · JSON · HTML"]

I1 --> PARSERS
I2 --> PARSERS
I3 --> PARSERS

PARSERS -- "every registry hive,<br/>evidence never written to" --> REPLAY
REPLAY -- "the state Windows<br/>had not finished writing" --> PARSERS

PARSERS -- "parsed artifacts" --> CASE
I4 -- "verbatim copy or<br/>converted to feather" --> CASE

CASE -- "read-only" --> TL
CASE -- "read-only" --> UB
CASE -- "read-only" --> CE
CASE -- "read-only" --> DL
CE --> RES
DL --> INTEL

CASE -- "read-only queries" --> EYE
RES -. "queried on demand" .-> EYE
EYE <== "verdict · narrative · evidence" ==> NM

EYE -- "audited by" --> COMP

EYE -- "report_* tools" --> OUT

class S1,S2,S3,S4 src
class I1,I2,I3,I4,PARSERS ing
class CASE,RES,INTEL store
class TL,UB,CE,DL ana
class EYE,NM,COMP ai
class OUT out

linkStyle default stroke-width:2px

*Sorgente prove → Ingest → Database del caso → Analisi → Livello AI → Report*


**Come leggerlo:**

| Fase | Cosa conta |
|---|---|
| ① → ② | **Quattro porte indipendenti verso un caso.** Non serve mai il collector di Crow-Eye — una cartella da Velociraptor, KAPE o un pacchetto EDR passa attraverso l'Offline Importer, e CSV/JSON/SQLite di terze parti passano da Import Evidence. |
| ② → ③ | Tutto converge in un unico posto: **i database del caso**. Gli artefatti analizzati finiscono in `Target_Artifacts/`; le prove importate da terze parti finiscono in `Imported_Evidence/` e vengono rilevate automaticamente. |
| ③ → ④ | **I tre percorsi di analisi sono indipendenti tra loro.** La Timeline e la UBA leggono direttamente i database del caso — nessuna delle due richiede un'esecuzione di correlazione. Il Correlation Engine è un livello *aggiuntivo*, non un prerequisito. |
| ③ → ④ | **Il Dynamic Linking affianca Timeline e UBA** — un quarto lettore indipendente dei database del caso (non ha nulla a che fare con la visualizzazione della Timeline). Raccoglie le mappature di identità (SID → nome utente, MAC → rete, hash/GUID → app) in un `Crow_Intelligence.db` per caso, poi sovrappone quel contesto **inline nelle tabelle dei dati degli artefatti** tramite `ATTACH` + `LEFT JOIN` non distruttivi. Cambia il modo in cui i record *si leggono*, mai le prove. |
| ④ → ⑤ | The Eye interroga direttamente i database del caso e può recuperare i risultati della correlazione **on demand**. Non tocca mai le prove stesse — emette chiamate di strumenti che Crow-Eye esegue e registra. |
| ⑤ → Report | Il **Living Report è costruito solo da The Eye**, tramite i suoi strumenti `report_*`. La Timeline e la UBA sono superfici di analisi — non scrivono nel report. I risultati a livello di caso possono comunque essere esportati separatamente tramite [Search & Export](#-search--export). |
| ⑤ ↔ | La **Narrative Map è bidirezionale**: The Eye ci scrive, tu ci scrivi, e i suoi contenuti vengono iniettati nel prompt di The Eye a ogni turno. È la memoria, e puoi comandarla. |
| ⑤ ⟳ | La **pagina Compliance controlla The Eye.** Ogni chiamata di strumento di The Eye è ancorata alla catena di hash **EvidenceSeal**; la pagina mostra lo stato **GEP** live per regola (10 principi) verificato da quella catena e da `EYE_Logs/`, esportabile come `audit_trail.json`. |

**Fasi indipendenti.** La Timeline e la UBA leggono **direttamente** i database degli artefatti del caso — nessuna delle due richiede un'esecuzione di correlazione, e la Timeline non dipende dal Correlation Engine (applica un proprio raggruppamento temporale leggero). La correlazione è un livello di analisi aggiuntivo che The Eye può interrogare.

**Sola lettura per progettazione.** L'analisi scrive nel database del caso; ogni fase a valle (UBA, Timeline, visualizzatori di correlazione, The Eye) apre quei database **in sola lettura**. Le prove originali non vengono mai modificate — il [Dynamic Linking](#-analysis-modes) legge i database del caso per costruire un `Crow_Intelligence.db` per caso con le mappature di identità e arricchisce le tabelle dei dati degli artefatti inline tramite query `ATTACH` + `LEFT JOIN` non distruttive, invece di riscrivere le righe.

**Governato per progettazione.** Ogni azione di The Eye è ancorata alla catena di hash **EvidenceSeal** a prova di manomissione, e la pagina **Compliance** verifica continuamente The Eye rispetto al [Ghassan Elsman Protocol (GEP)](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md) — stato live per regola, esportabile in `EYE_Logs/audit_trail.json`.

## 📥 Download e installazione

> **Consigliato:** ottieni la build Windows impacchettata (**installer MSI / EXE**) dal sito ufficiale — nessuna configurazione Python, funziona subito.

### ▶️ [Scarica Crow-Eye per Windows → crow-eye.com/download](https://crow-eye.com/download)

La **build MSI/EXE installata è il modo consigliato per eseguire Crow-Eye**, ed è la nostra **massima priorità per gli aggiornamenti**:

- 🛡️ **Correzioni più rapide.** Quando viene trovato un problema o segnalato un bug, pubblichiamo un EXE aggiornato **il prima possibile** — la build impacchettata è dove arrivano prima le correzioni.
- 🔄 **Aggiornamento automatico integrato.** Nell'app installata, apri **Settings → Updates** per **verificare gli aggiornamenti e installarli automaticamente** — nessuna reinstallazione manuale.
- 📦 **Zero configurazione.** Nessuna installazione di Python, Node o dipendenze richiesta.

> Preferisci eseguire dal sorgente? Vedi **[Quick Start](#-quick-start)** qui sotto. La build dal sorgente è pensata per i contributori e **non include l'auto-aggiornamento** — usa MSI/EXE per gli aggiornamenti automatici.

## 🚀 Avvio rapido

### Opzione A — Build installata (consigliata)
Scarica l'**MSI/EXE** da [crow-eye.com/download](https://crow-eye.com/download), installa e avvia **Crow-Eye** come Amministratore. Crea un caso e inizia ad analizzare.

### Opzione B — Esegui dal sorgente (sviluppatori)

> Per contributori e utenti avanzati. Questo percorso **non include l'auto-aggiornamento** — usa MSI/EXE per gli aggiornamenti automatici.

**Requisiti** (installati automaticamente al primo avvio):
- Python 3.12.4
- **Node.js & npm** — richiesti per la **Timeline Visualization**
- Pacchetti chiave: PyQt5, python-registry, pywin32, pandas, streamlit, altair, olefile, windowsprefetch, sqlite3, colorama, setuptools

**Hardware consigliato**

| | Minimo | Consigliato per casi di grandi dimensioni |
|---|---|---|
| **RAM** | 8 GB | 16 GB+ (set MFT/USN con milioni di record) |
| **Disco** | 5 GB liberi | Spazio libero ≥ 2× la dimensione delle prove da analizzare |
| **CPU** | 4 core | 8+ core |
| **OS** | Windows 10/11 (completo) · Linux (analisi offline e di immagini) | — |

> La correlazione trasmette in memoria costante per dataset molto grandi, quindi la RAM raramente è il limite rigido — di solito lo sono la velocità del disco e lo spazio libero.

**Avvio** (esegui come Amministratore così Crow-Eye può accedere agli artefatti di sistema):```bash
python "Crow Eye.py"

**Formati di importazione supportati:** CSV (qualsiasi file con intestazione), JSON (piatto o annidato) e SQLite (importazione diretta). Mappatura automatica delle colonne, rilevamento dei tipi di dati, normalizzazione dei timestamp in ISO, validazione e indici ottimizzati.```
prefetch.db (Feather)
├── feather_metadata (artifact type, source, record count)
├── prefetch_data (executable_name, path, last_executed, hash)
└── Indexes (timestamp, name, path)

#### 3. ⚙️ Motori (Strategie di Correlazione)

**Scopo**: Eseguire la logica di correlazione per trovare relazioni tra gli artefatti. I collegamenti strutturali vengono **prima**; un punteggio ponderato a livelli viene sovrapposto come *interpretazione/classificazione*, non come base per una corrispondenza.

**Motore di Scansione a Finestra Temporale** — ideale per analisi basate sul tempo e correlazione temporale sistematica. Scansiona il tempo a intervalli fissi, raccoglie i record da tutte le piume per finestra, applica il matching dei campi semantici + punteggio ponderato e previene i duplicati tramite il tracciamento MatchSet. **O(N log N)** (query indicizzate su timestamp); elaborazione batch (~2.567 finestre/secondo).

**Motore di Correlazione Basato su Identità** — ideale per set di dati di grandi dimensioni (>1.000 record) e tracciamento delle identità. Estrae e normalizza le identità, raggruppa i record per identità, costruisce ancore temporali all'interno di ciascun cluster, classifica le prove come primarie/secondarie/supportive e trasmette in streaming per set molto grandi (>5.000 ancore) a memoria costante. **O(N log N)**; 40+ modelli di campi di identità per tipo.

**Selezione del motore:** utilizzare il motore a finestra temporale per l'analisi basata sul tempo e il motore basato su identità per il tracciamento delle identità — entrambi sono pronti per la produzione e ottimizzati per set di dati di grandi dimensioni con query indicizzate.

#### 4. 🔄 Pipeline (Orchestrazione dei Flussi di Lavoro)

**Scopo**: Automatizzare flussi di lavoro di analisi completi, dalla creazione delle piume alla generazione dei risultati. Una pipeline legge la propria configurazione (tipo di motore, ali, piume), istanzia il motore corretto tramite EngineSelector, esegue ciascuna ala, aggrega le corrispondenze, salva i risultati (DB + JSON) e li visualizza nella GUI con filtri e visualizzazione.```json
{
  "pipeline_name": "Investigation Pipeline",
  "engine_type": "identity_based",
  "wings": [{"wing_id": "execution-proof"}, {"wing_id": "file-access"}],
  "feathers": [
    {"feather_id": "prefetch", "database_path": "data/prefetch.db"},
    {"feather_id": "srum", "database_path": "data/srum.db"},
    {"feather_id": "eventlogs", "database_path": "data/eventlogs.db"}
  ],
  "filters": {
    "time_period_start": "2024-01-01T00:00:00",
    "time_period_end": "2024-12-31T23:59:59"
  }
}

### Esempio di caso d'uso: ricerca della prova di esecuzione

**Scenario**: dimostrare che `malware.exe` è stato eseguito su un sistema.```json
{
  "wing_id": "malware-execution",
  "correlation_rules": { "time_window_minutes": 5, "minimum_matches": 2 },
  "feathers": ["prefetch", "shimcache", "amcache"]
}

Identity: malware.exe
  Anchor 1 (2024-01-15 10:30:00):
    ✓ Prefetch: malware.exe executed at 10:30:00
    ✓ ShimCache: malware.exe modified at 10:30:15
    ✓ AmCache:  malware.exe installed at 10:29:45

  Conclusion: Execution proven with 3 corroborating artifacts
```
### Benchmark delle Prestazioni

| Record | Motore a Finestra Temporale | Motore Basato su Identità |
|---|---|---|
| 1.000 | 0,5s | 2s |
| 10.000 | 5s | 15s |
| 100.000 | 50s | 2,5 min (streaming) |
| 1.000.000 | — | 25 min (streaming) |

### Per Iniziare con il Motore di Correlazione

1. **Avvio**: `python -m correlation_engine.main`
2. **Crea le Feather**: importa i tuoi artefatti forensi (Prefetch, ShimCache, …).
3. **Crea le Wings**: definisci le regole di correlazione per la tua indagine.
4. **Crea una Pipeline**: configura quali wings e feathers utilizzare.
5. **Esecuzione**: esegui la pipeline e visualizza i risultati correlati.
6. **Analisi**: usa il Visualizzatore dei Risultati per esplorare le relazioni temporali.

### 📚 Documentazione del Motore di Correlazione

- **[Panoramica del Motore di Correlazione](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — panoramica del sistema con diagrammi dell'architettura
- **[Documentazione del Motore](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md)** — architettura a doppio motore, selezione del motore, ottimizzazione delle prestazioni
- **[Architettura](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/ARCHITECTURE.md)** — integrazione dei componenti e flusso dei dati
- **[Documentazione delle Feather](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/feather/FEATHER_DOCUMENTATION.md)** — il sistema di normalizzazione dei dati
- **[Documentazione delle Wings](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/wings/WINGS_DOCUMENTATION.md)** — regole di correlazione
- **[Documentazione della Pipeline](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/pipeline/PIPELINE_DOCUMENTATION.md)** — orchestrazione del flusso di lavoro
- **[Aggiungere un Artefatto](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/ADDING_AN_ARTIFACT.md)** — il flusso di lavoro per collegare un nuovo parser al motore
- **[Registro dei Campi Standard](https://github.com/ghassan-elsman/crow-eye/blob/main/config/standard_fields)** — sinonimi canonici dei nomi di colonna caricati da entrambi i motori e dall'Eye
- **[Guida al Contributo](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)** — come contribuire al motore
- Collegamenti rapidi: [Selezione del Motore](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#engine-selection-guide) · [Risoluzione dei Problemi](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#troubleshooting) · [Ottimizzazione delle Prestazioni](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#performance-and-optimization)

## 👁️ Eye — L'Assistente AI Forense

> **Un potente assistente, non un sostituto.** Eye automatizza e *verifica* le ipotesi di un investigatore — non prende mai la decisione al posto tuo.

**Eye** è l'assistente AI forense integrato di Crow-Eye: un investigatore forense esperto supportato da una vera knowledge base di artefatti Windows. Ti offre un'interfaccia in linguaggio naturale per interrogare, correlare e documentare tutto in un caso — Prefetch, MFT, Registry, Event Logs, AmCache, ShimCache, SRUM e altro — mantenendo al contempo una registrazione verificabile e a prova di manomissione di esattamente ciò che ha fatto. Eye può essere eseguito interamente sulla tua hardware (incluso **completamente air-gapped**), in linea con la posizione sulla privacy di Crow-Eye di **"0 ms di dati inviati fuori dal dispositivo"**. Architettura completa: [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

| Capacità | Cosa significa per te |
|---|---|
| **Indagine in linguaggio naturale** | Chiedi in un inglese semplice; Eye scrive l'SQL e cerca per te. |
| **Integrazione multi-sorgente** | Accesso unificato a tutti gli artefatti analizzati nel caso. |
| **Analisi potenziata con RAG** | Eye recupera conoscenze forensi specifiche per l'artefatto prima di rispondere. |
| **Spazio di Lavoro del Report Vivente** | Risultati, tabelle, grafici e timeline vengono documentati in tempo reale. |
| **Human-in-the-loop** | Le azioni critiche (es. esportazione del report) richiedono la tua approvazione esplicita. |
| **Catena di custodia** | Prova crittografica di esattamente ciò che il modello ha analizzato. |

Eye trasforma domande conversazionali ("mostrami cosa è stato eseguito da `C:\Temp` dopo le 22:00") in vero lavoro forense: pianifica un approccio, recupera la conoscenza rilevante sugli artefatti, esegue SQL e ricerche cross-artefatto sui database del caso e sintetizza una risposta validata. Ogni risposta viene prodotta **in due posti contemporaneamente** — una risposta in chat per te e un blocco strutturato scritto in uno **Spazio di Lavoro del Report Vivente**, così il dossier si costruisce da solo mentre l'indagine procede.

### Il Protocollo Ghassan Elsman (GEP)

Tutto ciò che Eye fa è ancorato al **Protocollo Ghassan Elsman (GEP)** — uno standard **indipendente dal fornitore e dallo strumento** su *come qualsiasi IA dovrebbe essere utilizzata nella digital forensics*. Sono **10 principi** che un sistema conforme deve rispettare affinché i risultati assistiti dall'IA rimangano **veritieri, tracciabili rispetto ai record di origine e supportati da una catena verificabile e a prova di manomissione**, con l'investigatore umano al controllo:

| # | Principio | In una riga |
|---|---|---|
| **GEP-1** | Primato delle Prove | Le conclusioni derivano solo dagli artefatti effettivamente esaminati. |
| **GEP-2** | Tracciabilità | Ogni fatto è collegato a uno specifico record di origine. |
| **GEP-3** | Specificità e Cronologia | Timestamp UTC esatti, identificatori e percorsi, ordinati nel tempo. |
| **GEP-4** | Corroborazione Incrociata | Basarsi su più fonti; segnalare accordo, silenzio e conflitto. |
| **GEP-5** | Verifica delle Premesse | Trattare le affermazioni umane come ipotesi da provare o confutare. |
| **GEP-6** | Completezza | Non eliminare o troncare mai silenziosamente le prove. |
| **GEP-7** | Integrità e Non-Ripudio | Non modificare mai le prove; registrare ciò che è stato visto e fatto, in modo a prova di manomissione. |
| **GEP-8** | Trasparenza e Spiegabilità | Il ragionamento, gli strumenti utilizzati e i dati visti sono visibili e verificabili. |
| **GEP-9** | Autorità Umana | L'investigatore decide; le azioni durevoli sono attribuibili. |
| **GEP-10** | Difendibilità | L'output è obiettivo, preciso e strutturato per una revisione indipendente. |

L'Eye di Crow-Eye è l'**implementazione di riferimento** del GEP; i comportamenti nel prodotto che lo sostengono sono le **Regole Operative**. 📜 Leggi lo standard: [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

### Modalità di Distribuzione

Eye si adatta al tuo modello di minaccia attraverso tre modalità di distribuzione:

| Modalità | Ideale per | Backend |
|---|---|---|
| ☁️ **Modelli IA Cloud** | Analisi profonde e complesse con potenza di calcolo massima | OpenAI, Anthropic (Claude), Google Gemini |
| 🔒 **Server IA Offline** (air-gapped) | Indagini on-premise a esposizione zero | Ollama, LM Studio |
| ⚡ **Agenti Terminale CLI** | Riutilizzare un agente terminale IA che già possiedi come modello | Claude Code, Gemini CLI, ChatGPT CLI, llama.cpp, … |

In **modalità agente CLI**, Crow-Eye guida un **agente terminale/riga di comando IA esistente come modello** — invece di un'API cloud o di un server offline locale — così puoi indagare con l'agente che già utilizzi.

**Il ciclo di indagine:**

1. **Apri o crea un caso** — Eye si limita ai database degli artefatti e alla cronologia di quel caso.
2. **Fai una domanda** in linguaggio naturale, oppure avvia un triage completo con un clic.
3. **Eye esegue la sua pipeline** — rileva l'intento → recupera la conoscenza → esegue gli strumenti → sintetizza.
4. **Ottieni un doppio output** — una risposta diretta in chat *e* un nuovo blocco nel Report Vivente.
5. **Approva le azioni gated** — le esportazioni e altri passaggi critici attendono la tua firma.

Puoi cambiare modello in fase di esecuzione con lo strumento `switch_model`. Il passaggio è **limitato allo stesso backend**, quindi le prove non vengono mai inviate silenziosamente a un fornitore diverso da quello che hai scelto.

### Tracciare il Processo di Pensiero dell'LLM

Eye è costruito perché tu possa vedere — e successivamente provare — *come* ha raggiunto una conclusione. Mentre Eye lavora, trasmette aggiornamenti strutturati `ThinkingStep` all'interfaccia in tempo reale; ciascuno porta un `step_id`, un `type`, una `label` leggibile dall'uomo, uno `status` (`active` → `done`, o `error`) e `tool`/`params`/`detail` opzionali.

| Tipo di step | Cosa stai vedendo |
|---|---|
| `thinking` | Eye pianifica — rileva l'intento forense, costruisce il prompt di sistema, decide le mosse successive. |
| `rag` | Eye recupera la conoscenza sugli artefatti dalla sua knowledge base per fondare la risposta. |
| `tool_call` | Eye esegue uno strumento forense (una query SQL, una ricerca, una lookup di correlazione). |
| `synthesis` | Eye valida e assembla la risposta finale, supportata dalle prove. |

Una query tipica si svolge come `thinking → rag → thinking → tool_call → synthesis`, e ogni caso conserva artefatti di traccia su disco che puoi ispezionare successivamente:

| File | Cosa registra |
|---|---|
| `<case>/EYE_Logs/eye_payload_seal.jsonl` | I payload esatti inviati al modello, concatenati tramite hash. |
| `<case>/EYE_Logs/truncation_audit.log` | Quale contesto è stato mantenuto, riassunto, eliminato o bloccato — e perché. |
| `<case>/case_history.json` | La cronologia completa della conversazione, con conteggi di token per messaggio. |

### Esecuzione degli Strumenti

Eye è **guidato dagli strumenti**: il modello non tocca mai direttamente le prove. Emette chiamate agli strumenti, ed Eye le esegue sui database del caso e restituisce i risultati — così ogni azione è esplicita, registrata e riproducibile. Gli strumenti sono definiti in `configs/llm_config.json` e distribuiti tramite `eye/services/context_manager.py`.

**Strumenti investigativi** — leggono e analizzano le prove:

| Strumento | Scopo |
|---|---|
| `query_database` | Esegue una `SELECT` su un database forense. |
| `search_artifacts` | Ricerca testo / regex su più database. |
| `semantic_search_artifacts` | Ricerca semantica tra gli artefatti analizzati. |
| `get_schema` | Ispeziona gli schemi delle tabelle. |
| `query_timeline` | Una scansione cronologica unica su ogni database del caso — cosa è successo e quando. |
| `query_correlation_results` | Interroga l'output del Motore di Correlazione per tempo / identità. |
| `read_imported_evidence` | Legge le prove di terze parti importate nel caso verbatim (report, email, output di strumenti browser). |
| `correlate_imported_evidence` | Correla le prove di terze parti importate nel caso con gli artefatti nativi. |
| `analyze_large_dataset` | Analisi map-reduce di grandi set di risultati — **nessuna troncatura silenziosa**. |
| `list_case_files` | Elenca i file nella directory del caso. |
| `internet_search` / `fetch_web_content` | Cerca e recupera contesto esterno di minacce / tecnico. |
| `query_living_off_the_land_intel` | Lookup LOLBAS / LOLDrivers. |
| `query_threat_intel` | Lookup VirusTotal / threat-intel. |
| `switch_model` | Cambia modello in fase di esecuzione (solo stesso backend). |

**Strumenti di reporting** costruiscono lo Spazio di Lavoro del Report Vivente: `report_append_section`, `report_add_data_table`, `report_add_chart`, `report_add_timeline`, `report_add_heatmap`, `report_add_chain_of_custody`, `report_add_chat_transcript`, `report_add_image`, `report_edit_section`, `report_delete_section`, `chat_add_table` e `export_report` (l'esportazione richiede l'approvazione umana).

**Strumenti di authoring** (governati — vedi [Costruire Wings di Correlazione e Mapping Semantici](#building-correlation-wings--semantic-mappings)): `correlation_create_wing`, `correlation_edit_wing`, `correlation_create_semantic_mapping`, `correlation_edit_semantic_mapping`. Le chiamate agli strumenti vengono tradotte in ciò che il backend attivo si aspetta — function-calling nativo per API cloud e server locali, o un wrapper XML `<tool_call>` per gli agenti CLI.

### Costruire Wings di Correlazione e Mapping Semantici

Eye non si limita a *interrogare* il [Motore di Correlazione](#-correlation-engine) — può aiutare a **estenderlo**. Quando Eye individua un pattern cross-artefatto ricorrente, può proporre nuove **Wings** (regole di correlazione) e **Mapping Semantici** (traduzioni tecnico-umane). Questo è *authoring governato*: Eye propone, l'analista rivede l'artefatto salvato e ogni modifica è giustificata e supportata dalle prove.

**Una Wing** collega le feathers all'interno di una finestra temporale e di una soglia minima di corrispondenza per provare un'affermazione:

| Campo | Significato |
|---|---|
| `wing_name` | Nome leggibile dall'uomo per la regola. |
| `proves` | L'affermazione forense che supporta (es. *esecuzione di programmi*). |
| `feathers[]` | Artefatti da correlare — ciascuno con `artifact_type`, `weight` opzionale (0–1) e `tier` (1–4). |
| `time_window_minutes` | Finestra di correlazione (default **180** = 3 ore). |
| `minimum_matches` | Quante feathers devono corrispondere nella finestra (default **1**). |
| `reason` *(obbligatorio)* | Giustificazione forense per la regola. |
| `related_evidence` *(obbligatorio)* | Uno o più riferimenti `database:table:rowid` che l'hanno motivata. |

**Un Mapping Semantico** traduce un valore tecnico grezzo in un significato leggibile dall'uomo (es. *EventID 4624 → "Accesso riuscito"*). Esiste in due varianti: un semplice `mapping` (valore singolo/regex → valore semantico) o una `rule` multi-condizione (condizioni unite da AND/OR). Entrambi supportano `category`, `severity`, `confidence` e `scope`, ed entrambi richiedono `reason` + `related_evidence`.

**Governance — regole lato scrittura che sostengono il GEP:**
- **Reason-Required** (sostiene **GEP-9** + **GEP-2**): ogni creazione *e* modifica deve includere una `reason` forense.
- **Evidence-Link** (sostiene **GEP-2**): ogni creazione deve citare almeno un riferimento `database:table:rowid`.
- **Eye-Stamped / sola lettura per gli altri** (sostiene **GEP-7** + **GEP-9**): Eye appone la sua paternità + reason + cronologia delle modifiche e può modificare **solo ciò che Eye ha creato** — le regole integrate e quelle create dall'uomo restano **in sola lettura**.

### Contesto Auto-Riparante

Le indagini lunghe possono superare la finestra di contesto di un modello — specialmente i modelli offline più piccoli. Invece di bloccarsi o eliminare silenziosamente le prove, Eye **compatte automaticamente il proprio contesto** prima di ogni chiamata al modello (all'interno del suo percorso di generazione protetto, completamente verificato).

Prima di ogni chiamata, Eye misura il payload completo e riserva spazio per la risposta (**10%** della finestra, minimo 512 token, mai più della metà). Se ancora non entra, si ripara in due passaggi ordinati, senza mai toccare i messaggi **protetti** (bloccati, prove rilevate automaticamente o un risultato di uno strumento):

1. **Passaggio di riepilogo** *(una volta)* — la cronologia non protetta si comprime in un unico riepilogo, registrato come `SUMMARIZED`.
2. **Passaggio di eliminazione** — il messaggio **non protetto più vecchio** viene rimosso uno alla volta finché non entra, registrato come `TRUNCATED`.

Se il **nucleo di prove** irriducibile (bloccati + risultati degli strumenti + la domanda corrente) *ancora* va in overflow, Eye **rifiuta di procedere piuttosto che troncare le prove** (`REFUSED_OVERFLOW`) e ti chiede di restringere la query o usare `analyze_large_dataset`. Qualunque cosa vada infine al modello è il payload esatto che viene sigillato per la catena di custodia.

### 🗺️ Mappa Narrativa — La Memoria Persistente del Caso dell'Eye

L'Eye è **senza stato tra i turni** — quindi la **Mappa Narrativa** è dove "ciò che sappiamo e ciò che abbiamo concluso" vive per un caso. È la **memoria di lavoro persistente, verificabile e a prova di manomissione** dell'Eye, e i suoi contenuti vengono **iniettati nel prompt dell'Eye a ogni turno** (la mappa *è* letteralmente la memoria).

- 🧭 **Verdetto → Narrativa → Prove.** Una gerarchia rigorosa: un **Verdetto** del caso, le **Narrative** al di sotto (affermazioni, ciascuna con uno stato — `proven` · `open` · `negative` · `needs` · `absolute`) e le **Prove** supportate dagli artefatti al di sotto di queste.
- 🪟 **Una finestra propria.** Si apre dal pulsante **"Narrative Map"** nella finestra della chat dell'Eye, così puoi guardare la chat, il report vivente e la memoria del caso fianco a fianco; si aggiorna in tempo reale man mano che le cose cambiano.
- ↔️ **Bidirezionale — una memoria che comandi tu.** Sia le modifiche dell'Eye che le tue note personali passano attraverso un singolo **commit validato dal GEP** e vengono sigillate in un **log di audit concatenato tramite hash** (`narrative_map_audit.jsonl`). Puoi **aggiungere, modificare e rimuovere** le sue affermazioni e prove, plasmando direttamente come l'Eye comprende e interpreta il caso.
- 🚫 **Non afferma mai ciò che non è supportato.** Una narrativa dell'Eye può restare `open` senza prove mentre indaga, ma non può mai essere `proven` senza prove; un tema che l'Eye ha verificato ma trovato vuoto si converte automaticamente in **`negative`** — perché un'assenza documentata è di per sé un risultato.

### Come Funziona la Conformità

La conformità non è una funzionalità aggiunta a posteriori — è applicata nella pipeline.

- **🔗 Catena di custodia (Sigillo delle Prove).** Ogni payload che Eye invia a un LLM viene sigillato: lo **SHA-256 dei byte esatti**, il conteggio dei token, il modello + il suo limite di contesto e la provenienza di ogni riga di prova (`database:table:rowid`, più gli offset calcolati per i record MFT). I sigilli sono **append-only e concatenati tramite hash** in `<case>/EYE_Logs/eye_payload_seal.jsonl` — un singolo record alterato o rimosso rompe la catena, quindi il log prova *matematicamente* quali byte il modello ha analizzato.
- **🚫 Nessuna troncatura silenziosa.** Quando il contesto si fa stretto, Eye si [auto-ripara](#self-healing-context) e rialloca i budget in un ordine rigoroso: **Priorità 1 (Immovibile): Prove Grezze + Prompt di Sistema** › **Priorità 2 (Sacrificale): Conversazione Informale** › **Priorità 3 (Flessibile): Contesto RAG**. Se il nucleo di prove ancora non entra, Eye rifiuta piuttosto che eliminare silenziosamente le prove.
- **🧾 Traccia di audit della troncatura.** Ogni decisione sul contesto viene registrata in `<case>/EYE_Logs/truncation_audit.log` (`SUMMARIZED`, `TRUNCATED`, `PRESERVED`, `PINNED`, `UNPINNED`, `BUDGET_REDUCED`), ciascuna con un hash. Le prove rilevate vengono bloccate automaticamente al di sopra di una soglia di confidenza; puoi anche bloccare i messaggi manualmente.
- **📑 Mandato Prove-verso-Report.** Eye deve rispondere in chat **e** persistere le prove di supporto nel report; la mancata registrazione delle prove viene segnalata come violazione del protocollo.
- **⚖️ Governance della correlazione.** Qualsiasi Wing o mapping creato da Eye deve includere una `reason` forense e `related_evidence`; le regole create al di fuori di Eye sono in sola lettura e non possono essere riscritte silenziosamente.
- **🔐 Privacy e air-gapping.** Nelle modalità offline Eye effettua **zero chiamate in uscita**; le chiavi API cloud vivono nei portachiavi nativi del sistema operativo — mai hardcoded, mai scritte nei log.

📖 **Architettura completa dell'Eye:** [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

## 📖 Eye-Describe — Knowledge Base degli Artefatti a Livello di Byte

> 🔗 **[Esplora Eye-Describe → crow-eye.com/eye-describe](https://crow-eye.com/eye-describe)**

Storicamente, gli investigatori cadevano nella trappola di fidarsi dei propri strumenti forensi senza capire come si comportano gli artefatti sottostanti o come lo strumento li ha analizzati. Il rischio oggi è semplicemente sostituire *"lo strumento"* con *"l'IA"*. Un'IA può analizzare un record con perfetta accuratezza tecnica e comunque collocarlo nel contesto sbagliato — cambiando l'intero significato della prova.

**Eye-Describe** esiste affinché né l'uomo né il modello debbano tirare a indovinare. È un riferimento interattivo a livello di byte per le strutture binarie grezze degli artefatti Windows e svolge due ruoli contemporaneamente:

| Ruolo | Cosa fa |
|---|---|
| 🧑‍🏫 **Il progetto per l'uomo** | Un riferimento educativo interattivo all'anatomia profonda a livello di byte degli artefatti Windows — cos'è ogni struttura, come si comporta, cosa può e non può provare. Gratuito da usare, pensato per studenti, educatori e professionisti che vogliono capire la prova piuttosto che la colonna di output. |
| ⚖️ **L'ancora di conformità per l'IA** | La visibilità dell'Eye è vincolata ai comportamenti documentati degli artefatti in Eye-Describe. Il modello ragiona contro un riferimento hardcoded su ciò che un artefatto *significa realmente*, piuttosto che inferire la semantica da solo. |

Ancorando il livello IA al comportamento documentato degli artefatti, Crow-Eye non ti chiede di fidarti di un modello — vincola il modello a rispettare la forensica grezza.

> **Non sostituire la fiducia nello strumento con la fiducia nell'IA. Comprendi i dati.**

## 🧪 Qualità e Validazione

Gli strumenti forensi sono utili solo se il loro output può essere difeso. Il lavoro di correttezza di Crow-Eye è deliberatamente visibile:- **Suite di regressione.** Il Correlation Engine è protetto da una suite pytest che copre il parsing dei timestamp, la normalizzazione delle identità, il fan-out multi-timestamp, il contratto dello scrittore, la creazione di Eye (governance GEP lato scrittura) e il registro dei campi standard. Il motore UBA include la propria suite, incluso un test end-to-end su un caso reale.
- **Harness di validazione.** Un harness olistico esercita tutte le 7 ali predefinite su **entrambi** i motori con un caso Windows reale di ~700K record.
- **Storico dei difetti pubblicato.** Le regressioni di accuratezza e il loro impatto misurato sono documentati apertamente in [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) — inclusi i casi in cui una correzione ha modificato i record visti di ordini di grandezza. Sapere cosa era sbagliato, e quando, fa parte di ciò che rende un risultato difendibile.
- **Contabilità delle prove verificabile.** Ogni record finisce in una corrispondenza o in un bucket di scarto nominato, e il registro degli scarti per finestra rende "nessuna prova avanzata" qualcosa che puoi verificare dal log piuttosto che prendere per fede.
- **Log a prova di manomissione.** `verify_chain()` ripercorre il log di audit della Narrative Map e la catena dell'Evidence Seal per rilevare modifiche — incluse quelle ai campi leggibili dall'uomo.

## 🔬 Piattaforma di ricerca

Crow-Eye è più di un software — è una **piattaforma di ricerca aperta** che accelera l'intero campo della forensica Windows. Il progetto si concentra su:

- Pubblicazione di documentazione dettagliata sulle strutture interne degli artefatti.
- Condivisione di logiche e metodologie di correlazione.
- Abilitazione di revisione tra pari, trasparenza e collaborazione accademica.
- Contributo alla conoscenza collettiva della comunità forense.

## 🛠️ Note tecniche

- Il parsing del registro richiede file hive del registro completi.
- Alcuni artefatti richiedono una gestione speciale a causa dei meccanismi di blocco dei file di Windows (vedi [Registro personalizzato / file bloccati](#-artefatti-supportati)).
- Il parsing di LNK e Jump List è gestito dal parser dedicato di Crow-Eye.

## 📸 Screenshot

Una selezione delle viste dell'interfaccia e dell'analisi di Crow-Eye.

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/d631f2359d186d47eab815cc199d2c08c7c098cb8c64509d7c43185b6413d537.png)

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/140bd5b574f8b2d239f45be6b9d238a592da1cf3b7e6a0cf0a7450a653a75b88.png)

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b7593c596ea437f84cdf476c147fc363a9a87fd821023b2c93559cdc56ceebee.png)

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b67e55fc8c3bc87a5357add66c97e2b5d75310fe7ea5c1f571f5e8938c0a25ae.png)

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/8f10355f7d0f9f31e2e270ecf43fa70e94a6eda3b84b792d28479e0552eec000.png)

![Screenshot di Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/7bbf1b790d445d33a392b023cc14877e8ee0c72ed2aeec1aba1663da7d0419a2.png)

🎥 **Video demo:** [![Guarda la demo](https://assets.kitploit.com/production/public/readmes/9931/01aa6e4b5fb8732512fe81143b1dcd87d908401369284bad8cfaf1b119fcbf41.jpg)](https://youtu.be/hbvNlBhTfdQ)

## 🚧 Roadmap

Lavoro pianificato e in corso (vedi [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) per le modifiche rilasciate):

- 📊 **Viste GUI avanzate e report** — visualizzazione e reporting più ricchi.
- 🔄 **Dialogo di ricerca potenziato** — filtri avanzati con supporto al linguaggio naturale.
- 🎯 **Mappatura semantica potenziata** — mappatura completa dei campi su tutti i tipi di artefatti.
- 📈 **Punteggio di correlazione avanzato** — punteggio di confidenza raffinato e spiegabile.
- ⚡ **Correlazione parallela** — dispatch tramite process-pool, abilitato per impostazione predefinita per carichi di lavoro elevati.

Hai un'idea o vuoi aggiungere un artefatto? [Apri un issue](https://github.com/Ghassan-elsman/Crow-Eye/issues) o consulta [Contribuire](#-contribuire).

## 📚 Documentazione

- **[TECHNICAL_DOCUMENTATION.md](https://github.com/ghassan-elsman/crow-eye/blob/main/TECHNICAL_DOCUMENTATION.md)** — architettura, componenti e guida allo sviluppo.
- **[RELEASE_NOTES.md](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md)** — novità di ogni release (UBA, Narrative Map, backend Eye cloud, hardening della gestione dei casi, …).
- **[Documentazione del Correlation Engine](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — panoramica, motore, feathers, wings, pipeline.
- **[Architettura della timeline](https://github.com/ghassan-elsman/crow-eye/blob/main/timeline/ARCHITECTURE.md)** — interni del modulo timeline.
- **[Architettura di Eye](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md)** e **[standard GEP](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md)** — l'assistente AI e il suo protocollo di governance.

## 🤝 Contribuire

Crow-Eye è costruito come piattaforma di ricerca aperta e i contributi sono benvenuti — nuovi parser, regole di correlazione, documentazione e ricerca sugli artefatti.

- **Contributi generali:** [CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/CONTRIBUTING.md)
- **Correlation Engine (area prioritaria):** [correlation_engine/CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)
- **Contatti:** [[email protected]](mailto:[email protected]) · oppure apri un issue / pull request.

## 🌐 Sito web e community

- 🌍 **Sito ufficiale:** [crow-eye.com](https://crow-eye.com/) — risorse, documentazione e download.
- 💬 **Discord:** [Unisciti al Discord di Crow-Eye](https://discord.gg/2vag2Udf) — assistenza diretta, ricerca sugli artefatti e annunci delle release.

## 📄 Licenza

Crow-Eye è rilasciato sotto la **[GNU General Public License v3.0](https://github.com/ghassan-elsman/crow-eye/blob/main/LICENSE)** (GPL-3.0). È libero da usare, studiare, condividere e modificare secondo i termini di tale licenza.

## 📝 Citare Crow-Eye

Se utilizzi Crow-Eye in lavori accademici, ricerche pubblicate o un report di caso, ti preghiamo di citarlo:```bibtex
@software{elsman_crow_eye,
  author  = {Elsman, Ghassan},
  title   = {Crow-Eye: A Windows Forensics Engine},
  url     = {https://github.com/Ghassan-elsman/Crow-Eye},
  license = {GPL-3.0},
  year    = {2026}
}
```
Elsman, G. *Crow-Eye: A Windows Forensics Engine* (GPL-3.0). https://github.com/Ghassan-elsman/Crow-Eye

Per le citazioni metodologiche, il Protocollo Ghassan Elsman è documentato separatamente in [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

## 💖 Supporto

Crow-Eye è gratuito e open-source, sviluppato e mantenuto da una sola persona. Se ti è utile nel tuo lavoro, considera di sponsorizzarlo: finanzia direttamente nuovi parser e ricerca: **[SPONSORS.md](https://github.com/ghassan-elsman/crow-eye/blob/main/SPONSORS.md)** · **[GitHub Sponsors](https://github.com/sponsors/Ghassan-elsman)**.

## Crediti

Creato e mantenuto da **Ghassan Elsman**.