wasviking-sentinel em CI/CD

Coloque o mesmo binário Go no seu pipeline para SBOM, secrets, avaliação mobile e scans em nuvem orientados por política. Gates independentes, um único preflight, exit codes determinísticos.

O mesmo binário wasviking-sentinel que abre o túnel mTLS também roda como ferramenta de execução única (one-shot) em pipelines de CI/CD. Em um contexto de CI/CD o agente não precisa estar registrado (sem bootstrap de mTLS, sem certificados). Ele se autentica com uma chave de API da organização.

Três gates independentes estão disponíveis hoje, cada um como um subcomando de primeiro nível:

Cada subcomando é documentado em detalhe na sua própria página:

• wasviking-sentinel sbom
• wasviking-sentinel secrets
• (referência do subcomando scan: veja o gate de Cloud DAST abaixo)

Para receitas prontas para colar, veja DAST em CI/CD com GitHub Actions, SCA, SBOM e secrets no CI/CD com GitHub Actions e SCA, SBOM e secrets em CI/CD com Bitbucket Pipelines.

Início rápido (GitHub Actions)

# .github/workflows/security.yml
- name: WASViking · SCA
  run: ./wasviking-sentinel sbom --path . --fail-on high --submit
  env:
    WASV_API_KEY: ${{ secrets.WASVIKING_CI_KEY }}

- name: WASViking · Secrets
  run: ./wasviking-sentinel secrets --path . --verify --submit
  env:
    WASV_API_KEY: ${{ secrets.WASVIKING_CI_KEY }}

- name: WASViking · Cloud DAST
  run: ./wasviking-sentinel scan --template prod-web-strict --target https://staging.example.com
  env:
    WASV_API_KEY: ${{ secrets.WASVIKING_CI_KEY }}

Os mesmos três comandos rodam no Bitbucket Pipelines (exemplo completo em SCA, SBOM e secrets em CI/CD com Bitbucket Pipelines), no GitLab CI, no CircleCI, no Jenkins e no Buildkite. Qualquer runner Linux capaz de executar o binário funciona.

Autenticação

export WASV_API_KEY=wv_live_xxxxxxxxxxxxxxxxxxxxxxxx
./wasviking-sentinel version

As chaves de API são criadas no portal em Settings → API Keys. A chave precisa dos escopos certos para o que você de fato vai fazer:

Use uma chave dedicada de CI apenas com os escopos de que você precisa.

Verificação de licença (preflight)

Toda invocação de sbom, de secrets e de scan no lado do CI chama POST /api/v1/sentinel/preflight antes de fazer qualquer trabalho. O preflight é obrigatório: uma chave de API vazia ou rejeitada bloqueia a execução.

• --api-key (ou a variável de ambiente WASV_API_KEY) é obrigatório, mesmo quando você não está enviando resultados.
• As aprovações bem-sucedidas ficam em cache em ~/.wasviking/preflight_cache.json (modo 0600) por 30 minutos.
• Janela de tolerância de 24 horas se a API estiver inacessível mas existir uma aprovação recente em disco.
• Uma rejeição ativa (401 / 403) não recebe a janela de tolerância: chaves revogadas bloqueiam na próxima expiração do cache.
• O cache é invalidado na rotação da chave (a chave do cache é um SHA-256 truncado da chave de API).

Para o modelo completo do preflight, veja a seção de verificação de licença na página do sbom.

Gate de SCA (sbom)

./wasviking-sentinel sbom \
  --path . \
  --app-name checkout-api \
  --app-version "$CI_COMMIT_TAG" \
  --fail-on high \
  --submit

Comportamento:

1. Percorre os manifestos sob --path (recursivo).
2. Monta um SBOM CycloneDX 1.5.
3. Enriquece com os advisories do OSV.dev e com o CISA KEV.
4. Aplica a política de --fail-on.
5. Se houver --submit, faz POST para a API da WASViking.

Exit codes:

Uma falha no enriquecimento do OSV ou uma falha no envio gera um aviso e a execução segue em frente. Nenhuma das duas, sozinha, faz o build falhar.

Limiar padrão: high. Referência completa de flags: wasviking-sentinel sbom.

Gate de secrets (secrets)

