GUAC : visualiser et interroger votre supply chain

Vous avez généré des SBOM pour documenter vos composants logiciels. Vous avez des scans de vulnérabilités qui s’accumulent. Vous avez peut-être même des attestations SLSA pour prouver la provenance de vos builds. Mais quand une nouvelle CVE critique tombe un vendredi soir, êtes-vous capable de répondre rapidement à cette question : “Quels sont tous les artefacts en production qui utilisent log4j 2.14.0 ?”

Si la réponse implique de fouiller manuellement dans des dizaines de fichiers JSON, vous avez besoin de GUAC.

Qu’est-ce que GUAC ?

GUAC (prononcé “gouac”, comme la sauce mexicaine) signifie Graph for Understanding Artifact Composition. C’est un outil open source qui agrège toutes vos métadonnées de sécurité supply chain dans un graphe de connaissances interrogeable.

L'analogie du graphe

Imaginez une carte de métro géante où chaque station représente un composant logiciel (un package npm, une image Docker, un binaire). Les lignes de métro représentent les relations : “dépend de”, “a une vulnérabilité”, “provient de ce dépôt Git”. GUAC construit cette carte automatiquement à partir de vos SBOM, scans et attestations.

Pourquoi un graphe ?

Les outils traditionnels traitent les données de sécurité en silos :

• Un SBOM par image → fichier JSON isolé
• Un scan Trivy → rapport séparé
• Une attestation SLSA → document distinct

GUAC connecte toutes ces informations pour révéler les relations cachées. Par exemple : “Cette CVE affecte ce package → qui est inclus dans cette image → qui est déployée dans ces 15 services”.

Sans GUAC	Avec GUAC
500 fichiers SBOM à parcourir manuellement	Une requête pour tout le parc
”Est-ce qu’on utilise log4j ?” → plusieurs heures	Réponse en quelques secondes
Impact d’une CVE 0-day ? → “on ne sait pas”	Graphe des dépendances transitives
Corrélation CVE ↔ SBOM ↔ SLSA → tableur Excel	Relations automatiques dans le graphe

Projet OpenSSF

GUAC est un projet incubé à l’OpenSSF (Open Source Security Foundation), développé initialement par Google en collaboration avec Kusari, Purdue University et Citi. L’objectif est de démocratiser la visibilité sur la supply chain logicielle, un besoin rendu critique par des attaques comme SolarWinds ou Log4Shell.

Architecture de GUAC

Avant de passer à l’installation, comprenons comment GUAC fonctionne. Cette compréhension vous aidera à diagnostiquer les problèmes et à optimiser votre déploiement.

Les composants expliqués

Composant	Rôle	Analogie
Collectors	Récupèrent les documents (SBOM, attestations) depuis diverses sources	Le facteur qui récupère le courrier
Ingestor	Parse les documents et les traduit dans le modèle GUAC	Le traducteur qui standardise les formats
Assembler	Stocke les données dans la base de données graphe	L’archiviste qui range tout
CollectSub	Coordonne les demandes d’informations supplémentaires	Le chef d’équipe qui distribue le travail
Certifiers	Enrichissent automatiquement avec des données externes (CVE, licences)	Les enquêteurs qui creusent chaque piste
GraphQL Server	Expose les données via une API interrogeable	Le bibliothécaire qui répond aux questions

Backends supportés

GUAC supporte deux backends de stockage :

• In-memory : pour les démos et tests (données perdues au redémarrage)
• PostgreSQL : pour la production (persistance, performance)

En production, utilisez toujours PostgreSQL avec l’ORM ent ↗.

Prérequis

Avant d’installer GUAC, assurez-vous d’avoir :

• Docker et Docker Compose (v2.x recommandé)
• Au moins 4 Go de RAM disponibles pour les conteneurs
• Des SBOM à ingérer (sinon, GUAC sera vide et inutile)
• Optionnel : PostgreSQL 14+ si vous voulez la persistance

Générer des SBOM

Pas encore de SBOM ? Consultez le guide SBOM pour apprendre à les générer avec Syft ou Trivy.

Installation

Docker Compose (démo)

Cette méthode utilise le backend in-memory. Idéale pour découvrir GUAC, mais les données sont perdues au redémarrage.

# Cloner le dépôt officiel
git clone https://github.com/guacsec/guac.git
cd guac

