Aller au contenu

Modèle de menace et contrat de confinement

Kirexo laisse Claude Code travailler en bypassPermissions : toutes les confirmations sont levées, l'agent écrit, exécute et supprime sans demander. Ce choix n'est défendable que si l'environnement d'exécution est lui-même circonscrit — et surtout, que si l'on peut prouver à tout instant qu'il l'est encore. Cette page explique le raisonnement derrière le contrat de confinement : pourquoi il existe, pourquoi il se vérifie par l'effet, et pourquoi certaines de ses lignes sont volontairement affichées comme des dettes.

Le contrat lui-même — la liste des invariants C1…C10, leurs sondes, leurs profils et leurs sévérités — vit dans .claude/skills/_shared/confinement.md, source de vérité unique du sujet. Son implémentation vit dans infra/confinement/check.lib.sh (décision pure) et infra/confinement/check.sh (sondes). Cette page ne les recopie pas : elle dit pourquoi ils sont écrits comme ça.

Trois rôles dans un seul conteneur

Le conteneur php a longtemps porté trois rôles distincts qui n'ont aucune raison d'avoir les mêmes droits :

  1. le runtime applicatif — FrankenPHP, le worker Messenger, l'accès à Postgres, Redis, RabbitMQ, Typesense ;
  2. le bac à sable de l'agent — le processus Claude Code qui écrit dans le dépôt et lance des commandes ;
  3. le backend IDE — le serveur RemoteDev que PhpStorm injectait quand on ouvrait le projet dans le conteneur.

Cette fusion est la raison d'être de la séparation qui a sorti le troisième rôle : l'IDE ouvre le worktree nativement et n'utilise le conteneur que comme interpréteur distant. Le point important pour le confinement est ailleurs : les garanties dont dépend bypassPermissions — filesystem restreint à /app, sortie réseau filtrée, absence de socket Docker, absence de root — étaient écrites dans les fichiers mêmes que cette séparation supprimait. Les retirer sans re-matérialiser les garanties ne casse rien de visible : l'application démarre, l'agent travaille. Il peut simplement sortir sur Internet et écrire où il veut.

C'est pourquoi ces garanties vivent dans des fichiers que la stack charge toujours (compose.override.yaml, compose.shared.yaml, infra/) et sont vérifiées par leur effet à chaque ouverture de session, plutôt que d'être adossées à un mode d'ouverture particulier.

L'adversaire modélisé n'est pas un attaquant humain qui prendrait la main sur le poste. C'est un agent qui exécute du code qu'il n'a pas relu — un script de post-install Composer hostile, un contenu de ticket qui contient des instructions, une dépendance compromise — avec toutes les confirmations levées. Il peut aussi être simplement maladroit : un agent qui « simplifie » un script Bash d'infrastructure peut ouvrir une whitelist par inadvertance. Dans les deux cas, le résultat est le même, et c'est cet effet-là qu'on cherche à rendre observable.

L'incident fondateur : configuré mais inactif

curl https://example.com depuis le conteneur a répondu 200. Le pare-feu sortant était inactif depuis environ dix-neuf heures : le script d'amorçage avait échoué en silence, laissant derrière lui un marqueur .bootstrap.failed avec un exit_code: 1 que personne ne lisait. Une session entière a tourné en bypassPermissions sans confinement réseau, sans que rien ne le signale.

Rien n'était « cassé » au sens habituel : les fichiers de configuration du pare-feu étaient là, corrects, versionnés, lisibles. C'est précisément le problème. Un confinement configuré mais inactif est indiscernable d'un confinement actif tant qu'on regarde la configuration. Un contrôle qui aurait vérifié la présence de init-firewall.sh, l'existence de la baseline de domaines ou la présence d'un process dnsmasq aurait été vert pendant ces dix-neuf heures.

Vérifier l'effet, jamais la configuration

D'où la règle qui structure tout le dispositif :

Toute vérification de confinement teste un effet observable, jamais une configuration.

Concrètement, sont interdits comme sondes : test -f sur un script, pgrep sur un daemon, grep dans une conf de pare-feu, lecture d'un fichier d'état de bootstrap. Ce qui est mesuré à la place, c'est le résultat : une requête HTTP vers un domaine hors whitelist échoue-t-elle ? une écriture sur un fichier censé être monté en lecture seule est-elle refusée ? le socket Docker répond-il ? l'UID courant vaut-il zéro ?