./wasviking-sentinel secrets \
  --path . \
  --git \
  --verify \
  --fail-on high \
  --submit

Comportamento:

1. Percorre a working tree sob --path.
2. Com --git, percorre também o histórico git local.
3. Compara com 32 detectores.
4. Com --verify, consulta os endpoints de identidade dos provedores (somente leitura) para os 10 detectores que suportam verificação ao vivo.
5. Aplica a política de --fail-on.
6. Se houver --submit, faz POST para a API da WASViking (hash + prévia mascarada; os secrets brutos nunca saem do host).

Exit codes:

Limiar padrão: high. Referência completa de flags: wasviking-sentinel secrets.

Gate de Cloud DAST (scan)

./wasviking-sentinel scan \
  --template prod-web-strict \
  --target https://staging.example.com

O subcomando scan dispara um scan em nuvem usando um scan template com escopo de organização. O template é resolvido no lado do servidor, então os secrets configurados no template nunca chegam ao runner de CI. O binário acompanha o scan até a conclusão e encerra com um código que reflete a política.

Exit codes comuns:

Limiar padrão: critical.

O scan também pode executar os gates locais de SCA e de secrets na mesma passagem, com --sca e --secrets. Eles rodam antes de o scan em nuvem começar e mantêm os seus próprios códigos (70, 71, 73, 74). Em uma execução com --sca, um 70 significa uma dependência sinalizada no KEV, não um template ausente.

O scan é a contraparte em nuvem dos gates locais sbom e secrets. Ele não exige que o agente mTLS esteja registrado.

Falhas de cobertura (exit 79)

Um gate que não analisa nada não encontra nada e, sem uma verificação, isso parece exatamente uma execução limpa. O exit 79 existe para manter esses dois casos separados.

O agente lê a raiz do scan antes de percorrê-la e depois compara o que cobriu com o que havia ali. Quando a raiz contém entradas e a varredura não alcançou nenhuma delas, a execução para com exit 79 em vez de reportar aprovação. O mesmo vale quando a raiz não pode sequer ser listada, em geral um problema de permissão no runner.

O que o exit 79 não é: um achado, nem uma reclamação sobre um projeto vazio. Um repositório sem arquivos, ou um cujo conteúdo inteiro está em diretórios excluídos como node_modules, é percorrido corretamente e passa. O mesmo vale para um projeto sem manifesto suportado, que informa quantas entradas percorreu para que você veja a diferença.

Causas comuns, na ordem em que vale a pena verificar:

As exclusões de diretório nunca causam o exit 79. Elas se aplicam apenas a subdiretórios, então um projeto cujo checkout foi feito em um diretório chamado build, dist, target ou vendor é analisado normalmente. Quando isso acontece, o log diz isso de forma explícita.

Apontar um caminho para um diretório .git é recusado logo de início, com uma mensagem que indica --git, a flag que analisa o histórico de commits.

Concorrência e medição

Para o subcomando scan, a plataforma impõe dois limites por organização:

• Um limite de scans simultâneos. O provisionamento é rejeitado com HTTP 429 quando os scans de CI em andamento da organização atingem o limite.
• Uma janela mensal de medição. O início de um scan é rejeitado com HTTP 402 quando a cota medida se esgota.

O agente não enfileira nem tenta de novo em nenhum dos dois casos. A rejeição chega ao log do build e a etapa encerra com 1, então um pipeline que bateu no limite falha rápido em vez de segurar um runner à toa. Os dois eventos são exibidos na aba CI Usage do portal.

O que você deve fixar no CI

• Versão do binário. Distribua uma release assinada específica e verifique com o cosign antes de executar.
• Slug do template para o scan. Os templates são versionados no lado do servidor; o slug sempre resolve para a versão ativa do template.
• Escopos da chave de API. Use o escopo mínimo por estágio do pipeline.
• Limiares de --fail-on por trilha do pipeline (estrito na main, permissivo em feature branches).

O que este binário NÃO é no modo CI

• Ele não abre o túnel mTLS. run é o modo de tunelamento; sbom, secrets e scan são subcomandos one-shot de CI.
• Ele não chama o login de sessão do portal. A chave de API é a credencial.
• Ele não armazena achados localmente além dos artefatos de SBOM e de relatório em --out. A persistência fica no lado do portal após o --submit.