voight-kampff-forensics 0.1.0.dev0__py3-none-any.whl

voight_kampff/_travail/__main__.py

@@ -0,0 +1,7 @@
+"""Point d'entrée du processus de travail : ``python -I -B -m voight_kampff._travail``."""
+
+import sys
+
+from voight_kampff._travail.principal import canal_du_protocole, principal
+
+sys.exit(principal(sys.argv[1:], sys.stdin.buffer, canal_du_protocole()))

voight_kampff/_travail/contexte.py

@@ -0,0 +1,179 @@
+"""Contexte remis à chaque module : lecture du fichier et réception des résultats (ADR-0061).
+
+Les résultats d'un module restent dans son contexte jusqu'à ce qu'il rende la main ; s'il lève
+une exception, ils sont écartés (ADR-0060). Le contexte construit les objets du modèle, qui
+vérifient leurs invariants, et numérote les observations ``<module>/<n>``.
+"""
+
+from collections.abc import Collection, Mapping, Sequence
+
+from voight_kampff._protocole import TAILLE_MAX_MESSAGE, encoder
+from voight_kampff._travail import garde
+from voight_kampff._travail.fichier import Fichier
+from voight_kampff.rapport.modele import (
+    Categorie,
+    CategorieIdentifiante,
+    Constat,
+    Direction,
+    Fondement,
+    Graduation,
+    Localisation,
+    NonMenee,
+    Observation,
+    Phrase,
+    RaisonNonMenee,
+    ReferenceRegle,
+    Scalaire,
+)
+
+__all__ = ["RAISONS_D_UN_MODULE", "Contexte", "LimiteDepassee"]
+
+RAISONS_D_UN_MODULE = frozenset(
+    {
+        RaisonNonMenee.FORMAT_PARTIEL,
+        RaisonNonMenee.FICHIER_TRONQUE,
+        RaisonNonMenee.REFERENCE_MANQUANTE,
+        RaisonNonMenee.RESEAU_DESACTIVE,
+    }
+)
+"""Raisons qu'un module peut donner lui-même ; les autres sont produites par le moteur."""
+
+
+class LimiteDepassee(Exception):
+    """Résultats d'un module au-delà des tailles permises par le protocole."""
+
+
+class Contexte:
+    """Ce qu'un module voit du fichier et de l'analyse en cours."""
+
+    __slots__ = (
+        "_budget",
+        "_depasse",
+        "_directions",
+        "_fichier",
+        "_lignes",
+        "_numero",
+        "_observations",
+        "_taille_lignes",
+        "format_reel",
+        "module",
+        "taille",
+    )
+
+    def __init__(
+        self,
+        module: str,
+        directions: Collection[Direction],
+        fichier: Fichier,
+        format_reel: str,
+        taille: int,
+        budget: int,
+    ) -> None:
+        garde.exiger()
+        self.module = module
+        self.format_reel = format_reel
+        """Format identifié par le contenu (T13)."""
+        self.taille = taille
+        """Taille du fichier en octets."""
+        self._directions = frozenset(directions)
+        self._fichier = fichier
+        self._budget = budget
+        self._lignes: list[bytes] = []
+        self._taille_lignes = 0
+        self._numero = 0
+        self._observations: set[str] = set()
+        self._depasse = False
+
+    # Lecture
+
+    def lire(self, position: int, taille: int) -> bytes:
+        """Au plus ``taille`` octets du fichier à partir de ``position`` ; moins en fin."""
+        return self._fichier.lire(position, taille)
+
+    # Résultats
+
+    def observer(
+        self,
+        nom: str,
+        valeur: Scalaire | Sequence[Scalaire],
+        *,
+        unite: str | None = None,
+        localisation: Localisation | None = None,
+        identifiante: CategorieIdentifiante | None = None,
+    ) -> str:
+        """Enregistre une observation et renvoie son identifiant, à citer dans un constat."""
+        identifiant = f"{self.module}/{self._numero + 1}"
+        observation = Observation(
+            identifiant,
+            self.module,
+            nom,
+            valeur if isinstance(valeur, str | int | float | bool) else tuple(valeur),
+            unite=unite,
+            localisation=localisation,
+            identifiante=identifiante,
+        )
+        self._ajouter({"type": "observation", "observation": observation.vers_dict()})
+        self._numero += 1
+        self._observations.add(identifiant)
+        return identifiant
+
+    def constater(
+        self,
+        phrase: Phrase,
+        donnees: Sequence[str],
+        regle: ReferenceRegle,
+        *,
+        fondement: Fondement,
+        categorie: Categorie,
+        direction: Direction,
+        graduation: Graduation | None = None,
+        localisation: Localisation | None = None,
+    ) -> None:
+        """Enregistre un constat ; ses données sont des observations de ce module."""
+        if direction not in self._directions:
+            raise ValueError("constat : direction non permise par la fiche technique")
+        if not set(donnees) <= self._observations:
+            raise ValueError("constat.donnees : observation inconnue de ce module")
+        constat = Constat(
+            phrase,
+            tuple(donnees),
+            regle,
+            self.module,
+            fondement,
+            categorie,
+            direction,
+            graduation=graduation,
+            localisation=localisation,
+        )
+        self._ajouter({"type": "constat", "constat": constat.vers_dict()})
+
+    def non_mener(
+        self, raison: RaisonNonMenee, *, localisation: Localisation | None = None
+    ) -> None:
+        """Signale une partie de l'analyse que le module n'a pas pu mener."""
+        if raison not in RAISONS_D_UN_MODULE:
+            raise ValueError("non_menee.raison : réservée au moteur")
+        non_menee = NonMenee(raison, self.module, localisation)
+        self._ajouter({"type": "non_menee", "non_menee": non_menee.vers_dict()})
+
+    # Pour le moteur
+
+    @property
+    def depasse(self) -> bool:
+        """Vrai si le module a dépassé une limite, même s'il a intercepté l'exception."""
+        return self._depasse
+
+    @property
+    def lignes(self) -> tuple[bytes, ...]:
+        """Messages encodés, dans l'ordre où le module les a produits."""
+        return tuple(self._lignes)
+
+    def _ajouter(self, message: Mapping[str, object]) -> None:
+        if self._depasse:
+            raise LimiteDepassee
+        ligne = encoder(message)
+        if len(ligne) > TAILLE_MAX_MESSAGE or self._taille_lignes + len(ligne) > self._budget:
+            self._depasse = True
+            raise LimiteDepassee
+        self._lignes.append(ligne)
+        self._taille_lignes += len(ligne)