# Démarrer tous les services
docker compose up -d

Services démarrés :

Service	Port	Description
GraphQL API	8080	Point d’entrée pour les requêtes
Visualizer	3000	Interface web d’exploration
NATS	4222	Bus de messages interne
Collector	-	Écoute les nouvelles données

Vérification :

# Vérifier que tous les conteneurs tournent
docker compose ps

# Tester l'API GraphQL
curl -s http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "{ packages { type } }"}'

Vous devriez obtenir une réponse JSON (probablement vide si aucun SBOM n’a été ingéré).

Docker Compose + PostgreSQL

Cette méthode utilise PostgreSQL pour la persistance. Recommandée pour tout usage au-delà de la simple découverte.

git clone https://github.com/guacsec/guac.git
cd guac

# Utiliser la configuration PostgreSQL
docker compose -f docker-compose-postgres.yml up -d

Configuration PostgreSQL personnalisée :

Si vous avez déjà un PostgreSQL, créez un fichier .env :

.env

POSTGRES_HOST=votre-serveur-postgres.example.com
POSTGRES_PORT=5432
POSTGRES_USER=guac
POSTGRES_PASSWORD=votre-mot-de-passe-securise
POSTGRES_DB=guac

Sécurité PostgreSQL

En production :

• Ne jamais utiliser le mot de passe par défaut
• Activer SSL/TLS pour la connexion PostgreSQL
• Restreindre les accès réseau à la base

Binaires

Pour un déploiement sans Docker, téléchargez les binaires :

