GitGuardian Bridge Self-Hosted

GitGuardian Bridge (ggbridge) permet à votre installation GitGuardian de scanner des sources qu'elle ne peut pas atteindre directement, comme une instance GitLab dans un réseau isolé ou derrière un pare-feu.

Le bridge n'ouvre aucune connexion entrante vers votre réseau isolé. Le client situé à l'intérieur de ce réseau se connecte vers l'extérieur au serveur du bridge, et GitGuardian renvoie son trafic de scan par cette unique connexion.

info

Disponible à partir de GitGuardian 2026.9.0.

GitGuardian Bridge doit être activé sur votre licence. Contactez votre représentant GitGuardian si la section décrite ci-dessous n'apparaît pas dans votre dashboard.

Cette page couvre GitGuardian Bridge sur une installation self-hosted, où vous installez vous-même le serveur du bridge et déclarez les bridges dans vos valeurs Helm. Sur GitGuardian SaaS, les bridges sont créés et gérés depuis le dashboard : voir GitGuardian Bridge, qui liste également les services pris en charge par le bridge.

Fonctionnement

Un bridge est une paire de releases ggbridge :

• un serveur, installé dans le cluster qui exécute GitGuardian
• un client, installé à l'intérieur du réseau isolé

Chaque réseau isolé nécessite sa propre paire. Si vous avez deux réseaux isolés, installez deux serveurs et deux clients.

Avant de commencer

• Un cluster Kubernetes exécutant GitGuardian, où se trouve le serveur du bridge.
• Un cluster Kubernetes à l'intérieur du réseau isolé, où se trouve le client. S'il n'y en a pas, k3s/k3d sur une seule VM suffit — voir le dépôt ggbridge pour cette configuration.
• Un enregistrement DNS public pointant vers le serveur du bridge, accessible depuis le réseau isolé.
• Le HTTPS sortant autorisé depuis le réseau isolé vers ce nom d'hôte.
• Istio, Gateway API ou un contrôleur Ingress dans ce cluster, pour exposer le serveur.

Tout au long de cette page, le bridge d'exemple est nommé network-a et accessible à network-a.bridge.example.com.

Étape 1 : Générer les certificats

attention

Vous devez vous appuyer sur votre propre autorité de certification et vos procédures internes pour générer/obtenir ces certificats. Ce qui suit est fourni à titre d'exemple de base.

Le bridge authentifie les deux extrémités avec un TLS mutuel, en utilisant des certificats que vous fournissez. Créez une autorité de certification, un certificat serveur et un certificat client.

HOST=network-a.bridge.example.com

# Certificate Authority
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout ca.key -out ca.crt -subj "/CN=ggbridge-ca"

# Server certificate
printf 'subjectAltName=DNS:%s\nextendedKeyUsage=serverAuth\nbasicConstraints=critical,CA:FALSE\n' "$HOST" > server.ext
openssl req -newkey rsa:4096 -nodes -keyout server.key -out server.csr -subj "/CN=$HOST"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt -days 825 -sha256 -extfile server.ext

# Client certificate
printf 'extendedKeyUsage=clientAuth\nbasicConstraints=critical,CA:FALSE\n' > client.ext
openssl req -newkey rsa:4096 -nodes -keyout client.key -out client.csr -subj "/CN=network-a-client"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt -days 825 -sha256 -extfile client.ext

attention

Le subjectAltName du certificat serveur doit être exactement le nom d'hôte que le client contacte. Le client le vérifie et refuse de se connecter sinon.

Étape 2 : Créer les secrets

Dans le cluster GitGuardian :

kubectl create namespace ggbridge
kubectl -n ggbridge create secret generic ggbridge-network-a-server-tls \
  --from-file=ca.crt=ca.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

Dans le réseau isolé :

kubectl create namespace ggbridge
kubectl -n ggbridge create secret generic ggbridge-network-a-client-tls \
  --from-file=ca.crt=ca.crt --from-file=tls.crt=client.crt --from-file=tls.key=client.key

Étape 3 : Installer le serveur du bridge

Choisir comment exposer le serveur

Le client se connecte depuis l'extérieur du cluster, le serveur a donc besoin d'un point d'entrée. Choisissez celui que votre cluster exécute déjà — les trois prennent en charge le TLS mutuel et le routage par chemin sur lequel s'appuient les réplicas.

Ce que vous exécutez déjà	À ajouter à vos valeurs
Istio	server.istio.enabled: true
Gateway API	server.gateway.enabled: true
Un contrôleur Ingress	server.ingress.enabled: true, ainsi que server.ingress.controller pour nginx ou traefik

Istio

server:
  istio:
    enabled: true

Cible la gateway étiquetée istio: ingress. Pour une étiquette différente, définissez server.istio.gateway.selector. Pour vous rattacher à des gateways que vous gérez déjà, listez-les dans server.istio.gateways et définissez server.istio.gateway.create: false.

Gateway API

server:
  gateway:
    enabled: true
    gateway:
      className: your-gateway-class

Pour vous rattacher à une Gateway existante à la place, définissez server.gateway.parentRefs et server.gateway.gateway.create: false.

Ingress

server:
  ingress:
    enabled: true
    controller: nginx # or traefik
    className: nginx

attention

Le chart câble la vérification du certificat client pour nginx et traefik uniquement. Avec un autre contrôleur, ajoutez ses propres annotations d'authentification client via server.ingress.annotations, en pointant vers l'autorité de certification dans votre secret TLS.

N'exposez pas le serveur avec un simple Service LoadBalancer. Un Service ne peut pas router les chemins /0, /1, /2 sur lesquels les réplicas sont atteints, c'est pourquoi le chart refuse cela aussi sauf si deploymentCount vaut 1.