Trois corollaires découlent de cette règle, et ils expliquent la forme du code livré :

  • Aucune dépendance au bootstrap. Le contrôle ne suppose ni vendor/, ni FrankenPHP, ni la stack démarrée : c'est exactement quand le démarrage échoue qu'on en a besoin. C'est pourquoi le gate de session appelle infra/confinement/check.sh directement en Bash, sans passer par Castor ni PHP, alors même qu'une cible Castor existe pour le confort humain.
  • Aucun cache de verdict. Un vert périmé est le mode de panne que ce dispositif corrige ; le mémoriser le reproduirait.
  • Aucune sonde à effet de bord. Pas de rechargement de pare-feu, pas de sudo sur un script, pas de troncature de fichier. Une sonde qui modifie l'état qu'elle observe finit toujours par mentir sur cet état — le paragraphe suivant en donne le cas le plus vicieux.

Une écriture qui échoue ne prouve rien sans substrat

Deux invariants (C4 sur les whitelists de la sortie réseau, C5 sur settings.json et CLAUDE.md de l'espace Claude) reposent sur un montage :ro dont la cible utile est un fichier. La sonde évidente consiste à tenter une écriture et à conclure « refusée, donc protégé ». Elle est fausse.

Un open() en écriture peut échouer pour des raisons de nature opposée. EROFS signifie « le système de fichiers est monté en lecture seule » : l'invariant est tenu. EISDIR signifie « ce chemin est un répertoire » : il n'y a rien à protéger, le fichier attendu n'existe pas. Une sonde qui ne regarde que le code de retour confond les deux et rend vert un invariant qui n'a plus de substrat.

Ce n'est pas une hypothèse d'école, c'est le mode de panne nominal. Quand la source d'un bind de fichier n'existe pas sur l'hôte, Docker crée un répertoire root-owned à sa place ; et quand c'est un bind de dossier, le fichier attendu peut simplement manquer à l'intérieur. Or whitelist.local.txt est gitignoré (chaque dev a la sienne, ou pas), et ~/.claude/settings.json peut manquer sur un $HOME neuf. Dans les deux cas, le conteneur démarre normalement, l'écriture échoue — et l'invariant serait déclaré vert alors que le fichier qu'il est censé protéger n'existe nulle part. C'est le « configuré mais inactif » de l'incident fondateur, transposé au système de fichiers.

La conséquence est double, et elle se lit dans le code :

  • confinement_classify_write (infra/confinement/check.lib.sh) rend trois issues et non deux : substrat manquant (tout type autre qu'un fichier régulier, y compris chemin absent) → ko avec le remède ; fichier régulier + écriture refusée → ok ; fichier régulier + écriture réussie → ko.
  • L'ordre des opérations dans probe_write (infra/confinement/check.sh) est un invariant de sécurité : le type de la cible est constaté avant toute tentative d'écriture. printf '' >> <chemin absent> créerait le fichier — la sonde fabriquerait elle-même le substrat qu'elle est censée constater, laisserait une trace dans le dépôt, et rendrait l'invariant vert à jamais. Un répertoire root-owned se voit dans le détail affiché ; un fichier créé par la sonde ne se voit nulle part.

Le prix de ce durcissement est assumé : C5 est bloquant, donc un espace Claude sans settings.json fait virer le contrôle au rouge. C'est voulu — un espace projeté depuis un répertoire vide n'est pas protégé — mais ça impose que le message d'erreur porte le remède en toutes lettres (sudo rmdir côté hôte si Docker a posé un répertoire, puis recréation du fichier).

Ce qu'un hook SessionStart peut, et ne peut pas

L'exigence de départ était : « une session bypassPermissions refuse de démarrer si le confinement est rouge ». Elle n'est pas implémentable telle quelle. La documentation des hooks Claude Code est explicite : un hook SessionStart ne peut pas bloquer l'ouverture d'une session, et son exit 2 se contente d'afficher stderr.

Le levier réel est ailleurs : le champ commun continue: false, accompagné d'un stopReason, arrête tout traitement par Claude après le hook. La fenêtre s'ouvre, le message s'affiche, et rien ne se passe tant que le confinement n'est pas réparé. C'est une nuance d'implémentation, pas de garantie : l'agent ne travaille pas.

Trois arbitrages encadrent ce gate, et chacun corrige un mode de panne :

  • Fail-closed uniquement en bypassPermissions. Un contrôle absent, illisible ou en dépassement de temps vaut rouge : c'est la seule position tenable quand toutes les confirmations sont levées. Dans les autres modes de permission, le gate se contente d'alerter — l'utilisateur arbitre outil par outil, il n'a pas besoin qu'on décide à sa place.
  • Jamais de blocage hors du conteneur. Le contrat décrit le conteneur de l'agent ; lancé sur le poste de travail, le contrôle ne mesure rien de pertinent. Sans garde explicite, il sortirait en erreur, le verdict vaudrait « indisponible » et toute session ouverte côté hôte serait bloquée sans remède. Le hook détecte donc son contexte avant d'exécuter quoi que ce soit.
  • Jamais de blocage sur une compaction. Une compaction de contexte survient au milieu d'un travail en cours. L'interrompre détruirait le contexte sans rien protéger de plus, puisque la prochaine ouverture de session repassera par le gate.
  • Rouge sur une panne, pas seulement sur une violation. Le gate se ferme aussi quand la sortie réseau a purement et simplement disparu — le proxy mutualisé arrêté ou supprimé. Ce n'est pas un manquement au confinement : c'est l'absence du composant qui l'applique, et elle rend l'environnement inutilisable de toute façon. Une session qui s'ouvre en nommant la cause et le remède vaut mieux qu'une session qui travaille jusqu'au premier appel réseau et rend une erreur opaque. Le raisonnement d'architecture derrière cette bascule est dans Le revers : une sortie unique est un point de défaillance unique.

Contrepartie non négociable : le message doit être actionnable. Un gate qui bloque sans dire quoi corriger est un gate qu'on désarme — c'est pourquoi le stopReason nomme les invariants en échec, les points de montage fautifs et la fonction à mettre à jour. Le détail factuel du hook (entrée consommée, formes de sortie, effets de bord) est dans Hooks Claude Code.

Qui a le droit d'accorder le mode bypassPermissions

Le gate ne se ferme qu'en bypassPermissions. Encore faut-il que ce mode soit réellement en vigueur — et c'est là que le dispositif a rencontré une deuxième fois, sur lui-même, l'incident fondateur de cette page.

Claude Code refuse d'accorder bypassPermissions quand le mode vient d'un fichier que le dépôt contrôle. Un permissions.defaultMode posé dans .claude/settings.json (projectSettings) ou dans .claude/settings.local.json (localSettings) est ignoré, avec ce motif : « only policy/user/flag settings may grant bypass mode (projectSettings and localSettings are repo-controllable) ». Le raisonnement est le nôtre à l'envers, et il est juste : ce n'est pas au code versionné — ni à un fichier qu'un git pull, un script d'installation ou un agent peuvent écrire — de s'accorder la levée de toutes les confirmations.

Le problème n'était pas la règle, c'était son silence. Le refus ne s'affiche pas dans l'interface : il part dans le journal interne. Le dispositif du projet reposant sur .claude/settings.local.json, les sessions ont commencé à s'ouvrir en mode confirmation sans que rien ne le signale — et, plus grave, le gate de confinement, qui ne s'arme qu'en bypassPermissions, s'est désarmé du même coup. Configuré, inactif, muet : exactement la forme de panne que tout ce contrat existe pour éliminer, cette fois-ci logée dans le garde-fou lui-même.

Trois sources restent légitimes aux yeux de Claude Code : la politique machine (/etc/claude-code/managed-settings.json), les réglages utilisateur ($CLAUDE_CONFIG_DIR/settings.json) et la ligne de commande. Une seule est praticable ici, et le confinement lui-même explique pourquoi les deux autres ne le sont pas. Le settings.json utilisateur est monté en lecture seule dans le conteneur — c'est le substrat de l'invariant C5, posé précisément pour qu'un agent compromis ne puisse pas se réécrire ses propres autorisations : y loger le mode reviendrait à demander au projet d'écrire dans le fichier qu'il a rendu non inscriptible. Quant à la politique machine, elle vit dans l'image : l'y mettre ferait dépendre le mode d'un rebuild, et déplacerait une décision de poste de travail dans un artefact partagé.

Reste la ligne de commande. C'est castor wt:claude qui pose --permission-mode bypassPermissions, côté hôte, dans la cible que le développeur lance lui-même. Le déplacement est plus qu'un contournement : le bypass est désormais accordé par un geste, pas par un fichier du dépôt — et il s'efface devant le mode que ce même geste déclare explicitement (castor wt:claude --permission-mode plan reste obéi). Le raisonnement de fond, lui, ne bouge pas d'un pouce : le bypass n'est défendable que parce que la cellule est confinée et qu'on peut le prouver. Ce qui a changé, c'est par quoi il est accordé.

Un corollaire à assumer : le gate avait besoin de savoir en quel mode tourne la session, et son repli lisait justement le defaultMode du fichier — clé qui vient de disparaître. Le champ permission_mode que Claude Code passe au hook n'est pas garanti sur tous les événements, il ne peut donc pas rester la seule source. wt:claude publie donc dans la session un constat — KIREXO_CLAUDE_BYPASS_ACTIVE, calculé sur la ligne de commande finale —, soigneusement distingué par son nom de la demande du développeur (KIREXO_CLAUDE_BYPASS, qui sert à renoncer au bypass). Un seul nom pour les deux ferait lire « poser 1 accorde le bypass », qui est faux : rien, dans le conteneur, ne peut s'accorder ce mode. Et une session ouverte sans cette variable — un claude lancé à la main depuis wt:shell — n'est pas en bypass : le gate n'a pas à s'y armer, et ne s'y arme pas.

pending:<lot> : la dette dans le contrat, pas à côté

Le contrat a été écrit avant que tous ses invariants soient tenus. Plusieurs de ses lignes dépendaient d'un travail encore à faire : la sortie du pare-feu hors du conteneur qu'il surveille, le cloisonnement entre worktrees, le volet hôte du contrôle sur le socket Docker. Deux options mauvaises existaient :

  • ne pas les écrire tant qu'ils ne sont pas tenus — le contrôle serait tout vert et raconterait une histoire fausse ;
  • les écrire en bloquant — le contrôle serait rouge en permanence, donc ignoré, puis désarmé.

D'où la troisième voie : une sévérité pending:<lot>, affichée ⧗ PENDING (lot N) et non bloquante. La dette est dans le contrat, avec le numéro du lot qui doit la solder ; un pending sans numéro est interdit, parce que c'est le numéro qui rend la promesse vérifiable. Le lot cité a l'obligation, en le livrant, de faire basculer la ligne en blocking.

Un détail contre-intuitif en découle, et il est délibéré : une ligne pending est rendue PENDING même quand sa sonde est verte, le résultat brut partant dans la colonne de détail (sonde: ok — prêt à basculer). Sans cette règle, une dette soldée mais non basculée passerait au vert et la ligne du contrat resterait fausse indéfiniment — personne ne relit une ligne verte.

Le dispositif a fait son office : aucune ligne du contrat n'est en pending, toutes celles qui l'ont été ayant basculé en blocking — ou en advisory pour C10, seule exception. La sévérité reste dans la table de décision, pour la prochaine dette : c'est un mécanisme, pas un état transitoire à retirer une fois le dernier pending soldé.

Même logique pour les lignes hors profil : elles sont affichées · SKIP avec leur raison, jamais silencieusement omises. Un SKIP muet en intégration continue reproduirait exactement le mode de panne fondateur, à l'échelle de la CI.

Pourquoi C10 est advisory et non blocking

C10 porte le cloisonnement entre worktrees : le conteneur d'un worktree ne doit pas atteindre l'application d'un worktree voisin. Cet invariant est tenu depuis la mise en place du proxy hôte, et il est classé advisory — jamais blocking. La raison tient à la nature de la garantie.

Le cloisonnement n'est pas natif Docker. Sur un réseau bridge partagé, l'attachement est bidirectionnel : internal: true ferme l'extérieur, pas le voisinage. La propriété « répond mais n'initie pas » s'obtient par une règle DOCKER-USER posée côté hôte, avec sudo, et volatile : elle disparaît au redémarrage de la machine ou à un flush du démon.

Trois conséquences :

  • La sonde exécutée dans le conteneur mesure une atteignabilité, pas la présence d'une règle. Elle ne sait pas distinguer « règle jamais posée, faute de sudo » de « règle flushée » : les deux produisent le même effet observable — le voisin répond. Le diagnostic faisant autorité est côté hôte.
  • Le mode dégradé, sans sudo, est un mode supporté : un dev qui n'a pas les droits d'administration sur son poste doit pouvoir travailler. Faire armer le gate par C10 reviendrait à lui interdire toute session, pour une garantie que le conteneur ne peut de toute façon pas se poser à lui-même.
  • Le risque résiduel est borné et documenté : un agent peut atteindre l'application HTTP d'un worktree voisin. Il n'atteint ni son système de fichiers (couvert par C8, porté par les binds), ni Internet (le réseau reste internal). Ce que C8 ne couvre pas — l'historique git, partagé par construction — fait l'objet de la section suivante.

C'est le seul cas où la garantie est réelle mais hors de portée du conteneur qui l'observe. La sévérité advisory existe pour dire exactement ça : « on regarde, on affiche ⚠ WARN, on ne bloque pas ».

Un corollaire est resté implicite tant que la sonde désignait mal ses voisins : sur un poste où les conteneurs php partagent le réseau du proxy hôte, ce ⚠ WARN est permanent, et il est vrai. La tentation, devant un avertissement qui ne s'éteint jamais, est de le faire taire du côté de la mesure — c'est précisément l'inverse de ce que ce contrat protège. Un avertissement faux finit par être ignoré, et c'est alors le vrai qu'on n'entend plus. L'éteindre suppose de refermer le réseau, pas de réécrire la sonde. Comment les voisins sont désignés — et pourquoi une dérivation par le nom du dossier faisait sonder au conteneur sa propre adresse tout en ignorant le dépôt principal — est décrit dans castor confinement:check, « C10 — quels voisins sont sondés » ; le raisonnement complet vit dans .claude/skills/_shared/confinement.md, section « Le ⚠ WARN de C10 est normal, et il est VRAI ».

Ce que C8 ne prétend pas couvrir

C8 dit qu'un worktree ne voit pas ses voisins. La formulation exacte compte : aucun accès au système de fichiers des autres worktrees, jamais « aucun accès au code des autres branches ». La nuance n'est pas rhétorique, elle est la conséquence directe d'un arbitrage.

Pour qu'une commande git fonctionne dans le conteneur d'un worktree, il faut y monter le git common dir du dépôt principal. Le fichier .git d'un worktree n'est qu'un pointeur d'une ligne vers <common>/worktrees/<nom>, en chemin absolu côté hôte — et ce chemin doit rester valide côté hôte, où l'IDE indexe et fait du git nativement. On ne peut donc ni le réécrire ni le relativiser : le seul montage qui marche est le common dir au même chemin absolu, et en écriture, puisqu'un git commit y dépose les objets et déplace refs/heads/<branche>.

Trois choix étaient possibles : renoncer à git dans le conteneur (inacceptable, c'est le geste le plus fréquent d'une session), donner à chaque ticket un clone indépendant (coûteux en disque et en temps, et le partage d'objets est justement ce qui rend git worktree intéressant), ou monter le common dir en écriture et dire ce que ça coûte. C'est la troisième voie qui a été retenue, avec deux conséquences énoncées plutôt que corrigées :

  • les refs des autres branches sont accessibles en écriture depuis n'importe quel worktree. Un git branch -f, un git update-ref ou un git gc malencontreux affecte le travail d'un voisin. Le risque est jugé faible mais son impact élevé ; la seule mitigation en place est le verrou posé sur chaque worktree, qui empêche un git worktree prune de supprimer des métadonnées depuis le conteneur — où le gitdir des voisins pointe des chemins hôte inexistants ;
  • l'historique des autres branches reste lisible : git show autre-branche:fichier fonctionne, alors même que ls <autre worktree> rend ENOENT. C'est inhérent à git worktree : les objets sont partagés par construction.

La porte de sortie existe et elle est nommée : si un jour un agent doit tourner sur du code non maîtrisé, on passe au clone indépendant par ticket. Tant que ce n'est pas le cas, la limite est dans le contrat, à côté de l'invariant qu'elle borne — même logique que les lignes pending:<lot> : une garantie qu'on n'écrit pas est une garantie que personne ne vérifie. Le détail exécutable vit dans .claude/skills/_shared/confinement.md, section « Limites connues de C8 ».

Une troisième limite s'y est ajoutée depuis, de même nature : le var/claude du dépôt principal est monté en écriture dans chaque worktree, ce qui ouvre un canal d'écriture vers l'espace où vivent les scripts que l'humain lance ensuite. L'arbitrage — et ce qui le compense côté push — est discuté dans Pourquoi l'agent pousse lui-même, et ce qui le retient ; la limite elle-même est consignée dans le contrat, section « Limites connues de C8 ».

Ce montage a par ailleurs un effet de bord sur la sonde de C8, qu'il ne faut pas confondre avec ces limites : Docker matérialise le répertoire parent d'un point de montage, donc le chemin du dépôt principal existe dans le conteneur du worktree, sans son arbre de travail. Une sonde qui se contenterait de constater l'existence du chemin virerait au rouge dans tous les worktrees — d'où un marqueur qui, lui, n'est jamais fabriqué par la création des parents d'un bind.

Ce que cette page ne couvre pas