Aller au contenu

Ouvrir un domaine dans l'allowlist du proxy sortant

Vous êtes développeur·se sur Kirexo, une commande lancée depuis le conteneur échoue sur un domaine externe, et vous voulez l'autoriser. Cette recette explique où ajouter le domaine, comment recharger le proxy, et comment vérifier que ça passe.

Prérequis

  • Un terminal côté hôte ouvert à la racine du dépôt principal ou d'un worktree : toutes les commandes d'écriture sont hôte-only (voir l'encadré ci-dessous), et visent de toute façon les fichiers du dépôt principal.
  • La stack mutualisée démarrée (castor docker:up ou castor wt:up <ticket>) — le rechargement s'adresse au conteneur egress-proxy du projet kirexo-shared.
  • Le domaine exact à autoriser, sans schéma ni chemin (raw.githubusercontent.com, pas https://raw.githubusercontent.com/…).

Ouvrir un domaine se fait depuis l'hôte, jamais depuis le conteneur

Les fichiers de whitelist sont bind-montés en lecture seule dans le conteneur : toute écriture y renvoie Read-only file system. Et castor firewall:reload, firewall:whitelist-add et firewall:whitelist-remove refusent explicitement de tourner depuis l'intérieur.

C'est un double verrou volontaire : un agent qui pourrait s'ouvrir la sortie réseau rendrait le confinement cosmétique. Depuis le conteneur, seule la lecture est disponible (castor firewall:status) — Claude Code doit donc demander l'ouverture d'un domaine, pas la faire. Le rationale complet est dans Pourquoi la sortie réseau passe par un proxy à allowlist.

Étape 1 — Vérifier que le domaine n'est pas déjà couvert

castor firewall:status

La cible affiche un tableau Origine | Domaine (baseline = versionné, local = override personnel), le total, la ligne Lu dans <dossier> qui nomme le dossier réellement lu, les variables de proxy effectives, puis trois sondes réseau. Pour la liste seule, sans attendre les sondes :

castor firewall:status --no-probe

Un domaine listé couvre aussi tous ses sous-domaines. Si symfony.com est présent, ux.symfony.com et live.symfony.com le sont également — inutile de les ajouter.

Lecture directe des fichiers, sans Castor

Depuis la racine du dépôt principal — ailleurs, ces chemins désignent des fichiers que le proxy ne lit pas :

grep -v '^\s*#' infra/firewall/baseline-domains.txt | grep -v '^\s*$'
grep -v '^\s*#' infra/firewall/whitelist.local.txt 2>/dev/null | grep -v '^\s*$'

Et pour voir ce que le proxy applique réellement, le fichier généré : cat infra/egress/generated/allowlist.conf. Chaque ligne y porte un point de tête (.symfony.com) — c'est le générateur qui l'ajoute, on ne l'écrit jamais soi-même (voir Format des fichiers de whitelist).

Étape 2 — Choisir le bon fichier

Besoin Fichier Suivi par git
Domaine utile à toute l'équipe (registre, doc, service du projet) infra/firewall/baseline-domains.txt oui, à commiter
Domaine personnel ou ponctuel (mirror interne, service de votre entreprise) infra/firewall/whitelist.local.txt non, gitignored

Les deux fichiers sont ceux du dépôt principal, et valent pour tout le poste

Les cibles firewall:* lisent et écrivent dans <dépôt principal>/infra/firewall/, même lancées depuis un worktree : c'est là que le proxy mutualisé lit. La whitelist locale est donc commune à tous vos worktrees — un domaine ajouté depuis l'un est ouvert pour tous, et un domaine retiré est fermé pour tous.

Corollaire à l'édition manuelle : éditer infra/firewall/baseline-domains.txt dans un worktree n'a aucun effet sur le proxy tant que le commit n'est pas dans le dépôt principal. Le fichier whitelist.local.txt d'un worktree, lui, n'est jamais lu par le proxy — il n'est là que comme substrat du bind :ro de l'invariant C4. Le pourquoi est dans Une seule whitelist, celle du dépôt principal.

Étape 3a — Domaine personnel : la cible Castor

castor firewall:whitelist-add valide le format en amont, dédoublonne contre la baseline et contre les entrées locales, écrit dans infra/firewall/whitelist.local.txt, puis recharge le proxy — le tout en une commande :

# Depuis l'HÔTE, à la racine du dépôt
castor firewall:whitelist-add mirror-composer.boite-interne.example

Si le domaine est déjà couvert par la baseline (directement ou comme sous-domaine), la cible ne touche à rien et le dit. Pour retirer une entrée :

castor firewall:whitelist-remove mirror-composer.boite-interne.example

whitelist-remove ne touche pas à la baseline : elle réécrit uniquement le fichier local, en conservant commentaires et lignes vides. Les deux cibles terminent par un rechargement du proxy — rien d'autre à lancer.

Poste neuf : le fichier local est créé pour vous

<dépôt principal>/infra/firewall/whitelist.local.txt est créé depuis le modèle .dist par le préalable commun aux cibles qui démarrent une stack (castor docker:up, castor docs:build, castor image:refresh, castor wt:up). Il est gitignoré : sur un poste neuf, il n'existe pas encore, et castor firewall:whitelist-add ne saurait pas où écrire. Si vous démarrez la stack par un docker compose lancé à la main, créez-le vous-même :

# HÔTE, à la racine du dépôt principal
[ -e infra/firewall/whitelist.local.txt ] || cp infra/firewall/whitelist.local.txt.dist infra/firewall/whitelist.local.txt

castor wt:up crée en plus l'exemplaire du worktree, pour une tout autre raison : il sert de substrat au bind :ro de l'invariant C4, et n'alimente pas le proxy.

Étape 3b — Domaine partagé : éditer la baseline

Ajoutez le domaine dans infra/firewall/baseline-domains.txt, dans la section thématique qui convient, avec un commentaire qui explique pourquoi il est nécessaire :

# --- Écosystème PHP / Symfony ---------------------------------------------
# packagist.org : registre Composer (résolution des dépendances PHP).
packagist.org
# votre-domaine.example : ce que ce domaine sert, et pour quel usage.
votre-domaine.example

Puis rechargez le proxy :

castor firewall:reload

La cible régénère infra/egress/generated/allowlist.conf depuis les deux fichiers de whitelist, puis envoie un squid -k reconfigure au conteneur egress-proxy. Le processus n'est pas redémarré : les tunnels TLS en cours ne sont pas coupés.

Enfin, commitez — la baseline est la source de vérité versionnée :

git add infra/firewall/baseline-domains.txt
git commit -m "Autorise votre-domaine.example dans l'allowlist du proxy sortant"

Claude Code ne peut pas éditer ces fichiers

infra/firewall/ est verrouillé côté agent (montage :ro dans le conteneur, cibles de rechargement hôte-only). Si Claude a besoin d'un domaine pour une tâche, il doit vous le demander : c'est vous qui ajoutez la ligne et lancez le rechargement.

Étape 4 — Vérifier

castor firewall:status

Les trois sondes doivent afficher OK. Puis testez votre domaine depuis le conteneur :

castor docker:sh
curl -sS -o /dev/null -w '%{http_code}\n' https://votre-domaine.example

Une réponse HTTP confirme l'ouverture. Un curl: (56) CONNECT tunnel failed, response 403 signifie que le proxy refuse toujours le domaine — voir Diagnostiquer un blocage réseau sortant.

Format des fichiers de whitelist

Les deux fichiers partagent exactement le même format, lu côté bash par infra/egress/allowlist.lib.sh et côté PHP par castor/src/Firewall/FirewallWhitelist.php (une seule regex, verrouillée par un test de cohérence).

  • Une ligne = un FQDN nu : pas de schéma, pas de chemin, pas de port, pas de wildcard, pas d'IP littérale.
  • Jamais de point de tête. On écrit symfony.com ; c'est le générateur qui rend .symfony.com, forme qui couvre le domaine et ses sous-domaines.
  • Lignes vides ignorées, # en début de ligne = commentaire (les commentaires en fin de ligne ne sont pas supportés).
  • Une ligne invalide est ignorée avec un avertissement sur stderr, jamais fatale — une coquille ne doit pas couper toute la sortie réseau du poste.

Formes refusées et leur correction :

Entrée Pourquoi refusée
https://foo.com Schéma collé — écrire foo.com.
*.foo.com Wildcard inutile : foo.com couvre déjà tous les sous-domaines.
.foo.com Le point de tête est ajouté par le générateur, pas par vous.
1.2.3.4 IP littérale — une ACL dstdomain ne matche jamais une IP, l'entrée serait morte.
foo Single-label sans TLD.
foo.com/api, foo.com:8080 Chemin ou port — le proxy filtre le domaine du CONNECT, pas l'URL.
foo.com Accepté : les espaces autour sont supprimés, la casse est normalisée.

Le générateur dédoublonne aussi les entrées déjà couvertes par un parent : lister api.github.com alors que github.com est présent ne produit qu'une seule ligne dans l'allowlist finale. C'est normal, et c'est pour cela que le nombre de domaines affiché par castor firewall:status peut dépasser le nombre de lignes du fichier généré.

Cas particuliers

Le domaine refusé n'est pas celui que vous avez demandé

Le proxy filtre le domaine de chaque CONNECT, y compris ceux qu'une redirection ouvre. Le 403 nomme donc parfois un hôte que vous n'avez jamais tapé : c'est celui-là qu'il faut lister, en plus ou à la place du premier.

Le cas le plus courant est celui des assets de release GitHub. Un téléchargement annoncé sur github.com est redirigé vers release-assets.githubusercontent.com — présent dans la baseline pour cette raison — et c'est ce nom, jamais le premier, qui apparaît dans l'erreur :

In ErrorChunk.php line 73:
  CONNECT tunnel failed, response 403 for "https://release-assets.githubusercontent.com/…"

Lisez donc le domaine cité par le message, jamais celui de l'URL de départ. Et vérifiez l'emplacement du fichier avant de conclure que l'ouverture n'a pas fonctionné : un téléchargement refusé laisse souvent un artefact de 0 octet qui fait rejouer la même erreur, cf. Un téléchargement refusé laisse un artefact vide.

Le domaine partage une IP avec un domaine déjà autorisé

Ça ne suffit plus. Le filtre porte désormais sur le nom, pas sur l'IP résolue : un domaine absent de l'allowlist est refusé même s'il partage un CDN avec un domaine autorisé. Il faut donc lister explicitement chaque domaine utilisé, y compris ceux qui « passaient » auparavant.

Vous travaillez dans un worktree

Le proxy est mutualisé entre tous les worktrees, et les cibles firewall:* sont ancrées sur le dépôt principal : lancées depuis un worktree, elles écrivent et rendent l'allowlist dans le dépôt principal. Vous pouvez donc les lancer d'où vous voulez côté hôte — le résultat est le même, et c'est bien celui que le proxy applique.

Deux points restent à connaître :

  • l'ouverture vaut pour tous vos worktrees, puisqu'il n'y a qu'une whitelist locale sur le poste ;
  • depuis le conteneur d'un worktree, castor firewall:status lit la whitelist de ce worktree — le dépôt principal n'y est pas monté. La cible l'annonce (⚠️ Worktree : cette whitelist n'est PAS celle que le proxy applique) et affiche le dossier réellement lu. Dans la cellule du dépôt principal, il n'y a pas d'écart et aucun avertissement.

Dans tous les cas, ce sont les sondes qui mesurent la sortie réelle : aucune de ces cibles ne lit la politique chargée dans Squid.

Votre poste porte encore une whitelist à l'ancien emplacement

Avant la migration vers infra/firewall/, la whitelist locale vivait dans le dossier de configuration de l'environnement conteneurisé, à la racine du dépôt. Ce dossier a disparu du dépôt, mais le fichier étant gitignored, il a pu survivre sur votre poste sans suivre le déplacement du reste.

Il n'est plus lu : les seules sources de l'allowlist sont infra/firewall/baseline-domains.txt et infra/firewall/whitelist.local.txt (castor/src/Firewall/FirewallWhitelist.php). Aucune cible ne détecte ce résidu — le symptôme est un domaine que vous croyez autorisé et qui prend un 403. Le contrôle est manuel, côté hôte :

# HÔTE, à la racine du dépôt principal — ne doit rien rendre
find . -maxdepth 2 -name 'whitelist.local.txt' -not -path './infra/firewall/*'

Si un fichier ressort, reportez ses lignes utiles dans infra/firewall/whitelist.local.txt, supprimez le résidu, puis rechargez :

castor firewall:reload

Voir aussi