fix(security): Phase 1 — SSRF eScriptorium + Tesseract lang + bandit nosec

Trois durcissements sécurité identifiés par l'audit code-quality.

**1.1 SSRF résiduel sur eScriptorium**

``adapters/corpus/escriptorium.py:_get``, ``_post`` et le
``urllib.request.urlretrieve(part.image_url)`` ligne 410 ne
passaient pas par ``validate_http_url`` (qui existe pourtant dans
``_http.py`` et est utilisé par IIIF/Gallica/HTR-United). Un
manifeste pointant ``image_url=http://169.254.169.254/...``
exfiltrait les métadonnées cloud, ``http://127.0.0.1:6379/...``
parlait au Redis local, ``http://10.x/...`` aux services RFC 1918.

- ``_get`` et ``_post`` appellent désormais ``validate_http_url``
avant le ``Request``.
- Le download d'image utilise ``download_url`` (helper ``_http``
avec retry + validation) à la place d'``urlretrieve``.
- Cohérence avec les autres importeurs corpus.

**1.2 Injection ligne de commande Tesseract**

``adapters/ocr/tesseract.py:__init__`` n'avait aucune validation
sur ``lang``, concaténé in fine à ``tesseract -l <lang>``. Un
appelant programmatique passant ``lang="fra --user-words
/etc/passwd"`` lisait un fichier arbitraire (flag ``--user-words``
honoré par Tesseract).

Ajout d'une regex ``^[a-zA-Z]{3,}(\+[a-zA-Z]{3,})*$`` qui accepte
les codes ISO 639-3 (``fra``, ``eng``, ``Latin``...) optionnellement
combinés par ``+`` (``fra+eng``), et refuse tout caractère
exploitable (espaces, ``--``, ``/``, ``;``, ``|``, backticks, $,
newlines, etc.).

**1.3 Faux positifs bandit B608**

``interfaces/web/jobs.py:235`` et
``evaluation/metrics/history.py:341`` construisent des requêtes
SQL via f-string, mais les ``fields``/``clauses`` interpolés sont
des littéraux internes (``"status = ?"``, ``"engine_name = ?"``...) ;
les *valeurs* utilisent toutes des ``?``-placeholders. Pas de
SQLi exploitable. Documenté avec ``# nosec B608`` + commentaire
explicatif.

**Tests ajoutés**