# Télécharger la dernière version
VERSION=$(curl -s https://api.github.com/repos/guacsec/guac/releases/latest | grep tag_name | cut -d '"' -f 4)
curl -LO "https://github.com/guacsec/guac/releases/download/${VERSION}/guacone-linux-amd64"

# Rendre exécutable
chmod +x guacone-linux-amd64
sudo mv guacone-linux-amd64 /usr/local/bin/guacone

# Vérifier l'installation
guacone version

guacone vs guac

guacone est un binaire “tout-en-un” qui combine collector, ingestor et certifier. Pratique pour les tests et les petits déploiements. Pour la production à grande échelle, déployez les composants séparément.

Concepts clés : le modèle de données

GUAC organise les informations dans un graphe composé de nœuds (entités) et d’arêtes (relations). Comprendre ce modèle est essentiel pour écrire des requêtes efficaces.

Les types de nœuds

Type de nœud	Ce que c’est	Exemple concret
Package	Un composant logiciel identifié par un pURL	pkg:npm/lodash@4.17.21
Source	Un dépôt de code source	git+https://github.com/lodash/lodash
Artifact	Un fichier binaire ou une image	sha256:abc123... (image Docker)
Vulnerability	Une faille de sécurité connue	CVE-2021-44228 (Log4Shell)
Builder	Un système de build	https://github.com/actions

Qu'est-ce qu'un pURL ?

Un pURL (Package URL) est un format standardisé pour identifier un package de manière unique, quel que soit l’écosystème. Format : pkg:type/namespace/name@version

Exemples :

• pkg:npm/express@4.18.2 → package npm “express” version 4.18.2
• pkg:pypi/requests@2.28.0 → package Python “requests”
• pkg:golang/github.com/gin-gonic/gin@1.9.1 → module Go

Les types de relations

Relation	Ce qu’elle signifie	Utilité
IsDependencyOf	A est une dépendance de B	Tracer les dépendances transitives
HasSBOM	L’artefact possède un SBOM	Vérifier la couverture SBOM
CertifyVuln	Le package a une vulnérabilité connue	Identifier les composants vulnérables
HasSlsa	L’artefact a une attestation SLSA	Vérifier la provenance
HasSourceAt	Le package provient de ce dépôt	Tracer l’origine du code
IsOccurrenceOf	Cet artefact est une instance de ce package	Lier binaires et packages

Visualiser les relations

Voici comment ces relations forment un graphe pour une image Docker :

Ingérer des données

Un GUAC vide est inutile. Voyons comment alimenter le graphe avec vos données de sécurité.

Ingérer un SBOM

1. Générer un SBOM (si vous n’en avez pas déjà)

   # Avec Syft
   syft myimage:latest -o cyclonedx-json > sbom.json

2. Ingérer le SBOM dans GUAC

   # Avec guacone
   guacone collect files sbom.json

   Sortie attendue :

   {"level":"info","msg":"Collecting files from: sbom.json"}
   {"level":"info","msg":"Successfully ingested 1 document(s)"}

3. Vérifier l’ingestion

   Ouvrez le Visualizer sur http://localhost:3000 ↗ et recherchez votre package.

Ingérer depuis un registry OCI

GUAC peut extraire automatiquement les SBOM attachés aux images OCI :

# Ingérer depuis GitHub Container Registry
guacone collect oci ghcr.io/mon-org/mon-image:v1.0.0

# Ingérer depuis Docker Hub
guacone collect oci docker.io/library/nginx:latest

SBOM dans les registries OCI

Pour que cela fonctionne, l’image doit avoir un SBOM attaché (via Cosign ou Syft). De plus en plus de projets open source attachent leurs SBOM, mais ce n’est pas encore universel.

Ingérer des vulnérabilités (OSV)

Le certifier OSV surveille automatiquement les nouveaux packages et vérifie s’ils ont des vulnérabilités connues dans la base OSV.dev ↗ :

# Lancer le certifier OSV (s'exécute en continu)
guacone certifier osv

Connexion Internet requise

Le certifier OSV nécessite une connexion à Internet pour interroger l’API OSV. En environnement air-gapped, vous devrez alimenter manuellement les données de vulnérabilités.

Ingérer des attestations SLSA

# Ingérer une attestation de provenance signée
guacone collect files provenance.intoto.jsonl

Interroger GUAC

GUAC expose une API GraphQL. Vous pouvez l’interroger via :

• L’interface Visualizer (http://localhost:3000 ↗)
• cURL ou tout client HTTP
• Le CLI guacone pour les requêtes courantes

Via le CLI : requêtes courantes

Trouver les vulnérabilités d’un package :

guacone query vuln "pkg:npm/lodash@4.17.20"

Sortie :

+-------------+-----------+---------------------------------------+
| NODE TYPE   | NODE ID   | ADDITIONAL INFORMATION                |
+-------------+-----------+---------------------------------------+
| certifyVuln | 148776    | vulnerability ID: ghsa-35jh-r3h4-6jhm |
| certifyVuln | 148777    | vulnerability ID: cve-2021-23337      |
+-------------+-----------+---------------------------------------+

Obtenir tout ce qu’on sait sur un package :

guacone query known "pkg:golang/github.com/prometheus/client_golang@1.11.0"

Via GraphQL : requêtes avancées

Pour des requêtes complexes, utilisez directement l’API GraphQL.

Exemple 1 : Tous les packages vulnérables dans le graphe

query TousLesPackagesVulnerables {
  CertifyVuln(certifyVulnSpec: {}) {
    package {
      type
      namespaces {
        namespace
        names {
          name
          versions {
            version
          }
        }
      }
    }
    vulnerability {
      vulnerabilityIDs {
        vulnerabilityID
      }
    }
  }
}

Exécution via cURL :

curl -s http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ CertifyVuln { package { type namespaces { names { name versions { version } } } } vulnerability { vulnerabilityIDs { vulnerabilityID } } } }"
  }' | jq .

Exemple 2 : Impact d’une CVE spécifique

“Quels artefacts sont impactés par Log4Shell ?”

query ImpactLog4Shell {
  CertifyVuln(
    certifyVulnSpec: {
      vulnerability: { vulnerabilityID: "cve-2021-44228" }
    }
  ) {
    package {
      namespaces {
        names {
          name
          versions {
            version
          }
        }
      }
    }
  }
}

Exemple 3 : Packages sans SBOM

“Quels packages n’ont pas de SBOM attaché ?” (pour identifier les trous de couverture)

query PackagesSansSBOM {
  packages(pkgSpec: {}) {
    namespaces {
      names {
        name
        versions {
          version
          # Si ce package n'apparaît pas dans HasSBOM, c'est qu'il manque
        }
      }
    }
  }
}

Cas d’usage concrets

Réponse aux incidents (CVE 0-day)

Scénario : Une nouvelle CVE critique (type Log4Shell) est publiée un vendredi à 17h. Vous devez identifier rapidement tous les systèmes impactés.

1. Identifier le package concerné

   La CVE mentionne log4j-core versions 2.0 à 2.14.1. Le pURL est : pkg:maven/org.apache.logging.log4j/log4j-core