voight_kampff/_travail/fichier.py

@@ -0,0 +1,64 @@
+"""Accès du processus de travail au fichier analysé, par le descripteur hérité (ADR-0036)."""
+
+import hashlib
+import os
+import sys
+
+from voight_kampff._protocole import TAILLE_MAX_LECTURE
+
+__all__ = ["Fichier", "ouvrir_herite"]
+
+_BLOC = 1 << 20
+
+
+def ouvrir_herite(valeur: int) -> int:
+    """Descripteur du fichier transmis par le processus principal.
+
+    Sous Windows, le processus principal transmet un handle, converti ici en descripteur.
+    """
+    if sys.platform == "win32":  # pragma: no cover - exécuté par la CI Windows
+        import msvcrt
+
+        return msvcrt.open_osfhandle(valeur, os.O_RDONLY | os.O_BINARY)
+    return valeur
+
+
+class Fichier:
+    """Lectures à position explicite : le processus de travail ne dépend d'aucune position."""
+
+    __slots__ = ("_descripteur",)
+
+    def __init__(self, descripteur: int) -> None:
+        self._descripteur = descripteur
+
+    def lire(self, position: int, taille: int) -> bytes:
+        """Au plus ``taille`` octets à partir de ``position`` ; moins en fin de fichier."""
+        if position < 0 or not 0 <= taille <= TAILLE_MAX_LECTURE:
+            raise ValueError("lecture : position ou taille hors bornes")
+        morceaux: list[bytes] = []
+        reste = taille
+        while reste:
+            morceau = self._lire_a(position, reste)
+            if not morceau:
+                break
+            morceaux.append(morceau)
+            position += len(morceau)
+            reste -= len(morceau)
+        return b"".join(morceaux)
+
+    def _lire_a(self, position: int, taille: int) -> bytes:
+        if sys.platform == "win32":  # pragma: no cover - exécuté par la CI Windows
+            # Pas de pread sous Windows. Le processus principal ne lit plus le descripteur
+            # pendant l'analyse : déplacer la position commune ne gêne personne.
+            os.lseek(self._descripteur, position, os.SEEK_SET)
+            return os.read(self._descripteur, taille)
+        return os.pread(self._descripteur, taille, position)
+
+    def empreinte(self) -> tuple[str, int]:
+        """SHA-256 du fichier entier, en hexadécimal minuscule, et sa taille (ES-08, ADR-0040)."""
+        condensat = hashlib.sha256()
+        position = 0
+        while morceau := self._lire_a(position, _BLOC):
+            condensat.update(morceau)
+            position += len(morceau)
+        return condensat.hexdigest(), position

