Agente Sentinel

wasviking-sentinel sbom

Gere um SBOM CycloneDX 1.5 on-premises, enriqueça com OSV e CISA KEV e envie para o seu tenant.

O wasviking-sentinel sbom percorre os manifestos de build no host e produz um SBOM CycloneDX 1.5, enriquecido com os advisories do OSV.dev e as marcações do CISA KEV. A saída pode ser gravada localmente ou enviada para o seu tenant WASViking^®.

Manifestos suportados

Ecossistema	Arquivos de manifesto
npm	`package-lock.json`, `npm-shrinkwrap.json`
yarn	`yarn.lock`
pnpm	`pnpm-lock.yaml`
Python	`requirements.txt`, `Pipfile.lock`, `poetry.lock`
Go	`go.sum`, `go.mod`
PHP	`composer.lock`
Java	`pom.xml`, `gradle.lockfile`
Ruby	`Gemfile.lock`
Dart / Flutter	`pubspec.lock`

A varredura lê a partir de um diretório que você informa. Ela não exige que o toolchain da linguagem esteja instalado; ela interpreta o formato do lock diretamente.

Verificação de licença (preflight)

Antes de qualquer trabalho local, o sbom chama o endpoint de preflight da WASViking para confirmar que a chave de API da organização está ativa. Isso é obrigatório mesmo quando você não está enviando resultados.

--api-key (ou a variável de ambiente WASV_API_KEY) é obrigatória. Ausente ou vazia, a execução é recusada com exit 1.
A verificação é POST /api/v1/sentinel/preflight. Qualquer chave de API ativa da organização passa; nenhum escopo específico é necessário para o preflight em si.
O resultado fica em cache em ~/.wasviking/preflight_cache.json (modo 0600) por 30 minutos por padrão (TTL vindo do servidor, limitado ao intervalo 60s..6h).
Dentro do TTL, as chamadas seguintes dispensam a rede por completo.
Se a API estiver inacessível, mas houver em disco uma aprovação recente bem-sucedida (dentro de uma janela de tolerância de 24 horas), a execução continua. Indisponibilidades curtas da WASViking não quebram o CI do cliente.
Se a API rejeitar ativamente a chave (401 / 403), a janela de tolerância não se aplica. Chaves revogadas bloqueiam na próxima expiração do cache.
A chave do cache é um SHA-256 truncado da chave de API, então rotacionar a chave invalida o cache automaticamente.

A flag --submit é independente. --api-key é obrigatória, quer você envie o SBOM, quer não.

Uso básico

A partir do diretório que contém a árvore de código-fonte:

export WASV_API_KEY="wv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
wasviking-sentinel sbom --path .

Por padrão, a execução grava dois arquivos em --out (padrão .):

wasviking-sbom.cdx.json: documento CycloneDX 1.5.
wasviking-sbom.sarif: relatório SARIF dos componentes vulneráveis, para ingestão direta em IDEs e ferramentas de code scanning que consomem SARIF.

Envie para o seu tenant

wasviking-sentinel sbom \
  --path . \
  --app-name checkout-api \
  --app-version "$CI_COMMIT_TAG" \
  --submit \
  --api-key "$WASV_API_KEY"

O agente faz o envio para POST /api/v1/sentinel/sbom/submit. O envio carrega:

O documento CycloneDX 1.5.
O nome e a versão da aplicação (de --app-name / --app-version ou detectados automaticamente a partir dos manifestos).
O enriquecimento de OSV e KEV.
O hostname da máquina que o produziu.

No portal, o envio chega em Inventory → SBOM e alimenta o Supply Chain Watch.

Referência de flags

Flag	Finalidade	Padrão
`--path`	Diretório a ser percorrido em busca de manifestos, de forma recursiva.	`.`
`--out`	Diretório onde gravar `wasviking-sbom.cdx.json` e `wasviking-sbom.sarif`.	`.`
`--app-name`	Nome do projeto embutido no `metadata.component` do BOM.	(detectado automaticamente)
`--app-version`	Versão do projeto embutida no `metadata.component` do BOM.	(detectada automaticamente)
`--fail-on`	Limiar de severidade: `critical`, `high`, `medium`, `low`, `none`.	`high`
`--no-osv`	Dispensa o enriquecimento do OSV.dev (entrega um SBOM sem enriquecimento).	`false`
`--air-gapped`	Assegura que não há HTTP externo; usa somente a seed de KEV embutida.	`false`
`--submit`	Faz o POST do SBOM para a API da WASViking depois da geração.	`false`
`--api`	URL base da API da WASViking. Variável de ambiente: `WASV_API`.	`https://api.wasviking.com`
`--api-key`	Chave de API da organização. Obrigatória em toda execução (preflight). Adicione o escopo `sca:submit` à chave se você também usa `--submit`. Variável de ambiente: `WASV_API_KEY`.	(obrigatória)
`--timeout`	Tempo máximo de relógio (wall-clock) para o pipeline de SBOM.	`5m0s`

Execuções air-gapped. Com --air-gapped, o SBOM usa um snapshot do CISA KEV embutido no binário. Nenhum HTTP externo é realizado. O snapshot do KEV avança a cada release; atualize o binário para atualizar o snapshot.

Determinismo

Duas execuções sobre a mesma árvore de código-fonte produzem SBOMs cujo diff sai limpo. A varredura:

Ordena os componentes por purl antes da saída.
Fixa os timestamps de enriquecimento no início da execução.
Normaliza as strings de versão conforme as regras de cada ecossistema.

Isso importa para as decisões do gate de SCA e para comparar builds por diff.

Exit codes

Exit code	Significado
0	SBOM produzido, enviado se solicitado, nada em nível igual ou superior a `--fail-on`.
1	Falha genérica (erro de parsing, IO, rede).
2	Argumento inválido, ou `--submit` sem uma chave de API.
70	Achado sinalizado no KEV em nível igual ou superior a `--fail-on`. Exploração conhecida, trate como urgente.
71	Achados em nível igual ou superior a `--fail-on`, nenhum deles no KEV.
79	Falha de cobertura: a raiz não pôde ser percorrida, então nada foi analisado. Nunca é retornado para um projeto que simplesmente está vazio ou não tem nenhum manifesto suportado. Consulte Falhas de cobertura.

Duas condições deliberadamente não fazem o build falhar: uma falha no enriquecimento de OSV ou de KEV e uma falha no envio. As duas imprimem um aviso, os artefatos permanecem em disco, e o gate é decidido com base no que a execução realmente conseguiu ver. Uma rede com problemas não deveria, sozinha, bloquear um merge.

O sbom pode, ele próprio, ser usado como gate de CI por meio de --fail-on. Para o wrapper de nível mais alto, que também executa os scans de secrets e os scans guiados por template em uma única passada, consulte wasviking-sentinel ci.

O que isto não é

Isto não é um scanner de runtime. Ele lê lockfiles, não processos em execução. Para a detecção de componentes na camada de aplicação, de fora, a plataforma oferece a detecção de componentes a partir da nuvem (camada N1) e a combina com esta camada N2, no ambiente do cliente, para o quadro completo.