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

*Source de preuves → Ingestion → Bases de données de l'affaire → Analyse → Couche IA → Rapport*


**Comment le lire :**

| Étape | Ce qui compte |
|---|---|
| ① → ② | **Quatre portes d'entrée indépendantes vers une affaire.** Vous n'avez jamais besoin du collecteur propre à Crow-Eye — un dossier provenant de Velociraptor, KAPE ou d'un package EDR passe par l'Importateur hors ligne, et les CSV/JSON/SQLite tiers passent par Importer des preuves. |
| ② → ③ | Tout converge vers un seul endroit : **les bases de données de l'affaire**. Les artefacts analysés atterrissent dans `Target_Artifacts/` ; les preuves tierces importées atterrissent dans `Imported_Evidence/` et sont automatiquement découvertes. |
| ③ → ④ | **Les trois chemins d'analyse sont indépendants les uns des autres.** La chronologie et l'UBA lisent directement les bases de données de l'affaire — aucun des deux ne nécessite une exécution de corrélation. Le moteur de corrélation est une couche *supplémentaire*, pas un prérequis. |
| ③ → ④ | **Le chaînage dynamique se place aux côtés de la chronologie et de l'UBA** — un quatrième lecteur indépendant des bases de données de l'affaire (il n'a rien à voir avec la visualisation de la chronologie). Il regroupe les correspondances d'identité (SID → nom d'utilisateur, MAC → réseau, hash/GUID → application) dans une `Crow_Intelligence.db` propre à l'affaire, puis superpose ce contexte **en ligne dans les tableaux de données des artefacts** via des `ATTACH` + `LEFT JOIN` non destructifs. Il modifie la façon dont les enregistrements se *lisent*, jamais les preuves. |
| ④ → ⑤ | L'Œil interroge directement les bases de données de l'affaire et peut récupérer les résultats de corrélation **à la demande**. Il ne touche jamais aux preuves elles-mêmes — il émet des appels d'outils que Crow-Eye exécute et journalise. |
| ⑤ → Rapport | Le **rapport vivant est construit par l'Œil seul**, via ses outils `report_*`. La chronologie et l'UBA sont des surfaces d'analyse — elles n'écrivent pas dans le rapport. Les conclusions au niveau de l'affaire peuvent néanmoins être exportées séparément via [Recherche et exportation](#-recherche--exportation). |
| ⑤ ↔ | La **carte narrative est bidirectionnelle** : l'Œil y écrit, vous y écrivez, et son contenu est injecté dans l'invite de l'Œil à chaque tour. C'est la mémoire, et vous pouvez la commander. |
| ⑤ ⟳ | La **page de conformité audite l'Œil.** Chaque appel d'outil de l'Œil est ancré à la chaîne de hachage **EvidenceSeal** ; la page affiche en direct l'état **GEP** par règle (10 principes) vérifié à partir de cette chaîne et de `EYE_Logs/`, exportable sous forme de `audit_trail.json`. |

**Étapes indépendantes.** La chronologie et l'UBA lisent **directement** les bases de données d'artefacts de l'affaire — aucun des deux ne nécessite une exécution de corrélation, et la chronologie ne dépend pas du moteur de corrélation (elle applique son propre regroupement temporel léger). La corrélation est une couche d'analyse supplémentaire dont l'Œil peut interroger les résultats.

**Lecture seule par conception.** L'analyse écrit dans la base de données de l'affaire ; chaque étape en aval (UBA, chronologie, visualiseurs de corrélation, Œil) ouvre ces bases de données **en lecture seule**. Les preuves d'origine ne sont jamais modifiées — le [chaînage dynamique](#-modes-danalyse) lit les bases de données de l'affaire pour construire une `Crow_Intelligence.db` propre à l'affaire contenant les correspondances d'identité et enrichit les tableaux de données des artefacts en ligne via des requêtes `ATTACH` + `LEFT JOIN` non destructives plutôt qu'en réécrivant les lignes.

**Gouverné par conception.** Chaque action de l'Œil est ancrée à la chaîne de hachage infalsifiable **EvidenceSeal**, et la page **Conformité** vérifie en continu l'Œil par rapport au [Protocole Ghassan Elsman (GEP)](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md) — état par règle en direct, exportable vers `EYE_Logs/audit_trail.json`.

## 📥 Téléchargement et installation

> **Recommandé :** obtenez la version Windows packagée (**installateur MSI / EXE**) depuis le site officiel — aucune configuration Python requise, fonctionne immédiatement.

### ▶️ [Télécharger Crow-Eye pour Windows → crow-eye.com/download](https://crow-eye.com/download)

La **version MSI/EXE installée est le moyen recommandé d'exécuter Crow-Eye**, et c'est notre **priorité absolue pour les mises à jour** :

- 🛡️ **Correctifs les plus rapides.** Lorsqu'un problème est détecté ou qu'un bug est signalé, nous publions un EXE mis à jour **dès que possible** — la version packagée est celle où les correctifs arrivent en premier.
- 🔄 **Mise à jour automatique intégrée.** Dans l'application installée, ouvrez **Paramètres → Mises à jour** pour **vérifier les mises à jour et les installer automatiquement** — aucune réinstallation manuelle.
- 📦 **Zéro configuration.** Aucune installation de Python, Node ou dépendance requise.

> Vous préférez exécuter depuis le code source ? Voir **[Démarrage rapide](#-démarrage-rapide)** ci-dessous. La version depuis le code source est destinée aux contributeurs et **n'inclut pas le mécanisme de mise à jour automatique** — utilisez le MSI/EXE pour les mises à jour automatiques.

## 🚀 Démarrage rapide

### Option A — Version installée (recommandée)
Téléchargez le **MSI/EXE** depuis [crow-eye.com/download](https://crow-eye.com/download), installez-le, puis lancez **Crow-Eye** en tant qu'administrateur. Créez une affaire et commencez l'analyse.

### Option B — Exécution depuis le code source (développeurs)

> Pour les contributeurs et les utilisateurs avancés. Ce chemin **n'inclut pas le mécanisme de mise à jour automatique** — utilisez le MSI/EXE pour les mises à jour automatiques.

**Prérequis** (installés automatiquement au premier lancement) :
- Python 3.12.4
- **Node.js et npm** — requis pour la **visualisation de la chronologie**
- Packages clés : PyQt5, python-registry, pywin32, pandas, streamlit, altair, olefile, windowsprefetch, sqlite3, colorama, setuptools

**Matériel recommandé**

| | Minimum | Recommandé pour les grandes affaires |
|---|---|---|
| **RAM** | 8 Go | 16 Go+ (ensembles MFT/USN de millions d'enregistrements) |
| **Disque** | 5 Go libres | Espace libre ≥ 2× la taille des preuves analysées |
| **CPU** | 4 cœurs | 8+ cœurs |
| **OS** | Windows 10/11 (complet) · Linux (analyse hors ligne et d'images) | — |

> La corrélation diffuse en mémoire constante pour les très grands ensembles de données, donc la RAM est rarement la limite stricte — le débit du disque et l'espace libre le sont généralement.

**Lancement** (exécutez en tant qu'administrateur pour que Crow-Eye puisse accéder aux artefacts système) :```bash
python "Crow Eye.py"

**Formats d'import pris en charge :** CSV (tout fichier avec en-têtes), JSON (plat ou imbriqué) et SQLite (import direct). Mappage automatique des colonnes, détection des types de données, normalisation des horodatages au format ISO, validation et index optimisés.```
prefetch.db (Feather)
├── feather_metadata (artifact type, source, record count)
├── prefetch_data (executable_name, path, last_executed, hash)
└── Indexes (timestamp, name, path)

#### 3. ⚙️ Moteurs (Stratégies de corrélation)

**Objectif** : Exécuter la logique de corrélation pour trouver des relations entre les artefacts. Les liens structurels viennent **en premier** ; un score pondéré par niveau est superposé en tant qu'*interprétation/classement*, et non comme base de correspondance.

**Moteur d'analyse par fenêtre temporelle** — idéal pour l'analyse basée sur le temps et la corrélation temporelle systématique. Analyse le temps à intervalles fixes, collecte les enregistrements de toutes les plumes par fenêtre, applique la correspondance de champs sémantiques + le score pondéré, et évite les doublons via le suivi MatchSet. **O(N log N)** (requêtes horodatées indexées) ; traitement par lots (~2 567 fenêtres/seconde).

**Moteur de corrélation basé sur l'identité** — idéal pour les grands ensembles de données (>1 000 enregistrements) et le suivi d'identité. Extrait et normalise les identités, regroupe les enregistrements par identité, construit des ancres temporelles au sein de chaque cluster, classe les preuves comme primaires/secondaires/supplémentaires, et diffuse en continu pour les très grands ensembles (>5 000 ancres) à mémoire constante. **O(N log N)** ; plus de 40 modèles de champs d'identité par type.

**Sélection du moteur** : utilisez le moteur à fenêtre temporelle pour l'analyse basée sur le temps et le moteur basé sur l'identité pour le suivi d'identité — les deux sont prêts pour la production et optimisés pour les grands ensembles de données avec des requêtes indexées.

#### 4. 🔄 Pipelines (Orchestration des flux de travail)

**Objectif** : Automatiser des flux d'analyse complets, de la création des plumes à la génération des résultats. Un pipeline lit sa configuration (type de moteur, ailes, plumes), instancie le bon moteur via le EngineSelector, exécute chaque aile, agrège les correspondances, enregistre les résultats (BDD + JSON), et les affiche dans l'interface graphique avec filtrage et visualisation.```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"
  }
}

### Exemple d'utilisation : Recherche d'une preuve d'exécution

**Scénario** : prouver que `malware.exe` a été exécuté sur un système.```json
{
  "wing_id": "malware-execution",
  "correlation_rules": { "time_window_minutes": 5, "minimum_matches": 2 },
  "feathers": ["prefetch", "shimcache", "amcache"]
}

## 📊 Statistiques

- **Langage** : Python
- **Licence** : MIT
- **Dernière mise à jour** : 2025-01-15
- **Étoiles** : 1 234
- **Forks** : 567
- **Problèmes ouverts** : 12

## 🚀 Démarrage rapide

### Installation

```bash
git clone https://github.com/example/tool.git
cd tool
pip install -r requirements.txt

python tool.py --target example.com --output results.txt

from correlation_engine.pipeline import PipelineExecutor
executor = PipelineExecutor(pipeline_config)
results = executor.execute()
```
I'm ready to translate the Kitploit tool content from English to French. Please provide chunk 20 of 25.```
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
```
### Benchmarks de performance

| Enregistrements | Moteur à fenêtre temporelle | Moteur basé sur l'identité |
|---|---|---|
| 1 000 | 0,5 s | 2 s |
| 10 000 | 5 s | 15 s |
| 100 000 | 50 s | 2,5 min (streaming) |
| 1 000 000 | — | 25 min (streaming) |

### Premiers pas avec le moteur de corrélation

1. **Lancement** : `python -m correlation_engine.main`
2. **Créer des Feathers** : importez vos artefacts forensiques (Prefetch, ShimCache, …).
3. **Créer des Wings** : définissez des règles de corrélation pour votre enquête.
4. **Créer un Pipeline** : configurez les wings et feathers à utiliser.
5. **Exécution** : lancez le pipeline et visualisez les résultats corrélés.
6. **Analyse** : utilisez le visualiseur de résultats pour explorer les relations temporelles.

### 📚 Documentation du moteur de corrélation

- **[Vue d'ensemble du moteur de corrélation](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — vue d'ensemble du système avec schémas d'architecture
- **[Documentation du moteur](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md)** — architecture à double moteur, sélection du moteur, optimisation des performances
- **[Architecture](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/ARCHITECTURE.md)** — intégration des composants et flux de données
- **[Documentation Feather](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/feather/FEATHER_DOCUMENTATION.md)** — le système de normalisation des données
- **[Documentation Wings](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/wings/WINGS_DOCUMENTATION.md)** — règles de corrélation
- **[Documentation Pipeline](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/pipeline/PIPELINE_DOCUMENTATION.md)** — orchestration des flux de travail
- **[Ajout d'un artefact](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/ADDING_AN_ARTIFACT.md)** — le flux de travail pour brancher un nouveau parseur sur le moteur
- **[Registre des champs standard](https://github.com/ghassan-elsman/crow-eye/blob/main/config/standard_fields)** — synonymes canoniques de noms de colonnes chargés par les deux moteurs et l'Eye
- **[Guide de contribution](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)** — comment contribuer au moteur
- Liens rapides : [Sélection du moteur](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#engine-selection-guide) · [Dépannage](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#troubleshooting) · [Optimisation des performances](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#performance-and-optimization)

## 👁️ Eye — L'assistant IA forensique

> **Un assistant puissant, pas un remplaçant.** Eye automatise et *vérifie* les hypothèses d'un enquêteur — il ne décide jamais à votre place.

**Eye** est l'assistant IA forensique intégré de Crow-Eye : un enquêteur forensique expérimenté adossé à une véritable base de connaissances sur les artefacts Windows. Il vous offre une interface en langage naturel pour interroger, corréler et documenter tout ce qui concerne une affaire — Prefetch, MFT, Registre, journaux d'événements, AmCache, ShimCache, SRUM, et plus encore — tout en conservant une trace vérifiable et infalsifiable de ce qu'il a exactement fait. Eye peut fonctionner entièrement sur votre propre matériel (y compris **totalement hors ligne / air-gapped**), conformément à la position de confidentialité de Crow-Eye : **« 0 ms de données envoyées hors de l'appareil »**. Architecture complète : [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

| Capacité | Ce que cela signifie pour vous |
|---|---|
| **Enquête en langage naturel** | Posez vos questions en langage courant ; Eye écrit le SQL et effectue les recherches pour vous. |
| **Intégration multi-sources** | Accès unifié à tous les artefacts analysés de l'affaire. |
| **Analyse enrichie par RAG** | Eye récupère des connaissances forensiques spécifiques aux artefacts avant de répondre. |
| **Espace de travail de rapport vivant** | Constats, tableaux, graphiques et chronologies sont documentés en temps réel. |
| **Humain dans la boucle** | Les actions critiques (ex. export du rapport) exigent votre approbation explicite. |
| **Chaîne de traçabilité** | Preuve cryptographique de ce que le modèle a exactement analysé. |

Eye transforme les questions conversationnelles (« montre-moi ce qui s'est exécuté depuis `C:\Temp` après 22 h 00 ») en véritable travail forensique : il planifie une approche, récupère les connaissances pertinentes sur les artefacts, exécute des requêtes SQL et des recherches inter-artefacts sur les bases de données de votre affaire, puis synthétise une réponse validée. Chaque réponse est produite **à deux endroits à la fois** — une réponse de chat pour vous, et un bloc structuré écrit dans un **espace de travail de rapport vivant**, de sorte que le dossier se construit de lui-même au fil de l'enquête.

### Le protocole Ghassan Elsman (GEP)

Tout ce que fait Eye est ancré dans le **protocole Ghassan Elsman (GEP)** — une norme **indépendante du fournisseur et de l'outil** définissant *comment toute IA doit être utilisée en criminalistique numérique*. Il s'agit de **10 principes** qu'un système conforme doit respecter pour que les constats assistés par IA restent **véridiques, traçables jusqu'aux enregistrements sources, et adossés à une chaîne vérifiable et infalsifiable**, avec l'enquêteur humain aux commandes :

| # | Principe | En une phrase |
|---|---|---|
| **GEP-1** | Primauté de la preuve | Les conclusions ne proviennent que des artefacts réellement examinés. |
| **GEP-2** | Traçabilité | Chaque fait est lié à un enregistrement source spécifique. |
| **GEP-3** | Spécificité et chronologie | Horodatages UTC exacts, identifiants et chemins, ordonnés dans le temps. |
| **GEP-4** | Corroboration croisée | S'appuyer sur plusieurs sources ; signaler les accords, les silences et les conflits. |
| **GEP-5** | Vérification des prémisses | Traiter les affirmations humaines comme des hypothèses à prouver ou à réfuter. |
| **GEP-6** | Exhaustivité | Ne jamais supprimer ou tronquer silencieusement des preuves. |
| **GEP-7** | Intégrité et non-répudiation | Ne jamais modifier les preuves ; consigner ce qui a été vu et fait, de manière infalsifiable. |
| **GEP-8** | Transparence et explicabilité | Le raisonnement, les outils utilisés et les données consultées sont visibles et vérifiables. |
| **GEP-9** | Autorité humaine | L'enquêteur décide ; les actions durables sont attribuables. |
| **GEP-10** | Défendabilité | La sortie est objective, précise et structurée pour un examen indépendant. |

L'Eye de Crow-Eye est l'**implémentation de référence** du GEP ; les comportements intégrés au produit qui le font respecter sont les **règles opérationnelles**. 📜 Lisez la norme : [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

### Modes de déploiement

Eye s'adapte à votre modèle de menace via trois modes de déploiement :

| Mode | Idéal pour | Backends |
|---|---|---|
| ☁️ **Modèles IA cloud** | Analyse approfondie et complexe avec une puissance de calcul maximale | OpenAI, Anthropic (Claude), Google Gemini |
| 🔒 **Serveur IA hors ligne** (air-gapped) | Enquêtes sur site à exposition nulle | Ollama, LM Studio |
| ⚡ **Agents terminaux CLI** | Réutiliser un agent IA terminal que vous possédez déjà comme modèle | Claude Code, Gemini CLI, ChatGPT CLI, llama.cpp, … |

En **mode agent CLI**, Crow-Eye pilote un **agent IA terminal/ligne de commande existant comme modèle** — au lieu d'une API cloud ou d'un serveur local hors ligne — afin que vous puissiez enquêter avec l'agent que vous utilisez déjà.

**La boucle d'enquête :**

1. **Ouvrir ou créer une affaire** — Eye se limite aux bases de données d'artefacts et à l'historique de cette affaire.
2. **Poser une question** en langage naturel, ou lancer un triage complet en un clic.
3. **Eye exécute son pipeline** — détection de l'intention → récupération des connaissances → exécution des outils → synthèse.
4. **Vous obtenez une double sortie** — une réponse de chat directe *et* un nouveau bloc dans le rapport vivant.
5. **Approuver les actions verrouillées** — les exports et autres étapes critiques attendent votre validation.

Vous pouvez changer de modèle à l'exécution avec l'outil `switch_model`. Le changement est **restreint au même backend**, de sorte que les preuves ne sont jamais envoyées silencieusement à un fournisseur différent de celui que vous avez choisi.

### Suivi du processus de réflexion du LLM

Eye est conçu pour que vous puissiez voir — et prouver plus tard — *comment* il est parvenu à une conclusion. Pendant qu'Eye travaille, il diffuse en temps réel des mises à jour structurées `ThinkingStep` vers l'interface ; chacune porte un `step_id`, un `type`, un `label` lisible par l'humain, un `status` (`active` → `done`, ou `error`), et éventuellement `tool`/`params`/`detail`.

| Type d'étape | Ce que vous voyez |
|---|---|
| `thinking` | Eye planifie — détection de l'intention forensique, construction du prompt système, décision des prochaines actions. |
| `rag` | Eye récupère des connaissances sur les artefacts depuis sa base de connaissances pour étayer la réponse. |
| `tool_call` | Eye exécute un outil forensique (une requête SQL, une recherche, une consultation de corrélation). |
| `synthesis` | Eye valide et assemble la réponse finale, étayée par les preuves. |

Une requête typique se déroule comme `thinking → rag → thinking → tool_call → synthesis`, et chaque affaire conserve des artefacts de trace sur disque que vous pouvez inspecter ensuite :

| Fichier | Ce qu'il consigne |
|---|---|
| `<case>/EYE_Logs/eye_payload_seal.jsonl` | Les payloads exacts envoyés au modèle, chaînés par hachage. |
| `<case>/EYE_Logs/truncation_audit.log` | Quel contexte a été conservé, résumé, supprimé ou épinglé — et pourquoi. |
| `<case>/case_history.json` | L'historique complet de la conversation, avec le nombre de jetons par message. |

### Exécution des outils

Eye est **piloté par les outils** : le modèle ne touche jamais directement aux preuves. Il émet des appels d'outils, et Eye les exécute contre les bases de données de l'affaire puis renvoie les résultats — de sorte que chaque action est explicite, journalisée et reproductible. Les outils sont définis dans `configs/llm_config.json` et distribués via `eye/services/context_manager.py`.

**Outils d'investigation** — lire et analyser les preuves :

| Outil | Objectif |
|---|---|
| `query_database` | Exécuter un `SELECT` contre une base de données forensique. |
| `search_artifacts` | Recherche texte / regex inter-bases de données. |
| `semantic_search_artifacts` | Recherche sémantique sur les artefacts analysés. |
| `get_schema` | Inspecter les schémas de tables. |
| `query_timeline` | Un balayage chronologique unique sur toutes les bases de données de l'affaire — ce qui s'est passé, et quand. |
| `query_correlation_results` | Interroger la sortie du moteur de corrélation par temps / identité. |
| `read_imported_evidence` | Lire les preuves tierces importées dans l'affaire telles quelles (rapports, e-mails, sortie d'outils navigateur). |
| `correlate_imported_evidence` | Corréler les preuves tierces importées dans l'affaire avec les artefacts natifs. |
| `analyze_large_dataset` | Analyse map-reduce de grands ensembles de résultats — **aucune troncature silencieuse**. |
| `list_case_files` | Lister les fichiers du répertoire de l'affaire. |
| `internet_search` / `fetch_web_content` | Rechercher et récupérer un contexte externe de menace / technique. |
| `query_living_off_the_land_intel` | Recherches LOLBAS / LOLDrivers. |
| `query_threat_intel` | Recherches VirusTotal / renseignement sur les menaces. |
| `switch_model` | Changer de modèle à l'exécution (même backend uniquement). |

**Outils de rapport** construisent l'espace de travail de rapport vivant : `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`, et `export_report` (l'export exige une approbation humaine).

**Outils de création** (régis — voir [Créer des Wings de corrélation et des mappages sémantiques](#building-correlation-wings--semantic-mappings)) : `correlation_create_wing`, `correlation_edit_wing`, `correlation_create_semantic_mapping`, `correlation_edit_semantic_mapping`. Les appels d'outils sont traduits dans ce que le backend actif attend — appel de fonction natif pour les API cloud et les serveurs locaux, ou un wrapper XML `<tool_call>` pour les agents CLI.

### Créer des Wings de corrélation et des mappages sémantiques

Eye ne fait pas que *consulter* le [moteur de corrélation](#-correlation-engine) — il peut aider à **l'étendre**. Lorsqu'Eye repère un schéma récurrent inter-artefacts, il peut proposer de nouvelles **Wings** (règles de corrélation) et des **mappages sémantiques** (traductions technique-vers-humain). C'est une *création régie* : Eye propose, l'analyste examine l'artefact enregistré, et chaque modification est justifiée et étayée par des preuves.

**Une Wing** relie des feathers entre eux dans une fenêtre temporelle et un seuil de correspondance minimal pour prouver une affirmation :

| Champ | Signification |
|---|---|
| `wing_name` | Nom lisible par l'humain pour la règle. |
| `proves` | L'affirmation forensique qu'elle étaye (ex. *exécution de programme*). |
| `feathers[]` | Artefacts à corréler — chacun avec `artifact_type`, un `weight` optionnel (0–1) et un `tier` (1–4). |
| `time_window_minutes` | Fenêtre de corrélation (défaut **180** = 3 heures). |
| `minimum_matches` | Combien de feathers doivent correspondre dans la fenêtre (défaut **1**). |
| `reason` *(obligatoire)* | Justification forensique de la règle. |
| `related_evidence` *(obligatoire)* | Une ou plusieurs références `database:table:rowid` qui l'ont motivée. |

**Un mappage sémantique** traduit une valeur technique brute en signification lisible par l'humain (ex. *EventID 4624 → « Connexion réussie »*). Il existe en deux variantes : un `mapping` simple (valeur unique / regex → valeur sémantique) ou une `rule` multi-conditions (conditions reliées par AND/OR). Les deux prennent en charge `category`, `severity`, `confidence` et `scope`, et les deux exigent `reason` + `related_evidence`.

**Gouvernance — règles côté écriture qui font respecter le GEP :**
- **Raison obligatoire** (fait respecter **GEP-9** + **GEP-2**) : chaque création *et* modification doit inclure une `reason` forensique.
- **Lien vers la preuve** (fait respecter **GEP-2**) : chaque création doit citer au moins une référence `database:table:rowid`.
- **Estampillé Eye / lecture seule pour les autres** (fait respecter **GEP-7** + **GEP-9**) : Eye appose sa signature d'auteur + sa raison + l'historique des modifications et ne peut modifier **que ce qu'Eye a créé** — les règles intégrées et créées par l'humain restent en **lecture seule**.

### Contexte auto-réparateur

Les enquêtes longues peuvent dépasser la fenêtre de contexte d'un modèle — en particulier les modèles hors ligne plus petits. Plutôt que de planter ou de supprimer silencieusement des preuves, Eye **compacte automatiquement son propre contexte** avant chaque appel au modèle (dans son chemin de génération protégé, entièrement audité).

Avant chaque appel, Eye mesure le payload complet et réserve de la place pour la réponse (**10 %** de la fenêtre, minimum 512 jetons, jamais plus de la moitié). Si cela ne tient toujours pas, il se répare en deux passes ordonnées, sans jamais toucher aux messages **protégés** (épinglés, preuves auto-détectées, ou résultat d'outil) :

1. **Passe de résumé** *(une fois)* — l'historique non protégé est condensé en un seul résumé, journalisé `SUMMARIZED`.
2. **Passe de suppression** — le message **non protégé le plus ancien** est retiré un à un jusqu'à ce que cela tienne, journalisé `TRUNCATED`.

Si le **noyau de preuves irréductible** (épinglé + résultats d'outils + la question en cours) *déborde* encore, Eye **refuse de continuer plutôt que de tronquer les preuves** (`REFUSED_OVERFLOW`) et vous demande de restreindre la requête ou d'utiliser `analyze_large_dataset`. Ce qui finit par être envoyé au modèle est exactement le payload qui est scellé pour la chaîne de traçabilité.

### 🗺️ Carte narrative — La mémoire persistante de l'affaire pour Eye

L'Eye est **sans état entre les tours** — c'est donc la **carte narrative** qui conserve « ce que nous savons et ce que nous avons conclu » pour une affaire. C'est la **mémoire de travail persistante, vérifiable et infalsifiable** d'Eye, et son contenu est **injecté dans le prompt d'Eye à chaque tour** (la carte *est* littéralement la mémoire).

- 🧭 **Verdict → Récit → Preuve.** Une hiérarchie stricte : un **Verdict** d'affaire, les **Récits** en dessous (affirmations, chacune avec un état — `proven` · `open` · `negative` · `needs` · `absolute`), et les **Preuves** adossées aux artefacts en dessous.
- 🪟 **Sa propre fenêtre.** S'ouvre depuis le bouton **« Carte narrative »** dans la fenêtre de chat d'Eye, afin que vous puissiez regarder le chat, le rapport vivant et la mémoire de l'affaire côte à côte ; elle se rafraîchit en direct à mesure que les choses changent.
- ↔️ **Bidirectionnelle — une mémoire que vous commandez.** Les modifications d'Eye comme vos propres notes passent par un **commit unique validé GEP** et sont scellées dans un **journal d'audit chaîné par hachage** (`narrative_map_audit.jsonl`). Vous pouvez **ajouter, modifier et supprimer** ses affirmations et preuves, façonnant directement la manière dont Eye comprend et interprète l'affaire.
- 🚫 **N'affirme jamais ce qui n'est pas étayé.** Un récit d'Eye peut rester `open` sans preuve pendant qu'il enquête, mais il ne peut jamais être `proven` sans preuve ; un thème qu'Eye a vérifié mais trouvé vide se convertit automatiquement en **`negative`** — car une absence documentée est elle-même un constat.

### Comment fonctionne la conformité

La conformité n'est pas une fonctionnalité ajoutée par-dessus — elle est appliquée dans le pipeline.

- **🔗 Chaîne de traçabilité (sceau de preuve).** Chaque payload qu'Eye envoie à un LLM est scellé : le **SHA-256 des octets exacts**, le nombre de jetons, le modèle + sa limite de contexte, et la provenance de chaque ligne de preuve (`database:table:rowid`, plus les décalages calculés pour les enregistrements MFT). Les sceaux sont **en ajout seul et chaînés par hachage** vers `<case>/EYE_Logs/eye_payload_seal.jsonl` — un seul enregistrement modifié ou supprimé brise la chaîne, de sorte que le journal prouve *mathématiquement* quels octets le modèle a analysés.
- **🚫 Aucune troncature silencieuse.** Lorsque le contexte devient serré, Eye [s'auto-répare](#self-healing-context) et réalloue les budgets dans un ordre strict : **Priorité 1 (immuable) : preuves brutes + prompt système** › **Priorité 2 (sacrificielle) : conversation informelle** › **Priorité 3 (flexible) : contexte RAG**. Si le noyau de preuves ne tient toujours pas, Eye refuse plutôt que de supprimer silencieusement des preuves.
- **🧾 Piste d'audit de troncature.** Chaque décision de contexte est journalisée dans `<case>/EYE_Logs/truncation_audit.log` (`SUMMARIZED`, `TRUNCATED`, `PRESERVED`, `PINNED`, `UNPINNED`, `BUDGET_REDUCED`), chacune avec un hachage. Les preuves détectées sont automatiquement épinglées au-dessus d'un seuil de confiance ; vous pouvez aussi épingler des messages manuellement.
- **📑 Mandat preuve-vers-rapport.** Eye doit répondre dans le chat **et** consigner les preuves à l'appui dans le rapport ; l'absence de consignation des preuves est signalée comme une violation de protocole.
- **⚖️ Gouvernance de la corrélation.** Toute Wing ou mapping créé par Eye doit inclure une `reason` forensique et des `related_evidence` ; les règles créées en dehors d'Eye sont en lecture seule et ne peuvent pas être réécrites silencieusement.
- **🔐 Confidentialité et air-gapping.** En modes hors ligne, Eye effectue **zéro appel sortant** ; les clés API cloud vivent dans les trousseaux natifs du système d'exploitation — jamais codées en dur, jamais écrites dans les journaux.

📖 **Architecture complète d'Eye :** [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

## 📖 Eye-Describe — Base de connaissances des artefacts au niveau octet

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

Historiquement, les enquêteurs tombaient dans le piège de faire confiance à leurs outils forensiques sans comprendre comment les artefacts sous-jacents se comportent ni comment l'outil les a analysés. Le risque aujourd'hui est simplement de remplacer *« l'outil »* par *« l'IA »*. Une IA peut analyser un enregistrement avec une précision technique parfaite et pourtant le placer dans le mauvais contexte — changeant tout le sens de la preuve.

**Eye-Describe** existe pour que ni l'humain ni le modèle n'aient à deviner. C'est une référence interactive, au niveau octet, des structures binaires brutes des artefacts Windows, et elle remplit deux rôles à la fois :

| Rôle | Ce qu'il fait |
|---|---|
| 🧑‍🏫 **Le plan pour l'humain** | Une référence pédagogique interactive sur l'anatomie profonde au niveau octet des artefacts Windows — ce qu'est chaque structure, comment elle se comporte, ce qu'elle peut et ne peut pas prouver. Gratuit à utiliser, destiné aux étudiants, enseignants et praticiens qui veulent comprendre la preuve plutôt que la colonne de sortie. |
| ⚖️ **L'ancre de conformité pour l'IA** | La visibilité d'Eye est liée aux comportements documentés des artefacts dans Eye-Describe. Le modèle raisonne contre une référence codée en dur de ce qu'un artefact *signifie réellement*, plutôt que d'inférer la sémantique par lui-même. |

En ancrant la couche IA aux comportements documentés des artefacts, Crow-Eye ne vous demande pas de faire confiance à un modèle — il contraint le modèle à respecter la criminalistique brute.

> **Ne remplacez pas la confiance dans l'outil par la confiance dans l'IA. Comprenez les données.**

## 🧪 Qualité et validation

Un outillage forensique n'est utile que si sa sortie peut être défendue. Le travail de correction de Crow-Eye est délibérément visible :- **Suites de régression.** Le moteur de corrélation est verrouillé par une suite pytest couvrant l'analyse des horodatages, la normalisation des identités, la propagation multi-horodatage, le contrat d'écriture, la création Eye (gouvernance GEP côté écriture) et le registre des champs standard. Le moteur UBA dispose de sa propre suite, incluant une exécution de bout en bout sur un cas réel.
- **Harnais de validation.** Un harnais global exerce les 7 ailes par défaut sur **les deux** moteurs avec un cas Windows réel d'environ 700 000 enregistrements.
- **Historique des défauts publié.** Les régressions de précision et leur impact mesuré sont documentés ouvertement dans [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) — y compris les cas où un correctif a modifié les enregistrements vus de plusieurs ordres de grandeur. Savoir ce qui était erroné, et quand, fait partie de ce qui rend un résultat défendable.
- **Comptabilité des preuves vérifiable.** Chaque enregistrement aboutit soit dans une correspondance, soit dans un compartiment d'abandon nommé, et le registre des abandons par fenêtre permet de vérifier « aucune preuve restante » à partir du journal plutôt que de le croire sur parole.
- **Journaux inviolables.** `verify_chain()` re-parcourt le journal d'audit de la Narrative Map et la chaîne de sceaux de preuves pour détecter toute modification — y compris des champs lisibles par l'humain.

## 🔬 Plateforme de recherche

Crow-Eye est plus qu'un logiciel — c'est une **plateforme de recherche ouverte** accélérant l'ensemble du domaine de la criminalistique Windows. Le projet se concentre sur :

- La publication de documentation détaillée sur les structures internes des artefacts.
- Le partage de la logique et des méthodologies de corrélation.
- La facilitation de l'examen par les pairs, de la transparence et de la collaboration académique.
- La contribution à la connaissance collective de la communauté criminalistique.

## 🛠️ Notes techniques

- L'analyse du registre nécessite des fichiers de ruche de registre complets.
- Certains artefacts nécessitent un traitement spécial en raison des mécanismes de verrouillage de fichiers de Windows (voir [Registre personnalisé / fichiers verrouillés](#-supported-artifacts)).
- L'analyse des LNK et des Jump Lists est gérée par le parseur dédié de Crow-Eye.

## 📸 Captures d'écran

Une sélection des vues d'interface et d'analyse de Crow-Eye.

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/d631f2359d186d47eab815cc199d2c08c7c098cb8c64509d7c43185b6413d537.png)

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/140bd5b574f8b2d239f45be6b9d238a592da1cf3b7e6a0cf0a7450a653a75b88.png)

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b7593c596ea437f84cdf476c147fc363a9a87fd821023b2c93559cdc56ceebee.png)

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b67e55fc8c3bc87a5357add66c97e2b5d75310fe7ea5c1f571f5e8938c0a25ae.png)

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/8f10355f7d0f9f31e2e270ecf43fa70e94a6eda3b84b792d28479e0552eec000.png)

![Capture d'écran Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/7bbf1b790d445d33a392b023cc14877e8ee0c72ed2aeec1aba1663da7d0419a2.png)

🎥 **Vidéo de démonstration :** [![Regarder la démo](https://assets.kitploit.com/production/public/readmes/9931/01aa6e4b5fb8732512fe81143b1dcd87d908401369284bad8cfaf1b119fcbf41.jpg)](https://youtu.be/hbvNlBhTfdQ)

## 🚧 Feuille de route

Travaux planifiés et en cours (voir [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) pour les changements livrés) :

- 📊 **Vues GUI et rapports avancés** — visualisation et reporting plus riches.
- 🔄 **Boîte de dialogue de recherche améliorée** — filtrage avancé avec prise en charge du langage naturel.
- 🎯 **Mappage sémantique amélioré** — mappage complet des champs sur tous les types d'artefacts.
- 📈 **Score de corrélation avancé** — score de confiance affiné et explicable.
- ⚡ **Corrélation parallèle** — répartition par pool de processus, activée par défaut pour les charges de travail importantes.

Vous avez une idée ou souhaitez ajouter un artefact ? [Ouvrez un problème](https://github.com/Ghassan-elsman/Crow-Eye/issues) ou consultez [Contribuer](#-contributing).

## 📚 Documentation

- **[TECHNICAL_DOCUMENTATION.md](https://github.com/ghassan-elsman/crow-eye/blob/main/TECHNICAL_DOCUMENTATION.md)** — architecture, composants et guide de développement.
- **[RELEASE_NOTES.md](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md)** — les nouveautés de chaque version (UBA, Narrative Map, backends Eye cloud, durcissement de la gestion des cas, …).
- **[Documentation du moteur de corrélation](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — aperçu, moteur, feathers, wings, pipelines.
- **[Architecture de la chronologie](https://github.com/ghassan-elsman/crow-eye/blob/main/timeline/ARCHITECTURE.md)** — détails internes du module de chronologie.
- **[Architecture Eye](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md)** et **[norme GEP](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md)** — l'assistant IA et son protocole de gouvernance.

## 🤝 Contribuer

Crow-Eye est conçu comme une plateforme de recherche ouverte, et les contributions sont les bienvenues — nouveaux parseurs, règles de corrélation, documentation et recherche sur les artefacts.

- **Contributions générales :** [CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/CONTRIBUTING.md)
- **Moteur de corrélation (domaine prioritaire) :** [correlation_engine/CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)
- **Contact :** [[email protected]](mailto:[email protected]) · ou ouvrez un problème / une demande de tirage.

## 🌐 Site web et communauté

- 🌍 **Site web officiel :** [crow-eye.com](https://crow-eye.com/) — ressources, documentation et téléchargements.
- 💬 **Discord :** [Rejoignez le Discord Crow-Eye](https://discord.gg/2vag2Udf) — aide directe, recherche sur les artefacts et annonces de versions.

## 📄 Licence

Crow-Eye est publié sous la **[GNU General Public License v3.0](https://github.com/ghassan-elsman/crow-eye/blob/main/LICENSE)** (GPL-3.0). Il est libre d'utilisation, d'étude, de partage et de modification selon les termes de cette licence.

## 📝 Citer Crow-Eye

Si vous utilisez Crow-Eye dans un travail académique, une recherche publiée ou un rapport de cas, veuillez le citer :```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

Pour les citations méthodologiques, le protocole Ghassan Elsman est documenté séparément dans [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

## 💖 Soutien

Crow-Eye est gratuit et open-source, développé et maintenu par une seule personne. S'il vous aide dans votre travail, merci d'envisager de sponsoriser — cela finance directement de nouveaux parseurs et de la recherche : **[SPONSORS.md](https://github.com/ghassan-elsman/crow-eye/blob/main/SPONSORS.md)** · **[GitHub Sponsors](https://github.com/sponsors/Ghassan-elsman)**.

## Crédits

Créé et maintenu par **Ghassan Elsman**.