Sentinel agent

wasviking-sentinel sbom

Generate a CycloneDX 1.5 SBOM on-premises, enrich with OSV and CISA KEV, and submit to your tenant.

wasviking-sentinel sbom walks build manifests on the host and produces a CycloneDX 1.5 SBOM, enriched with OSV.dev advisories and CISA KEV flags. The output can be written locally or submitted to your WASViking^® tenant.

Supported manifests

Ecosystem	Manifest files
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`

The walker reads from a directory you pass in. It does not require the language toolchain to be installed; it parses the lock format directly.

License check (preflight)

Before any local work, sbom calls the WASViking preflight endpoint to confirm the organization API key is active. This is required even when you are not submitting results.

--api-key (or env WASV_API_KEY) is required. Missing or empty refuses with exit 1.
The check is POST /api/v1/sentinel/preflight. Any active org API key passes; no specific scope is needed for the preflight itself.
Result cached at ~/.wasviking/preflight_cache.json (mode 0600) for 30 minutes by default (TTL from server, clamped 60s..6h).
Within TTL, subsequent calls skip the network entirely.
If the API is unreachable but a recent successful approval is on disk (within a 24-hour grace window), the run continues. Short WASViking outages do not break customer CI.
If the API actively rejects the key (401 / 403), the grace window does not apply. Revoked keys block on the next cache expiration.
The cache is keyed by a truncated SHA-256 of the API key, so rotating the key invalidates the cache automatically.

The --submit flag is independent. --api-key is required regardless of whether you submit the SBOM.

Basic usage

From the directory containing the source tree:

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

The default writes two files into --out (default .):

wasviking-sbom.cdx.json: CycloneDX 1.5 document.
wasviking-sbom.sarif: SARIF report of the vulnerable components, for direct ingestion in IDE / code scanning tooling that consumes SARIF.

Submit to your tenant

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

The agent posts to POST /api/v1/sentinel/sbom/submit. The submission carries:

The CycloneDX 1.5 document.
App name and version (from --app-name / --app-version or auto- detected from the manifests).
OSV and KEV enrichment.
The hostname of the machine that produced it.

In the portal, the submission lands at Inventory → SBOM and feeds the Supply Chain Watch.

Flags reference

Flag	Purpose	Default
`--path`	Directory to scan for manifests, recursive.	`.`
`--out`	Directory to write `wasviking-sbom.cdx.json` and `wasviking-sbom.sarif`.	`.`
`--app-name`	Project name embedded in the BOM `metadata.component`.	(auto-detected)
`--app-version`	Project version embedded in the BOM `metadata.component`.	(auto-detected)
`--fail-on`	Severity threshold: `critical`, `high`, `medium`, `low`, `none`.	`high`
`--no-osv`	Skip OSV.dev enrichment (ships a bare SBOM).	`false`
`--air-gapped`	Guarantee no external HTTP; uses the bundled KEV seed only.	`false`
`--submit`	POST the SBOM to the WASViking API after generation.	`false`
`--api`	WASViking API base URL. Env: `WASV_API`.	`https://api.wasviking.com`
`--api-key`	Organization API key. Required for every run (preflight). Add the `sca:submit` scope on the key if you also use `--submit`. Env: `WASV_API_KEY`.	(required)
`--timeout`	Max wall-clock time for the SBOM pipeline.	`5m0s`

Air-gapped runs. With --air-gapped, the SBOM uses a CISA KEV snapshot bundled inside the binary. No external HTTP is performed. The KEV snapshot moves forward with each release; refresh the binary to refresh the snapshot.

Determinism

Two runs over the same source tree produce SBOMs that diff cleanly. The walker:

Sorts components by purl before output.
Pins enrichment timestamps to the run start.
Normalizes version strings per ecosystem rules.

This matters for SCA gate decisions and for diff'ing across builds.

Exit codes

Exit code	Meaning
0	SBOM produced, submitted if requested, no findings at or above `--fail-on`.
1	Generic failure (parsing error, IO, network).
60	OSV or KEV enrichment failed but SBOM produced.
61	Submission failed; SBOM is on disk.
70	Findings at or above the `--fail-on` threshold detected.

sbom is itself usable as a CI gate via --fail-on. For the higher- level wrapper that also runs the secrets and template-driven scans in one pass, see wasviking-sentinel ci.

What this is not

This is not a runtime scanner. It reads lockfiles, not running processes. For application-layer component detection from outside, the platform ships cloud-side component detection (N1 layer) and pairs it with this premise-side N2 layer for the full picture.