Connecter un dépôt Git

Ctadel analyse vos dépôts à chaque push et à chaque pull request : Terraform, manifestes Kubernetes, Dockerfiles, secrets dans les sources et dépendances vulnérables. Le résultat revient dans la pull request sous forme de commentaire et de statut de vérification, et dans l’application.

GitHub ou GitLab

Installer l’application GitHub

1. Ouvrez « Paramètres », onglet « Intégrations », sous-onglet « Git (IaC) ».
2. Cliquez sur « Installer Ctadel sur GitHub ». Votre instance vous envoie vers GitHub ; le lien est valable dix minutes.
3. Sur GitHub, choisissez l’organisation et les dépôts à couvrir, tous ou une sélection.
4. GitHub vous ramène sur votre instance. Le message « Application GitHub installée » confirme la création de l’intégration : « Les webhooks sont livrés automatiquement. Le premier scan se déclenche au prochain push ou à la prochaine PR. »

Ctadel ne stocke que l’identifiant d’installation. À chaque besoin, Ctadel obtient de GitHub un jeton de courte durée, jamais conservé.

L’application demande l’accès en écriture contents et pull_requests, nécessaires pour ouvrir la pull request d’étiquetage décrite plus bas et pour écrire un dossier dans le dépôt. Si une installation plus ancienne ne les a pas, un bandeau « Autorisez à nouveau Ctadel sur … » apparaît avec le bouton « Vérifier les permissions sur GitHub ». Les analyses continuent sans ces droits ; seule l’ouverture de pull requests attend.

L’application lit aussi les coureurs auto-hébergés, avec deux permissions en lecture seule : « Self-hosted runners » sur l’organisation et « Administration » sur les dépôts. Le graphe montre alors les coureurs sur lesquels vos workflows peuvent tourner, avec leurs étiquettes, leur système et leur état, les jobs que chacun sert, et la machine sur laquelle il tourne quand elle est dans l’un de vos comptes cloud. Sans ces permissions, rien d’autre ne change.

Avec la permission en lecture seule « Organization administration », l’application liste aussi les autres applications GitHub installées sur votre organisation : chacune apparaît dans le graphe comme un compte de service de l’organisation, avec son numéro d’installation, le compte qui publie l’application et les permissions qui lui ont été accordées. Sans elle, rien d’autre ne change.

Ctadel vérifie la signature de chaque livraison de GitHub avant de la traiter. Une livraison que votre instance ne peut pas recevoir sur le moment est conservée et réessayée pendant 48 heures.

Connecter GitLab

1. Dans le même sous-onglet, cliquez sur « Connecter Ctadel à GitLab ». GitLab vous demande d’autoriser l’application avec les portées api et read_repository.
2. De retour sur votre instance, le bandeau « GitLab connecté — terminez la configuration » affiche un secret de webhook. Il n’est affiché qu’une fois.
3. Dans chaque projet GitLab à analyser, créez un webhook vers https://<INSTANCE>/webhook/git (votre instance Ctadel), collez ce secret dans le champ de jeton secret du webhook, et cochez les événements de push et de merge request.
4. Modifiez l’intégration pour lui donner un « Libellé ».

Le jeton OAuth est celui de l’utilisateur qui a autorisé : les analyses accèdent aux projets avec ses droits. Il est conservé dans la base de votre instance et renouvelé automatiquement avant chaque analyse qui en a besoin. Quand cet utilisateur est mainteneur du projet, le graphe montre aussi les coureurs enregistrés sur le projet et sur ses groupes.

Ce qui se passe à chaque push et pull request

Deux interrupteurs par intégration, activés par défaut : « Scanner à chaque push » et « Scanner chaque pull request ». Côté GitHub, Ctadel reçoit les événements push et pull_request (ouverture, nouveau commit, réouverture). Côté GitLab, les événements de push et de merge request (ouverture, réouverture, mise à jour).

Pour chaque événement, Ctadel clone le commit seul, sans l’historique, lance les trois familles sur cette copie, puis la supprime.

Chaque analyse a sa page dans l’application, liée depuis le commentaire de la pull request. Les constats rejoignent les pages IaC, Secrets et Vulnérabilités.

Une pull request fermée sans fusion ne sera jamais déployée : les constats IaC qu’elle avait introduits sont résolus aussitôt.

Le commentaire et le statut de vérification

Sur GitHub, chaque famille publie un commentaire dans la pull request et un statut sur le commit. Le commentaire est mis à jour à chaque nouveau commit plutôt que dupliqué. Le commentaire IaC liste au plus dix constats, du plus grave au moins grave, avec le lien vers le rapport complet. Le statut ctadel/sca reste « pending » pendant la confrontation à la NVD, puis prend son état final.

La « Politique par analyseur » de l’intégration décide, famille par famille, de ce que vaut le statut :