- ``tests/security/test_escriptorium_ssrf.py`` (14 tests, 8 IPs
internes bloquées sur _get, 3 sur _post, 1 sur download_url,
garde-fou d'import).
- ``tests/adapters/ocr/test_tesseract_lang_validation.py`` (30
tests, 9 langs valides + 20 injections bloquées + défaut).

Bandit re-scan : 2 issues MEDIUM (B608) → 0 MEDIUM, 2 explicitement
skipped via ``# nosec``.

**Compteurs**

Le test ``test_claude_md_count_close_to_reality`` a échoué après
ajout de 47 tests (tolérance ±50 dépassée). Régénération de
CLAUDE.md + README.md via ``scripts/gen_readme_tables.py`` —
préfigure la Phase 2.1 du plan (script orphelin à câbler en CI).

Suite : 4 731 passed, 16 skipped, 8 deselected, 2 xfailed.
Ruff propre, bandit propre (1 LOW résiduel inoffensif).

CLAUDE.md

@@ -116,7 +116,7 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4700 passed, 12 skipped, 8 deselected, 0 failed**
+`pytest tests/` → **4750 passed, 12 skipped, 8 deselected, 0 failed**
 (post-S59).  Les deselected sont les markers `live` (5 tests d'intégration
 contre vraie API/binaire) + `network` (3 tests qui hit le réseau réel),
 opt-in en local via `pytest -m live` ou `pytest -m network`.  Le
@@ -302,7 +302,7 @@ détecte, arbitre, rend.
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces, Python 3.11+
-- **Tests** : `pytest tests/ -q` → 4700 passed, 9 skipped, 24
+- **Tests** : `pytest tests/ -q` → 4750 passed, 9 skipped, 24
   deselected, 0 failed (post-v2.0).
 - **Manifeste architecture** : [`docs/explanation/architecture.md`](docs/explanation/architecture.md).
 - **API publique stable** : [`docs/reference/api-stable.md`](docs/reference/api-stable.md).

README.md

@@ -397,7 +397,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4700 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4750 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when

picarones/adapters/corpus/escriptorium.py

@@ -54,6 +54,7 @@ warnings.warn(
 )
 
 
+from picarones.adapters.corpus._http import download_url, validate_http_url
 from picarones.evaluation.corpus import Corpus, Document
 
 if TYPE_CHECKING:
@@ -162,9 +163,15 @@ class EScriptoriumClient:
         url = f"{self.base_url}/api/{path.lstrip('/')}"
         if params:
             url += "?" + urllib.parse.urlencode(params)
+        # Anti-SSRF — refuse loopback, lien-local, RFC 1918, metadata cloud.
+        # Cohérence avec IIIF/Gallica/HTR-United qui passent par _http.
+        try:
+            validate_http_url(url)
+        except ValueError as exc:
+            raise RuntimeError(str(exc)) from exc
         req = urllib.request.Request(url, headers=self._headers())
         try:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310
                 return json.loads(resp.read().decode("utf-8"))
         except urllib.error.HTTPError as exc:
             raise RuntimeError(
@@ -178,12 +185,17 @@ class EScriptoriumClient:
     def _post(self, path: str, payload: dict) -> dict:
         """Effectue une requête POST avec payload JSON."""
         url = f"{self.base_url}/api/{path.lstrip('/')}"
+        # Anti-SSRF — cf. _get.
+        try:
+            validate_http_url(url)
+        except ValueError as exc:
+            raise RuntimeError(str(exc)) from exc
         data = json.dumps(payload).encode("utf-8")
         req = urllib.request.Request(
             url, data=data, headers=self._headers(), method="POST"
         )
         try:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310
                 body = resp.read().decode("utf-8")
                 return json.loads(body) if body else {}
         except urllib.error.HTTPError as exc:
@@ -406,11 +418,17 @@ class EScriptoriumClient:
             if out_path and part.image_url and download_images:
                 ext = Path(urllib.parse.urlparse(part.image_url).path).suffix or ".jpg"
                 local_img = out_path / f"part_{part.pk:05d}{ext}"
+                # Anti-SSRF + retry exponentiel — utilise download_url plutôt
+                # que urlretrieve qui ne valide pas l'URL.
                 try:
-                    urllib.request.urlretrieve(part.image_url, local_img)
+                    image_bytes = download_url(part.image_url)
+                    local_img.write_bytes(image_bytes)
                     image_path = str(local_img)
-                except Exception as exc:
-                    logger.warning("Impossible de télécharger l'image %s: %s", part.image_url, exc)
+                except (ValueError, RuntimeError) as exc:
+                    logger.warning(
+                        "[escriptorium] Impossible de télécharger l'image %s : %s",
+                        part.image_url, exc,
+                    )
 
                 # Sauvegarder la GT
                 gt_path = out_path / f"part_{part.pk:05d}.gt.txt"

picarones/adapters/ocr/tesseract.py

@@ -56,6 +56,7 @@ Anti-sur-ingénierie
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import Any
 
@@ -63,6 +64,14 @@ from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
 from picarones.adapters.output_paths import resolve_output_path
 from picarones.domain.artifacts import Artifact, ArtifactType
 
+#: Codes langue Tesseract acceptés : ISO 639-3 (3 lettres ASCII)
+#: éventuellement combinés par ``+`` (ex. ``"fra+eng"``).  Le ``lang``
+#: étant in fine passé à la ligne de commande Tesseract via
+#: pytesseract, on refuse tout caractère qui pourrait être interprété
+#: comme un flag ou un séparateur (espaces, ``--``, ``/``, etc.).
+#: Phase 1.2 de l'audit code-quality (2026-05).
+_TESSERACT_LANG_RE = re.compile(r"^[a-zA-Z]{3,}(?:\+[a-zA-Z]{3,})*$")
+
 
 class TesseractAdapter(BaseOCRAdapter):
     """Adapter Tesseract 5 natif au nouveau contrat (S26).
@@ -123,6 +132,15 @@ class TesseractAdapter(BaseOCRAdapter):
                 f"TesseractAdapter : name invalide {name!r} — "
                 "alphanumérique + _ - uniquement.",
             )
+        # Anti-injection ligne de commande Tesseract — refuse les
+        # espaces, ``--user-words``, ``/``, etc.  ``lang`` est in fine
+        # concaténé à ``tesseract -l <lang>``.
+        if not _TESSERACT_LANG_RE.fullmatch(lang):
+            raise OCRAdapterError(
+                f"TesseractAdapter : lang invalide {lang!r} — "
+                "format attendu : code ISO 639-3 (3+ lettres ASCII), "
+                "optionnellement combiné via ``+`` (ex. ``fra+eng``).",
+            )
         if not 0 <= psm <= 13:
             raise OCRAdapterError(
                 f"TesseractAdapter : psm doit être ∈ [0, 13], reçu {psm}.",

picarones/evaluation/metrics/history.py

@@ -337,8 +337,13 @@ class BenchmarkHistory:
         params.append(limit)
 
         conn = self._connect()
+        # Faux positif bandit B608 : ``clauses`` est construit à partir
+        # de littéraux internes (``"engine_name = ?"``, ``"corpus_name = ?"``,
+        # ``"timestamp >= ?"``) — aucune entrée utilisateur n'est
+        # concaténée dans la requête.  Les *valeurs* (engine, corpus,
+        # since, limit) passent par ``?``-placeholders.
         rows = conn.execute(
-            f"SELECT * FROM runs {where} ORDER BY timestamp ASC LIMIT ?",
+            f"SELECT * FROM runs {where} ORDER BY timestamp ASC LIMIT ?",  # nosec B608
             params,
         ).fetchall()
 

picarones/interfaces/web/jobs.py

@@ -231,8 +231,13 @@ class JobStore:
         values.append(time.time())
         values.append(job_id)
         with self._conn() as c:
+            # Faux positif bandit B608 : ``fields`` est construit
+            # uniquement à partir de littéraux internes (``"status = ?"``,
+            # ``"total_docs = ?"`` etc.) — aucune entrée utilisateur
+            # n'est concaténée dans la requête.  Les *valeurs* passent
+            # toutes par ``?``-placeholders (paramètre ``values``).
             c.execute(
-                f"UPDATE jobs SET {', '.join(fields)} WHERE job_id = ?",
+                f"UPDATE jobs SET {', '.join(fields)} WHERE job_id = ?",  # nosec B608
                 values,
             )
 

tests/adapters/ocr/test_tesseract_lang_validation.py

@@ -0,0 +1,92 @@
+"""Phase 1.2 du plan d'audit — TesseractAdapter valide le format
+de ``lang`` à la construction (refuse les injections CLI).
+
+Risque parée : ``lang`` est in fine concaténé par pytesseract à la
+ligne de commande ``tesseract -l <lang>``.  Sans validation, un
+appelant qui passe ``lang="fra --user-words /etc/passwd"`` lirait
+un fichier arbitraire (Tesseract honore ce flag).
+
+La validation côté UI (``get_tesseract_langs()``) protégeait le
+chemin web, mais pas les usages programmatiques ni la CLI.  Phase
+1.2 ajoute une défense locale dans ``__init__``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.adapters.ocr.tesseract import TesseractAdapter
+
+
+class TestTesseractLangAccepted:
+    """Codes Tesseract canoniques acceptés."""
+
+    @pytest.mark.parametrize(
+        "lang",
+        [
+            "fra",
+            "eng",
+            "lat",
+            "frk",         # Fraktur
+            "deu",
+            "fra+eng",     # combinaison standard
+            "lat+deu+eng",
+            "Latin",       # script (3+ lettres)
+            "Cyrillic",
+        ],
+    )
+    def test_valid_lang_accepted(self, lang: str) -> None:
+        adapter = TesseractAdapter(lang=lang)
+        assert adapter.lang == lang
+
+
+class TestTesseractLangRejected:
+    """Toute valeur exploitable pour injection CLI doit lever."""
+
+    @pytest.mark.parametrize(
+        "lang",
+        [
+            # Injection classique : un espace permet d'ajouter un flag
+            # Tesseract qui lit un fichier arbitraire.
+            "fra --user-words /etc/passwd",
+            "fra --tessdata-dir /tmp",
+            # Doubles tirets sans espace = même attaque.
+            "fra--user-words",
+            # Slash : chemin / path traversal.
+            "fra/eng",
+            "../etc",
+            # Caractères de séparation shell.
+            "fra;ls",
+            "fra|cat",
+            "fra`whoami`",
+            "fra$IFS",
+            "fra\nrm",
+            # Vide ou trop court.
+            "",
+            "f",
+            "fr",
+            # Caractères non-ASCII (peuvent contourner la regex naive).
+            "frà",
+            "français",
+            # Combinaison mal formée.
+            "fra+",
+            "+fra",
+            "fra++eng",
+            # Avec chiffres (pas un code ISO 639-3).
+            "fra1",
+            "1fra",
+        ],
+    )
+    def test_invalid_lang_raises(self, lang: str) -> None:
+        with pytest.raises(OCRAdapterError, match="lang invalide"):
+            TesseractAdapter(lang=lang)
+
+
+def test_default_lang_is_valid() -> None:
+    """Régression : le défaut ``"fra"`` doit toujours passer la
+    validation (sinon TesseractAdapter() planterait sans
+    arguments).
+    """
+    adapter = TesseractAdapter()
+    assert adapter.lang == "fra"

tests/security/test_escriptorium_ssrf.py

@@ -0,0 +1,135 @@
+"""Phase 1.1 du plan d'audit — l'adapter eScriptorium passe
+désormais par ``validate_http_url`` pour les fetch GET/POST et par
+``download_url`` pour les téléchargements d'images.
+
+Audit code-quality (2026-05) : ``escriptorium._get/_post`` et le
+``urllib.request.urlretrieve(part.image_url)`` ligne 410 fetchaient
+sans valider l'URL — un manifeste pointant
+``http://169.254.169.254/...`` exfiltrait les métadonnées cloud,
+``http://127.0.0.1:6379/...`` parlait au Redis local, etc.  Le
+helper ``validate_http_url`` existait déjà pour IIIF/Gallica/
+HTR-United mais n'était pas branché pour eScriptorium.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+
+from picarones.adapters.corpus.escriptorium import EScriptoriumClient
+
+
+@pytest.fixture
+def client() -> EScriptoriumClient:
+    """Client eScriptorium configuré sur un hôte fictif valide.
+
+    Le constructeur n'effectue aucun fetch — on peut donc fabriquer
+    un client avec une URL publique fictive et tester les méthodes
+    individuellement.
+    """
+    return EScriptoriumClient("https://escriptorium.example.org", token="dummy")
+
+
+# --------------------------------------------------------------------------
+# _get / _post : hostnames bloqués
+# --------------------------------------------------------------------------
+
+
+class TestGetBlocksDangerousHosts:
+    """``_get`` doit refuser les hostnames internes avant tout fetch."""
+
+    @pytest.mark.parametrize(
+        "base_url",
+        [
+            "http://localhost:8000",
+            "http://127.0.0.1:8000",
+            "http://169.254.169.254",          # AWS metadata
+            "http://metadata.google.internal",  # GCP metadata
+            "http://10.0.0.42",                 # RFC 1918
+            "http://192.168.1.1",               # RFC 1918
+            "http://172.16.0.5",                # RFC 1918
+            "http://0.0.0.0",                   # unspecified
+        ],
+    )
+    def test_get_refuses_internal_host(self, base_url: str) -> None:
+        """Chaque IP/host interne fait lever RuntimeError sans fetch."""
+        client = EScriptoriumClient(base_url, token="dummy")
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            with pytest.raises(RuntimeError, match="(anti-SSRF|refusé|Schéma)"):
+                client._get("projects/")
+            # Le fetch ne doit jamais avoir lieu.
+            mock_urlopen.assert_not_called()
+
+    def test_get_refuses_file_scheme(self) -> None:
+        """Le schéma ``file://`` est refusé avant fetch."""
+        client = EScriptoriumClient("file:///etc/passwd", token="dummy")
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            with pytest.raises(RuntimeError):
+                client._get("anything")
+            mock_urlopen.assert_not_called()
+
+
+class TestPostBlocksDangerousHosts:
+    """``_post`` (création de couche OCR) doit aussi valider."""
+
+    @pytest.mark.parametrize(
+        "base_url",
+        [
+            "http://169.254.169.254",
+            "http://localhost",
+            "http://10.0.0.1",
+        ],
+    )
+    def test_post_refuses_internal_host(self, base_url: str) -> None:
+        client = EScriptoriumClient(base_url, token="dummy")
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            with pytest.raises(RuntimeError, match="(anti-SSRF|refusé|Schéma)"):
+                client._post("documents/1/parts/2/transcriptions/", {"key": "value"})
+            mock_urlopen.assert_not_called()
+
+
+# --------------------------------------------------------------------------
+# Image download via download_url (Phase 1.1) — anti-SSRF
+# --------------------------------------------------------------------------
+
+
+class TestImageDownloadValidatesURL:
+    """``import_document`` doit refuser de fetch une image dont
+    l'``image_url`` pointe vers un hôte interne.
+
+    On teste ici uniquement la sous-routine qui télécharge l'image
+    (le helper ``download_url`` lève ``ValueError`` validate_http_url).
+    """
+
+    def test_download_url_rejects_metadata_host(self) -> None:
+        """Vérification directe de l'invariant : download_url
+        ne fetch pas une URL metadata cloud."""
+        from picarones.adapters.corpus._http import download_url
+
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            with pytest.raises(ValueError, match="(anti-SSRF|refusé)"):
+                download_url("http://169.254.169.254/latest/meta-data/")
+            mock_urlopen.assert_not_called()
+
+
+# --------------------------------------------------------------------------
+# Garde-fou — l'import du module ne plante pas
+# --------------------------------------------------------------------------
+
+
+def test_module_imports_validate_http_url() -> None:
+    """Le module ``escriptorium`` doit avoir importé ``validate_http_url``
+    au top-level — protection contre une régression d'import lazy
+    qui contournerait la vérification.
+    """
+    import picarones.adapters.corpus.escriptorium as mod
+
+    assert hasattr(mod, "validate_http_url"), (
+        "escriptorium.py n'importe plus validate_http_url — "
+        "régression Phase 1.1 de l'audit code-quality."
+    )
+    assert hasattr(mod, "download_url"), (
+        "escriptorium.py n'importe plus download_url — "
+        "régression Phase 1.1 de l'audit code-quality."
+    )