Comece em 5 minutos

Do zero a uma ronda lida pelo seu código. Precisa de uma conta no plano Pro ou Business e de ser dono dela — chaves são coisa de dono.

Os cinco passos#

1. Crie a chave

   Em Configurações → Desenvolvedores, crie uma chave com os escopos scans:read e scans:write. Dê um nome que diga onde ela roda (ci-producao, não chave 1).

   O segredo aparece uma vez.

   A Guarita guarda só um hash. Copie o gsk_… pro cofre de segredos do seu CI antes de fechar a tela. Perdeu? Revogue e crie outra.

2. Guarde no ambiente

   Nunca no repositório, nunca no front-end. Variável de ambiente, e só.

   export GUARITA_API_KEY="gsk_a1b2c3d4KZ8mQvR7tYw2NpX5LhJ0eSg6UdF9BcA3iOk"

3. Confirme que funciona

   GET /me devolve a conta, os escopos e o plano. É o primeiro request de toda integração — e o primeiro a rodar quando algo parar.

   curlNode.jsPython

   curl https://api.guarita.dev/v1/public/me \
     -H "Authorization: Bearer $GUARITA_API_KEY"

   {
     "account_id": "acc_9f2c1b7e",
     "key_id": "key_3a8d41c6",
     "scopes": [
       "scans:read",
       "scans:write",
       "apps:read"
     ],
     "plan": "pro"
   }

4. Dispare uma ronda

   Só target é obrigatório — a declaração de autorização você já fez ao criar a chave. ai: true (o padrão) consome 1 análise da cota e exige app verificado; sem verificação, use ai: false pra ronda básica. Testes autenticados, modo agressivo, LGPD e escopo de infra são opções do mesmo corpo — veja as opções da ronda.

   curlNode.jsPython

   curl -X POST https://api.guarita.dev/v1/public/scans \
     -H "Authorization: Bearer $GUARITA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "target": "https://app.exemplo.com.br",
       "ai": true
     }'

   {
     "id": "scan_e11a03d9",
     "status": "running"
   }

   202 = aceitei e enfileirei, não terminei. A ronda leva alguns minutos (teto de 30).

5. Leia o resultado

   Consulte GET /scans/{id} a cada 10 s até status virar done. Enquanto roda, progress diz em que fase está. Aí summary traz o número que importa.

   curlNode.jsPython

   curl https://api.guarita.dev/v1/public/scans/scan_7b3e9a12 \
     -H "Authorization: Bearer $GUARITA_API_KEY"

   {
     "id": "scan_7b3e9a12",
     "hostname": "app.exemplo.com.br",
     "target": "https://app.exemplo.com.br",
     "status": "done",
     "created_at": "2026-08-27T14:02:56.902Z",
     "finished_at": "2026-08-27T14:09:24.106Z",
     "progress": null,
     "summary": {
       "id": "scan_7b3e9a12",
       "target": "https://app.exemplo.com.br",
       "hostname": "app.exemplo.com.br",
       "status": "done",
       "score": 78,
       "riskLabel": "HIGH_RISK",
       "criticalCount": 2,
       "finishedAt": "2026-08-27T14:09:24.106Z",
       "durationMs": 387096,
       "blocked": false
     }
   }

Decidir pelo resultado#

O par score + criticalCount é o que um pipeline usa pra decidir. Antes de decidir, olhe blocked: ronda que não viu o app não tem nota que valha.

const { summary } = ronda; // GET /scans/{id} com status "done"

if (summary.blocked) {
  // A Guarita não conseguiu ver o app — a nota não vale. Não falhe o build por isso.
  console.warn(`Ronda inconclusiva (${summary.blockedReason}).`);
} else if (summary.criticalCount > 0) {
  console.error(`${summary.criticalCount} crítico(s) — exposição ${summary.score} (${summary.riskLabel})`);
  process.exit(1);
} else {
  console.log(`Sem críticos — exposição ${summary.score} (${summary.riskLabel})`);
}

O laço completo de disparar, acompanhar e decidir está em Rondas → Disparar e acompanhar, em Node e Python.

Depois disso#

• GitHub Actions— a receita pronta de ronda a cada deploy.
• Relatório— os achados completos, com o conserto pronto pra colar na IA.
• Webhooks— ser avisado em vez de perguntar — com assinatura.
• Erros— o que cada código significa e o que fazer.