Guardrail-Ledger-Dokumentation

Pipeline verbinden

Die Scanner laufen auf Ihren Agents oder Runnern. Die Task oder Action sammelt deren SARIF, sendet es an Ihren Workspace und liest das Gate-Ergebnis.

1. Ein Ingest-Token erzeugen

Ein Owner oder Admin öffnet die Seite Pipeline, gibt einen Token-Namen ein und wählt Mint ingest token (Ingest-Token erzeugen). Das Token wird einmal angezeigt. Speichern Sie es als geheime Variable GUARDRAIL_TOKEN in Azure Pipelines oder als Repository-Secret GUARDRAIL_INGEST_TOKEN auf GitHub.

2. Die vier Scanner installieren

Trivy, Gitleaks, Checkov und Opengrep müssen im PATH des Agents oder Runners liegen. Die Task installiert sie nicht.

3a. Azure DevOps

1. Geben Sie auf der Seite Pipeline den Namen Ihrer Azure-DevOps-Organisation ein (der Name in dev.azure.com/<organisation>) und wählen Sie Share the extension with this organisation (Erweiterung mit dieser Organisation teilen).
2. Öffnen Sie den dort erscheinenden Marketplace-Link, wählen Sie Get it free und wählen Sie die Organisation. Für die Installation ist die Berechtigung zum Verwalten von Erweiterungen in dieser Organisation nötig. Solange die Erweiterung nicht geteilt ist, wird der Link nicht angezeigt.
3. Fügen Sie den Schritt zu azure-pipelines.yml hinzu und führen Sie die Pipeline bei Pull Requests aus.

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

Die Zeile env erlaubt der Task, das Gate-Ergebnis als Kommentar am Pull Request zu hinterlegen. Die Build-Service-Identität des Projekts benötigt außerdem die Berechtigung Contribute to pull requests (Zu Pull Requests beitragen) für das Repository.

3b. GitHub Actions

1. Laden Sie auf der Seite Pipeline action.yml und index.js herunter. Committen Sie sie als .github/actions/guardrail-ledger/action.yml und .github/actions/guardrail-ledger/dist/index.js.
2. Fügen Sie den Workflow hinzu, den die Seite Pipeline anzeigt. Er installiert die Scanner und führt dann die Action mit Ihrer Workspace-Adresse und dem Secret GUARDRAIL_INGEST_TOKEN aus.
3. Führen Sie den Scan bei Pull Requests aus Branches im Repository aus. Bei Forks gibt GitHub dem Job keine Secrets.

Der Job benötigt diese Berechtigungen, damit die Action den Code lesen und den Pull Request kommentieren kann:

permissions:
  contents: read
  pull-requests: write

Jede andere CI

Jede CI, die SARIF schreibt, kann es an Ihren Workspace senden. Der Body ist JSON mit repo und sarif, und das Token steht in einem Bearer-Header.

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":[...]}}'

Wenn ein Scanner fehlschlägt

Der Schritt schlägt fehl und nennt den Scanner, wenn ein Scanner fehlt, abstürzt, mit einem Fehler endet oder kein brauchbares SARIF schreibt. In diesem Fall wird nichts gesendet. Um mit den übrigen Scannern fortzufahren, setzen Sie allowMissingScanners: true an der Azure-DevOps-Task oder allow-missing-scanners: true an der Action. Der Lauf wird dann als unvollständig gesendet, sodass dadurch kein Befund als behoben gilt und das Gate bei fehlenden Ergebnissen nicht besteht.

Was gesendet wird

Die Task sendet die SARIF-Ergebnisse der Scanner, den Repository-Namen, den Commit, die Pull-Request-Nummer, den Login der Person, die den Build ausgeführt hat, und die Pfade von KI-Tooling-Dateien wie AGENTS.md oder mcp.json. Sie entfernt Code-Ausschnitte und Kontextzeilen aus dem SARIF, bevor sie es sendet. Sie lädt das Repository nicht hoch. Die Scanner-Ausgabe wird in das temporäre Verzeichnis des Agents außerhalb der Quellen geschrieben und nach dem Lesen gelöscht.