voight_kampff/_travail/garde.py

@@ -0,0 +1,28 @@
+"""Garde des analyseurs : ils refusent de s'exécuter hors d'un processus de travail (ES-17).
+
+Le processus de travail se déclare verrouillé après avoir appliqué ses restrictions et avant
+d'envoyer l'état de l'isolation (ADR-0036). Un programme qui importerait un module d'analyse
+pour l'appeler dans son propre processus est arrêté par :func:`exiger`.
+"""
+
+__all__ = ["HorsProcessusDeTravail", "exiger", "verrouiller"]
+
+_verrouille = False
+
+
+class HorsProcessusDeTravail(RuntimeError):
+    """Analyse demandée hors d'un processus de travail verrouillé."""
+
+
+def verrouiller() -> None:
+    """Déclare le processus courant processus de travail verrouillé ; sans retour arrière."""
+    global _verrouille  # état du processus entier, posé une seule fois
+    _verrouille = True
+
+
+def exiger() -> None:
+    """Lève :class:`HorsProcessusDeTravail` hors d'un processus de travail verrouillé."""
+    if not _verrouille:
+        raise HorsProcessusDeTravail(
+            "les analyseurs ne s'exécutent que dans un processus de travail (ES-17)"
+        )

voight_kampff/_travail/principal.py

