labfy-investigation/README.md

542 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Labfy Investigation
> [!IMPORTANT]
> **Forgejo est le dépôt principal du projet.**
>
> Le code peut également être publié sur GitHub comme miroir public, mais le suivi du développement, les tickets, les décisions techniques et la feuille de route se trouvent sur :
>
> **https://git.labfytools.com/fy59/labfy-investigation**
>
> Tickets :
>
> **https://git.labfytools.com/fy59/labfy-investigation/issues**
>
> Les tickets et pull requests ouverts uniquement sur GitHub risquent de ne pas être suivis.
Labfy Investigation est un poste de travail libre dinvestigation numérique et dOSINT, développé en **C17** avec **GTK4**.
Le projet vise à fournir un environnement local, modulaire et traçable pour organiser une enquête, préserver les preuves originales, analyser des données, corréler des entités et produire des rapports exploitables.
La fiche dune preuve permet aussi de consigner une appréciation humaine
dauthenticité documentaire. Cet historique est immuable, justifié selon le
statut choisi et ne peut jamais être produit automatiquement par lOCR.
Les seules valeurs OCR pouvant alimenter un profil de personne sont celles
confirmées par un humain, sélectionnées sans choix par défaut puis validées
avec une cible et une stratégie de conflit explicites.
La fiche personne relit ensuite ces champs structurés depuis SQLite.
> **État du projet : développement actif**
>
> Le logiciel nest pas encore prêt pour un usage opérationnel en production. Les formats internes, linterface et les mécanismes dintégration peuvent encore évoluer.
---
## Objectifs
Labfy Investigation doit permettre de :
- créer et ouvrir une enquête autonome ;
- conserver les preuves originales sans les modifier ;
- organiser les fichiers, entités, relations et événements ;
- stocker les données structurées dans SQLite ;
- afficher larborescence complète dune enquête ;
- exécuter des traitements longs en arrière-plan ;
- intégrer progressivement des outils OSINT externes ;
- conserver les sorties brutes, les versions et les paramètres dexécution ;
- analyser localement des messages EML et inventorier leurs pièces jointes
sans modifier la preuve originale ;
- conserver les propositions IBAN/BIC avec leur provenance et leur statut de
vérification ;
- distinguer les faits observés, les résultats doutils, les corrélations et les hypothèses ;
- produire des rapports compréhensibles et traçables.
Le logiciel est pensé pour des usages légaux par des particuliers, journalistes, analystes OSINT, experts judiciaires et forces de lordre.
---
## Cadre légal et éthique
Labfy Investigation est conçu pour travailler avec :
- des sources publiquement accessibles ;
- des données fournies légalement par une victime ou un enquêteur ;
- des API utilisées conformément à leurs autorisations ;
- des recherches passives ou explicitement autorisées ;
- des copies locales dont la provenance peut être documentée.
Le projet na pas vocation à fournir ou automatiser :
- lintrusion dans un système ;
- le contournement dune authentification ;
- lexploitation de vulnérabilités ;
- le brute force ou le credential stuffing ;
- le phishing ou lusurpation ;
- lutilisation de secrets découverts ;
- laccès à des données privées sans autorisation ;
- la modification ou la suppression de données distantes.
Un résultat produit par un outil OSINT constitue une **piste à vérifier**, pas une preuve didentité à lui seul.
---
## Principes fondamentaux
### Une enquête est autonome
Chaque enquête est stockée dans un dossier transportable :
```text
MonEnquete/
├── 00_BaseDeDonnees/
│ └── Enquete.sqlite
├── 01_Preuves_Originales/
├── 02_Preuves_Traitees/
├── 03_Chronologie/
├── 04_Entites/
└── 05_Rapports/
```
Une enquête peut être copiée, déplacée, sauvegardée, archivée ou transmise avec ses données.
### Les preuves originales sont immuables
Toute annotation, conversion, extraction ou analyse doit produire un nouveau fichier. Une preuve originale ne doit jamais être modifiée.
### SQLite est la source de vérité
Les tableaux, graphes, chronologies et résultats de recherche sont des vues différentes des mêmes données persistées.
### Les résultats bruts et normalisés sont séparés
Chaque traitement doit conserver :
- loutil utilisé ;
- sa version ;
- les arguments ;
- la date et lheure UTC ;
- la source interrogée ;
- la sortie brute ;
- lempreinte des fichiers produits ;
- les données normalisées utilisées par lapplication.
### Linterface ne doit jamais être bloquée
Les opérations longues doivent sexécuter en arrière-plan et rester annulables.
### Aucun shell construit dynamiquement
Les outils externes sont lancés avec `GSubprocess` et des arguments séparés. Les commandes concaténées puis transmises à un shell sont interdites.
---
## Fonctionnalités déjà présentes
La création dune personne et limport normal dune preuve proposent un OCR
contrôlé des documents didentité. Il ne démarre que sur action explicite,
travaille sur une copie vérifiée PNG, JPEG, HEIC, HEIF ou sur une page PDF
choisie, et conserve séparément le texte OCR brut immuable et une transcription
corrigée rééditable et réinitialisable. Les propositions restent révisables :
elles peuvent être acceptées, corrigées à nouveau, restaurées depuis leur
valeur brute ou rejetées. Un champ visible mais omis par lOCR peut être saisi
avec lorigine `manual_entry` ; une correction dune valeur extraite conserve
lorigine `manual_override`. Des notes factuelles peuvent signaler un document
tronqué, flou, masqué ou incomplet, sans reconstruire une zone absente.
La fiche directe dune preuve relit depuis SQLite le texte brut, la
transcription corrigée, les exécutions `OcrRun`, observations, champs, notes,
artefacts, empreintes SHA-256, personne liée et provenance graphique. Un run
est sélectionné explicitement lorsquun historique en contient plusieurs.
« Réviser lanalyse OCR » modifie uniquement ce run sans relancer Tesseract ;
« Relancer une nouvelle analyse » crée un nouveau run sans écraser
lhistorique.
Limport multiple sans OCR reste disponible. LOCR groupé nest pas pris en
charge : les preuves importées ensemble sont ensuite analysées une par une
depuis leur fiche, sur leur UUID définitif et sans doublon. Aucun de ces
parcours ne produit de verdict dauthenticité, de reconnaissance faciale, de
fusion de personne, didentité certaine ou de rôle dauteur automatique.
Le socle actuel comprend notamment :
- création et ouverture denquêtes ;
- validation de larborescence ;
- sessions denquête remplaçables proprement ;
- base SQLite versionnée ;
- transactions et remontée structurée des erreurs ;
- DAO et modèles denquête ;
- arborescence des fichiers ;
- fenêtre principale GTK4 ;
- barre latérale et espace de travail ;
- navigation et recherche locale des entités dans la barre latérale ;
- navigation et recherche locale des relations dans la barre latérale ;
- affichage graphique des erreurs ;
- tâches asynchrones annulables ;
- gestionnaire de tâches ;
- panneau dactivité GTK ;
- import groupé de preuves avec confirmation globale, révision individuelle,
copie contrôlée, empreinte SHA-256 et bilan détaillé ;
- correction du type, de la source et de la description d'une preuve avec
contrôle d'intégrité et déplacement cohérent de sa copie interne ;
- registre doutils externes ;
- exécution sécurisée par `GSubprocess` ;
- exécution doutils en tâche de fond ;
- catalogue initial doutils ;
- détection de présence et de version ;
- menu OSINT contextuel préparé pour les entités et relations du graphe ;
- contexte de sélection OSINT indépendant de GTK et validé par des tests ;
- catalogue déterministe des actions compatibles avec la sélection OSINT ;
- disponibilité des actions OSINT synchronisée avec le registre doutils ;
- résolution DNS asynchrone avec `dig` depuis une entité domaine ;
- affichage sélectionnable des sorties standard et derreur, sans persistance ;
- révision des réponses DNS sous forme de propositions avant intégration ;
- sélection explicite et intégration transactionnelle des propositions DNS
compatibles, avec normalisation et détection des doublons ;
- création transactionnelle des relations DNS `resolves_to`, `aliases_to` et
`uses_name_server` depuis l'entité interrogée ;
- provenance OSINT SQLite V3 conservant les arguments, sorties brutes,
empreinte SHA-256 et liaisons vers les entités et relations intégrées ;
- comptes sociaux structurés en SQLite V4 (TikTok, Instagram, Facebook, X,
Telegram ou autre), avec URL, pseudonyme, identifiant stable facultatif,
première observation, état, notes et rattachement à une preuve ;
- pictogrammes vectoriels des plateformes sociales dans les nœuds du graphe,
conservant leur lisibilité pendant le zoom ;
- création de personnes observées avec statut d'identification, confiance,
notes factuelles et rattachement facultatif à une preuve ;
- catégories d'enquête des personnes en SQLite V5, modifiables depuis leur
fiche et représentées par une couleur et un libellé dans le graphe ;
- relations représentées par des flèches directes à libellé cliquable, sans
ajouter de faux nœud visuel entre les entités ;
- historique OSINT contextuel en lecture seule avec détail des exécutions,
sorties standard et d'erreur, et objets créés ou réutilisés ;
- vérification manuelle de l'intégrité des sorties OSINT enregistrées, sans
réécriture de l'empreinte ou des données contrôlées.
- glisser-déposer des extractions texte depuis l'arborescence vers le graphe,
avec confirmation explicite, création d'entité ou rattachement à une entité
existante, sans déplacement du fichier produit ;
- pivot forensique EML : contrôle SHA-256 avant analyse, lecture des en-têtes,
extraction MIME récursive, inventaire des pièces jointes et analyse locale
facultative par PDF, OCR et ExifTool ;
- propositions bancaires issues du texte ou de l'OCR, avec validation IBAN/BIC
avant toute conservation ;
- observations EML persistantes dans la fiche de preuve, sans création
automatique d'un nœud ;
- promotion facultative et explicite d'une observation vers une entité du
graphe, puis retrait réversible conservant l'observation.
- propriété persistante V13 des rattachements preuve-entité : un retrait EML
ne supprime que la source de l'observation concernée.
- assistant de création dune personne avec sélection multiple de preuves
existantes et import multiple différé : les nouveaux fichiers sont copiés
dans un staging temporaire, qualifiés individuellement et ne deviennent
définitifs quaprès confirmation globale ;
- rattachement transactionnel de toutes les preuves retenues, avec rollback
SQLite et suppression compensatoire des copies définitives en cas déchec.
- aperçu asynchrone contrôlé PNG/JPEG, HEIC/HEIF, MP4/MOV, texte, EML et PDF
multipage, avec zoom de 25 à 400 %, ajustement, défilements horizontal et
vertical, navigation et compteur de pages ; la provenance OCR reste alignée
avec la page, le zoom et le défilement ;
Les dialogues métiers complexes suivent une politique GTK commune : parent
réel via `transient_for`, modalité adaptée et présentation sans coordonnées
absolues sous Wayland. Ils visent 1200 × 800, avec un minimum utile de
800 × 600 lorsque la zone de travail le permet, un formulaire défilable à
gauche sur environ deux tiers, un aperçu redimensionnable à droite et une
barre dactions fixe. Les alertes simples, popups `GtkDropDown` et sélecteurs
de fichiers natifs ne sont pas concernés.
### Pivot EML
L'action « Analyser l'e-mail » vérifie d'abord que l'empreinte SHA-256 de la
preuve correspond à celle enregistrée. Le pipeline lit ensuite les en-têtes,
parcourt la structure MIME et présente les pièces jointes, textes PDF ou OCR,
métadonnées ExifTool et propositions bancaires disponibles.
Une proposition cochée avec « Conserver dans la fiche » devient une
observation persistante liée à la preuve. Cette confirmation normale ne crée
ni entité, ni nœud, ni rattachement `preuve_entites`. « Promouvoir en entité »
est une décision séparée, facultative et désactivée par défaut. Une promotion
peut ensuite être retirée du graphe sans supprimer l'observation ; une entité
encore utilisée par une autre observation, une autre preuve ou une relation
est conservée.
Les outils documentaires sont optionnels : leur absence produit un résultat
partiel sans empêcher la lecture des en-têtes ni l'extraction MIME. Les
métadonnées sensibles, notamment GPS, sont signalées et ne sont jamais
promues automatiquement.
Les outils actuellement présents dans le catalogue initial sont :
```text
dig
host
whois
curl
openssl
```
Ils restent optionnels : labsence dun outil ne doit pas empêcher Labfy Investigation de démarrer.
---
## Architecture
Le projet sépare strictement les responsabilités :
```text
Interface GTK4
Application
Services métier
Adaptateurs
├── SQLite
├── système de fichiers
├── outils CLI
└── futures API
```
Règles principales :
- le cœur métier ne dépend pas de GTK ;
- les widgets ne manipulent ni SQLite ni les preuves ;
- les modèles ne connaissent ni GTK ni SQLite ;
- les erreurs remontent jusquà lapplication ;
- chaque allocation possède une responsabilité de libération claire ;
- les tests du cœur ne doivent pas nécessiter le lancement de GTK.
Organisation actuelle :
```text
database/ Ressources et éléments liés à la base
docs/ Architecture, conventions et feuille de route
include/core/ Interfaces du cœur
include/dao/ Interfaces daccès aux données
include/database/ Infrastructure SQLite
include/models/ Modèles métier
include/views/ Fenêtres GTK
include/widgets/ Widgets réutilisables
resources/ Ressources de lapplication
src/core/ Implémentation du cœur
src/dao/ Accès aux données
src/database/ Implémentation SQLite
src/models/ Modèles métier
src/views/ Vues GTK
src/widgets/ Widgets GTK
tests/ Tests unitaires
```
La documentation détaillée se trouve dans :
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md)
- [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)
- [`docs/ROADMAP.md`](docs/ROADMAP.md)
- [`docs/database/`](docs/database/)
---
## Environnements ciblés
### Ubuntu
Ubuntu est la cible principale de distribution, notamment pour un futur déploiement auprès des forces de lordre.
Dépendances de compilation :
```bash
sudo apt update
sudo apt install build-essential pkg-config libgtk-4-dev libglib2.0-dev libsqlite3-dev
```
La disponibilité réelle des paquets devra être vérifiée sur les postes utilisant des dépôts institutionnels restreints.
### Arch Linux
Arch Linux est lenvironnement principal de développement et de validation.
```bash
sudo pacman -S --needed base-devel pkgconf gtk4 glib2 sqlite
```
Les paquets AUR ne devront jamais devenir une dépendance obligatoire du futur paquet Ubuntu.
---
## Compilation
Depuis la racine du dépôt :
```bash
make -j8
```
Le binaire produit est :
```text
./labfy-investigation
```
Lancer lapplication :
```bash
make run
```
Nettoyer les fichiers générés :
```bash
make clean
```
Le projet est compilé en C17 avec les avertissements traités comme des erreurs.
Lassistant de création dune personne suit sept étapes distinctes :
`Personne`, `Rôles`, `Preuves`, `OCR identité`, `Projection OCR`,
`Relations factuelles`, puis `Confirmation`. La révision OCR conserve les
valeurs brute, normalisée, corrigée et confirmée avant toute projection. La
projection et les relations sont facultatives, vides par défaut et résumées
séparément avant lunique écriture transactionnelle finale.
Le schéma SQLite courant est la V20. Une création neuve installe directement
les extensions V19 et V20 ; une base V19 utilise `database/schema_v20.sql`.
La fiche de preuve sépare lauthenticité de lévaluation humaine de lusage
didentité, dont lhistorique est append-only et jamais produit par lOCR.
---
## Tests
Lancer tous les tests :
```bash
make -j8 test
```
Vérifications recommandées avant chaque commit :
```bash
make clean
make -j8
make check-source-size
DISPLAY="$DISPLAY" WAYLAND_DISPLAY="$WAYLAND_DISPLAY" make -j8 test
git diff --check
```
Les nouveaux modules doivent être accompagnés de tests couvrant :
- les arguments invalides ;
- le fonctionnement nominal ;
- les erreurs ;
- lannulation lorsque nécessaire ;
- les responsabilités mémoire ;
- les régressions possibles.
Les parcours GTK OCR et aperçu doivent aussi être exécutés séparément sur un
poste avec affichage :
```bash
G_DEBUG=fatal-criticals timeout 30s ./tests/test_create_person_dialog_ocr_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_evidence_identity_import_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_workspace_identity_ocr_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_evidence_preview_widget_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_dialog_geometry_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_person_factual_relation_editor_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_document_authenticity_editor_gtk
G_DEBUG=fatal-criticals timeout 30s ./tests/test_person_ocr_projection_editor_gtk
```
Les tests emploient uniquement des documents `SPECIMEN`, des fichiers
temporaires et des bases SQLite temporaires fermées puis rouvertes. Un `SKIP`
lié à labsence daffichage ne remplace pas cette validation GTK réelle.
---
## Développement
Conventions essentielles :
- C17 uniquement ;
- fichiers et fonctions en `snake_case` ;
- fonctions préfixées par leur module ;
- noms de variables explicites ;
- aucune logique métier dans les widgets ;
- aucun commit tant que la fonctionnalité ne compile pas et ne fonctionne pas ;
- compilation sans avertissement ;
- tests valides avant intégration.
Exemples de préfixes :
```text
database_*
investigation_*
task_manager_*
tool_registry_*
tool_process_*
tool_catalog_*
```
---
## Outils OSINT externes
Le ticket historique **#42** reste ouvert comme inventaire évolutif des outils OSINT potentiels.
Les outils ne sont pas intégrés en masse. Lorsquun besoin concret apparaît :
1. un ticket Forgejo dédié est créé ;
2. loutil est audité techniquement et juridiquement ;
3. sa compatibilité Ubuntu et Arch est vérifiée ;
4. son adaptateur est développé ;
5. ses sorties brutes et normalisées sont testées ;
6. son état est mis à jour dans linventaire.
Aucun outil absent nest installé automatiquement par lapplication.
---
## Suivi du projet
Les tickets sont désormais suivis directement dans Forgejo :
```text
https://git.labfytools.com/fy59/labfy-investigation/issues
```
Les tickets historiques jusquau numéro 40 conservent leur numérotation. Les nouveaux tickets utilisent uniquement le numéro attribué automatiquement par Forgejo.
Le prochain chantier porte sur linitialisation asynchrone du registre et des versions doutils au démarrage.
---
## État du packaging
Le packaging nest pas encore finalisé.
Les cibles prévues sont :
- paquet `.deb` pour Ubuntu ;
- dossier source accompagné dun script de compilation ;
- procédure de développement et de test pour Arch Linux.
Le futur installateur Ubuntu devra fonctionner autant que possible sans dépendre de dépôts non standards.
---
## Contribution
Avant toute modification :
1. consulter les tickets ouverts ;
2. lire larchitecture et les conventions ;
3. limiter chaque changement à un objectif cohérent ;
4. ajouter ou adapter les tests ;
5. vérifier la compilation complète ;
6. documenter toute dérogation architecturale.
---
## Licence
Labfy Investigation est distribué sous licence MIT.
Voir le fichier `LICENSE` pour les conditions complètes.