Documentação do Guardrail Ledger

Ligar o seu pipeline

Os scanners correm nos seus agentes ou runners. A tarefa ou a Action recolhe o SARIF deles, envia-o para o seu espaço de trabalho e lê o resultado do gate.

1. Criar um token de ingestão

Um proprietário ou administrador abre a página Pipeline, introduz um nome para o token e escolhe Criar token de ingestão. O token é mostrado uma só vez. Guarde-o como variável secreta GUARDRAIL_TOKEN no Azure Pipelines, ou como segredo do repositório GUARDRAIL_INGEST_TOKEN no GitHub.

2. Instalar os quatro scanners

Trivy, Gitleaks, Checkov e Opengrep têm de estar no PATH do agente ou do runner. A tarefa não os instala.

3a. Azure DevOps

1. Na página Pipeline, introduza o nome da sua organização do Azure DevOps (o nome em dev.azure.com/<organisation>) e escolha Partilhar a extensão com esta organização.
2. Abra a ligação do Marketplace que aí aparece, escolha Get it free e selecione a organização. A instalação exige permissão para gerir extensões nessa organização. Enquanto a extensão não for partilhada, a ligação não é mostrada.
3. Adicione o passo a azure-pipelines.yml e execute o pipeline nos pull requests.

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

O env permite que a tarefa comente o resultado do gate no pull request. A identidade do serviço de compilação do projeto também precisa da permissão Contribute to pull requests no repositório.

3b. GitHub Actions

1. Na página Pipeline, transfira action.yml e index.js. Faça commit deles como .github/actions/guardrail-ledger/action.yml e .github/actions/guardrail-ledger/dist/index.js.
2. Adicione o workflow que a página Pipeline mostra. Instala os scanners e depois executa a Action com o endereço do seu espaço de trabalho e o segredo GUARDRAIL_INGEST_TOKEN.
3. Execute a análise em pull requests de ramos do próprio repositório. Em forks, o GitHub não dá segredos ao job.

O job precisa destas permissões para que a Action possa ler o código e comentar no pull request:

permissions:
  contents: read
  pull-requests: write

Qualquer outro CI

Qualquer CI que escreva SARIF pode enviá-lo para o seu espaço de trabalho. O corpo é JSON com repo e sarif, e o token vai num cabeçalho 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":[...]}}'

Quando um scanner falha

O passo falha, e indica o scanner, quando um scanner está em falta, falha, termina com erro ou não escreve SARIF utilizável. Nesse caso nada é enviado. Para continuar com os outros scanners, defina allowMissingScanners: true na tarefa do Azure DevOps, ou allow-missing-scanners: true na Action. A execução é então enviada como incompleta, pelo que nenhuma descoberta é resolvida com ela e o gate não passa com base no que falta.

O que é enviado

A tarefa envia os resultados SARIF dos scanners, o nome do repositório, o commit, o número do pull request, o login de quem executou a compilação e os caminhos de ficheiros de ferramentas de IA como AGENTS.md ou mcp.json. Remove fragmentos de código e linhas de contexto do SARIF antes de o enviar. Não carrega o repositório. O resultado dos scanners é escrito no diretório temporário do agente, fora do código-fonte, e eliminado depois de lido.