@@ -0,0 +1,218 @@
+"""Déroulé du processus de travail (ADR-0036) et acheminement vers les modules (ADR-0042).
+
+1. Importer les modules livrés, tant que le système de fichiers est accessible.
+2. Appliquer les restrictions (T14), se déclarer verrouillé, envoyer l'état de l'isolation :
+   aucun octet du fichier n'a encore été lu.
+3. Lire la configuration : modules actifs, dans l'ordre d'exécution.
+4. Recalculer l'empreinte, identifier le format (T13), exécuter chaque module actif, envoyer
+   ses résultats puis son message « module » (ADR-0062), et enfin les versions et la fin.
+
+Une exception dans un module ne touche que ce module (NF-03, ADR-0060) ; toute autre erreur
+arrête le processus, et le processus principal en fait une analyse non menée.
+"""
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import BinaryIO
+
+from voight_kampff import modules
+from voight_kampff._protocole import (
+    TAILLE_MAX_CONFIGURATION,
+    TAILLE_MAX_SORTIE,
+    encoder,
+)
+from voight_kampff._travail import garde
+from voight_kampff._travail.contexte import Contexte, LimiteDepassee
+from voight_kampff._travail.fichier import Fichier, ouvrir_herite
+from voight_kampff.rapport.modele import (
+    VERSION_SCHEMA,
+    Direction,
+    EtatIsolation,
+    ManqueIsolation,
+    NiveauIsolation,
+    NonMenee,
+    RaisonNonMenee,
+)
+
+__all__ = [
+    "Analyseur",
+    "ModuleConfigure",
+    "canal_du_protocole",
+    "importer",
+    "lire_configuration",
+    "principal",
+]
+
+type Analyseur = Callable[[Contexte], None]
+
+_RESERVE = 64 << 10
+"""Part de la sortie gardée pour les messages du moteur après le dernier module."""
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleConfigure:
+    """Module actif, tel que le processus principal l'a lu dans son manifeste validé."""
+
+    identifiant: str
+    formats: frozenset[str]
+    directions: frozenset[Direction]
+
+
+def canal_du_protocole() -> BinaryIO:
+    """Réserve la sortie standard au protocole et renvoie le flux qui y écrit.
+
+    Un module qui afficherait du texte écrirait ensuite sur la sortie d'erreur, que le processus
+    principal ne lit pas (ES-15) : il ne peut pas glisser une ligne dans le protocole.
+    """
+    canal = os.fdopen(os.dup(sys.stdout.fileno()), "wb")
+    os.dup2(sys.stderr.fileno(), sys.stdout.fileno())
+    sys.stdout = sys.stderr
+    return canal
+
+
+def importer() -> tuple[dict[str, Analyseur], frozenset[str]]:
+    """Importe les modules livrés ; renvoie leurs analyseurs et ceux qui n'ont pas pu l'être.
+
+    Appelé avant les restrictions : après, le code ne peut plus être lu sur le disque.
+    """
+    analyseurs: dict[str, Analyseur] = {}
+    echecs: set[str] = set()
+    for dossier in modules.dossiers():
+        try:
+            code = importlib.import_module(f"{modules.__name__}.{dossier.name}")
+            analyseur = code.analyser
+            if not callable(analyseur):
+                raise TypeError("analyser n'est pas appelable")
+        except Exception:
+            # Le module en échec sera non mené ; les autres continuent (NF-03).
+            echecs.add(dossier.name)
+        else:
+            analyseurs[dossier.name] = analyseur
+    return analyseurs, frozenset(echecs)
+
+
+def lire_configuration(entree: BinaryIO) -> tuple[ModuleConfigure, ...]:
+    """Lit la configuration envoyée par le processus principal (ADR-0065).
+
+    Elle vient d'un processus de confiance : une configuration mal formée est un défaut de
+    l'outil, qui arrête le processus de travail.
+    """
+    ligne = entree.readline(TAILLE_MAX_CONFIGURATION + 1)
+    if not ligne.endswith(b"\n") or len(ligne) > TAILLE_MAX_CONFIGURATION:
+        raise ValueError("configuration : absente ou trop longue")
+    document = json.loads(ligne)
+    if document["version_schema"] != VERSION_SCHEMA:
+        raise ValueError("configuration : version de schéma différente")
+    return tuple(
+        ModuleConfigure(
+            identifiant=str(module["identifiant"]),
+            formats=frozenset(str(f) for f in module["formats"]),
+            directions=frozenset(Direction(d) for d in module["directions"]),
+        )
+        for module in document["modules"]
+    )
+
+
+def _identifier(_fichier: Fichier) -> str | None:
+    """Format réel du fichier ; aucun avant T13, donc aucun module n'est applicable."""
+    return None
+
+
+class _Canal:
+    """Sortie du protocole : une ligne par message, comptée contre la taille maximale."""
+
+    __slots__ = ("_sortie", "envoye")
+
+    def __init__(self, sortie: BinaryIO) -> None:
+        self._sortie = sortie
+        self.envoye = 0
+
+    def envoyer(self, lignes: Sequence[bytes]) -> None:
+        for ligne in lignes:
+            self._sortie.write(ligne)
+            self.envoye += len(ligne)
+        self._sortie.flush()
+
+    def message(self, message: Mapping[str, object]) -> None:
+        self.envoyer((encoder(message),))
+
+
+def _executer(
+    module: ModuleConfigure,
+    analyseur: Analyseur | None,
+    fichier: Fichier,
+    format_reel: str,
+    taille: int,
+    canal: _Canal,
+) -> None:
+    raison: RaisonNonMenee | None = RaisonNonMenee.ERREUR_MODULE
+    contexte: Contexte | None = None
+    if analyseur is not None:
+        budget = TAILLE_MAX_SORTIE - canal.envoye - _RESERVE
+        contexte = Contexte(
+            module.identifiant, module.directions, fichier, format_reel, taille, budget
+        )
+        try:
+            analyseur(contexte)
+        except LimiteDepassee:
+            raison = RaisonNonMenee.LIMITE_DEPASSEE
+        except Exception:  # NF-03 : seul ce module est touché
+            raison = RaisonNonMenee.ERREUR_MODULE
+        else:
+            raison = RaisonNonMenee.LIMITE_DEPASSEE if contexte.depasse else None
+    if raison is None and contexte is not None:
+        canal.envoyer(contexte.lignes)
+    else:
+        # Résultats écartés (ADR-0060) : rien de ce que le module a produit n'est envoyé.
+        non_menee = NonMenee(raison or RaisonNonMenee.ERREUR_MODULE, module.identifiant)
+        canal.message({"type": "non_menee", "non_menee": non_menee.vers_dict()})
+
+
+def principal(
+    argv: Sequence[str],
+    entree: BinaryIO,
+    sortie: BinaryIO,
+    *,
+    analyseurs: Mapping[str, Analyseur] | None = None,
+    identifier: Callable[[Fichier], str | None] = _identifier,
+) -> int:
+    """Analyse le fichier transmis par le processus principal ; renvoie le code de sortie.
+
+    ``analyseurs`` et ``identifier`` remplacent, pour les tests, les modules livrés et
+    l'identification du format.
+    """
+    arguments = argparse.ArgumentParser(prog="voight_kampff._travail")
+    arguments.add_argument("--descripteur", type=int, required=True)
+    descripteur = arguments.parse_args(argv).descripteur
+
+    echecs: frozenset[str] = frozenset()
+    if analyseurs is None:
+        analyseurs, echecs = importer()
+
+    # Restrictions du système : T14. Jusque-là, aucune n'est appliquée et le rapport le dit.
+    isolation = EtatIsolation(NiveauIsolation.REDUITE, tuple(ManqueIsolation))
+    garde.verrouiller()
+    canal = _Canal(sortie)
+    canal.message(
+        {"type": "isolation", "version_schema": VERSION_SCHEMA, "isolation": isolation.vers_dict()}
+    )
+
+    configures = lire_configuration(entree)
+    fichier = Fichier(ouvrir_herite(descripteur))
+    empreinte, taille = fichier.empreinte()
+    format_reel = identifier(fichier)
+    for module in configures:
+        applicable = format_reel is not None and format_reel in module.formats
+        if format_reel is not None and applicable:
+            analyseur = None if module.identifiant in echecs else analyseurs.get(module.identifiant)
+            _executer(module, analyseur, fichier, format_reel, taille, canal)
+        canal.message({"type": "module", "module": module.identifiant, "applicable": applicable})
+    # Versions des bibliothèques qui lisent le fichier : avec le premier module qui en emploie.
+    canal.message({"type": "versions", "dependances": []})
+    canal.message({"type": "fin", "empreinte": empreinte})
+    return 0