2. Requêter GUAC

   guacone query vuln "pkg:maven/org.apache.logging.log4j/log4j-core"

3. Analyser les résultats

   GUAC retourne la liste de tous les artefacts qui utilisent log4j (directement ou transitivement).

4. Prioriser la remédiation

   • Production critique → patch immédiat
   • Environnements de dev → planifier
   • Dépendances transitives → évaluer le risque réel

Temps de réponse : Quelques minutes au lieu de plusieurs heures.

Conformité réglementaire (CRA, NIS2)

Le Cyber Resilience Act européen et NIS2 imposent :

• Inventaire des composants logiciels → SBOM dans GUAC
• Traçabilité des artefacts → Attestations SLSA dans GUAC
• Gestion des vulnérabilités → Certifiers OSV dans GUAC

Requête d’audit : “Prouvez que vous savez ce qui compose votre logiciel”

# Export de tous les packages connus
guacone query known --all > inventaire-complet.json

Évaluation avant adoption

Avant d’ajouter une nouvelle dépendance, interrogez GUAC :

query EvaluerDependance {
  # Score OpenSSF Scorecard
  scorecards(scorecardSpec: { source: { name: "github.com/nouveau/projet" } }) {
    aggregateScore
    checks {
      check
      score
    }
  }

  # Historique de vulnérabilités
  CertifyVuln(
    certifyVulnSpec: { package: { name: "nouveau-projet" } }
  ) {
    vulnerability {
      vulnerabilityIDs {
        vulnerabilityID
      }
    }
  }
}

Intégrations

GUAC s’intègre dans votre écosystème existant :

Outil	Type d’intégration	Direction
Syft / Trivy	Générateurs SBOM	SBOM → GUAC
Cosign	Signatures et attestations	Attestations → GUAC
Grype	Scanner de vulnérabilités	Résultats scan → GUAC
Dependency-Track	Gestion vulnérabilités	Bidirectionnel
GitHub Actions	CI/CD	Ingestion automatique
Harbor	Registry OCI	Pull SBOM automatique

Exemple : Ingestion automatique en CI

.github/workflows/supply-chain.yml

name: Supply Chain Security

on:
  push:
    branches: [main]

jobs:
  sbom-to-guac:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Generate SBOM
        uses: anchore/sbom-action@v0
        with:
          format: cyclonedx-json
          output-file: sbom.json

      - name: Push to GUAC
        run: |
          curl -X POST http://guac.internal:8080/collect/files \
            -F "file=@sbom.json"

Dépannage

Symptôme	Cause probable	Solution
”No packages found”	SBOM pas encore ingéré	Vérifier guacone collect et les logs
Visualizer ne répond pas	Port 3000 non exposé	Vérifier docker compose ps
Pas de vulnérabilités	Certifier OSV non lancé	Lancer guacone certifier osv
Ingestion lente	Backend in-memory saturé	Passer à PostgreSQL
”Connection refused” GraphQL	API pas démarrée	Vérifier le conteneur guac-graphql

Logs de débogage

# Voir les logs de tous les conteneurs GUAC
docker compose logs -f

# Logs d'un composant spécifique
docker compose logs -f guac-ingestor

À retenir

1. GUAC = graphe de connaissances qui connecte SBOM, vulnérabilités, attestations SLSA et dépendances

2. Une requête remplace des heures de recherche manuelle lors d’incidents de sécurité

3. Les certifiers enrichissent automatiquement le graphe avec les données OSV, Scorecard et licences

4. PostgreSQL en production : le backend in-memory est uniquement pour les démos

5. L’alimentation est clé : un GUAC vide est inutile. Intégrez la génération et l’ingestion SBOM dans votre CI/CD

6. GraphQL pour les requêtes avancées : le CLI couvre 80% des besoins, mais GraphQL débloque les cas complexes

Pour aller plus loin

SBOM avec Syft Générer les SBOM à ingérer dans GUAC

VEX : qualifier les CVE Indiquer si une CVE vous affecte vraiment

SLSA : provenance des builds Générer les attestations pour GUAC

OpenSSF Scorecard Évaluer la posture sécurité des projets

Ressources externes

• Documentation officielle GUAC ↗
• Dépôt GitHub ↗
• Site web du projet ↗
• OpenSSF Supply Chain Integrity WG ↗