Blocage activé, le statut passe en échec dès qu’un constat atteint le seuil. Blocage désactivé, le statut est toujours en succès et l’intégration affiche « (info) » à côté de la famille. Dans les deux cas, GitHub ne bloque la fusion que si votre règle de protection de branche exige le contexte de statut correspondant.

Sur GitLab, l’analyse IaC publie une note dans la merge request, mise à jour à chaque commit, et un statut sur le commit. Les familles secrets et dépendances ne publient rien dans GitLab ; leurs constats sont dans l’application.

Le fichier .ctadel.yaml

Un fichier .ctadel.yaml à la racine du dépôt porte deux choses : le dossier où classer le dépôt dans l’application, et des règles d’ignorance.

version: 1
folder: "Production/Europe/France"
ignores:
  - rule: IAC-AWS-S3-001
    paths:
      - "**/sandbox/*.tf"
    resources:
      - aws_s3_bucket.logs
    reason: "Bucket de journaux interne, accès public exigé par le CDN"
    expires: "2027-01-31"

• rule : une clé de règle exacte, ou un préfixe suivi de *. Obligatoire.
• paths : des motifs de chemins. Un motif sans / ni ** ne s’applique qu’à la racine du dépôt.
• resources : des adresses de ressources (type.nom en Terraform, Kind/namespace/nom en Kubernetes).
• reason : obligatoire, dix caractères au minimum.
• expires : facultatif. Passée la date, l’entrée est ignorée et le constat réapparaît.

Un constat couvert par une règle est conservé avec l’état « Ignoré », pas supprimé : il reste visible dans l’application avec la raison. Une règle ne couvre que les familles IaC et secrets. Un fichier invalide n’arrête pas l’analyse : l’erreur est reportée dans le rapport de l’analyse et aucune règle ne s’applique.

Le champ folder classe le dépôt dans l’arborescence de « Dossiers » de l’application ; les dossiers manquants sont créés. Dans l’autre sens, déplacer un dépôt GitHub dans un dossier depuis l’application ouvre une pull request qui écrit la ligne folder: du fichier. Le fichier reste la référence : le dossier est confirmé à l’analyse suivante, après fusion.

La pull request d’étiquetage

Après l’installation sur GitHub, Ctadel ouvre dans chaque dépôt accessible qui contient du Terraform une pull request sur une branche ctadel/iac-tagging-<date>, intitulée « Ctadel: enable code-to-cloud tagging ». Elle ajoute à chaque ressource une étiquette ctadel:id portant un identifiant opaque (des tags en général, des labels sur Google Cloud) ; aucun chemin ni nom de votre code n’est écrit dans le cloud. Une fois la pull request fusionnée, l’inventaire suivant relie chaque ressource cloud au fichier qui la déclare.

Les règles de cette pull request :

• une seule pull request ouverte par dépôt à la fois ;
• fermée sans fusion, elle n’est reproposée qu’après 30 jours, et une seule fois ; réouverte, elle est suivie à nouveau ;
• un dépôt sans Terraform est passé, puis réexaminé au premier push sur sa branche par défaut qui en ajoute ;
• après plusieurs échecs consécutifs d’ouverture, Ctadel n’essaie plus sur ce dépôt ;
• les commits sont signés ctadel-bot, et les branches ctadel/iac-tagging- ne sont jamais analysées.

Après fusion, une seconde pull request peut suivre pour couvrir les ressources ajoutées depuis.

Limites

• GitHub et GitLab seulement. Bitbucket, Azure DevOps, Gitea ou un serveur Git nu ne sont pas pris en charge.
• GitHub Enterprise Server n’est pas pris en charge : l’application parle à github.com.
• Sur GitLab, seule la famille IaC publie une note et un statut. La pull request d’étiquetage et l’écriture du dossier dans .ctadel.yaml existent sur GitHub seulement.
• Sur GitLab, l’événement de mise à jour d’une merge request couvre aussi un changement de titre, qui coûte une analyse.
• Les modèles Helm et les surcouches Kustomize ne sont pas du YAML valide et ne sont pas analysés ; ils sont comptés comme fichiers non lus dans le rapport, avec la raison.
• Dépendances : Maven, Gradle, pnpm, Poetry, PDM, NuGet, Conda, Helm, Nix, Bun, SwiftPM, CocoaPods, Conan, vcpkg, Hex et Pub ne sont pas lus. Quand un tel manifeste est présent sans manifeste pris en charge, le statut ctadel/sca est en erreur et le dit, plutôt qu’en succès.
• Les secrets détectés sont marqués « UNKNOWN » dans le commentaire tant que leur validité n’a pas été testée.
• Pour un dépôt GitHub, le statut de la famille dépendances n’est publié que dans les pull requests.
• Les analyses sont déclenchées par les webhooks seulement : un dépôt sans push ni pull request n’est pas réanalysé.