Installer

Créez server-values.yaml, en combinant les éléments de base avec le bloc d'exposition que vous avez choisi. Remplacez domain par le vôtre, et gardez subdomain court et unique par bridge.

mode: server

subdomain: network-a
domain: bridge.example.com

tls:
  enabled: true
  existingSecret: ggbridge-network-a-server-tls

server:
  istio:
    enabled: true

Puis installez-le :

helm -n ggbridge upgrade --install --create-namespace \
  ggbridge-network-a oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge \
  -f server-values.yaml

Faites pointer votre enregistrement DNS pour network-a.bridge.example.com vers l'adresse publiée par votre méthode d'exposition.

attention

Les pods proxy du serveur restent NotReady jusqu'à ce que le client de l'étape 5 se connecte. Leur sonde de disponibilité teste le tunnel lui-même, et il n'y a pas encore de tunnel, donc kubectl get pods -n ggbridge affichant 0/1 pods proxy à ce stade est attendu. Ils deviennent disponibles par eux-mêmes une fois le client en cours d'exécution — aucune sonde de vivacité ne les redémarre entre-temps.

De ce fait, la release serveur ne peut pas atteindre un état sain par elle-même. Ne la conditionnez pas à la disponibilité : helm --wait, et les outils GitOps qui attendent la santé des ressources comme Argo CD ou Flux, expireront ici. Installez le serveur sans attendre, puis continuez à l'étape 5.

Étape 4 : Déclarer le bridge dans GitGuardian

Ajoutez le bloc GGBridge à vos valeurs Helm GitGuardian, puis mettez à niveau votre release.

GGBridge:
  enabled: true
  basePublicDomain: bridge.example.com
  baseInternalDomain: ggbridge.svc.cluster.local
  bridges:
    - subdomain: network-a
      name: Isolated network A
      domains:
        - gitlab.internal.example.com

• basePublicDomain est le domain de l'étape 3.
• baseInternalDomain est le suffixe DNS du cluster pour le namespace contenant les serveurs du bridge, soit <namespace>.svc.cluster.local. Installez chaque serveur du bridge dans ce namespace unique.
• subdomain doit correspondre exactement à la release serveur.
• domains sont les noms d'hôte que GitGuardian doit atteindre via ce bridge.

attention

Ces valeurs font foi. Supprimer un bridge ou un domaine de celles-ci le retire de GitGuardian lors de la prochaine mise à niveau, gardez donc le fichier sous contrôle de version.

Étape 5 : Installer le client du bridge

Créez client-values.yaml à l'intérieur du réseau isolé. hostname est le subdomain du serveur et le domain concaténés.

hostname: network-a.bridge.example.com

tls:
  enabled: true
  existingSecret: ggbridge-network-a-client-tls

Puis installez-le :

helm -n ggbridge upgrade --install --create-namespace \
  ggbridge-network-a oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge \
  -f client-values.yaml

Les deux côtés exécutent trois réplicas par défaut pour la haute disponibilité. Si vous modifiez deploymentCount, définissez la même valeur sur le serveur et le client.

Étape 6 : Vérifier

Dans GitGuardian, ouvrez Settings → Workspace → Security. Le bridge apparaît dans la section GitGuardian bridge (ggbridge) et passe à Connected environ une minute après le démarrage du client.

Ajoutez ensuite votre source, par exemple votre GitLab self-hosted, et lancez un scan. Le trafic vers les domaines que vous avez listés transite désormais par le bridge.

remarque

Sur une installation self-hosted, les bridges sont entièrement gérés via vos valeurs Helm, cette section est donc en lecture seule.

Ajouter un autre réseau isolé

Répétez l'ensemble du processus pour le second réseau, avec son propre subdomain et nom d'hôte :

1. Émettez un nouveau certificat serveur et client depuis la même autorité de certification, avec le nouveau nom d'hôte dans le certificat serveur.
2. Installez un second serveur du bridge dans le même namespace que le premier.
3. Ajoutez une seconde entrée à GGBridge.bridges.
4. Installez un client dans le nouveau réseau.

Chaque réseau doit avoir sa propre paire. Un seul serveur du bridge ne peut pas desservir deux réseaux.

Dépannage

Symptôme	Ce qu'il faut vérifier
La section est absente du dashboard	GitGuardian Bridge n'est pas activé sur votre licence.
Le bridge est sous licence mais la section reste vide	Les bridges sont créés lors d'un déploiement. Si GitGuardian Bridge a été activé sur votre licence après votre dernière mise à niveau, mettez à niveau de nouveau.
Les pods proxy du serveur sont NotReady après l'étape 3	Attendu jusqu'à ce que le client se connecte : la sonde de disponibilité teste le tunnel. Continuez à l'étape 5.
L'installation du serveur expire ou n'atteint jamais l'état sain	Vous avez conditionné la release à la disponibilité (helm --wait, ou une vérification de santé GitOps). Le serveur ne peut pas être sain avant l'existence de son client — installez-le sans attendre.
Le bridge reste sur Waiting for first connection	Le client ne peut pas atteindre le serveur. Vérifiez le DNS, les règles de pare-feu sortantes et les logs du client.
Le client enregistre une erreur de certificat	Le subjectAltName du certificat serveur ne correspond pas au nom d'hôte que le client contacte, ou les deux côtés ne partagent pas la même autorité de certification.
Le bridge est connecté mais les scans échouent	Le domaine est absent de GGBridge.bridges[].domains, ou la source n'est pas accessible depuis le réseau du client.

Pour plus de détails, voir le guide de dépannage ggbridge.