Guardrail Ledger-documentatie

Koppel uw pijplijn

De scanners draaien op uw agents of runners. De taak of Action verzamelt hun SARIF, stuurt die naar uw werkruimte en leest het gate-resultaat.

1. Maak een ingest-token aan

Een eigenaar of beheerder opent de pagina Pijplijn, voert een tokennaam in en kiest Ingest-token aanmaken. Het token wordt één keer getoond. Bewaar het als geheime variabele GUARDRAIL_TOKEN in Azure Pipelines, of als repositorygeheim GUARDRAIL_INGEST_TOKEN op GitHub.

2. Installeer de vier scanners

Trivy, Gitleaks, Checkov en Opengrep moeten in het PATH van de agent of runner staan. De taak installeert ze niet.

3a. Azure DevOps

1. Voer op de pagina Pijplijn de naam van uw Azure DevOps-organisatie in (de naam in dev.azure.com/<organisation>) en kies Extensie delen met deze organisatie.
2. Open de Marketplace-link die daar verschijnt, kies Get it free en selecteer de organisatie. Voor het installeren is toestemming nodig om extensies in die organisatie te beheren. Zolang de extensie niet is gedeeld, wordt de link niet getoond.
3. Voeg de stap toe aan azure-pipelines.yml en voer de pijplijn uit bij pull requests.

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

Met de regel env kan de taak het gate-resultaat als opmerking op de pull request plaatsen. De identiteit van de buildservice van het project heeft daarnaast de machtiging Contribute to pull requests op de repository nodig.

3b. GitHub Actions

1. Download op de pagina Pijplijn action.yml en index.js. Commit ze als .github/actions/guardrail-ledger/action.yml en .github/actions/guardrail-ledger/dist/index.js.
2. Voeg de workflow toe die de pagina Pijplijn toont. Die installeert de scanners en voert daarna de Action uit met het adres van uw werkruimte en het geheim GUARDRAIL_INGEST_TOKEN.
3. Voer de scan uit op pull requests vanuit branches in de repository. Bij forks geeft GitHub de job geen geheimen.

De job heeft deze machtigingen nodig, zodat de Action de code kan lezen en een opmerking op de pull request kan plaatsen:

permissions:
  contents: read
  pull-requests: write

Elke andere CI

Elke CI die SARIF schrijft, kan die naar uw werkruimte sturen. De body is JSON met repo en sarif, en het token gaat in een 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":[...]}}'

Wanneer een scanner faalt

De stap faalt, en noemt de scanner, wanneer een scanner ontbreekt, crasht, met een fout eindigt of geen bruikbare SARIF schrijft. In dat geval wordt er niets verstuurd. Om door te gaan met de andere scanners, stelt u allowMissingScanners: true in op de Azure DevOps-taak, of allow-missing-scanners: true op de Action. De run wordt dan als onvolledig verstuurd, zodat er geen bevinding op wordt opgelost en de gate niet slaagt op wat ontbreekt.

Wat er wordt verstuurd

De taak verstuurt de SARIF-resultaten van de scanners, de repositorynaam, de commit, het nummer van de pull request, de login van de persoon die de build heeft gestart en de paden van AI-toolingbestanden zoals AGENTS.md of mcp.json. Vóór het versturen verwijdert hij codefragmenten en contextregels uit de SARIF. Hij uploadt de repository niet. Scanneruitvoer wordt naar de tijdelijke map van de agent geschreven, buiten de bronbestanden, en verwijderd nadat hij is gelezen.