Configurer un pipeline par fichier, catalogue et ligne de commande

En bref

• Un fichier texte (TOML ou JSON) décrit toute la chaîne de protection, c'est-à-dire ce qu'on cherche, comment on le remplace, où on garde la mémoire des conversations.
• Le fichier ne contient jamais de secret. Les clés et mots de passe viennent des variables d'environnement du serveur.
• Les listes de motifs (e-mails, numéros de carte, etc.) peuvent venir d'un registre en ligne, le catalogue. Une version figée est téléchargée une fois, puis lue en local.
• La commande piighost validate contrôle un fichier sans rien lancer. Elle convient à une vérification automatique avant mise en production.
• Une faute de frappe dans le fichier est refusée, jamais ignorée.

Il n'y a pas d'interface graphique. Toute la configuration passe par ce fichier et par la ligne de commande. Les termes sont définis dans le glossaire. Chaque section et chaque clé du fichier sont listées dans la référence de configuration du guide technique. Le tutoriel de configuration construit un fichier pas à pas.

Choisir comment charger la configuration

source est un chemin de fichier ou une référence du catalogue (catalog:piighost/generic). Le suffixe .json choisit le lecteur JSON, tout autre suffixe le lecteur TOML (config/settings.py:54-69).

Écrire un fichier minimal

Le plus petit fichier valide ne déclare qu'un détecteur (examples/config/detector_only.toml) :

[detector]
type = "regex"
patterns = { EMAIL = '[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}' }

Le regroupement en entités, l'anonymiseur et le résolveur de chevauchements prennent leur valeur par défaut. Une adresse devient <<EMAIL:1>>. D'autres exemples sont dans examples/config/, à savoir pipeline.toml, thread_redis.toml, thread_sqlalchemy.toml, minimal.json.

Règles à connaître

BR-CFG-01 BR-CFG-01 Configurer un pipeline par fichier, catalogue et ligne de commande Quand le fichier contient une clé non déclarée, alors le chargement échoue avec ConfigValidationError.. Quand le fichier contient une clé non déclarée, alors le chargement échoue avec ConfigValidationError. Par exemple, [detectr] au lieu de [detector] est refusé. 2 emplacements

BR-CFG-02 BR-CFG-02 Configurer un pipeline par fichier, catalogue et ligne de commande Quand le fichier déclare une section [memory], alors il décrit un pipeline de conversation.. Quand le fichier déclare une section [memory], alors il décrit un pipeline de conversation. load_pipeline le refuse avec this configuration declares a memory; use load_thread_pipeline. À l'inverse, load_thread_pipeline refuse un fichier sans [memory]. 1 emplacement · 17 tests directs

BR-CFG-03 BR-CFG-03 Configurer un pipeline par fichier, catalogue et ligne de commande Quand token_memo_ttl est renseigné sans section [memory], alors la validation échoue.. Quand token_memo_ttl est renseigné sans section [memory], alors la validation échoue. Seul un pipeline de conversation garde ce cache. 1 emplacement

BR-CFG-04 BR-CFG-04 Configurer un pipeline par fichier, catalogue et ligne de commande Quand une valeur est donnée à plusieurs endroits, alors les arguments explicites priment, puis les variables PIIGHOST_*, puis le fichier ou le catalogue.. Quand une valeur est donnée à plusieurs endroits, alors les arguments explicites priment, puis les variables PIIGHOST_*, puis le fichier ou le catalogue. 1 emplacement

BR-CFG-05 BR-CFG-05 Configurer un pipeline par fichier, catalogue et ligne de commande Quand une variable vise une sous-clé, comme PIIGHOST_DETECTOR__TYPE, alors elle n'a aucun effet, parce qu'aucun délimiteur imbriqué (le __ qui sépare une section de sa clé) n'est configuré.. Quand une variable vise une sous-clé, comme PIIGHOST_DETECTOR__TYPE, alors elle n'a aucun effet, parce qu'aucun délimiteur imbriqué (le __ qui sépare une section de sa clé) n'est configuré. Une section entière se surcharge par un objet JSON, par exemple PIIGHOST_DETECTOR='{"type": "exact", "values": {"Patrick": "PERSON"}}'. 1 emplacement

BR-CFG-06 BR-CFG-06 Configurer un pipeline par fichier, catalogue et ligne de commande Quand un secret manque, alors l'erreur ConfigError survient à la construction, pas à la validation.. Quand un secret manque, alors l'erreur ConfigError survient à la construction, pas à la validation. piighost validate accepte donc un fichier dont les secrets ne sont pas encore fournis. 2 emplacements · 4 tests directs

