GitGuardian Bridge Self-Hosted

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

Le bridge n'ouvre aucune connexion entrante dans votre réseau isolé. Le client à l'intérieur de ce réseau établit une connexion sortante vers le serveur du bridge, et GitGuardian renvoie son trafic de scan via 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ù le serveur du bridge est installé.
• Un cluster Kubernetes à l'intérieur du réseau isolé, où le client est installé. 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é.
• Un accès 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 TLS mutuel, à l'aide de 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 correspondre exactement au nom d'hôte que le client contacte. Le client le vérifie et refuse de se connecter dans le cas contraire.

É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 les réplicas s'appuient.

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, plus 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 attacher à 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 attacher à 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 configure 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 la CA de 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, donc le chart le refuse également, 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 pour chaque 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 que publie 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 ; il est donc normal que kubectl get pods -n ggbridge affiche 0/1 pod proxy à ce stade. Ils deviennent disponibles d'eux-mêmes une fois le client en cours d'exécution — aucune sonde de vivacité ne les redémarre entre-temps.

Pour cette raison, la release du serveur ne peut pas atteindre un état sain d'elle-même. Ne la conditionnez pas à la disponibilité : helm --wait, ainsi que les outils GitOps qui attendent la santé des ressources comme Argo CD ou Flux, atteindront un délai d'expiration 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 à jour 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 du namespace hébergeant les serveurs du bridge, soit <namespace>.svc.cluster.local. Installez chaque serveur du bridge dans ce même namespace.
• subdomain doit correspondre exactement à la release du serveur.
• domains sont les noms d'hôtes que GitGuardian doit atteindre via ce bridge.

attention

Ces valeurs constituent la source de vérité. Supprimer un bridge ou un domaine de celles-ci le supprime de GitGuardian lors de la prochaine mise à jour ; 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 et le domain du serveur joints ensemble.

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, donc cette section est en lecture seule.

Ajouter un autre réseau isolé

Répétez tout le processus pour le deuxième réseau, avec son propre subdomain et nom d'hôte :

1. Émettez un nouveau certificat serveur et client à partir de la même CA, avec le nouveau nom d'hôte dans le certificat serveur.
2. Installez un deuxième serveur du bridge dans le même namespace que le premier.
3. Ajoutez une deuxième 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 à jour, effectuez à nouveau la mise à jour.
Les pods proxy du serveur sont NotReady après l'étape 3	Normal jusqu'à ce que le client se connecte : la sonde de disponibilité teste le tunnel. Continuez à l'étape 5.
L'installation du serveur atteint un délai d'expiration ou ne devient jamais saine	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 sortant 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 extrémités ne partagent pas la même CA.
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.