Documentation Guardrail Ledger

Relier votre pipeline

Les scanners s'exécutent sur vos agents ou vos runners. La tâche ou l'Action collecte leur SARIF, l'envoie à votre espace de travail et lit le résultat du contrôle.

1. Créer un jeton d'ingestion

Un propriétaire ou un administrateur ouvre la page Pipeline, saisit un nom de jeton et choisit Créer un jeton d'ingestion. Le jeton n'est affiché qu'une fois. Stockez-le comme variable secrète GUARDRAIL_TOKEN dans Azure Pipelines, ou comme secret de dépôt GUARDRAIL_INGEST_TOKEN sur GitHub.

2. Installer les quatre scanners

Trivy, Gitleaks, Checkov et Opengrep doivent se trouver dans le PATH de l'agent ou du runner. La tâche ne les installe pas.

3a. Azure DevOps

1. Sur la page Pipeline, saisissez le nom de votre organisation Azure DevOps (le nom dans dev.azure.com/<organisation>) et choisissez Partager l'extension avec cette organisation.
2. Ouvrez le lien vers la Marketplace qui s'y affiche, choisissez Get it free et sélectionnez l'organisation. L'installation nécessite la permission de gérer les extensions dans cette organisation. Tant que l'extension n'est pas partagée, le lien n'est pas affiché.
3. Ajoutez l'étape à azure-pipelines.yml et exécutez le pipeline sur les pull requests.

- task: GuardrailLedgerScan@0
  inputs:
    guardrailUrl: 'https://<workspace>.guardrail-ledger.com'
    ingestToken: '$(GUARDRAIL_TOKEN)'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

La ligne env permet à la tâche de commenter le résultat du contrôle sur la pull request. L'identité du service de build du projet a aussi besoin de la permission Contribute to pull requests sur le dépôt.

3b. GitHub Actions

1. Sur la page Pipeline, téléchargez action.yml et index.js. Validez-les (commit) sous .github/actions/guardrail-ledger/action.yml et .github/actions/guardrail-ledger/dist/index.js.
2. Ajoutez le workflow que montre la page Pipeline. Il installe les scanners, puis exécute l'Action avec l'adresse de votre espace de travail et le secret GUARDRAIL_INGEST_TOKEN.
3. Exécutez le scan sur les pull requests issues de branches du dépôt. Sur les forks, GitHub ne donne aucun secret au job.

Le job a besoin de ces permissions pour que l'Action puisse lire le code et commenter la pull request :

permissions:
  contents: read
  pull-requests: write

Toute autre CI

Toute CI qui écrit du SARIF peut l'envoyer à votre espace de travail. Le corps est du JSON avec repo et sarif, et le jeton est placé dans un en-tête Bearer.

curl -sS -X POST 'https://<workspace>.guardrail-ledger.com/api/v1/ingest/sarif' \
  -H "Authorization: Bearer $GUARDRAIL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"repo":"example-repo","sarif":{"version":"2.1.0","runs":[...]}}'

Quand un scanner échoue

L'étape échoue, en nommant le scanner, lorsqu'un scanner est absent, plante, se termine par une erreur ou n'écrit aucun SARIF exploitable. Rien n'est envoyé dans ce cas. Pour continuer avec les autres scanners, définissez allowMissingScanners: true sur la tâche Azure DevOps, ou allow-missing-scanners: true sur l'Action. L'exécution est alors envoyée comme incomplète : aucun constat n'est résolu à partir d'elle et le contrôle ne passe pas sur ce qui manque.

Ce qui est envoyé

La tâche envoie les résultats SARIF des scanners, le nom du dépôt, le commit, le numéro de la pull request, l'identifiant de la personne qui a lancé le build et les chemins des fichiers d'outillage d'IA tels que AGENTS.md ou mcp.json. Elle retire les extraits de code et les lignes de contexte du SARIF avant l'envoi. Elle ne téléverse pas le dépôt. La sortie des scanners est écrite dans le répertoire temporaire de l'agent, en dehors des sources, et supprimée après lecture.