BR-CFG-07 BR-CFG-07 Configurer un pipeline par fichier, catalogue et ligne de commande Quand une référence du catalogue se termine par huit caractères hexadécimaux (un commit), alors la réponse est mise en cache sur disque et n'est plus jamais téléchargée.. Quand une référence du catalogue se termine par huit caractères hexadécimaux (un commit), alors la réponse est mise en cache sur disque et n'est plus jamais téléchargée. Une référence qui finit par un tag, ou qui n'a pas de sélecteur (latest), est retéléchargée à chaque construction. 1 emplacement · 3 tests directs

BR-CFG-08 BR-CFG-08 Configurer un pipeline par fichier, catalogue et ligne de commande Quand un détecteur regex combine catalogues et motifs en ligne, alors les catalogues fusionnent dans l'ordre, puis les motifs en ligne.. Quand un détecteur regex combine catalogues et motifs en ligne, alors les catalogues fusionnent dans l'ordre, puis les motifs en ligne. Sur une même étiquette, le dernier gagne, donc un motif en ligne l'emporte sur tout catalogue. 1 emplacement · 11 tests directs

BR-CFG-09 BR-CFG-09 Configurer un pipeline par fichier, catalogue et ligne de commande Quand un catalogue s'appelle generic, us, eu ou fr sans préfixe du catalogue, alors il est refusé avec la référence du catalogue qui le remplace (catalog:piighost/generic).. Quand un catalogue s'appelle generic, us, eu ou fr sans préfixe du catalogue, alors il est refusé avec la référence du catalogue qui le remplace (catalog:piighost/generic). 1 emplacement · 11 tests directs

Fournir les secrets

Les secrets ne se lisent que dans l'environnement. Ne les écrivez jamais dans le fichier.

Les variables non secrètes lues ailleurs sont PIIGHOST_CATALOG_URL (registre privé), XDG_CACHE_HOME (racine du cache du catalogue), PIIGHOST_API_URL et PIIGHOST_HOOK_LOG (hooks Claude Code, voir Brancher la protection sur un agent).

Tirer des motifs du catalogue

Le catalogue est la seule source de motifs. La bibliothèque n'en embarque aucun. Une référence s'écrit namespace/name, avec un sélecteur facultatif :tag ou :commit, et le préfixe catalog: facultatif. Une référence écrite avec le préfixe hub: de la 1.x marche toujours, de même que PIIGHOST_HUB_URL quand PIIGHOST_CATALOG_URL n'est pas défini.

• Origine : https://catalog.piighost.dev, ou PIIGHOST_CATALOG_URL. Seuls http et https sont acceptés.
• Délai d'attente : 10 secondes (catalog.py:57).
• Cache : $XDG_CACHE_HOME/piighost/catalog/, sinon ~/.cache/piighost/catalog/. Le nom du fichier est une empreinte SHA-256 de l'URL. Le cache de la 1.x, sous piighost/hub/, n'est pas relu, donc chaque référence épinglée est téléchargée une fois de plus.
• Un détecteur regex ne prend que la partie ?part=detector. Si la référence décrit un détecteur à modèle, le chargement lève CatalogPayloadError. Chargez alors la configuration entière avec load_config("catalog:…").

Contrôler depuis la ligne de commande

La commande piighost demande l'extra config (typer). Sans lui, elle affiche The piighost CLI requires typer. Install it with: pip install piighost[config] et sort en code 1.

Les options de anonymize sont --config <fichier>, --api <url> (exclusives, sinon Pass at most one of --config and --api.), --thread-id (défaut default), --json. Sans --config ni --api, la commande lance un détecteur regex sur catalog:piighost/generic:fab51b33 (e-mail, URL, IPv4, numéro de carte).

Vérifier

uv run piighost validate examples/config/pipeline.toml
echo "Écrivez à claire.dubois@example.com" | uv run piighost anonymize --config examples/config/detector_only.toml

La première commande affiche OK: examples/config/pipeline.toml. La seconde affiche Écrivez à <<EMAIL:1>>.

Pièges

• validate ne prouve pas que le pipeline démarre. Les secrets, les groupes du catalogue et les modèles ne sont lus qu'à la construction (BR-CFG-06 BR-CFG-06 Configurer un pipeline par fichier, catalogue et ligne de commande Quand un secret manque, alors l'erreur ConfigError survient à la construction, pas à la validation.).
• Construire un fichier qui nomme un groupe du catalogue appelle le réseau au premier lancement. Un serveur sans accès sortant échoue avec CatalogUnreachableError, sauf si le cache est déjà rempli.
• Un cache non inscriptible est ignoré en silence (catalog.py:298-308). Le pipeline retélécharge alors à chaque démarrage.
• anonymize ne capture que ConfigError et CatalogError. Un extra manquant ou un garde-fou qui bloque (PIIRemainingError) remonte en trace Python complète.
• --thread-id vaut default par défaut. Deux appels sans identifiant partagent la même conversation sur un pipeline de conversation.

Où vivent les règles

Tests

Voir aussi Stocker les conversations et protéger les traces pour la section [memory].