voight_kampff/cli.py

@@ -0,0 +1,48 @@
+"""Ligne de commande, installée sous les noms ``voight-kampff`` et ``vk`` (ADR-0045)."""
+
+import argparse
+from collections.abc import Sequence
+
+from voight_kampff import __version__
+from voight_kampff._orchestration import manifestes
+
+_DESCRIPTION = (
+    "Analyse la provenance et l'intégrité d'un fichier : preuves et indices de "
+    "génération ou de retouche, sans verdict certain."
+)
+
+
+def construire_analyseur() -> argparse.ArgumentParser:
+    """Construit l'analyseur d'arguments de la ligne de commande."""
+    analyseur = argparse.ArgumentParser(prog="voight-kampff", description=_DESCRIPTION)
+    analyseur.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    analyseur.add_argument(
+        "--modules",
+        action="store_true",
+        help="liste les modules d'analyse livrés, avec leur version",
+    )
+    return analyseur
+
+
+def _lister_modules() -> None:
+    livres = manifestes.decouvrir()
+    if not livres:
+        print("Aucun module d'analyse livré dans cette version.")
+    for manifeste in livres:
+        print(f"{manifeste.identifiant} {manifeste.version}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Point d'entrée ; renvoie le code de sortie du processus."""
+    analyseur = construire_analyseur()
+    arguments = analyseur.parse_args(argv)
+    if arguments.modules:
+        _lister_modules()
+        return 0
+    # Aucune commande d'analyse avant T13 : sans option, l'aide est affichée.
+    analyseur.print_help()
+    return 0

voight_kampff/modules/__init__.py

@@ -0,0 +1,31 @@
+"""Modules d'analyse : une technique par sous-paquet, avec son manifeste (ADR-0042).
+
+Un module est un dossier ``modules/<identifiant>/`` qui contient ``manifeste.toml`` et un
+``__init__.py`` exposant ``analyser(contexte)`` (ADR-0061). Le processus principal lit les
+manifestes sans importer ce code ; seul le processus de travail l'importe.
+
+La découverte se limite à ce dossier : aucune extension tierce n'est chargée (ADR-0042). Aucun
+module n'est livré avant T13.
+"""
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+__all__ = ["MANIFESTE", "dossiers"]
+
+MANIFESTE = "manifeste.toml"
+"""Nom du manifeste dans le dossier de chaque module."""
+
+
+def dossiers(racine: Traversable | None = None) -> tuple[Traversable, ...]:
+    """Dossiers des modules, triés par nom : ceux qui contiennent un manifeste.
+
+    ``racine`` vaut par défaut le dossier de ce paquet ; les tests en donnent un autre.
+    """
+    racine = files(__name__) if racine is None else racine
+    trouves = (
+        dossier
+        for dossier in racine.iterdir()
+        if dossier.is_dir() and (dossier / MANIFESTE).is_file()
+    )
+    return tuple(sorted(trouves, key=lambda dossier: dossier.name))

voight_kampff/rapport/__init__.py

@@ -0,0 +1 @@
+"""Rapport d'analyse : modèle de données (T11), exports HTML et JSON (T16)."""