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.

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

Glissez pour voir

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
Collectors	Récupèrent les documents (SBOM, attestations) depuis diverses sources
Ingestor	Parse les documents et les traduit dans le modèle GUAC
Assembler	Stocke les données dans la base de données graphe
CollectSub	Coordonne les demandes d'informations supplémentaires
Certifiers	Enrichissent automatiquement avec des données externes (CVE, licences)
GraphQL Server	Expose les données via une API interrogeable

Glissez pour voir

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

Glissez pour voir

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

Glissez pour voir

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

Ces relations sont les arêtes du graphe, et ce sont elles qui font la valeur de GUAC : sans arêtes, vous n'auriez qu'une base de nœuds isolés, comme vos fichiers JSON de départ. La plus stratégique en réponse à incident est IsDependencyOf, car c'est elle qui remonte les dépendances transitives, ces composants que vous n'avez jamais installés directement mais qu'une de vos dépendances a tirés. Retenez le sens de lecture : la relation se lit de la dépendance vers ce qui la consomme, c'est en la parcourant à l'envers qu'une requête répond à « qui utilise ce paquet vulnérable ».

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

Glissez pour voir

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

Une attestation SLSA décrit la provenance d'un artefact : quel système de build l'a produit, à partir de quelle source, avec quels paramètres. Ingérée dans GUAC, elle alimente la relation HasSlsa et permet ensuite de répondre à « cet artefact a-t-il été construit par un pipeline de confiance ? », une question distincte de « contient-il une CVE ? ». La commande est la même que pour un SBOM, guacone collect files détecte le type de document. Le format attendu est le in-toto signé, souvent une ligne JSON par attestation, d'où l'extension .intoto.jsonl.

# 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 la 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

Glissez pour voir

Exemple : Ingestion automatique en CI

Le vrai gain de GUAC vient de l'alimentation continue : un SBOM généré à chaque push sur main, poussé automatiquement dans le graphe, garde l'inventaire aligné sur ce qui tourne réellement. Le workflow ci-dessous applique le moindre privilège attendu sur le site : permissions: {} au niveau global neutralise le jeton par défaut, chaque job ne réclame que ce dont il a besoin (contents: read pour lire le code), et persist-credentials: false empêche le checkout de laisser traîner le jeton Git dans le runner. Les deux actions sont épinglées par SHA commenté avec leur version, seule protection contre le redéploiement silencieux d'un tag mobile.

.github/workflows/supply-chain.yml

name: Supply Chain Security

on:
  push:
    branches: [main]

permissions: {}

jobs:
  sbom-to-guac:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - name: Generate SBOM
        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610  # v0.24.0
        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

La plupart des blocages de GUAC ne sont pas des erreurs mais des silences trompeurs : le graphe répond sans jamais planter, il répond juste vide. Le réflexe de diagnostic est donc de distinguer trois couches, dans l'ordre : les données ont-elles été ingérées (guacone collect), les certifiers tournent-ils pour enrichir en vulnérabilités (guacone certifier osv), et les conteneurs sont-ils tous debout (docker compose ps). Le tableau ci-dessous suit cet ordre, du plus fréquent au plus structurel, et docker compose logs reste l'arbitre quand le symptôme reste ambigu.

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

Glissez pour voir

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 : la CLI couvre 80% des besoins, mais GraphQL débloque les cas complexes

Pour aller plus loin

Kusari : décisions go/no-go Transformer les données GUAC en contrôles bloquants dans les PR

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

×

📖 Voir la documentation →